agent_client_protocol/lib.rs
1#![deny(missing_docs)]
2
3//! # agent-client-protocol -- the Agent Client Protocol (ACP) SDK
4//!
5//! **agent-client-protocol** is a Rust SDK for building [Agent-Client Protocol (ACP)][acp] applications.
6//! ACP is a protocol for communication between AI agents and their clients (IDEs, CLIs, etc.),
7//! enabling features like tool use, permission requests, and streaming responses.
8//!
9//! [acp]: https://agentclientprotocol.com/
10//!
11//! ## What can you build with agent-client-protocol?
12//!
13//! - **Clients** that talk to ACP agents (like building your own Claude Code interface)
14//! - **Proxies** that add capabilities to existing agents (like adding custom tools via MCP)
15//! - **Agents** that respond to prompts with AI-powered responses
16//!
17//! ## Quick Start: Connecting to an Agent
18//!
19//! The most common use case is connecting to an existing ACP agent as a client.
20//! Here's a minimal example that initializes a connection, creates a session,
21//! and sends a prompt:
22//!
23//! ```no_run
24//! use agent_client_protocol::Client;
25//! use agent_client_protocol::schema::{InitializeRequest, ProtocolVersion};
26//!
27//! # async fn run(transport: impl agent_client_protocol::ConnectTo<agent_client_protocol::Client>) -> agent_client_protocol::Result<()> {
28//! Client.builder()
29//! .name("my-client")
30//! .connect_with(transport, async |cx| {
31//! // Step 1: Initialize the connection
32//! cx.send_request(InitializeRequest::new(ProtocolVersion::V1))
33//! .block_task().await?;
34//!
35//! // Step 2: Create a session and send a prompt
36//! cx.build_session_cwd()?
37//! .block_task()
38//! .run_until(async |mut session| {
39//! session.send_prompt("What is 2 + 2?")?;
40//! let response = session.read_to_string().await?;
41//! println!("{}", response);
42//! Ok(())
43//! })
44//! .await
45//! })
46//! .await
47//! # }
48//! ```
49//!
50//! For a complete working example, see [`yolo_one_shot_client.rs`][yolo].
51//!
52//! [yolo]: https://github.com/agentclientprotocol/rust-sdk/blob/main/src/agent-client-protocol/examples/yolo_one_shot_client.rs
53//!
54//! ## Cookbook
55//!
56//! The [`agent_client_protocol_cookbook`] crate contains practical guides and examples:
57//!
58//! - Connecting as a client
59//! - Global MCP server
60//! - Per-session MCP server with workspace context
61//! - Building agents and reusable components
62//! - Running proxies with the conductor
63//!
64//! [`agent_client_protocol_cookbook`]: https://docs.rs/agent-client-protocol-cookbook
65//!
66//! ## Core Concepts
67//!
68//! The [`concepts`] module provides detailed explanations of how agent-client-protocol works,
69//! including connections, sessions, callbacks, ordering guarantees, and more.
70//!
71//! ## Related Crates
72//!
73//! - [`agent-client-protocol-tokio`] - Tokio utilities for spawning agent processes
74//! - [`agent-client-protocol-conductor`] - Binary for running proxy chains
75//!
76//! [`agent-client-protocol-tokio`]: https://crates.io/crates/agent-client-protocol-tokio
77//! [`agent-client-protocol-conductor`]: https://crates.io/crates/agent-client-protocol-conductor
78
79/// Capability management for the `_meta.symposium` object
80mod capabilities;
81/// Component abstraction for agents and proxies
82pub mod component;
83/// Core concepts for understanding and using agent-client-protocol
84pub mod concepts;
85/// Cookbook of common patterns for building ACP components
86pub mod cookbook;
87/// JSON-RPC handler types for building custom message handlers
88pub mod handler;
89/// JSON-RPC connection and handler infrastructure
90mod jsonrpc;
91/// MCP server support for providing MCP tools over ACP
92pub mod mcp_server;
93/// Role types for ACP connections
94pub mod role;
95/// ACP protocol schema types - all message types, requests, responses, and supporting types
96pub mod schema;
97/// Utility functions and types
98pub mod util;
99
100pub use capabilities::*;
101
102/// JSON-RPC message types.
103///
104/// This module re-exports types from the `jsonrpcmsg` crate that are transitively
105/// reachable through the public API (e.g., via [`Channel`]).
106///
107/// Users of the `agent-client-protocol` crate can use these types without adding a direct dependency
108/// on `jsonrpcmsg`.
109pub mod jsonrpcmsg {
110 pub use jsonrpcmsg::{Error, Id, Message, Params, Request, Response};
111}
112
113pub use jsonrpc::{
114 Builder, ByteStreams, Channel, ConnectionTo, Dispatch, HandleDispatchFrom, Handled,
115 IntoHandled, JsonRpcMessage, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, Lines,
116 NullHandler, Responder, ResponseRouter, SentRequest, UntypedMessage,
117 run::{ChainRun, NullRun, RunWithConnectionTo},
118};
119
120pub use role::{
121 Role, RoleId, UntypedRole,
122 acp::{Agent, Client, Conductor, Proxy},
123};
124
125pub use component::{ConnectTo, DynConnectTo};
126
127// Re-export BoxFuture for implementing Component traits
128pub use futures::future::BoxFuture;
129
130// Re-export the six primary message enum types at the root
131pub use schema::{
132 AgentNotification, AgentRequest, AgentResponse, ClientNotification, ClientRequest,
133 ClientResponse,
134};
135
136// Re-export commonly used infrastructure types for convenience
137pub use schema::{Error, ErrorCode, Result};
138
139// Re-export derive macros for custom JSON-RPC types
140pub use agent_client_protocol_derive::{JsonRpcNotification, JsonRpcRequest, JsonRpcResponse};
141
142mod session;
143pub use session::*;
144
145/// This is a hack that must be given as the final argument of
146/// [`McpServerBuilder::tool_fn`](`crate::mcp_server::McpServerBuilder::tool_fn`) when defining tools.
147/// Look away, lest ye be blinded by its vileness!
148///
149/// Fine, if you MUST know, it's a horrific workaround for not having
150/// [return-type notation](https://github.com/rust-lang/rust/issues/109417)
151/// and for [this !@$#!%! bug](https://github.com/rust-lang/rust/issues/110338).
152/// Trust me, the need for it hurts me more than it hurts you. --nikomatsakis
153#[macro_export]
154macro_rules! tool_fn_mut {
155 () => {
156 |func, params, context| Box::pin(func(params, context))
157 };
158}
159
160/// This is a hack that must be given as the final argument of
161/// [`McpServerBuilder::tool_fn`](`crate::mcp_server::McpServerBuilder::tool_fn`) when defining stateless concurrent tools.
162/// See [`tool_fn_mut!`] for the gory details.
163#[macro_export]
164macro_rules! tool_fn {
165 () => {
166 |func, params, context| Box::pin(func(params, context))
167 };
168}
169
170/// This macro is used for the value of the `to_future_hack` parameter of
171/// [`Builder::on_receive_request`] and [`Builder::on_receive_request_from`].
172///
173/// It expands to `|f, req, responder, cx| Box::pin(f(req, responder, cx))`.
174///
175/// This is needed until [return-type notation](https://github.com/rust-lang/rust/issues/109417)
176/// is stabilized.
177#[macro_export]
178macro_rules! on_receive_request {
179 () => {
180 |f: &mut _, req, responder, cx| Box::pin(f(req, responder, cx))
181 };
182}
183
184/// This macro is used for the value of the `to_future_hack` parameter of
185/// [`Builder::on_receive_notification`] and [`Builder::on_receive_notification_from`].
186///
187/// It expands to `|f, notif, cx| Box::pin(f(notif, cx))`.
188///
189/// This is needed until [return-type notation](https://github.com/rust-lang/rust/issues/109417)
190/// is stabilized.
191#[macro_export]
192macro_rules! on_receive_notification {
193 () => {
194 |f: &mut _, notif, cx| Box::pin(f(notif, cx))
195 };
196}
197
198/// This macro is used for the value of the `to_future_hack` parameter of
199/// [`Builder::on_receive_dispatch`] and [`Builder::on_receive_dispatch_from`].
200///
201/// It expands to `|f, dispatch, cx| Box::pin(f(dispatch, cx))`.
202///
203/// This is needed until [return-type notation](https://github.com/rust-lang/rust/issues/109417)
204/// is stabilized.
205#[macro_export]
206macro_rules! on_receive_dispatch {
207 () => {
208 |f: &mut _, dispatch, cx| Box::pin(f(dispatch, cx))
209 };
210}