Skip to content

Commit 733e677

Browse files
benbrandtbenbrandt
committed
Schema -> MD docs
1 parent ebc5801 commit 733e677

14 files changed

Lines changed: 2229 additions & 168 deletions

File tree

‎docs/protocol/schema.mdx‎

Lines changed: 1226 additions & 0 deletions
Large diffs are not rendered by default.

‎rust/acp.rs‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,11 @@
1515
//! ## Core Components
1616
//!
1717
//! - **Agent**: Programs that use generative AI to autonomously modify code
18-
//! - See: <https://agentclientprotocol.com/protocol/overview#agent>
18+
//! - See: [https://agentclientprotocol.com/protocol/overview#agent](https://agentclientprotocol.com/protocol/overview#agent)
1919
//! - **Client**: Code editors that provide the interface between users and agents
20-
//! - See: <https://agentclientprotocol.com/protocol/overview#client>
20+
//! - See: [https://agentclientprotocol.com/protocol/overview#client](https://agentclientprotocol.com/protocol/overview#client)
2121
//! - **Session**: A conversation context between a client and agent
22-
//! - See: <https://agentclientprotocol.com/protocol/session-setup>
22+
//! - See: [https://agentclientprotocol.com/protocol/session-setup](https://agentclientprotocol.com/protocol/session-setup)
2323
//!
2424
//! ## Getting Started
2525
//!
@@ -42,7 +42,7 @@
4242
//! methods for managing sessions and sending prompts.
4343
//!
4444
//! For the complete protocol specification and documentation, visit:
45-
//! <https://agentclientprotocol.com>
45+
//! [https://agentclientprotocol.com](https://agentclientprotocol.com)
4646
4747
mod agent;
4848
mod client;
@@ -52,6 +52,7 @@ mod plan;
5252
mod rpc;
5353
#[cfg(test)]
5454
mod rpc_tests;
55+
mod schema_metadata;
5556
mod stream_broadcast;
5657
mod tool_call;
5758
mod version;
@@ -90,8 +91,9 @@ use crate::rpc::{MessageHandler, RpcConnection, Side};
9091
/// let session_id = SessionId(Arc::from("sess_abc123def456"));
9192
/// ```
9293
///
93-
/// See: <https://agentclientprotocol.com/protocol/session-setup#session-id>
94+
/// See: [https://agentclientprotocol.com/protocol/session-setup#session-id](https://agentclientprotocol.com/protocol/session-setup#session-id)
9495
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq, Hash)]
96+
#[schemars(transform = crate::schema_metadata::add_group_session)]
9597
#[serde(transparent)]
9698
pub struct SessionId(pub Arc<str>);
9799

