> ## 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.

# ACP Protocol

> Use the Agent Client Protocol (ACP) to connect Broker to ACP-compatible agents like OpenCode and Goose

## Overview

ACP is the [Agent Client Protocol](https://agentclientprotocol.com), 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:

* [ACP specification](https://agentclientprotocol.com)
* [ACP TypeScript SDK](https://agentclientprotocol.com/libraries/typescript)

Open source agents that support ACP include
[OpenCode](https://github.com/opencode-ai/opencode) and
[Goose](https://github.com/block/goose).

## Getting started

To try out fully working code examples, check out the [axon-broker-agents example repo](https://github.com/runloopai/runloop-examples/tree/main/axon-broker-agents).

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.

```bash theme={null}
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:

```json theme={null}
{
  "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

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.

<Steps>
  <Step title="Create Devbox with Broker">
    Create an Axon for communication and launch a Devbox with an ACP-compatible agent (OpenCode) mounted via Broker:

    ```typescript theme={null}
    // 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"],
      },
    });
    ```
  </Step>

  <Step title="Initialize and Create Session">
    Send the ACP `initialize` and `session/new` requests to set up the agent:

    ```typescript theme={null}
    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: [],
    });
    ```
  </Step>

  <Step title="Prepare Prompt">
    Prepare the prompt value so you can register timeline listeners before calling `prompt()` in the next step:

    ```typescript theme={null}
    const prompt = [{ type: "text", text: "hi! where are you?" }];
    ```
  </Step>

  <Step title="Stream Agent Response">
    Subscribe to the Axon stream and print agent responses:

    ```typescript theme={null}
    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,
    });
    ```
  </Step>
</Steps>

## Cancel a turn

Often, you'll want to interrupt an in-progress turn or conversation.

```typescript theme={null}
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](https://agentclientprotocol.com/protocol/agent-plan) 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](https://agentclientprotocol.com/protocol/slash-commands)** for triggering agent-specific actions
* **[Agent plans](https://agentclientprotocol.com/protocol/agent-plan)** for multi-step structured work
* **[Tool calls](https://agentclientprotocol.com/protocol/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](https://agentclientprotocol.com) for complete protocol details.