Overview
Broker sits between an Axon and an agent process running inside a Devbox. The Axon is the system of record and Broker is the bridge that turns stream events into serialized agent work. Axon records and sequences events. Broker turns those events into agent turns. Its job is to:- receive user and external events from the Axon stream
- forward them to the agent through the configured protocol adapter
- publish agent output back to the same Axon stream
- enforce serial turn execution so only one turn runs at a time
Event Flow
Broker owns the turn lifecycle:- It reads inbound events from Axon.
- It starts a turn when it receives a user or external event.
- While that turn is running, additional inbound turn-starting events are queued.
- It publishes turn output back into Axon as structured events.
- When the turn completes, it moves back to idle and processes the next queued event.
Responsibilities
Message Forwarding
Broker consumes inbound events such asuser.message from Axon and forwards them to the attached agent.
Turn Serialization
Broker enforces one active turn at a time. This prevents overlapping agent turns and gives downstream consumers a clear ordered stream of turn output.Event Publishing
Broker republishes agent and turn lifecycle output back into Axon so clients can subscribe to the same stream they published into. Common outbound events include:| Event Type | Origin | Description |
|---|---|---|
turn.started | SYSTEM_EVENT | A new turn has begun |
turn.message_chunk | AGENT_EVENT | Incremental agent text output |
turn.tool_call | SYSTEM_EVENT | A tool call started |
turn.tool_call_update | SYSTEM_EVENT | Tool call progress or result update |
turn.completed | SYSTEM_EVENT | The turn ended normally |
turn.cancelled | SYSTEM_EVENT | The turn was cancelled |
turn.failed | SYSTEM_EVENT | The turn ended with a failure condition |
Loop Prevention
Broker ignores agent- and system-originated events when reading from Axon so it does not re-consume its own output.Protocol Forwarding
Broker is protocol-agnostic. It launches agent binaries, understands each protocol to manage turn lifecycle, and forwards protocol-specific messages between the Axon stream and the agent process. Events published to and from Axon remain protocol-specific—Broker does not normalize them into a common schema. Clients should send and receive events in the format defined by the agent’s protocol.Supported Protocols
Runloop currently supports the following Broker protocols:acpfor agents that implement the Agent Client Protocol over stdin/stdoutclaude_jsonfor Claude Code CLI in streaming JSON Lines modecodex_app_serverfor Codex CLI in app-server mode over JSON-RPC
The choice of protocol is independent of the agent binary. Broker uses the configured protocol adapter to translate between Axon events and the agent process.
broker_mount on your Devbox to select the protocol adapter and attach Broker to an Axon stream.
Related Documentation
- Axons Overview — Learn how Axons sequence and expose event streams
- Devbox Overview — Learn where agents and Broker run
- Agent Gateways — Securely proxy outbound API requests from a devbox