Crate agent_client_protocol

Expand description

§agent-client-protocol – the Agent Client Protocol (ACP) SDK

agent-client-protocol is a Rust SDK for building Agent-Client Protocol (ACP) applications. ACP is a protocol for communication between AI agents and their clients (IDEs, CLIs, etc.), enabling features like tool use, permission requests, and streaming responses.

§What can you build with agent-client-protocol?

Clients that talk to ACP agents (like building your own Claude Code interface)
Proxies that add capabilities to existing agents (like adding custom tools via MCP)
Agents that respond to prompts with AI-powered responses

§Quick Start: Connecting to an Agent

The most common use case is connecting to an existing ACP agent as a client. This example uses stable ACP protocol v1. The draft protocol v2 feature provides a command-only V2Session API and receives updates and interactive requests through typed connection handlers because prompt acceptance and inbound traffic are independent. With both v2 and MCP-over-ACP features, Proxy.v2() supports global MCP attachment, while V2SessionBuilder and V2ResumeSessionBuilder support per-session attachment plus non-blocking proxy setup. With unstable_session_fork, V2ForkSessionBuilder provides the same shape for forked sessions and uses the response’s new session ID. Per-session MCP routes and runners are ready before a setup request is published, as is proxy session routing for resume replay. Successful v2 setup detaches MCP handlers for the connection lifetime; dropping the returned V2Session does not unregister them. In v1, ActiveSession owns per-session MCP registrations until drop, unless a proxy handoff detaches them (proxy_remaining_messages or successful on_proxy_session_start). Global proxy attachments are connection-scoped in both versions.

Here’s a minimal example that initializes a v1 connection, creates a session, and sends a prompt:

use agent_client_protocol::Client;
use agent_client_protocol::schema::{ProtocolVersion, v1::InitializeRequest};

Client.builder()
    .name("my-client")
    .connect_with(transport, async |cx| {
        // Step 1: Initialize the connection
        cx.send_request(InitializeRequest::new(ProtocolVersion::V1))
            .block_task().await?;

        // Step 2: Create a session and send a prompt
        cx.build_session_cwd()?
            .block_task()
            .run_until(async |mut session| {
                session.send_prompt("What is 2 + 2?")?;
                let response = session.read_to_string().await?;
                println!("{}", response);
                Ok(())
            })
            .await
    })
    .await

For a complete working example, see yolo_one_shot_client.rs.

§Cookbook

The agent_client_protocol_cookbook crate contains practical guides and examples:

Connecting as a client
Global MCP server
Per-session MCP server with workspace context
Building agents and reusable components
Running proxies with the conductor

§Cargo Features

No features are enabled by default. Protocol serialization, connections, sessions, custom MCP servers, and the generic transport adapters remain available without opting in to native I/O or JSON Schema generation.

process: native subprocess support through AcpAgent and AcpAgentConfig.
stdio: the native Stdio adapter.
schemars: JsonSchema implementations on protocol types and typed MCP tool helpers in mcp_server.

For example, a native client launching an agent opts into process:

agent-client-protocol = { version = "3", features = ["process"] }

Enable stdio for an agent using Stdio, or schemars for typed MCP tool definitions. LineDirection is available on native targets with either process or stdio; neither feature enables the other.

The agent-client-protocol-rmcp crate explicitly enables schemars for its tool builders. Unstable protocol features remain independent opt-ins. When upgrading from 2.x, explicitly enable every feature your application uses; default-features = false is no longer needed for a lean dependency.

§WebAssembly

The runtime-neutral protocol engine and transport abstractions compile for wasm32-wasip1 and wasm32-wasip2 without additional features. For JavaScript-hosted wasm32-unknown-unknown, enable wasm_js to select Web Crypto through wasm-bindgen as the UUID randomness backend. The target does not imply a JavaScript host, so this feature is not enabled by default; other OS-less WebAssembly hosts must arrange a compatible UUID randomness backend instead.

This crate does not provide a WebAssembly executor or host I/O adapter. The native process and stdio features depend on process spawning and blocking-thread facilities, so their dependencies and exports (including LineDirection) remain excluded on WebAssembly even when enabled.

Embedders provide their own runtime and transport. They can exchange TransportFrame values through Channel, newline-delimited JSON through Lines, or use ByteStreams with futures::io::AsyncRead and AsyncWrite. The embedding runtime must drive the resulting connection future.

§Core Concepts

The concepts module provides detailed explanations of how agent-client-protocol works, including connections, sessions, callbacks, ordering guarantees, and more.

agent-client-protocol-conductor - Binary for running proxy chains

