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 attachments remain active for the connection lifetime.

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

§WASI

The runtime-neutral protocol engine and transport abstractions compile for wasm32-wasip1 and wasm32-wasip2. This crate does not provide a WASI executor or host I/O adapter. The native AcpAgent and Stdio implementations depend on process spawning and blocking-thread facilities, so they and LineDirection are not exported on these targets.

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 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::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§

AcpAgentNon-target_family=wasm: A component representing an external ACP agent running in a separate process.
AcpAgentConfigNon-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.
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.
StdioNon-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.
LineDirectionNon-target_family=wasm: Direction of a line being sent or received.
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.
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.