agent_client_protocol_schema/v2/
protocol_level.rs

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

agent_client_protocol_schema/v2/
protocol_level.rs
