ACP (Agent Client Protocol)

Expose docker-agent agents via the Agent Client Protocol for integration with ACP-compatible hosts like VS Code, IDEs, and other developer tools.

Overview

The docker agent serve acp command starts an ACP server that communicates over stdio (standard input/output). This makes it ideal for integration with editors, IDEs, and other tools that spawn agent processes — the host sends JSON-RPC messages to docker-agent’s stdin and reads responses from stdout.

ACP is built on the ACP Go SDK and provides a standardized way for client applications to interact with AI agents.

Usage

# Start ACP server on stdio
$ docker agent serve acp ./agent.yaml

# With a multi-agent team config
$ docker agent serve acp ./team.yaml

# From the agent catalog
$ docker agent serve acp agentcatalog/pirate

# With a custom session database
$ docker agent serve acp ./agent.yaml --session-db ./my-sessions.db

How It Works

1. The host application spawns docker agent serve acp agent.yaml as a child process
2. Communication happens over stdin/stdout using the ACP protocol
3. The host sends user messages, docker-agent processes them through the agent
4. Agent responses, tool calls, and events stream back to the host
5. Sessions are persisted in a SQLite database for continuity

# Conceptual flow:
Host Application
  └── spawns: docker agent serve acp agent.yaml
        ├── stdin  ← JSON-RPC requests from host
        └── stdout → JSON-RPC responses to host

Features

• Stdio transport — No network ports needed; ideal for subprocess integration
• Session persistence — SQLite-backed sessions survive process restarts
• Full agent support — All docker-agent features work: tools, multi-agent, model fallbacks
• Multi-agent configs — Team configurations with sub-agents work transparently
• Filesystem operations — Agents can read/write files relative to the host’s working directory

CLI Flags

docker agent serve acp <agent-file>|<registry-ref> [flags]

Integration Example

A host application would spawn docker-agent as a subprocess and communicate via the ACP protocol:

// Pseudocode for an IDE extension
const child = spawn("docker", ["agent", "serve", "acp", "./agent.yaml"]);

// Send a message to the agent
child.stdin.write(
  JSON.stringify({
    jsonrpc: "2.0",
    method: "agent/run",
    params: { message: "Explain this code" },
  }),
);

// Read responses
child.stdout.on("data", (data) => {
  const response = JSON.parse(data);
  // Handle agent response, tool calls, etc.
});