ACP (Agent Communication Protocol) agents allow integration of external coding agents and AI assistants into the AgentPool pool. These agents run as separate processes and communicate via the ACP protocol.

Overview¶

AgentPool supports integration with many popular coding agents:

Claude Code: Anthropic's Claude-based coding agent
Gemini CLI: Google's Gemini-based coding agent
Codex: OpenAI Codex-based agent
OpenCode: Open-source coding agent
Goose: Block's AI coding assistant
OpenHands: Open-source AI coding agent
FastAgent: Fast and lightweight coding agent
Amp: Sourcegraph's AI coding assistant
Auggie: AI pair programming assistant
Cagent: AI coding agent
Kimi: Moonshot's AI coding agent
Stakpak: AI infrastructure assistant
VTCode: Visual Studio Code AI assistant
Mistral: Mistral AI's coding agent

These agents can be configured to work alongside AgentPool agents, enabling hybrid workflows that leverage specialized external tools.

Configuration Reference¶

Custom ACP Agent Configuration¶

Configuration for a custom ACP agent with explicit command.

Use this for ACP servers that don't have a preset, or when you need full control over the command and arguments.

Example:

agents:
  custom_agent:
    type: acp
    provider: custom
    command: my-acp-server
    args: ["--mode", "coding"]
    cwd: /path/to/project

Custom ACP Agent Configuration (YAML)
agentname:
  provider: custom  # Discriminator for custom ACP agent.
  command: claude-code-acp  # Command to spawn the ACP server.
  args: []  # Arguments to pass to the command.
  type: acp  # Top-level discriminator for agent type.
  cwd: null  # Working directory for the session.
  env_vars: {}  # Environment variables to set.
  tools: []  # Tools and toolsets to expose to this ACP agent via MCP bridge.
  client_execution_environment: null  # Execution environment for handling subprocess requests (filesystem, terminals).
  protocol_version: null  # ACP protocol version to use. Overrides ACP_PROTOCOL_VERSION environment variable if set. If None, us...
  allow_file_operations: true  # Whether to allow file read/write operations.
  allow_terminal: true  # Whether to allow terminal operations.
  auto_approve: false  # If True, automatically approve all permission requests from the remote agent.
  requires_tool_confirmation: per_tool  # How to handle tool confirmation:
  hooks: null  # Hooks for intercepting and customizing agent behavior at key lifecycle points.
  metadata: {}  # Arbitrary metadata for the agent.
  environment: null  # Execution environment config for the agent's own toolsets.
  capabilities: []  # Pydantic-ai capabilities attached to this agent.
  team_mode: null  # Per-agent team mode overlay.
  elicitation_timeout: null  # How long to wait for user elicitation responses before aborting the run.
  lifecycle: null  # Configuration for the RunLoop lifecycle dimensions.
  resources:  # Configuration for unified resource access tools.
    enabled: true  # When True, resource access tools are attached to the agent.
  name: null  # Identifier for the node. Set from dict key, not from YAML.
  display_name: null  # Human-readable display name for the node.
  description: null  # Optional description of the agent / team.
  triggers: []  # Event sources that activate this agent / team
  connections: []  # Targets to forward results to.
  mcp_servers: []  # List of MCP server configurations:
  input_provider: null  # Provider for human-input-handling.
  event_handlers: []  # Event handlers for processing agent stream events.

Registry ACP Agent Configuration¶

Configuration for an ACP agent resolved from the ACP registry.

The agent binary/package is automatically installed and launched based on the registry entry. Supports uvx, npx, and binary distributions.

Example:

agents:
  coder:
    type: acp
    provider: registry
    registry_id: goose
    extra_args: ["--model", "gpt-4o"]
    cwd: /path/to/project

  gemini:
    type: acp
    provider: registry
    registry_id: gemini
    extra_args: ["--experimental-acp", "--model", "gemini-2.5-pro"]

Registry ACP Agent Configuration (YAML)
agentname:
  provider: registry  # Discriminator for registry-based ACP agent.
  registry_id: goose  # Agent ID in the ACP registry (https://agentclientprotocol.com).
  extra_args: []  # Extra CLI arguments appended after the registry-defined command.
  type: acp  # Top-level discriminator for agent type.
  cwd: null  # Working directory for the session.
  env_vars: {}  # Environment variables to set.
  tools: []  # Tools and toolsets to expose to this ACP agent via MCP bridge.
  client_execution_environment: null  # Execution environment for handling subprocess requests (filesystem, terminals).
  protocol_version: null  # ACP protocol version to use. Overrides ACP_PROTOCOL_VERSION environment variable if set. If None, us...
  allow_file_operations: true  # Whether to allow file read/write operations.
  allow_terminal: true  # Whether to allow terminal operations.
  auto_approve: false  # If True, automatically approve all permission requests from the remote agent.
  requires_tool_confirmation: per_tool  # How to handle tool confirmation:
  hooks: null  # Hooks for intercepting and customizing agent behavior at key lifecycle points.
  metadata: {}  # Arbitrary metadata for the agent.
  environment: null  # Execution environment config for the agent's own toolsets.
  capabilities: []  # Pydantic-ai capabilities attached to this agent.
  team_mode: null  # Per-agent team mode overlay.
  elicitation_timeout: null  # How long to wait for user elicitation responses before aborting the run.
  lifecycle: null  # Configuration for the RunLoop lifecycle dimensions.
  resources:  # Configuration for unified resource access tools.
    enabled: true  # When True, resource access tools are attached to the agent.
  name: null  # Identifier for the node. Set from dict key, not from YAML.
  display_name: null  # Human-readable display name for the node.
  description: null  # Optional description of the agent / team.
  triggers: []  # Event sources that activate this agent / team
  connections: []  # Targets to forward results to.
  mcp_servers: []  # List of MCP server configurations:
  input_provider: null  # Provider for human-input-handling.
  event_handlers: []  # Event handlers for processing agent stream events.

Configuration Notes¶

ACP agents run as separate processes managed by AgentPool
Each agent type has specific configuration options for its underlying tool
Model selection depends on what the external agent supports
MCP servers can be attached to capable agents for extended functionality
Environment variables can be used for API keys and secrets
Agents are started on-demand and terminated when the pool closes