ACP Protocol - Runloop AI Docs

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"]
}

Field	Type	Description
`type`	`string`	Must be `broker_mount`
`axon_id`	`string`	Required. The Axon stream Broker reads from and writes to
`protocol`	`string`	Must be `acp`
`agent_binary`	`string`	Required. Binary to launch for the ACP agent
`launch_args`	`string[]`	Optional. Extra arguments passed to the agent process, such as `["acp"]`

How Broker uses ACP

Broker launches your registered binary with arguments
Your client initializes and sets up the agent for the interaction
Your client starts and initiates the session by publishing ACP session events to the Axon
Broker forwards those messages to your running agent
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.

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"],
  },
});

Initialize and Create Session

Send the ACP initialize and session/new requests to set up the agent:

import { ACPAxonConnection, PROTOCOL_VERSION } from "@runloop/remote-agents-sdk/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: [],
});

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?" }];

Stream Agent Response

Subscribe to the Axon stream and print agent responses:

import {
  isAgentTextChunk,
  isNewSessionEvent,
  isSessionUpdateEvent,
  isTurnCompletedEvent,
} from "@runloop/remote-agents-sdk/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:

Slash commands for triggering agent-specific actions
Agent plans for multi-step structured work
Tool calls for controlled access to files, commands, and other resources

All of these capabilities are fully supported over ACP + Broker. See the ACP specification for complete protocol details.

​Overview

​Getting started

​Broker mount configuration

​How Broker uses ACP

​Send a simple message to an ACP agent

​Cancel a turn

​Handling agent plans and permissions

​Building a complete integration