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

agent_client_protocol_schema/v1/
protocol_level.rs
