ACP: The Agent Client Protocol

The problem: a harness that feels external

Before ACP, driving a CLI harness meant the marker protocol: hand it one giant text prompt, let it run, and parse tool-call markers back out of its raw output — re-spawning the whole process for every round. That works, but it makes the agent feel like something outside the platform: it reads a document and hands back a document, rather than acting inside a live session, and a quiet or one-shot mode shows no live thinking at all while it works.

What ACP actually fixes

The Agent Client Protocol lets a harness run one continuous agentic loop instead of being re-spawned per round: it calls real tools mounted over MCP directly, and streams session/update notifications — thinking, tool calls, answer deltas — continuously as it works. The difference is architectural, not cosmetic: a marker-protocol harness is driven like a batch job; an ACP harness is driven like a live session you can watch.

The wire format, concretely

ACP is newline-delimited JSON-RPC 2.0 over stdio (verified against hermes acp v0.16.0). The flow is fixed and simple: initialize → session/new (with the working directory and MCP servers to mount) → session/prompt (the actual ask) → a stream of session/update notifications while the harness works → a final result carrying the stop reason. The harness can also call back into the client mid-turn — a permission request, a filesystem operation — and the client answers those inline, so an autonomous, tool-using turn never sits blocked waiting on a TTY prompt that nothing is watching.

Who speaks it in Agentis today — two adapters, not one

Two Agentis adapters drive a real ACP connection today: HermesAgentAdapter against Hermes's own acp mode, and OpenClawAdapter against OpenClaw's official ACP CLI server (openclaw acp) — OpenClaw's chat surface is ACP, so it's the stable integration boundary rather than one option among several. Both share the same client and the same wire mechanics described above; OpenClaw's variant additionally owns its own remote tool loop, so Agentis streams its ACP activity rather than re-running those tools locally.

ACP itself is a real, named protocol outside Agentis, not something invented for this platform — and industry-wide, editor-grade harnesses beyond Hermes and OpenClaw are adopting it as the standard way to expose a streaming, tool-using turn. That's a claim about the protocol's own adoption, not a claim that every Agentis adapter speaks it: ClaudeCodeAdapter, CodexAdapter, CursorAdapter, and AntigravityAdapter use their own native protocols today, not ACP.

Why the client is harness-agnostic anyway

The Agentis-side client is deliberately transport-only: it drives the JSON-RPC conversation and hands normalized updates upward, while each adapter maps those updates onto Agentis's own normalized chat-delta shape. That split is what makes wiring up a third ACP-speaking harness, if one arrives later, a mapping exercise against an already-working client — not a new transport to build from scratch.

Continue