agent_client_protocol_schema/v1/
protocol_level.rs

1use schemars::JsonSchema;
2use serde::{Deserialize, Serialize};
3use serde_with::skip_serializing_none;
4
5use crate::IntoOption;
6
7use super::{Meta, RequestId};
8
9/// **UNSTABLE**
10///
11/// This capability is not part of the spec yet, and may be removed or changed at any point.
12///
13/// Notification to cancel an ongoing request.
14///
15/// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)
16#[cfg(feature = "unstable_cancel_request")]
17#[skip_serializing_none]
18#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
19#[schemars(extend("x-side" = "protocol", "x-method" = CANCEL_REQUEST_METHOD_NAME))]
20#[serde(rename_all = "camelCase")]
21#[non_exhaustive]
22pub struct CancelRequestNotification {
23    /// The ID of the request to cancel.
24    pub request_id: RequestId,
25    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
26    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
27    /// these keys.
28    ///
29    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
30    #[serde(rename = "_meta")]
31    pub meta: Option<Meta>,
32}
33
34#[cfg(feature = "unstable_cancel_request")]
35impl CancelRequestNotification {
36    /// Builds [`CancelRequestNotification`] with the required notification fields set; optional fields start unset or empty.
37    #[must_use]
38    pub fn new(request_id: impl Into<RequestId>) -> Self {
39        Self {
40            request_id: request_id.into(),
41            meta: None,
42        }
43    }
44
45    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
46    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
47    /// these keys.
48    ///
49    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
50    #[must_use]
51    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
52        self.meta = meta.into_option();
53        self
54    }
55}
56
57// Method schema
58
59/// Names of all methods that agents handle.
60///
61/// Provides a centralized definition of method names used in the protocol.
62#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
63#[non_exhaustive]
64pub struct GeneralMethodNames {
65    /// Method name for protocol-level request cancellation notifications.
66    #[cfg(feature = "unstable_cancel_request")]
67    pub cancel_request: &'static str,
68}
69
70/// Constant containing all agent method names.
71pub const PROTOCOL_LEVEL_METHOD_NAMES: GeneralMethodNames = GeneralMethodNames {
72    #[cfg(feature = "unstable_cancel_request")]
73    cancel_request: CANCEL_REQUEST_METHOD_NAME,
74};
75
76/// Method name for general cancel notification
77pub(crate) const CANCEL_REQUEST_METHOD_NAME: &str = "$/cancel_request";
78
79/// General protocol-level notifications that all sides are expected to
80/// implement.
81///
82/// Notifications whose methods start with '$/' are messages which
83/// are protocol implementation dependent and might not be implementable in all
84/// clients or agents. For example if the implementation uses a single threaded
85/// synchronous programming language then there is little it can do to react to
86/// a `$/cancel_request` notification. If an agent or client receives
87/// notifications starting with '$/' it is free to ignore the notification.
88///
89/// Notifications do not expect a response.
90#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
91#[serde(untagged)]
92#[schemars(inline)]
93#[non_exhaustive]
94pub enum ProtocolLevelNotification {
95    /// **UNSTABLE**
96    ///
97    /// This capability is not part of the spec yet, and may be removed or
98    /// changed at any point.
99    ///
100    /// Cancels an ongoing request.
101    ///
102    /// This is a notification sent by the side that sent a request to cancel that request.
103    ///
104    /// Upon receiving this notification, the receiver:
105    ///
106    /// 1. MUST cancel the corresponding request activity and all nested activities
107    /// 2. MAY send any pending notifications.
108    /// 3. MUST send one of these responses for the original request:
109    ///   - Valid response with appropriate data (partial results or cancellation marker)
110    ///   - Error response with code `-32800` (Cancelled)
111    ///
112    /// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)
113    #[cfg(feature = "unstable_cancel_request")]
114    CancelRequestNotification(CancelRequestNotification),
115}
116
117impl ProtocolLevelNotification {
118    /// Returns the corresponding method name of the notification.
119    #[must_use]
120    pub fn method(&self) -> &str {
121        match self {
122            #[cfg(feature = "unstable_cancel_request")]
123            Self::CancelRequestNotification(..) => PROTOCOL_LEVEL_METHOD_NAMES.cancel_request,
124        }
125    }
126}
agent_client_protocol_schema/v1/protocol_level.rs

agent_client_protocol_schema/v1/
protocol_level.rs
