agent_client_protocol/
agent.rs

1use std::{rc::Rc, sync::Arc};
2
3use agent_client_protocol_schema::{
4    AuthenticateRequest, AuthenticateResponse, CancelNotification, Error, ExtNotification,
5    ExtRequest, ExtResponse, InitializeRequest, InitializeResponse, LoadSessionRequest,
6    LoadSessionResponse, NewSessionRequest, NewSessionResponse, PromptRequest, PromptResponse,
7    Result, SetSessionConfigOptionRequest, SetSessionConfigOptionResponse, SetSessionModeRequest,
8    SetSessionModeResponse,
9};
10#[cfg(feature = "unstable_session_fork")]
11use agent_client_protocol_schema::{ForkSessionRequest, ForkSessionResponse};
12#[cfg(feature = "unstable_session_list")]
13use agent_client_protocol_schema::{ListSessionsRequest, ListSessionsResponse};
14#[cfg(feature = "unstable_session_resume")]
15use agent_client_protocol_schema::{ResumeSessionRequest, ResumeSessionResponse};
16#[cfg(feature = "unstable_session_model")]
17use agent_client_protocol_schema::{SetSessionModelRequest, SetSessionModelResponse};
18use serde_json::value::RawValue;
19
20/// Defines the interface that all ACP-compliant agents must implement.
21///
22/// Agents are programs that use generative AI to autonomously modify code. They handle
23/// requests from clients and execute tasks using language models and tools.
24#[async_trait::async_trait(?Send)]
25pub trait Agent {
26    /// Establishes the connection with a client and negotiates protocol capabilities.
27    ///
28    /// This method is called once at the beginning of the connection to:
29    /// - Negotiate the protocol version to use
30    /// - Exchange capability information between client and agent
31    /// - Determine available authentication methods
32    ///
33    /// The agent should respond with its supported protocol version and capabilities.
34    ///
35    /// See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization)
36    async fn initialize(&self, args: InitializeRequest) -> Result<InitializeResponse>;
37
38    /// Authenticates the client using the specified authentication method.
39    ///
40    /// Called when the agent requires authentication before allowing session creation.
41    /// The client provides the authentication method ID that was advertised during initialization.
42    ///
43    /// After successful authentication, the client can proceed to create sessions with
44    /// `new_session` without receiving an `auth_required` error.
45    ///
46    /// See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization)
47    async fn authenticate(&self, args: AuthenticateRequest) -> Result<AuthenticateResponse>;
48
49    /// Creates a new conversation session with the agent.
50    ///
51    /// Sessions represent independent conversation contexts with their own history and state.
52    ///
53    /// The agent should:
54    /// - Create a new session context
55    /// - Connect to any specified MCP servers
56    /// - Return a unique session ID for future requests
57    ///
58    /// May return an `auth_required` error if the agent requires authentication.
59    ///
60    /// See protocol docs: [Session Setup](https://agentclientprotocol.com/protocol/session-setup)
61    async fn new_session(&self, args: NewSessionRequest) -> Result<NewSessionResponse>;
62
63    /// Processes a user prompt within a session.
64    ///
65    /// This method handles the whole lifecycle of a prompt:
66    /// - Receives user messages with optional context (files, images, etc.)
67    /// - Processes the prompt using language models
68    /// - Reports language model content and tool calls to the Clients
69    /// - Requests permission to run tools
70    /// - Executes any requested tool calls
71    /// - Returns when the turn is complete with a stop reason
72    ///
73    /// See protocol docs: [Prompt Turn](https://agentclientprotocol.com/protocol/prompt-turn)
74    async fn prompt(&self, args: PromptRequest) -> Result<PromptResponse>;
75
76    /// Cancels ongoing operations for a session.
77    ///
78    /// This is a notification sent by the client to cancel an ongoing prompt turn.
79    ///
80    /// Upon receiving this notification, the Agent SHOULD:
81    /// - Stop all language model requests as soon as possible
82    /// - Abort all tool call invocations in progress
83    /// - Send any pending `session/update` notifications
84    /// - Respond to the original `session/prompt` request with `StopReason::Cancelled`
85    ///
86    /// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)
87    async fn cancel(&self, args: CancelNotification) -> Result<()>;
88
89    /// Loads an existing session to resume a previous conversation.
90    ///
91    /// This method is only available if the agent advertises the `loadSession` capability.
92    ///
93    /// The agent should:
94    /// - Restore the session context and conversation history
95    /// - Connect to the specified MCP servers
96    /// - Stream the entire conversation history back to the client via notifications
97    ///
98    /// See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions)
99    async fn load_session(&self, _args: LoadSessionRequest) -> Result<LoadSessionResponse> {
100        Err(Error::method_not_found())
101    }
102
103    /// Sets the current mode for a session.
104    ///
105    /// Allows switching between different agent modes (e.g., "ask", "architect", "code")
106    /// that affect system prompts, tool availability, and permission behaviors.
107    ///
108    /// The mode must be one of the modes advertised in `availableModes` during session
109    /// creation or loading. Agents may also change modes autonomously and notify the
110    /// client via `current_mode_update` notifications.
111    ///
112    /// This method can be called at any time during a session, whether the Agent is
113    /// idle or actively generating a response.
114    ///
115    /// See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)
116    async fn set_session_mode(
117        &self,
118        _args: SetSessionModeRequest,
119    ) -> Result<SetSessionModeResponse> {
120        Err(Error::method_not_found())
121    }
122
123    /// **UNSTABLE**
124    ///
125    /// This capability is not part of the spec yet, and may be removed or changed at any point.
126    ///
127    /// Select a model for a given session.
128    #[cfg(feature = "unstable_session_model")]
129    async fn set_session_model(
130        &self,
131        _args: SetSessionModelRequest,
132    ) -> Result<SetSessionModelResponse> {
133        Err(Error::method_not_found())
134    }
135
136    /// Sets the current value for a session configuration option.
137    ///
138    /// Configuration options allow agents to expose arbitrary selectors (like model choice,
139    /// reasoning level, etc.) that clients can display and modify.
140    ///
141    /// The response returns the full list of configuration options with their current values,
142    /// as changing one option may affect others.
143    async fn set_session_config_option(
144        &self,
145        _args: SetSessionConfigOptionRequest,
146    ) -> Result<SetSessionConfigOptionResponse> {
147        Err(Error::method_not_found())
148    }
149
150    /// **UNSTABLE**
151    ///
152    /// This capability is not part of the spec yet, and may be removed or changed at any point.
153    ///
154    /// Lists existing sessions known to the agent.
155    ///
156    /// Only available if the Agent supports the `sessionCapabilities.list` capability.
157    #[cfg(feature = "unstable_session_list")]
158    async fn list_sessions(&self, _args: ListSessionsRequest) -> Result<ListSessionsResponse> {
159        Err(Error::method_not_found())
160    }
161
162    /// **UNSTABLE**
163    ///
164    /// This capability is not part of the spec yet, and may be removed or changed at any point.
165    ///
166    /// Forks an existing session, creating a new session with the same conversation history.
167    ///
168    /// Only available if the Agent supports the `sessionCapabilities.fork` capability.
169    #[cfg(feature = "unstable_session_fork")]
170    async fn fork_session(&self, _args: ForkSessionRequest) -> Result<ForkSessionResponse> {
171        Err(Error::method_not_found())
172    }
173
174    /// **UNSTABLE**
175    ///
176    /// This capability is not part of the spec yet, and may be removed or changed at any point.
177    ///
178    /// Resumes an existing session without replaying message history.
179    ///
180    /// This is similar to `load_session`, except it does not return previous messages.
181    /// Useful for agents that support continuing conversations but don't store full history.
182    ///
183    /// Only available if the Agent supports the `sessionCapabilities.resume` capability.
184    #[cfg(feature = "unstable_session_resume")]
185    async fn resume_session(&self, _args: ResumeSessionRequest) -> Result<ResumeSessionResponse> {
186        Err(Error::method_not_found())
187    }
188
189    /// Handles extension method requests from the client.
190    ///
191    /// Extension methods provide a way to add custom functionality while maintaining
192    /// protocol compatibility.
193    ///
194    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
195    async fn ext_method(&self, _args: ExtRequest) -> Result<ExtResponse> {
196        Ok(ExtResponse::new(RawValue::NULL.to_owned().into()))
197    }
198
199    /// Handles extension notifications from the client.
200    ///
201    /// Extension notifications provide a way to send one-way messages for custom functionality
202    /// while maintaining protocol compatibility.
203    ///
204    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
205    async fn ext_notification(&self, _args: ExtNotification) -> Result<()> {
206        Ok(())
207    }
208}
209
210#[async_trait::async_trait(?Send)]
211impl<T: Agent> Agent for Rc<T> {
212    async fn initialize(&self, args: InitializeRequest) -> Result<InitializeResponse> {
213        self.as_ref().initialize(args).await
214    }
215    async fn authenticate(&self, args: AuthenticateRequest) -> Result<AuthenticateResponse> {
216        self.as_ref().authenticate(args).await
217    }
218    async fn new_session(&self, args: NewSessionRequest) -> Result<NewSessionResponse> {
219        self.as_ref().new_session(args).await
220    }
221    async fn load_session(&self, args: LoadSessionRequest) -> Result<LoadSessionResponse> {
222        self.as_ref().load_session(args).await
223    }
224    async fn set_session_mode(
225        &self,
226        args: SetSessionModeRequest,
227    ) -> Result<SetSessionModeResponse> {
228        self.as_ref().set_session_mode(args).await
229    }
230    async fn prompt(&self, args: PromptRequest) -> Result<PromptResponse> {
231        self.as_ref().prompt(args).await
232    }
233    async fn cancel(&self, args: CancelNotification) -> Result<()> {
234        self.as_ref().cancel(args).await
235    }
236    #[cfg(feature = "unstable_session_model")]
237    async fn set_session_model(
238        &self,
239        args: SetSessionModelRequest,
240    ) -> Result<SetSessionModelResponse> {
241        self.as_ref().set_session_model(args).await
242    }
243    async fn set_session_config_option(
244        &self,
245        args: SetSessionConfigOptionRequest,
246    ) -> Result<SetSessionConfigOptionResponse> {
247        self.as_ref().set_session_config_option(args).await
248    }
249    #[cfg(feature = "unstable_session_list")]
250    async fn list_sessions(&self, args: ListSessionsRequest) -> Result<ListSessionsResponse> {
251        self.as_ref().list_sessions(args).await
252    }
253    #[cfg(feature = "unstable_session_fork")]
254    async fn fork_session(&self, args: ForkSessionRequest) -> Result<ForkSessionResponse> {
255        self.as_ref().fork_session(args).await
256    }
257    #[cfg(feature = "unstable_session_resume")]
258    async fn resume_session(&self, args: ResumeSessionRequest) -> Result<ResumeSessionResponse> {
259        self.as_ref().resume_session(args).await
260    }
261    async fn ext_method(&self, args: ExtRequest) -> Result<ExtResponse> {
262        self.as_ref().ext_method(args).await
263    }
264    async fn ext_notification(&self, args: ExtNotification) -> Result<()> {
265        self.as_ref().ext_notification(args).await
266    }
267}
268
269#[async_trait::async_trait(?Send)]
270impl<T: Agent> Agent for Arc<T> {
271    async fn initialize(&self, args: InitializeRequest) -> Result<InitializeResponse> {
272        self.as_ref().initialize(args).await
273    }
274    async fn authenticate(&self, args: AuthenticateRequest) -> Result<AuthenticateResponse> {
275        self.as_ref().authenticate(args).await
276    }
277    async fn new_session(&self, args: NewSessionRequest) -> Result<NewSessionResponse> {
278        self.as_ref().new_session(args).await
279    }
280    async fn load_session(&self, args: LoadSessionRequest) -> Result<LoadSessionResponse> {
281        self.as_ref().load_session(args).await
282    }
283    async fn set_session_mode(
284        &self,
285        args: SetSessionModeRequest,
286    ) -> Result<SetSessionModeResponse> {
287        self.as_ref().set_session_mode(args).await
288    }
289    async fn prompt(&self, args: PromptRequest) -> Result<PromptResponse> {
290        self.as_ref().prompt(args).await
291    }
292    async fn cancel(&self, args: CancelNotification) -> Result<()> {
293        self.as_ref().cancel(args).await
294    }
295    #[cfg(feature = "unstable_session_model")]
296    async fn set_session_model(
297        &self,
298        args: SetSessionModelRequest,
299    ) -> Result<SetSessionModelResponse> {
300        self.as_ref().set_session_model(args).await
301    }
302    async fn set_session_config_option(
303        &self,
304        args: SetSessionConfigOptionRequest,
305    ) -> Result<SetSessionConfigOptionResponse> {
306        self.as_ref().set_session_config_option(args).await
307    }
308    #[cfg(feature = "unstable_session_list")]
309    async fn list_sessions(&self, args: ListSessionsRequest) -> Result<ListSessionsResponse> {
310        self.as_ref().list_sessions(args).await
311    }
312    #[cfg(feature = "unstable_session_fork")]
313    async fn fork_session(&self, args: ForkSessionRequest) -> Result<ForkSessionResponse> {
314        self.as_ref().fork_session(args).await
315    }
316    #[cfg(feature = "unstable_session_resume")]
317    async fn resume_session(&self, args: ResumeSessionRequest) -> Result<ResumeSessionResponse> {
318        self.as_ref().resume_session(args).await
319    }
320    async fn ext_method(&self, args: ExtRequest) -> Result<ExtResponse> {
321        self.as_ref().ext_method(args).await
322    }
323    async fn ext_notification(&self, args: ExtNotification) -> Result<()> {
324        self.as_ref().ext_notification(args).await
325    }
326}
agent_client_protocol/agent.rs

agent_client_protocol/
agent.rs
