agent_client_protocol/
agent.rs

1//! Methods and notifications the agent handles/receives
2
3use std::{path::PathBuf, sync::Arc};
4
5use anyhow::Result;
6use schemars::JsonSchema;
7use serde::{Deserialize, Serialize};
8
9use crate::{ClientCapabilities, ContentBlock, Error, ProtocolVersion, SessionId};
10
11pub trait Agent {
12    fn initialize(
13        &self,
14        arguments: InitializeRequest,
15    ) -> impl Future<Output = Result<InitializeResponse, Error>>;
16
17    fn authenticate(
18        &self,
19        arguments: AuthenticateRequest,
20    ) -> impl Future<Output = Result<(), Error>>;
21
22    fn new_session(
23        &self,
24        arguments: NewSessionRequest,
25    ) -> impl Future<Output = Result<NewSessionResponse, Error>>;
26
27    fn load_session(
28        &self,
29        arguments: LoadSessionRequest,
30    ) -> impl Future<Output = Result<(), Error>>;
31
32    fn prompt(
33        &self,
34        arguments: PromptRequest,
35    ) -> impl Future<Output = Result<PromptResponse, Error>>;
36
37    fn cancel(&self, args: CancelNotification) -> impl Future<Output = Result<(), Error>>;
38}
39
40// Initialize
41
42#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
43#[serde(rename_all = "camelCase")]
44pub struct InitializeRequest {
45    /// The latest protocol version supported by the client
46    pub protocol_version: ProtocolVersion,
47    /// Capabilities supported by the client
48    #[serde(default)]
49    pub client_capabilities: ClientCapabilities,
50}
51
52#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
53#[serde(rename_all = "camelCase")]
54pub struct InitializeResponse {
55    /// The protocol version the client specified if supported by the agent,
56    /// or the latest protocol version supported by the agent.
57    ///
58    /// The client should disconnect, if it doesn't support this version.
59    pub protocol_version: ProtocolVersion,
60    /// Capabilities supported by the agent
61    #[serde(default)]
62    pub agent_capabilities: AgentCapabilities,
63    /// Authentication methods supported by the agent
64    #[serde(default)]
65    pub auth_methods: Vec<AuthMethod>,
66}
67
68// Authentication
69
70#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
71#[serde(rename_all = "camelCase")]
72pub struct AuthenticateRequest {
73    pub method_id: AuthMethodId,
74}
75
76#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq, Hash)]
77#[serde(transparent)]
78pub struct AuthMethodId(pub Arc<str>);
79
80#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
81#[serde(rename_all = "camelCase")]
82pub struct AuthMethod {
83    pub id: AuthMethodId,
84    pub name: String,
85    pub description: Option<String>,
86}
87
88// New session
89
90#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
91#[serde(rename_all = "camelCase")]
92pub struct NewSessionRequest {
93    pub mcp_servers: Vec<McpServer>,
94    pub cwd: PathBuf,
95}
96
97#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
98#[serde(rename_all = "camelCase")]
99pub struct NewSessionResponse {
100    pub session_id: SessionId,
101}
102
103// Load session
104
105#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
106#[serde(rename_all = "camelCase")]
107pub struct LoadSessionRequest {
108    pub mcp_servers: Vec<McpServer>,
109    pub cwd: PathBuf,
110    pub session_id: SessionId,
111}
112
113// MCP
114
115#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
116#[serde(rename_all = "camelCase")]
117pub struct McpServer {
118    pub name: String,
119    pub command: PathBuf,
120    pub args: Vec<String>,
121    pub env: Vec<EnvVariable>,
122}
123
124#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
125#[serde(rename_all = "camelCase")]
126pub struct EnvVariable {
127    pub name: String,
128    pub value: String,
129}
130
131// Prompt
132
133#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
134#[serde(rename_all = "camelCase")]
135pub struct PromptRequest {
136    pub session_id: SessionId,
137    pub prompt: Vec<ContentBlock>,
138}
139
140#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
141#[serde(rename_all = "camelCase")]
142pub struct PromptResponse {
143    pub stop_reason: StopReason,
144}
145
146#[derive(Debug, Copy, Clone, Eq, PartialEq, Serialize, Deserialize, JsonSchema)]
147#[serde(rename_all = "snake_case")]
148pub enum StopReason {
149    /// The turn ended successfully.
150    EndTurn,
151    /// The turn ended because the agent reached the maximum number of tokens.
152    MaxTokens,
153    /// The turn ended because the agent refused to continue. The user prompt
154    /// and everything that comes after it won't be included in the next
155    /// prompt, so this should be reflected in the UI.
156    Refusal,
157    /// The turn was cancelled by the client.
158    Cancelled,
159}
160
161// Capabilities
162
163#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema)]
164#[serde(rename_all = "camelCase")]
165pub struct AgentCapabilities {
166    /// Agent supports `session/load`
167    #[serde(default)]
168    load_session: bool,
169}
170
171// Method schema
172
173#[derive(Debug, Clone, Serialize, Deserialize)]
174pub struct AgentMethodNames {
175    pub initialize: &'static str,
176    pub authenticate: &'static str,
177    pub session_new: &'static str,
178    pub session_load: &'static str,
179    pub session_prompt: &'static str,
180    pub session_cancel: &'static str,
181}
182
183pub const AGENT_METHOD_NAMES: AgentMethodNames = AgentMethodNames {
184    initialize: INITIALIZE_METHOD_NAME,
185    authenticate: AUTHENTICATE_METHOD_NAME,
186    session_new: SESSION_NEW_METHOD_NAME,
187    session_load: SESSION_LOAD_METHOD_NAME,
188    session_prompt: SESSION_PROMPT_METHOD_NAME,
189    session_cancel: SESSION_CANCEL_METHOD_NAME,
190};
191
192pub const INITIALIZE_METHOD_NAME: &str = "initialize";
193pub const AUTHENTICATE_METHOD_NAME: &str = "authenticate";
194pub const SESSION_NEW_METHOD_NAME: &str = "session/new";
195pub const SESSION_LOAD_METHOD_NAME: &str = "session/load";
196pub const SESSION_PROMPT_METHOD_NAME: &str = "session/prompt";
197pub const SESSION_CANCEL_METHOD_NAME: &str = "session/cancel";
198
199/// Requests the client sends to the agent
200#[derive(Debug, Serialize, Deserialize, JsonSchema)]
201#[serde(untagged)]
202pub enum ClientRequest {
203    InitializeRequest(InitializeRequest),
204    AuthenticateRequest(AuthenticateRequest),
205    NewSessionRequest(NewSessionRequest),
206    LoadSessionRequest(LoadSessionRequest),
207    PromptRequest(PromptRequest),
208}
209
210/// Responses the agent sends to the client
211#[derive(Debug, Serialize, Deserialize, JsonSchema)]
212#[serde(untagged)]
213pub enum AgentResponse {
214    InitializeResponse(InitializeResponse),
215    AuthenticateResponse,
216    NewSessionResponse(NewSessionResponse),
217    LoadSessionResponse,
218    PromptResponse(PromptResponse),
219}
220
221/// Notifications the client sends to the agent
222#[derive(Debug, Serialize, Deserialize, JsonSchema)]
223#[serde(untagged)]
224pub enum ClientNotification {
225    CancelNotification(CancelNotification),
226}
227
228#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
229#[serde(rename_all = "camelCase")]
230pub struct CancelNotification {
231    pub session_id: SessionId,
232}
agent_client_protocol/agent.rs

agent_client_protocol/
agent.rs
