Agent
Agent holds a provider, a model, a system prompt, a tool registry, a skill registry, and the active conversation. send() is the verb.
import { Agent, anthropic } from "@fifthrevision/axle";
const agent = new Agent({
provider: anthropic(apiKey),
model: "claude-sonnet-4-5",
system: "You are a helpful assistant.",
tools: [getWeather],
});One thing it deliberately doesn't hold: a transcript. It emits events and keeps only the active messages. Transcripts explains why, and what you do about it.
send()
const handle = agent.send("Write me a poem.");
const result = await handle.final;
if (!result.ok) throw new Error(result.error.message);
console.log(result.response);send() takes a plain string or an Instruct, and hands back a handle immediately. What you get in response follows what you put in:
- a string → the assistant's text
- an
Instructwith a schema → the parsed, typed object - an
Instructwithout one → text
Two small conveniences you don't have to think about, but might appreciate knowing. Strings get wrapped in an Instruct with vars: "optional", so if a user types {{braces}} at you, nothing explodes. And an Instruct you pass in gets cloned, so you can reuse and even mutate the same object afterwards without affecting a send in flight.
after — continuations run after the turn settles
A send can carry after, a program that runs once the turn settles, holds the queue until it returns, and runs further turns inline:
declare const judge: (result: unknown) => Promise<{ ok: boolean; feedback: string }>;
const handle = agent.send("Summarize the report.", {
after: async (result, ctx) => {
for (let attempt = 0; attempt < 3; attempt++) {
const verdict = await judge(result);
if (verdict.ok) break;
result = await ctx.send(verdict.feedback);
}
},
});
agent.send("Next question."); // waits until the continuation returnsThe continuation runs after the send's turn settles with a result, ok or not; a turn whose handle rejects (cancelled, a fatal tool error, a setup failure) skips it. ctx.send() runs an inline turn — the same arguments as send() without after, an ordinary turn in every way except it starts at once with no pending:queued. Inline sends run one at a time in call order and return a promise, not a handle. ctx also carries signal, id (the send's user turn id), and read-only messages and pending.
The handle resolves when the continuation returns, with the inline turns listed under result.after. A plain send's result has no after. A manual compact() carries no continuation, and an inline turn carries none. Full types are in the Agent reference.
Sends line up in a queue
Call send() while a turn is running and it waits its turn. Sends never run concurrently or interleave.
const a = agent.send("First question.");
const b = agent.send("Second question."); // waits for aEach handle settles with its own result, and b sees the history a committed.
The queue is doing more work than it looks like: compact() goes through it too, so compaction never races a turn. (Saving doesn't queue: snapshot() waits for the agent to go idle instead, and session reads the state as it stands — see Sessions & persistence.) Every accepted operation also announces itself: send() emits pending:queued with a preview turn carrying the id the committed turn will have, so a UI rendering [...transcript.turns, ...transcript.pending] keyed by id shows queued work. A handle cancelled while still queued emits pending:dropped and commits nothing. See Turn events.
One way to deadlock
agent.compact() queues behind in-flight work, and agent.snapshot() waits for idle — so if you await either from inside a tool's execute, an onToolCall handler, a compaction callback, an onStep callback, or an onSettled callback, you'll hang. The send is holding the queue (or the idle) that your nested call is waiting on. Call them from outside a send instead — or read agent.session when you need the state from inside one.
Interrupting: four different things
agent.stop(), agent.cancel(), agent.clear() and handle.cancel() sound similar and do quite different jobs. Here's the short version:
| You want to | Use |
|---|---|
| Let the current work finish, then stop | agent.stop() |
| Stop the active operation right now | agent.cancel() |
| Throw away what's queued up behind it | agent.clear() |
| Stop one specific send right now, mid-request | handle.cancel() |
These are the four calls. A turn can also stop without you asking: a turnTimeoutMs cancels it from the inside, with a timeout as the abort reason (see Listening in).
stop() — wind down gracefully
agent.stop(); // false if nothing was runningThis asks the active turn to finish at its next tool-batch boundary. Every call in the in-flight batch runs to completion and commits — they're already running at once. Then the handle settles without another provider request. Nothing gets wasted, and the history stays coherent.
stop() won't interrupt a request or a tool that's already in flight, and it leaves queued sends alone.
One consequence to expect: since a stopped turn ends on its tool-call exchange, a plain send resolves with whatever text that step produced — often nothing. An Instruct send may come back ok: false with a parse error. That's not a bug; there genuinely isn't a final answer yet.
agent.cancel() — stop the active operation now
agent.cancel("user-navigated-away"); // false if nothing was runningImmediate, like handle.cancel(), but aimed at whatever is active rather than a specific handle: the active operation aborts, a turn that already opened settles cancelled with its partial work committed, and queued operations are unaffected — the next one starts. stop() remains the gentle form. Graceful shutdown is clear(), then stop() or cancel(), then snapshot() (or the last onSettled).
clear() — empty the queue
const dropped = agent.clear(); // how many you cancelledCancels everything queued, leaves the active turn alone. Each cleared handle rejects with AxleAgentAbortError, having committed nothing. A waiting snapshot() is not queued work, so clear() doesn't touch it.
handle.cancel() — stop one send now
const handle = agent.send("Long task...");
handle.cancel("user-navigated-away");Immediate, and local to that handle. handle.final rejects with AxleAgentAbortError.
Whether anything commits comes down to timing, and the line is whether the turn opened:
- Cancel before it (while queued) and the handle just disappears —
pending:queuedis followed bypending:dropped, no user message, nothing committed. (Failing or cancelling while listing MCP tools no longer drops the send: the user turn opens first, so the user message stays and the agent turn endserrororcancelled. A retry is a new send, so remove the first user message first if you don't want both kept.) - Cancel after it and the user message stays, with the agent turn marked
cancelled. A cancelled turn is always recorded ascancelled, even when the provider rethrows something that doesn't look like an abort. That includes cancelling duringbeforeTurncompaction — compaction is ordinary work inside an already-open turn, so cancelling it doesn't unwind anything.
One timing subtlety: the user turn is stamped when send() is called, so the queued preview and the committed turn share their id, parts, and timing. For a send that waited in the queue, the turn's timing is the moment of the call, not the moment it committed.
Either way, the rejected error hangs on to reason, usage, turn, and whatever partial output existed. You paid for that; you may as well show it. When the cancel landed while the model was still writing its response, the partial keeps only what was written — no tool calls, no empty text or thinking parts — and is undefined when nothing was written.
Steering: stop, clear, send
The pattern you'll reach for most combines three of them — stop() so the active turn commits what it has, clear() so queued work the user has just superseded is dropped, then send() to land the new instruction on a clean history. The order matters, and the full recipe with the chat-box wiring is Interrupting & cancelling.
Listening in
const unsubscribe = agent.on((event) => {
if (event.type === "text:delta") process.stdout.write(event.delta);
});on() gives you back an unsubscribe function. Callbacks fire for every send from then on, so you wire them once rather than per turn. Turn events covers what you'll receive.
Beside the turn events, on() delivers the operation's lifecycle — the frame around the turns: operation:start when a send or compaction takes the queue, after:start / after:end around its continuation, operation:end with the outcome, and agent:idle when nothing is left behind it. The callback type is AgentEventCallback. If all you want is "is it working," skip the events and read agent.status — { phase: "idle" }, or { phase: "busy", id } with the running operation's id. It already reads the new value by the time the event that moved it reaches you.
Two hooks run at the edges of an operation. onStart() fires once an operation holds the queue, before its turn opens, with { kind, id, signal } — and it can refuse the work by throwing, which drops the pending turn and rejects the handle without running anything:
agent.onStart(({ kind, id }) => {
if (shuttingDown) throw new Error("shutting down");
});onSettled() fires once per operation that ran — one send, one call, however it ended: after its turn and its continuation, before its handle settles — handing you the session and exactly what the handle is about to settle with. That's the hook for saving after each operation without awaiting the queue empty the way snapshot() does. The agent awaits your callback, so returning a promise holds the handle and the next queued operation; a callback that throws can't affect the operation. onIdle() fires each time the agent goes from busy to idle, after the last operation's onSettled callbacks — the place to close whatever your host opened when work began. Neither fires for an operation cancelled while still queued: it never ran. See the Agent reference.
One more hook, at a finer grain: onStep() fires at the end of each step inside a turn — one model call and the tools it asked for — however the step ended. The agent waits for your callback before sending the next request, so it's where you save usage and state while the turn is still running instead of once at turn:end. Read agent.session there, not snapshot(). Full shape in the Agent reference.
Reading the conversation
agent.messages; // AxleMessage[] — a copy
agent.context(); // estimated token usage, broken down
agent.sessionId; // stable id, generated if you didn't supply one
agent.system; // readonly getter — configured prompt, then the skills catalog when skills existmessages is a copy, so mutating it does nothing. If you want to change the conversation, that's compaction. It grows as each step ends while a turn runs — an assistant message that asked for tools appears together with its tool results — so code that reads it mid-turn (a tool, an event listener, onStep) sees the finished steps. system is derived — set the prompt at construction; skills append their own section (see Skills).
A send takes options beyond the message. id names the send's user turn — the id its pending:queued preview, its committed turn, and onSettled all carry (generated when omitted, so pass one when an outside system needs to correlate). And two timeouts bound the work: turnTimeoutMs cancels a turn that runs too long — every step, tool call, and deferred wait included — while streamStallMs fails a step whose provider stream goes silent. Both are unset by default, and both can be set on the agent or per send.
Tools and MCP
Supply tools at construction or add them later. MCP servers resolve lazily — their tool lists get fetched on the first send that needs them, once per client.
const agent = new Agent({ provider, model, tools: [a], providerTools: [b] });
agent.addMcp(mcpClient);
agent.hasTools(); // true
agent.registry; // the ToolRegistry, if you want to poke at it
agent.skills; // the SkillRegistry — add/remove/set at any time, lands on the next requesttools takes executable and deferred tools side by side. An executable tool runs through its own execute; a deferred tool's calls go to the handler registered with agent.onToolCall(), one per agent, or wait for agent.toolCall(id) when no branch answers. See Tools and Skills.
Picking up where you left off
const session = agent.session;
// ...later, in a new process
const restored = new Agent(config, session);snapshot() (which waits for the agent to go idle) is deprecated — read session instead. See Sessions & persistence.
Next
- Instruct — when a string isn't enough
- Results & errors — what
send()gives you back - Remote agents — driving an agent served elsewhere
- Agent reference — every option and method