@@ -110,7 +112,7 @@ impl fmt::Display for SessionId {
110112
/// the [`Agent`] trait to provide methods for initializing sessions, sending
111113
/// prompts, and managing the agent lifecycle.
112114
///
113-
/// See: <https://agentclientprotocol.com/protocol/overview#client>
115+
/// See: [https://agentclientprotocol.com/protocol/overview#client](https://agentclientprotocol.com/protocol/overview#client)
114116
pub struct ClientSideConnection {
115117
conn: RpcConnection<ClientSide, AgentSide>,
116118
}
@@ -134,7 +136,7 @@ impl ClientSideConnection {
134136
/// - The connection instance for making requests to the agent
135137
/// - An I/O future that must be spawned to handle the underlying communication
136138
///
137-
/// See: <https://agentclientprotocol.com/protocol/overview#communication-model>
139+
/// See: [https://agentclientprotocol.com/protocol/overview#communication-model](https://agentclientprotocol.com/protocol/overview#communication-model)
138140
pub fn new(
139141
client: impl MessageHandler<ClientSide> + 'static,
140142
outgoing_bytes: impl Unpin + AsyncWrite,
@@ -217,7 +219,7 @@ impl Agent for ClientSideConnection {
217219
/// This type is used by the RPC layer to determine which messages
218220
/// are incoming vs outgoing from the client's perspective.
219221
///
220-
/// See: <https://agentclientprotocol.com/protocol/overview#communication-model>
222+
/// See: [https://agentclientprotocol.com/protocol/overview#communication-model](https://agentclientprotocol.com/protocol/overview#communication-model)
221223
#[derive(Clone)]
222224
pub struct ClientSide;
223225

@@ -295,7 +297,7 @@ impl<T: Client> MessageHandler<ClientSide> for T {
295297
/// to provide methods for requesting permissions, accessing the file system,
296298
/// and sending session updates.
297299
///
298-
/// See: <https://agentclientprotocol.com/protocol/overview#agent>
300+
/// See: [https://agentclientprotocol.com/protocol/overview#agent](https://agentclientprotocol.com/protocol/overview#agent)
299301
pub struct AgentSideConnection {
300302
conn: RpcConnection<AgentSide, ClientSide>,
301303
}
@@ -319,7 +321,7 @@ impl AgentSideConnection {
319321
/// - The connection instance for making requests to the client
320322
/// - An I/O future that must be spawned to handle the underlying communication
321323
///
322-
/// See: <https://agentclientprotocol.com/protocol/overview#communication-model>
324+
/// See: [https://agentclientprotocol.com/protocol/overview#communication-model](https://agentclientprotocol.com/protocol/overview#communication-model)
323325
pub fn new(
324326
agent: impl MessageHandler<AgentSide> + 'static,
325327
outgoing_bytes: impl Unpin + AsyncWrite,
@@ -390,7 +392,7 @@ impl Client for AgentSideConnection {
390392
/// This type is used by the RPC layer to determine which messages
391393
/// are incoming vs outgoing from the agent's perspective.
392394
///
393-
/// See: <https://agentclientprotocol.com/protocol/overview#communication-model>
395+
/// See: [https://agentclientprotocol.com/protocol/overview#communication-model](https://agentclientprotocol.com/protocol/overview#communication-model)
394396
#[derive(Clone)]
395397
pub struct AgentSide;
396398

‎rust/agent.rs‎

Lines changed: 37 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ pub trait Agent {
2525
///
2626
/// The agent should respond with its supported protocol version and capabilities.
2727
///
28-
/// See: <https://agentclientprotocol.com/protocol/initialization>
28+
/// See: [https://agentclientprotocol.com/protocol/initialization](https://agentclientprotocol.com/protocol/initialization)
2929
fn initialize(
3030
&self,
3131
arguments: InitializeRequest,
@@ -39,7 +39,7 @@ pub trait Agent {
3939
/// After successful authentication, the client can proceed to create sessions with
4040
/// `new_session` without receiving an `auth_required` error.
4141
///
42-
/// See: <https://agentclientprotocol.com/protocol/initialization>
42+
/// See: [https://agentclientprotocol.com/protocol/initialization](https://agentclientprotocol.com/protocol/initialization)
4343
fn authenticate(
4444
&self,
4545
arguments: AuthenticateRequest,
@@ -57,7 +57,7 @@ pub trait Agent {
5757
///
5858
/// May return an `auth_required` error if the agent requires authentication.
5959
///
60-
/// See: <https://agentclientprotocol.com/protocol/session-setup>
60+
/// See: [https://agentclientprotocol.com/protocol/session-setup](https://agentclientprotocol.com/protocol/session-setup)
6161
fn new_session(
6262
&self,
6363
arguments: NewSessionRequest,
@@ -71,7 +71,7 @@ pub trait Agent {
7171
/// - Connect to the specified MCP servers
7272
/// - Stream the entire conversation history back to the client via notifications
7373
///
74-
/// See: <https://agentclientprotocol.com/protocol/session-setup#loading-sessions>
74+
/// See: [https://agentclientprotocol.com/protocol/session-setup#loading-sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions)
7575
fn load_session(
7676
&self,
7777
arguments: LoadSessionRequest,
@@ -85,7 +85,7 @@ pub trait Agent {
8585
/// - Executes any requested tool calls
8686
/// - Returns when the turn is complete with a stop reason
8787
///
88-
/// See: <https://agentclientprotocol.com/protocol/prompt-turn>
88+
/// See: [https://agentclientprotocol.com/protocol/prompt-turn](https://agentclientprotocol.com/protocol/prompt-turn)
8989
fn prompt(
9090
&self,
9191
arguments: PromptRequest,
@@ -101,7 +101,7 @@ pub trait Agent {
101101
/// - Send any pending `session/update` notifications
102102
/// - Respond to the original `session/prompt` request with `StopReason::Cancelled`
103103
///
104-
/// See: <https://agentclientprotocol.com/protocol/prompt-turn#cancellation>
104+
/// See: [https://agentclientprotocol.com/protocol/prompt-turn#cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)
105105
fn cancel(&self, args: CancelNotification) -> impl Future<Output = Result<(), Error>>;
106106
}
107107

@@ -111,8 +111,9 @@ pub trait Agent {
111111
///
112112
/// Sent by the client to establish connection and negotiate capabilities.
113113
///
114-
/// See: <https://agentclientprotocol.com/protocol/initialization>
114+
/// See: [https://agentclientprotocol.com/protocol/initialization](https://agentclientprotocol.com/protocol/initialization)
115115
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
116+
#[schemars(transform = crate::schema_metadata::add_group_initialization)]
116117
#[serde(rename_all = "camelCase")]
117118
pub struct InitializeRequest {
118119
/// The latest protocol version supported by the client.
@@ -126,8 +127,9 @@ pub struct InitializeRequest {
126127
///
127128
/// Contains the negotiated protocol version and agent capabilities.
128129
///
129-
/// See: <https://agentclientprotocol.com/protocol/initialization>
130+
/// See: [https://agentclientprotocol.com/protocol/initialization](https://agentclientprotocol.com/protocol/initialization)
130131
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
132+
#[schemars(transform = crate::schema_metadata::add_group_initialization)]
131133
#[serde(rename_all = "camelCase")]
132134
pub struct InitializeResponse {
133135
/// The protocol version the client specified if supported by the agent,
@@ -149,6 +151,7 @@ pub struct InitializeResponse {
149151
///
150152
/// Specifies which authentication method to use.
151153
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
154+
#[schemars(transform = crate::schema_metadata::add_group_initialization)]
152155
#[serde(rename_all = "camelCase")]
153156
pub struct AuthenticateRequest {
154157
/// The ID of the authentication method to use.
@@ -158,11 +161,13 @@ pub struct AuthenticateRequest {
158161

159162
/// Unique identifier for an authentication method.
160163
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq, Hash)]
164+
#[schemars(transform = crate::schema_metadata::add_group_initialization)]
161165
#[serde(transparent)]
162166
pub struct AuthMethodId(pub Arc<str>);
163167

164168
/// Describes an available authentication method.
165169
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
170+
#[schemars(transform = crate::schema_metadata::add_group_initialization)]
166171
#[serde(rename_all = "camelCase")]
167172
pub struct AuthMethod {
168173
/// Unique identifier for this authentication method.
@@ -177,8 +182,9 @@ pub struct AuthMethod {
177182

178183
/// Request parameters for creating a new session.
179184
///
180-
/// See: <https://agentclientprotocol.com/protocol/session-setup#creating-a-session>
185+
/// See: [https://agentclientprotocol.com/protocol/session-setup#creating-a-session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session)
181186
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
187+
#[schemars(transform = crate::schema_metadata::add_group_session)]
182188
#[serde(rename_all = "camelCase")]
183189
pub struct NewSessionRequest {
184190
/// List of MCP (Model Context Protocol) servers the agent should connect to.
@@ -191,8 +197,9 @@ pub struct NewSessionRequest {
191197

192198
/// Response from creating a new session.
193199
///
194-
/// See: <https://agentclientprotocol.com/protocol/session-setup#creating-a-session>
200+
/// See: [https://agentclientprotocol.com/protocol/session-setup#creating-a-session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session)
195201
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
202+
#[schemars(transform = crate::schema_metadata::add_group_session)]
196203
#[serde(rename_all = "camelCase")]
197204
pub struct NewSessionResponse {
198205
/// Unique identifier for the created session.
@@ -206,8 +213,9 @@ pub struct NewSessionResponse {
206213
///
207214
/// Only available if the agent supports the `loadSession` capability.
208215
///
209-
/// See: <https://agentclientprotocol.com/protocol/session-setup#loading-sessions>
216+
/// See: [https://agentclientprotocol.com/protocol/session-setup#loading-sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions)
210217
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
218+
#[schemars(transform = crate::schema_metadata::add_group_session)]
211219
#[serde(rename_all = "camelCase")]
212220
pub struct LoadSessionRequest {
213221
/// List of MCP servers to connect to for this session.
@@ -225,8 +233,9 @@ pub struct LoadSessionRequest {
225233
/// MCP servers provide tools and context that the agent can use when
226234
/// processing prompts.
227235
///
228-
/// See: <https://agentclientprotocol.com/protocol/session-setup#mcp-servers>
236+
/// See: [https://agentclientprotocol.com/protocol/session-setup#mcp-servers](https://agentclientprotocol.com/protocol/session-setup#mcp-servers)
229237
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
238+
#[schemars(transform = crate::schema_metadata::add_group_mcp)]
230239
#[serde(rename_all = "camelCase")]
231240
pub struct McpServer {
232241
/// Human-readable name identifying this MCP server.
@@ -241,6 +250,7 @@ pub struct McpServer {
241250

242251
/// An environment variable to set when launching an MCP server.
243252
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
253+
#[schemars(transform = crate::schema_metadata::add_group_mcp)]
244254
#[serde(rename_all = "camelCase")]
245255
pub struct EnvVariable {
246256
/// The name of the environment variable.
@@ -255,8 +265,9 @@ pub struct EnvVariable {
255265
///
256266
/// Contains the user's message and any additional context.
257267
///
258-
/// See: <https://agentclientprotocol.com/protocol/prompt-turn#1-user-message>
268+
/// See: [https://agentclientprotocol.com/protocol/prompt-turn#1-user-message](https://agentclientprotocol.com/protocol/prompt-turn#1-user-message)
259269
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
270+
#[schemars(transform = crate::schema_metadata::add_group_session)]
260271
#[serde(rename_all = "camelCase")]
261272
pub struct PromptRequest {
262273
/// The ID of the session to send this user message to
@@ -281,8 +292,9 @@ pub struct PromptRequest {
281292

282293
/// Response from processing a user prompt.
283294
///
284-
/// See: <https://agentclientprotocol.com/protocol/prompt-turn#4-check-for-completion>
295+
/// See: [https://agentclientprotocol.com/protocol/prompt-turn#4-check-for-completion](https://agentclientprotocol.com/protocol/prompt-turn#4-check-for-completion)
285296
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
297+
#[schemars(transform = crate::schema_metadata::add_group_session)]
286298
#[serde(rename_all = "camelCase")]
287299
pub struct PromptResponse {
288300
/// Indicates why the agent stopped processing the turn.
@@ -291,8 +303,9 @@ pub struct PromptResponse {
291303

292304
/// Reasons why an agent stops processing a prompt turn.
293305
///
294-
/// See: <https://agentclientprotocol.com/protocol/prompt-turn#stop-reasons>
306+
/// See: [https://agentclientprotocol.com/protocol/prompt-turn#stop-reasons](https://agentclientprotocol.com/protocol/prompt-turn#stop-reasons)
295307
#[derive(Debug, Copy, Clone, Eq, PartialEq, Serialize, Deserialize, JsonSchema)]
308+
#[schemars(transform = crate::schema_metadata::add_group_session)]
296309
#[serde(rename_all = "snake_case")]
297310
pub enum StopReason {
298311
/// The turn ended successfully.
@@ -322,8 +335,9 @@ pub enum StopReason {
322335
/// Advertised during initialization to inform the client about
323336
/// available features and content types.
324337
///
325-
/// See: <https://agentclientprotocol.com/protocol/initialization#agent-capabilities>
338+
/// See: [https://agentclientprotocol.com/protocol/initialization#agent-capabilities](https://agentclientprotocol.com/protocol/initialization#agent-capabilities)
326339
#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema)]
340+
#[schemars(transform = crate::schema_metadata::add_group_initialization)]
327341
#[serde(rename_all = "camelCase")]
328342
pub struct AgentCapabilities {
329343
/// Whether the agent supports `session/load`.
@@ -345,8 +359,9 @@ pub struct AgentCapabilities {
345359
/// Indicates which content types beyond the baseline (text and resource links)
346360
/// the agent can process.
347361
///
348-
/// See: <https://agentclientprotocol.com/protocol/initialization#prompt-capabilities>
362+
/// See: [https://agentclientprotocol.com/protocol/initialization#prompt-capabilities](https://agentclientprotocol.com/protocol/initialization#prompt-capabilities)
349363
#[derive(Default, Debug, Clone, Copy, Serialize, Deserialize, JsonSchema)]
364+
#[schemars(transform = crate::schema_metadata::add_group_initialization)]
350365
#[serde(rename_all = "camelCase")]
351366
pub struct PromptCapabilities {
352367
/// Agent supports [`ContentBlock::Image`].
@@ -414,6 +429,7 @@ pub(crate) const SESSION_CANCEL_METHOD_NAME: &str = "session/cancel";
414429
///
415430
/// This enum encompasses all method calls from client to agent.
416431
#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
432+
#[schemars(transform = crate::schema_metadata::add_group_message_types)]
417433
#[serde(untagged)]
418434
pub enum ClientRequest {
419435
InitializeRequest(InitializeRequest),
@@ -430,6 +446,7 @@ pub enum ClientRequest {
430446
///
431447
/// These are responses to the corresponding ClientRequest variants.
432448
#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
449+
#[schemars(transform = crate::schema_metadata::add_group_message_types)]
433450
#[serde(untagged)]
434451
pub enum AgentResponse {
435452
InitializeResponse(InitializeResponse),
@@ -446,15 +463,17 @@ pub enum AgentResponse {
446463
///
447464
/// Notifications do not expect a response.
448465
#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
466+
#[schemars(transform = crate::schema_metadata::add_group_message_types)]
449467
#[serde(untagged)]
450468
pub enum ClientNotification {
451469
CancelNotification(CancelNotification),
452470
}
453471

454472
/// Notification to cancel ongoing operations for a session.
455473
///
456-
/// See: <https://agentclientprotocol.com/protocol/prompt-turn#cancellation>
474+
/// See: [https://agentclientprotocol.com/protocol/prompt-turn#cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)
457475
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
476+
#[schemars(transform = crate::schema_metadata::add_group_session)]
458477
#[serde(rename_all = "camelCase")]
459478
pub struct CancelNotification {
460479
/// The ID of the session to cancel operations for.

0 commit comments

Comments
 (0)