Re-exports§

pub use jsonrpc::Builder;
pub use jsonrpc::ByteStreams;
pub use jsonrpc::Channel;
pub use jsonrpc::ConnectionTo;
pub use jsonrpc::Dispatch;
pub use jsonrpc::DynamicHandlerGuard;
pub use jsonrpc::HandleConnectionClose;
pub use jsonrpc::HandleDispatchFrom;
pub use jsonrpc::Handled;
pub use jsonrpc::INCOMING_TRANSPORT_CLOSED_REASON;
pub use jsonrpc::IntoHandled;
pub use jsonrpc::JsonRpcMessage;
pub use jsonrpc::JsonRpcNotification;
pub use jsonrpc::JsonRpcRequest;
pub use jsonrpc::JsonRpcResponse;
pub use jsonrpc::Lines;
pub use jsonrpc::NullClose;
pub use jsonrpc::NullHandler;
pub use jsonrpc::PreparedRequest;
pub use jsonrpc::RawJsonRpcError;
pub use jsonrpc::RawJsonRpcMessage;
pub use jsonrpc::RawJsonRpcParams;
pub use jsonrpc::RawJsonRpcResponse;
pub use jsonrpc::Responder;
pub use jsonrpc::ResponseRouter;
pub use jsonrpc::SentRequest;
pub use jsonrpc::TransportBatch;
pub use jsonrpc::TransportBatchEntry;
pub use jsonrpc::TransportFrame;
pub use jsonrpc::UntypedMessage;
pub use jsonrpc::is_incoming_transport_closed;
pub use jsonrpc::run::ChainRun;
pub use jsonrpc::run::NullRun;
pub use jsonrpc::run::RunWithConnectionTo;
pub use jsonrpc::V2Builder;unstable_protocol_v2
pub use jsonrpc::V2ConnectionTo;unstable_protocol_v2
pub use role::acp::AgentProtocolRouter;unstable_protocol_v2
pub use role::acp::ClientProtocolConnector;unstable_protocol_v2
pub use role::acp::ProxyProtocolRouter;unstable_protocol_v2
pub use role::Role;
pub use role::RoleId;
pub use role::UntypedRole;
pub use role::acp::Agent;
pub use role::acp::Client;
pub use role::acp::Conductor;
pub use role::acp::Proxy;
pub use component::ConnectTo;
pub use component::ConnectionDriver;
pub use component::DynConnectTo;

Modules§

component: Component abstraction for agents and proxies ConnectTo abstraction for agents and proxies.
concepts: Core concepts for understanding and using agent-client-protocol Core concepts for understanding and using agent-client-protocol.
mcp_server: Runtime-agnostic MCP server support, including optional attachment to ACP sessions. Runtime-agnostic MCP server support.
role: Role types for ACP connections Role types for ACP connections.
schema: ACP protocol schema types - all message types, requests, responses, and supporting types ACP protocol schema types and message implementations.
util: Utility functions and types

Macros§

on_receive_dispatch: This macro is used for the value of the to_future_hack parameter of Builder::on_receive_dispatch and Builder::on_receive_dispatch_from.
on_receive_notification: This macro is used for the value of the to_future_hack parameter of Builder::on_receive_notification and Builder::on_receive_notification_from.
on_receive_request: This macro is used for the value of the to_future_hack parameter of Builder::on_receive_request and Builder::on_receive_request_from.
tool_fn: This is a hack that must be given as the final argument of the MCP server builder’s tool_fn method when defining stateless concurrent tools.
tool_fn_mut: This is a hack that must be given as the final argument of the MCP server builder’s tool_fn_mut method when defining tools.

Structs§

