agent_client_protocol_schema/
lib.rs

1//! [![Agent Client Protocol](https://zed.dev/img/acp/banner-dark.webp)](https://agentclientprotocol.com/)
2//!
3//! # Agent Client Protocol (ACP)
4//!
5//! The Agent Client Protocol standardizes communication between code editors
6//! (IDEs, text-editors, etc.) and coding agents (programs that use generative AI
7//! to autonomously modify code).
8//!
9//! ## Protocol & Transport
10//!
11//! ACP is a JSON-RPC based protocol. While clients typically start agents as
12//! subprocesses and communicate over stdio (stdin/stdout), this crate is
13//! transport-agnostic.
14//!
15//! You can use any bidirectional stream that implements `AsyncRead` and `AsyncWrite`.
16//!
17//! ## Core Components
18//!
19//! - **Agent**: Programs that use generative AI to autonomously modify code
20//!   - See: [Agent](https://agentclientprotocol.com/protocol/overview#agent)
21//! - **Client**: Code editors that provide the interface between users and agents
22//!   - See: [Client](https://agentclientprotocol.com/protocol/overview#client)
23//!
24//! ## Getting Started
25//!
26//! To understand the protocol, start by exploring the [`Agent`] and [`Client`] traits,
27//! which define the core methods and capabilities of each side of the connection.
28//!
29//! To see working examples of these traits in action, check out the
30//! [agent](https://github.com/agentclientprotocol/rust-sdk/blob/main/examples/agent.rs)
31//! and
32//! [client](https://github.com/agentclientprotocol/rust-sdk/blob/main/examples/client.rs)
33//! example binaries included with this crate.
34//!
35//! ### Implementation Pattern
36//!
37//! ACP uses a symmetric design where each participant implements one trait and
38//! creates a connection that provides the complementary trait:
39//!
40//! - **Agent builders** implement the [`Agent`] trait to handle client requests
41//!   (like initialization, authentication, and prompts). They pass this implementation
42//!   to [`AgentSideConnection::new`], which returns a connection providing [`Client`]
43//!   methods for requesting permissions and accessing the file system.
44//!
45//! - **Client builders** implement the [`Client`] trait to handle agent requests
46//!   (like file system operations and permission checks). They pass this implementation
47//!   to [`ClientSideConnection::new`], which returns a connection providing [`Agent`]
48//!   methods for managing sessions and sending prompts.
49//!
50//! For the complete protocol specification and documentation, visit:
51//! [https://agentclientprotocol.com](https://agentclientprotocol.com)
52
53mod agent;
54mod client;
55mod content;
56mod error;
57mod ext;
58mod plan;
59mod rpc;
60mod tool_call;
61mod version;
62
63pub use agent::*;
64pub use client::*;
65pub use content::*;
66use derive_more::{Display, From};
67pub use error::*;
68pub use ext::*;
69pub use plan::*;
70pub use rpc::*;
71pub use serde_json::value::RawValue;
72pub use tool_call::*;
73pub use version::*;
74
75use schemars::JsonSchema;
76use serde::{Deserialize, Serialize};
77use std::{
78    borrow::Cow,
79    ffi::OsStr,
80    path::{Path, PathBuf},
81    sync::Arc,
82};
83
84/// A unique identifier for a conversation session between a client and agent.
85///
86/// Sessions maintain their own context, conversation history, and state,
87/// allowing multiple independent interactions with the same agent.
88///
89/// See protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)
90#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq, Hash, Display, From)]
91#[serde(transparent)]
92#[from(Arc<str>, String, &'static str)]
93#[non_exhaustive]
94pub struct SessionId(pub Arc<str>);
95
96impl SessionId {
97    pub fn new(id: impl Into<Arc<str>>) -> Self {
98        Self(id.into())
99    }
100}
101
102/// Utility trait for builder methods for optional values.
103/// This allows the caller to either pass in the value itself without wrapping it in `Some`,
104/// or to just pass in an Option if that is what they have.
105pub trait IntoOption<T> {
106    fn into_option(self) -> Option<T>;
107}
108
109impl<T> IntoOption<T> for Option<T> {
110    fn into_option(self) -> Option<T> {
111        self
112    }
113}
114
115impl<T> IntoOption<T> for T {
116    fn into_option(self) -> Option<T> {
117        Some(self)
118    }
119}
120
121impl IntoOption<String> for &str {
122    fn into_option(self) -> Option<String> {
123        Some(self.into())
124    }
125}
126
127impl IntoOption<String> for &mut str {
128    fn into_option(self) -> Option<String> {
129        Some(self.into())
130    }
131}
132
133impl IntoOption<String> for &String {
134    fn into_option(self) -> Option<String> {
135        Some(self.into())
136    }
137}
138
139impl IntoOption<String> for Box<str> {
140    fn into_option(self) -> Option<String> {
141        Some(self.into())
142    }
143}
144
145impl IntoOption<String> for Cow<'_, str> {
146    fn into_option(self) -> Option<String> {
147        Some(self.into())
148    }
149}
150
151impl IntoOption<String> for Arc<str> {
152    fn into_option(self) -> Option<String> {
153        Some(self.to_string())
154    }
155}
156
157impl<T: ?Sized + AsRef<OsStr>> IntoOption<PathBuf> for &T {
158    fn into_option(self) -> Option<PathBuf> {
159        Some(self.into())
160    }
161}
162
163impl IntoOption<PathBuf> for Box<Path> {
164    fn into_option(self) -> Option<PathBuf> {
165        Some(self.into())
166    }
167}
168
169impl IntoOption<PathBuf> for Cow<'_, Path> {
170    fn into_option(self) -> Option<PathBuf> {
171        Some(self.into())
172    }
173}
174
175impl IntoOption<serde_json::Value> for &str {
176    fn into_option(self) -> Option<serde_json::Value> {
177        Some(self.into())
178    }
179}
180
181impl IntoOption<serde_json::Value> for String {
182    fn into_option(self) -> Option<serde_json::Value> {
183        Some(self.into())
184    }
185}
186
187impl IntoOption<serde_json::Value> for Cow<'_, str> {
188    fn into_option(self) -> Option<serde_json::Value> {
189        Some(self.into())
190    }
191}
agent_client_protocol_schema/lib.rs

agent_client_protocol_schema/
lib.rs
