Orchestrating CLI Coding Agents#

AG2 can drive external CLI coding agents — Claude Code, Codex, OpenCode, Gemini CLI, and others — as first-class agents, using the Agent Client Protocol (ACP).

AG2 plays the ACP Client role; each CLI agent runs as an ACP Agent subprocess. Everything the agent does — message output, thinking, tool calls, plans, and permission prompts — is externalized onto AG2's event stream, so you can observe, gate, and orchestrate it like any other AG2 agent.

pip install "ag2[acp]"

The integration is a configuration class — a subclass of ACPConfig carrying the launch defaults for each adapter (ClaudeCodeConfig, CodexConfig, OpenCodeConfig) — and there are no changes to the Agent API.

Basic Usage#

1
2
3
4
5
6
7

from autogen import Agent
from autogen.acp import ClaudeCodeConfig

agent = Agent("coder", config=ClaudeCodeConfig(cwd="/path/to/repo"))

reply = await agent.ask("Refactor the auth module and add tests")
print(reply.body)

A single ask()/run() maps to one ACP prompt turn: the CLI agent runs its own internal tool loop and AG2 streams every step as it happens.

Choosing an agent#

Each adapter is a preset with its own launch command and authentication:

1
2
3
4
5

from autogen import Agent
from autogen.acp import ClaudeCodeConfig

# Launches `claude-agent-acp`; auth via ANTHROPIC_API_KEY (env) or CLAUDE_CONFIG_DIR.
agent = Agent("coder", config=ClaudeCodeConfig(cwd="/path/to/repo"))

1
2
3
4
5

from autogen import Agent
from autogen.acp import CodexConfig

# Launches `codex-acp`; auth via CODEX_API_KEY or OPENAI_API_KEY (env).
agent = Agent("coder", config=CodexConfig(cwd="/path/to/repo"))

1
2
3
4
5
6

from autogen import Agent
from autogen.acp import OpenCodeConfig

# Launches `opencode acp`; auth via `opencode auth login` (or env / .env).
# Pick the model in OpenCode's own config (opencode.json: "model": "provider/model").
agent = Agent("coder", config=OpenCodeConfig(cwd="/path/to/repo"))

Observing the agent's work#

Subscribe to the run's stream to see thoughts, tool calls, and plans live:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

from autogen import Agent
from autogen.acp import ClaudeCodeConfig
from autogen.events import ModelMessageChunk, ModelReasoning
from autogen.events.tool_events import BuiltinToolCallEvent
from autogen.acp.events import ACPPlan

agent = Agent("coder", config=ClaudeCodeConfig(cwd="/path/to/repo"))

def observe(event):
    if isinstance(event, ModelReasoning):
        print("💭", event.content)
    elif isinstance(event, ModelMessageChunk):
        print(event.content, end="")
    elif isinstance(event, BuiltinToolCallEvent):
        print(f"🔧 {event.name}({event.arguments})")
    elif isinstance(event, ACPPlan):
        for step in event.entries:
            print(f"  [{step.status}] {step.content}")

async with agent.run("Add a healthcheck endpoint") as run:
    run.stream.subscribe(observe)  # subscribe before driving
    reply = await run.result()

Permissions (Human-in-the-Loop)#

When the agent asks to perform a sensitive action, it sends a permission request. permission_policy controls the response:

1
2
3
4

agent = Agent(
    "coder",
    config=ClaudeCodeConfig(cwd="/repo", permission_policy="auto"),  # autonomous
)

Orchestrating multiple agents#

Because each CLI agent is an Agent, you can compose them — including as tools of one another via .as_tool():

1
2
3
4
5
6
7
8
9

from autogen import Agent
from autogen.acp import ClaudeCodeConfig

reviewer = Agent("reviewer", config=ClaudeCodeConfig(cwd="/repo"))
manager = Agent(
    "manager",
    config=ClaudeCodeConfig(cwd="/repo"),
    tools=[reviewer.as_tool(description="Review the changes for correctness")],
)

Configuration reference#

ACPConfig (and its presets like ClaudeCodeConfig) accept:

File and terminal operations the agent requests are mediated by AG2: file access is confined to fs_root, and the agent's commands run under AG2's control.

Lifecycle#

The ACP subprocess is created on the first turn and reused for the run. Call await config.aclose() to tear down any live subprocesses started from a config (a finalizer terminates them as a safety net if you don't).