AcpAgentprocess and non-target_family=wasm: A component representing an external ACP agent running in a separate process.
AcpAgentConfigprocess and non-target_family=wasm: Configuration for launching an ACP agent subprocess.
ActiveSession: Stable protocol v1 active session that lets you send prompts and receive updates.
Blocking: Marker type indicating the session builder will block the current task.
Builder: A JSON-RPC connection that can act as either a server, client, or both.
ByteStreams: A component that communicates over byte streams (stdin/stdout, sockets, pipes, etc.).
ChainRun: Chains two RunIn implementations to run in parallel.
Channel: A channel endpoint representing one side of a bidirectional JSON-RPC transport.
ConnectionTo: Connection context for sending messages and spawning tasks.
DynamicHandlerGuard: A guard that keeps a dynamic message handler registered.
Error: JSON-RPC error object.
Lines: A component that communicates over line streams.
NonBlocking: Marker type indicating the session builder will not block the current task.
NullClose: A close handler that does nothing.
NullHandler: Null handler that accepts no messages.
NullRun: A no-op RunIn that completes immediately.
OpenedV2Sessionunstable_protocol_v2: A newly available protocol v2 session and its operation-specific response.
PreparedRequest: A request that has not been published to its connection.
RawJsonRpcError: A JSON-RPC error without ACP-specific interpretation.
RequestCancellation: A request-local marker that is set when the peer asks to cancel the request.
Responder: The context to respond to an incoming request.
ResponseRouter: Context for handling an incoming JSON-RPC response.
RestoreSessionBuilder: Stable protocol v1 builder for session/load or session/resume.
RestoredSession: A restored stable-v1 session and the exact operation response that opened it.
SentRequest: Represents a pending response of type R from an outgoing request.
SessionBuilder: Stable protocol v1 session builder for a new session request. Allows you to add MCP servers or set other details for this session.
Stdiostdio and non-target_family=wasm: A transport that connects to an ACP peer via standard input/output.
TransportBatch: A structurally non-empty JSON-RPC batch retained across framed relays.
UntypedMessage: An incoming JSON message without any typing. Can be a request or a notification.
V2ConnectionTounstable_protocol_v2: A protocol-v2 connection context.
V2ForkSessionBuilderunstable_protocol_v2 and unstable_session_fork: Builder for an unstable draft protocol v2 session/fork request.
V2ResumeSessionBuilderunstable_protocol_v2: Builder for a draft protocol v2 session/resume request.
V2Sessionunstable_protocol_v2: Cloneable command handle for a draft protocol v2 session.
V2SessionBuilderunstable_protocol_v2: Builder for a draft protocol v2 session/new request.

Enums§

Dispatch: An incoming request, notification, or response being dispatched through handlers. Requests include the context used to answer them; responses include the context used to route them to the local requester.
ErrorCode: Predefined error codes for common JSON-RPC and ACP-specific errors.
Handled: Return type from JrHandler; indicates whether the request was handled or not.
LineDirection(process or stdio) and non-target_family=wasm: Direction of a line being sent or received by a native transport.
RawJsonRpcMessage: One valid JSON-RPC message carried inside a TransportFrame.
RawJsonRpcParams: Raw JSON-RPC request or notification parameters.
SessionMessage: Incoming stable protocol v1 message from the agent.
TransportBatchEntry: One entry in a TransportBatch.
TransportFrame: A JSON-RPC frame exchanged between protocol components and transports.

Constants§

INCOMING_TRANSPORT_CLOSED_REASON: Stable discriminator stored in the data.reason field of errors produced when the incoming transport reaches clean EOF before a request receives its response.

Traits§

HandleConnectionClose: A handler that runs after the incoming transport reaches clean EOF.
HandleDispatchFrom: Handlers process incoming JSON-RPC messages on a connection.
IntoHandled: Trait for converting handler return values into Handled.
JsonRpcMessage: Common bounds for any JSON-RPC message.
JsonRpcNotification: A struct that represents a notification (JSON-RPC message that does not expect a response).
JsonRpcRequest: A struct that represents a request (JSON-RPC message expecting a response).
JsonRpcResponse: Defines the “payload” of a successful response to a JSON-RPC request.
MetaCapability: Trait for capabilities stored in the _meta.symposium object.
MetaCapabilityExt: Extension trait for checking and modifying capabilities in InitializeRequest.
RunWithConnectionTo: A background task that runs alongside a connection.
SessionBlockState: Trait for marker types that indicate blocking vs non-blocking API. See SessionBuilder::block_task.

Functions§

is_cancel_request_notification: Whether a notification is a $/cancel_request, even when it is still wrapped in _proxy/successor envelopes.
is_incoming_transport_closed: Return whether error reports that the incoming transport reached clean EOF before a request received its response.

Type Aliases§

BoxFuturealloc: An owned dynamically typed Future for use in cases where you can’t statically type your result or need to add some indirection.
RawJsonRpcResponse: A transport-level JSON-RPC response with an opaque result or raw error.
Result: Convenience result type using this protocol version’s error type.
V2Builderunstable_protocol_v2: A JSON-RPC connection builder whose callbacks receive V2ConnectionTo.

Derive Macros§

JsonRpcNotification: Derive macro for implementing JsonRpcNotification and JsonRpcMessage traits.
JsonRpcRequest: Derive macro for implementing JsonRpcRequest and JsonRpcMessage traits.
JsonRpcResponse: Derive macro for implementing JsonRpcResponse trait.