agent-client-protocol

agent-client-protocol is the reference Rust implementation of ACP, a protocol that standardizes how code editors and AI coding agents talk to each other over JSON-RPC. Rather than every editor integrating against every agent’s bespoke API, both sides implement ACP once: editors become ACP clients, agents implement the ACP agent role, and the two can be paired freely. The core crate ships typed roles for Client, Agent, Proxy, and Conductor, a connection builder with async handler registration, and the full set of ACP protocol schema types.

Beyond the base protocol, the workspace includes crates for HTTP/SSE and WebSocket transports, an MCP integration built on rmcp so agents can expose Model Context Protocol tools over ACP, and a conductor binary that chains proxy components between an editor and an agent without touching the agent’s own code. A draft protocol v2 API is available behind feature flags for teams that want session forking, MCP-over-ACP attachment, and other in-progress capabilities ahead of stabilization.

What You Get

• Typed Client, Agent, Proxy, and Conductor roles with builder APIs for constructing ACP connections
• A JSON-RPC connection engine with request/response routing, notifications, batching, and cancellation support
• Full ACP protocol schema types for sessions, prompts, tool calls, and permission requests
• Pluggable transports — stdio for local process pairs, plus HTTP/SSE and WebSocket via the companion agent-client-protocol-http crate
• An MCP integration (agent-client-protocol-rmcp) for exposing Model Context Protocol tools to agents over ACP
• A conductor crate and binary for chaining multiple proxy components between an editor and an agent
• Draft protocol v2 support (feature-gated) for session forking and global or per-session MCP server attachment

Common Use Cases

• Building an editor-side ACP client so an IDE or CLI can talk to any ACP-compatible coding agent
• Implementing a new coding agent that exposes itself over ACP instead of a bespoke API
• Writing a proxy that injects extra tools or context into an existing agent via MCP-over-ACP, without modifying the agent
• Chaining several proxies together with the conductor to compose capabilities between an editor and an agent
• Adding WebSocket or HTTP/SSE transport to an ACP integration that started over stdio

Under The Hood

Architecture The crate is organized around a Role trait (src/role.rs) that fixes each endpoint’s counterpart at the type level — Client pairs with Agent, Proxy pairs with Conductor — so a connection can only be built between compatible roles. A Builder<Role> (in the jsonrpc module) accumulates typed request/notification/dispatch handlers and produces a ConnectionContext that drives the actual JSON-RPC exchange over a Channel, Lines, or raw ByteStreams transport, keeping the wire protocol decoupled from any specific I/O source. Sessions layer on top of connections (src/session.rs, src/session/v2.rs) as the unit of a prompt/response exchange, with a separate mcp_server module handling MCP tool registration and dispatch for agents and proxies that need to surface tools. Swapping the core JSON-RPC engine would ripple through every role and the schema macros that wire request/response types to it, but transports and the MCP layer are cleanly pluggable behind their own traits.

Tech Stack The workspace targets Rust 2024 edition on a 1.88 MSRV and is built on futures/futures-concurrency for async orchestration rather than committing to a single runtime, with tokio pulled in for concrete executors and process I/O. Protocol types are generated from agent-client-protocol-schema and implemented with serde/serde_json (order-preserving, raw-value features enabled) plus schemars for JSON Schema derivation; agent-client-protocol-derive supplies the #[derive(JsonRpcRequest/Response/Notification)] macros used throughout. HTTP/WebSocket transports use axum, reqwest, async-tungstenite, and eventsource-stream; the MCP bridge depends on rmcp. uuid, rustc-hash, tracing, and thiserror/anyhow round out the core dependency set, and the whole thing compiles for wasm32-wasip1/wasip2 in addition to native targets.

Code Quality The core crate enforces #![deny(missing_docs)], and rustdoc comments are extensive and dense throughout the source, including a dedicated concepts module that documents connection, session, ordering, and cancellation semantics in prose rather than leaving them implicit. Testing is thorough: dozens of integration test files cover JSON-RPC edge cases, batching, cancellation, deep proxy chains, transport close behavior, protocol v2, and derive-macro output, run through cargo test in CI alongside cargo deny for dependency/license auditing (deny.toml) and a typo checker (typos.toml). Error handling favors typed Result/Error values over unwrap(), which appears only sparingly outside test code, consistent with a library meant to be embedded in long-running editor and agent processes.

API Design The public API leans on builder chains (Client.builder().name(...).connect_with(...)) and typed session handles rather than raw JSON-RPC calls, so integrators work with InitializeRequest, build_session_cwd(), and send_prompt() instead of hand-rolled method strings and payloads. Stable v1 and draft v2 entry points are kept side by side (.builder() vs .v2()) so adopters can move to newer protocol capabilities without a hard cutover, and the crate ships runnable examples for both a simple agent and a one-shot client, plus a separate cookbook crate of rendered rustdoc patterns for common integration shapes.