ACP (Agent Client Protocol)

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

Overview

The cagent 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 cagent’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
$ cagent acp ./agent.yaml

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

# From the agent catalog
$ cagent acp agentcatalog/pirate

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

How It Works

1. The host application spawns cagent acp agent.yaml as a child process
2. Communication happens over stdin/stdout using the ACP protocol
3. The host sends user messages, cagent 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: cagent 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 cagent 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

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

Integration Example

A host application would spawn cagent as a subprocess and communicate via the ACP protocol:

// Pseudocode for an IDE extension
const child = spawn("cagent", ["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.
});