Agent runners
One runner interface for Hermes Agent (ACP), CopilotKit/OpenBot, Claude Code and Codex β task in, result, artifacts and trace out.
@agentskit/runtime/runners gives every external agent backend the same contract, so a factory or a product can swap the backend through configuration.
interface AgentRunner {
id: string
run(task: RunnerTask): Promise<RunnerResult>
}
// task: { prompt, cwd?, allowedTools?, budget?: { timeoutMs?, maxTurns?, maxCostUsd? }, signal? }
// result: { status: 'completed' | 'failed' | 'aborted', output, artifacts, trace, costUsd?, error? }budget.maxCostUsd is accepted but not enforced by any current adapter; only costUsd is reported back on the result.
run never throws for agent failures: a missing binary, non-zero exit, timeout, abort or HTTP error all come back as status: 'failed' | 'aborted' with error set.
#Adapters
| Factory | Backend | How it talks |
|---|---|---|
hermesAcpRunner() | Hermes Agent | Agent Client Protocol (JSON-RPC over stdio, hermes acp); allowedTools is enforced on the agent's session/request_permission requests (allow only listed tools, or everything when omitted), other agent requests get -32601 |
copilotKitRunner({ url }) | CopilotKit / OpenBot | HTTP POST of { prompt, cwd, allowedTools, budget }; JSON { output, artifacts?, costUsd? } or plain text back. This is a custom JSON shape, not the CopilotKit runtime / AG-UI protocol: the endpoint must be a thin adapter that accepts it |
claudeCodeRunner() | Claude Code | claude -p --output-format json, maps allowedTools and maxTurns |
codexRunner() | Codex | codex exec; no per-tool allow list, so allowedTools is not forwarded |
#Trace
result.trace is a list of spans with the same shape as TraceSpan in @agentskit/observability (id, name, parentId, startTime, endTime, attributes, status). The first span is the run (runner:<id>, parentId: null); the others are its children.
#Choosing the runner
Select by id from configuration instead of importing a backend directly:
import { claudeCodeRunner, codexRunner, createRunnerRegistry } from '@agentskit/runtime/runners'
const runners = createRunnerRegistry([claudeCodeRunner(), codexRunner()])
const result = await runners.get(process.env.AGENT_RUNNER ?? 'claude-code').run({
prompt: 'Fix the failing test',
cwd: repoDir,
allowedTools: ['Read', 'Edit'],
budget: { timeoutMs: 600_000, maxTurns: 20 },
})Custom backends implement AgentRunner and are registered the same way. Use the contract in packages/runtime/tests/runners.test.ts (assertRunnerContract) against a fake runner to test code that depends on a runner without spawning anything.
Explore nearby
- PeerAgents
Everything that runs the loop β runtime, tools, skills, delegation, durable execution, topologies, background agents, HITL, self-debug.
- PeerRuntime
Execution engine for autonomous agents β runs a ReAct loop (observe, think, act) until final answer or step limit.
- PeerMulti-Agent Delegation
Coordinate multiple specialist agents from a parent agent using directed delegation.