Remote agents over HTTP
Remote agents explains the pieces and shows the whole thing over loopbackTransport, in one process. This is the HTTP version: two routes on the server, a client that folds the stream, and the reconnect that makes a dropped Wi-Fi connection a non-event.
Experimental
Remote agents are under active design and may change in any release.
The shape to keep in mind: commands go in over POST, everything else comes back out over one GET stream. The client never asks for state — it reads the events.
One agent, two routes
The server owns the agents: it builds them from the provider key and the tools whose execute only works there, and keeps an InMemoryEventStore beside each one.
import { Agent, InMemoryEventStore, toEventStreamResponse, parseAgentCommand } from "@fifthrevision/axle";
type Served = { agent: Agent; store: InMemoryEventStore };
const live = new Map<string, Served>();
const ended = new Set<string>();
function serve(sessionId: string): Served {
const agent = new Agent({ provider, model, tools: [askUser] });
const served = { agent, store: new InMemoryEventStore(agent) };
live.set(sessionId, served);
return served;
}Both routes sit on the same URL — that's what httpTransport expects — and differ only by method:
async function handle(request: Request, sessionId: string): Promise<Response> {
if (ended.has(sessionId)) return new Response("Agent ended", { status: 410 });
const served = live.get(sessionId);
if (!served) return new Response("No such agent", { status: 404 });
if (request.method === "GET") {
const after = request.headers.get("last-event-id");
const subscription = served.store.subscribe(request.signal, after);
return toEventStreamResponse(subscription, request);
}
if (request.method === "POST") {
const command = parseAgentCommand(await request.json());
if (!command) return new Response("Unrecognized command", { status: 400 });
const outcome = await runCommand(served.agent, command);
return new Response(JSON.stringify(outcome), {
headers: { "content-type": "application/json" },
});
}
return new Response("Method not allowed", { status: 405 });
}Three things in there are load-bearing:
last-event-idis the resume cursor. The client sets that header — on its first connection when you gavehttpTransportanafter, and on every reconnect with the last cursor it actually received. Pass it straight tosubscribe, which replays what the consumer missed and then goes live.request.headers.get()returnsstring | null, which is exactly whatsubscribetakes.request.signalends the subscription when the client disconnects, so a closed tab doesn't leave a subscriber behind.404and410are terminal. The client stops and rejects every openfinalon either, rather than retrying. Anything5xxit will retry, which is what you want mid-deploy — so don't answer a dead agent with a500.
The command switch
parseAgentCommand hands you a typed AgentCommand; turning it into Agent calls is yours, because only the server knows how to find the agent:
import { Instruct, type AgentCommand, type CommandOutcome } from "@fifthrevision/axle";
const accepted: CommandOutcome = { accepted: true };
const notWaiting = (callId: string): CommandOutcome => ({
accepted: false,
reason: { type: "not-waiting", message: `No waiting call ${callId}` },
});
async function runCommand(agent: Agent, command: AgentCommand): Promise<CommandOutcome> {
switch (command.type) {
case "send": {
const handle = agent.send(Instruct.fromJSON(command.instruct), { id: command.id });
handle.final.catch(() => {}); // the result reaches the client as events
return accepted;
}
case "answer": {
const call = agent.toolCall(command.callId);
if (!call) return notWaiting(command.callId);
await call.answer(command.content);
return accepted;
}
case "fail": {
const call = agent.toolCall(command.callId);
if (!call) return notWaiting(command.callId);
await call.fail(command.message);
return accepted;
}
case "cancel":
case "stop": {
const took = command.type === "cancel" ? agent.cancel() : agent.stop();
return took
? accepted
: { accepted: false, reason: { type: "idle", message: "No active turn" } };
}
case "clear":
agent.clear();
return accepted;
}
}Note the handle.final.catch(() => {}). The response to a send says only whether the agent took it; the turn, the answer and any failure travel as events. Without that catch, a send that fails takes down the process with an unhandled rejection — the client is reading the outcome, nobody is awaiting the handle.
The client
import { RemoteAgent, Transcript, httpTransport, isCall } from "@fifthrevision/axle";
declare function setOffline(offline: boolean): void;
const remoteAgent = new RemoteAgent(httpTransport(`/agents/${sessionId}`));
const transcript = new Transcript();
remoteAgent.on((event) => transcript.apply(event));
remoteAgent.onConnection((connection) => setOffline(connection.phase !== "open"));
remoteAgent.onToolCall((call) => {
if (!isCall(askUser, call)) return;
return prompt(call.input.question);
});
const result = await remoteAgent.send("Summarize today's incidents.").final;That is the same code you'd write against a local Agent, with three differences worth planning for:
- A remote send's handle has
finaland nothing else. There is nohandle.cancel(), because a queued send can't be cancelled by id across a wire. UseremoteAgent.cancel(),stop()orclear()— each posts one command and resolvestruewhen the served agent took it,falsewhen the switch answeredaccepted: false(nothing running, in the case of a cancel). - A remote
onToolCallhandler gets noToolContext. Noemitfor progress, nosignal; cancellation shows up in the events instead. - The agent's work is not your connection.
remoteAgent.statusis the served agent's idle/busy;remoteAgent.connectionis the link. A spinner driven by the wrong one lies to the user — see Status and connection are separate.
Resuming after a drop
Every event carries a cursor and every turn keeps the one it was folded from, so the thing you persist for resume is already in your transcript:
const resumed = new RemoteAgent(
httpTransport(`/agents/${sessionId}`, { after: saved.turns.at(-1)?.cursor }),
);Reconnects inside a live RemoteAgent need nothing from you: the transport reopens with the last cursor it delivered, waiting reconnectDelayMs and doubling up to maxReconnectDelayMs, for as long as it takes. after is for the first connection — a reload, a second device, a client that was away long enough to be restarted.
A cursor the store doesn't recognize replays everything rather than nothing, which is the safe direction: a client that resumes against a restarted server rebuilds its transcript instead of silently missing the middle.
Ending an agent
The server decides when an agent is over. Close the store so open streams finish what they hold, then answer that URL with 410:
function end(sessionId: string): void {
const served = live.get(sessionId);
served?.store.close();
live.delete(sessionId);
ended.add(sessionId);
}On the client that ends the RemoteAgent: the connection goes to ended and every open final rejects. remoteAgent.close() is the same ending chosen from the other side — it stops listening and leaves the served agent alone.
Auth
headers is sent with every request, and a function is called per request, so a token that expires mid-stream is a one-liner:
declare function freshToken(): Promise<string>;
const authed = httpTransport(url, {
headers: async () => ({ authorization: `Bearer ${await freshToken()}` }),
});Each reconnect calls it again, which is what makes a long-lived stream survive a rotation.
Keeping the browser bundle clean
Import the client half from @fifthrevision/axle/ui:
import { RemoteAgent, Transcript, httpTransport, isCall } from "@fifthrevision/axle/ui";RemoteAgent, httpTransport, Transcript and the narrowing helpers all live there, and that entry point depends only on chalk, marked and zod — no provider SDKs. The browser never had the key anyway; now it doesn't have the SDKs either.
See also
- Remote agents — the pieces, and the loopback version
- Remote agents reference — every method, transport and wire type
- Streaming to a UI — rendering the stream you receive
- Tools — the deferred calls a client answers