Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runloop.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

ACP is the Agent Client Protocol, a JSON-RPC based protocol for communication between clients and AI coding agents. When using Broker with the ACP protocol, Broker will launch your agent binary and exchange bidirectional JSON-RPC messages over stdin / stdout. For the full specification and official TypeScript SDK: Open source agents that support ACP include OpenCode and Goose.

​
Getting started

To try out fully working code examples, check out the axon-broker-agents example repo. Clone the repo and run the test commands. The example will create a Devbox with OpenCode and start a “hello world” conversation by publishing an Axon event. 
git clone https://github.com/runloopai/runloop-examples \
  && cd runloop-examples/axon-broker-agents \
  && bun install \
  && bun run axon_acp_docs.ts

​
Broker mount configuration

Create a Devbox with a broker_mount to bind an Axon stream to the ACP adapter: 
{
  "type": "broker_mount",
  "axon_id": "<axon-id>",
  "protocol": "acp",
  "agent_binary": "opencode",
  "launch_args": ["acp"]
}
FieldTypeDescription
typestringMust be broker_mount
axon_idstringRequired. The Axon stream Broker reads from and writes to
protocolstringMust be acp
agent_binarystringRequired. Binary to launch for the ACP agent
launch_argsstring[]Optional. Extra arguments passed to the agent process, such as ["acp"]

​
How Broker uses ACP

  1. Broker launches your registered binary with arguments
  2. Your client initializes and sets up the agent for the interaction
  3. Your client starts and initiates the session by publishing ACP session events to the Axon
  4. Broker forwards those messages to your running agent
  5. Agent output streams back through Axon as <update_type> events

​
Send a simple message to an ACP agent

Create a Devbox with an ACP Broker mount and send a ‘hello world’ message to the agent.
1

Create Devbox with Broker

Create an Axon for communication and launch a Devbox with an ACP-compatible agent (OpenCode) mounted via Broker:
// Create Axon for agent communication
const axon = await sdk.axon.create({ name: "acp-tutorial-axon" });

// Create a Devbox with an ACP-compliant agent, OpenCode
const devbox = await sdk.devbox.create({
  name: "acp-tutorial-opencode-devbox",
  mounts: [
    {
      type: "broker_mount",
      axon_id: axon.id,
      protocol: "acp",
      agent_binary: "opencode",
      launch_args: ["acp"],
    },
  ],
  launch_parameters: {
    launch_commands: ["npm i -g opencode-ai"],
  },
});
2

Initialize and Create Session

Send the ACP initialize and session/new requests to set up the agent:
import { ACPAxonConnection, PROTOCOL_VERSION } from "@runloop/agent-axon-client/acp";

const conn = new ACPAxonConnection(axon, devbox);

await conn.connect();
await conn.initialize({
  protocolVersion: PROTOCOL_VERSION,
  clientInfo: { name: "agentflow", version: "1.0.0" },
});

const session = await conn.newSession({
  cwd: "/home/user",
  mcpServers: [],
});
3

Prepare Prompt

Prepare the prompt value so you can register timeline listeners before calling prompt() in the next step:
const prompt = [{ type: "text", text: "hi! where are you?" }];
4

Stream Agent Response

Subscribe to the Axon stream and print agent responses:
import {
  isAgentTextChunk,
  isNewSessionEvent,
  isSessionUpdateEvent,
  isTurnCompletedEvent,
} from "@runloop/agent-axon-client/acp";

conn.onTimelineEvent((event) => {
  if (isNewSessionEvent(event) && event.axonEvent.origin === "AGENT_EVENT") {
    console.log(`Session ready: ${event.data.sessionId}`);
  }

  if (isSessionUpdateEvent(event) && isAgentTextChunk(event.data.update)) {
    process.stdout.write(event.data.update.content.text);
  }

  if (isTurnCompletedEvent(event)) {
    console.log("\nTurn complete");
  }
});

await conn.prompt({
  sessionId: session.sessionId,
  prompt,
});

​
Cancel a turn

Often, you’ll want to interrupt an in-progress turn or conversation. 
await axon.publish({
  event_type: "session/cancel",
  origin: "USER_EVENT",
  source: "axon_acp",
  payload: JSON.stringify({
    sessionId,
  }),
});

​
Handling agent plans and permissions

ACP agents can propose plans for structured, multi-step work. Agents also request permissions for actions like file access or command execution. Currently, Broker automatically accepts all ACP permission requests, allowing agents to proceed with their planned operations.

​
Building a complete integration

The examples above cover the basics of launching an ACP agent and exchanging messages. To build a production-ready integration, you should become familiar with the full ACP state machine — understanding how sessions transition between states like idle, working, and completed will help you handle edge cases and build reliable orchestration logic. ACP also supports advanced features beyond simple prompting, including: All of these capabilities are fully supported over ACP + Broker. See the ACP specification for complete protocol details.