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. Here’s a minimal example that initializes a connection, creates a session, and sends a prompt:

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

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

§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-tokio - Tokio utilities for spawning agent processes
agent-client-protocol-conductor - Binary for running proxy chains

Re-exports§

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.
cookbook: Cookbook of common patterns for building ACP components Cookbook of common patterns for building ACP components.
handler: JSON-RPC handler types for building custom message handlers Handler types for building custom JSON-RPC message handlers.
jsonrpcmsg: JSON-RPC message types.
mcp_server: MCP server support for providing MCP tools over ACP MCP server support for providing MCP tools over ACP.
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 McpServerBuilder::tool_fn when defining stateless concurrent tools. See tool_fn_mut! for the gory details.
tool_fn_mut: This is a hack that must be given as the final argument of McpServerBuilder::tool_fn when defining tools. Look away, lest ye be blinded by its vileness!

Structs§

ActiveSession: Active session struct 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 message channel.
ConnectionTo: Connection context for sending messages and spawning tasks.
Error: JSON-RPC error object.
Lines: A component that communicates over line streams.
McpAcpTransport: The mcp_acp_transport capability - indicates support for MCP-over-ACP bridging.
NonBlocking: Marker type indicating the session builder will not block the current task.
NullHandler: Null handler that accepts no messages.
NullRun: A no-op RunIn that completes immediately.
Responder: The context to respond to an incoming request.
ResponseRouter: Context for handling an incoming JSON-RPC response.
SentRequest: Represents a pending response of type R from an outgoing request.
SessionBuilder: Session builder for a new session request. Allows you to add MCP servers or set other details for this session.
UntypedMessage: An incoming JSON message without any typing. Can be a request or a notification.

Enums§

AgentNotification: All possible notifications that an agent can send to a client.
AgentRequest: All possible requests that an agent can send to a client.
AgentResponse: All possible responses that an agent can send to a client.
ClientNotification: All possible notifications that a client can send to an agent.
ClientRequest: All possible requests that a client can send to an agent.
ClientResponse: All possible responses that a client can send to an agent.
Dispatch: An enum capturing an in-flight request or notification. In the case of a request, also includes the context used to respond to the request.
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.
SessionMessage: Incoming message from the agent

Traits§

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 blocking API. See SessionBuilder::block_task.

Type Aliases§

BoxFuture: An owned dynamically typed Future for use in cases where you can’t statically type your result or need to add some indirection.
Result

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.