agent_client_protocol_schema/v2/
ext.rs

1//! Extension types and constants for protocol extensibility.
2use derive_more::From;
3use serde::{Deserialize, Serialize};
4use serde_json::value::RawValue;
5use std::sync::Arc;
6
7/// Value attached to a given ACP type on the `_meta` field.
8///
9/// The _meta property is reserved by ACP to allow clients and agents to attach
10/// additional metadata to their interactions. Implementations MUST NOT make assumptions about
11/// values at these keys.
12///
13/// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
14pub type Meta = serde_json::Map<String, serde_json::Value>;
15
16/// Allows for sending an arbitrary request that is not part of the ACP spec.
17/// Extension methods provide a way to add custom functionality while maintaining
18/// protocol compatibility.
19///
20/// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
21#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
22#[derive(Debug, Clone, Serialize, Deserialize)]
23#[serde(transparent)]
24#[non_exhaustive]
25pub struct ExtRequest {
26    /// Wire method name for this extension request.
27    ///
28    /// Extension method names must start with `_`.
29    #[serde(skip)] // this is used for routing, but when serializing we only want the params
30    pub method: Arc<str>,
31    /// Raw JSON parameters for this extension message.
32    #[cfg_attr(feature = "schemars", schemars(with = "serde_json::Value"))]
33    pub params: Arc<RawValue>,
34}
35
36impl ExtRequest {
37    /// Builds [`ExtRequest`] with the required request fields set; optional fields start unset or empty.
38    #[must_use]
39    pub fn new(method: impl Into<Arc<str>>, params: Arc<RawValue>) -> Self {
40        Self {
41            method: method.into(),
42            params,
43        }
44    }
45}
46
47/// Allows for sending an arbitrary response to an [`ExtRequest`] that is not part of the ACP spec.
48/// Extension methods provide a way to add custom functionality while maintaining
49/// protocol compatibility.
50///
51/// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
52#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
53#[derive(Debug, Clone, Serialize, Deserialize, From)]
54#[serde(transparent)]
55#[non_exhaustive]
56pub struct ExtResponse(
57    #[cfg_attr(feature = "schemars", schemars(with = "serde_json::Value"))] pub Arc<RawValue>,
58);
59
60impl ExtResponse {
61    /// Builds [`ExtResponse`] with the required response fields set; optional fields start unset or empty.
62    #[must_use]
63    pub fn new(params: Arc<RawValue>) -> Self {
64        Self(params)
65    }
66}
67
68/// Allows the Agent to send an arbitrary notification that is not part of the ACP spec.
69/// Extension notifications provide a way to send one-way messages for custom functionality
70/// while maintaining protocol compatibility.
71///
72/// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
73#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
74#[derive(Debug, Clone, Serialize, Deserialize)]
75#[serde(transparent)]
76#[non_exhaustive]
77pub struct ExtNotification {
78    /// Wire method name for this extension notification.
79    ///
80    /// Extension method names must start with `_`.
81    #[serde(skip)] // this is used for routing, but when serializing we only want the params
82    pub method: Arc<str>,
83    /// Raw JSON parameters for this extension message.
84    #[cfg_attr(feature = "schemars", schemars(with = "serde_json::Value"))]
85    pub params: Arc<RawValue>,
86}
87
88impl ExtNotification {
89    /// Builds [`ExtNotification`] with the required notification fields set; optional fields start unset or empty.
90    #[must_use]
91    pub fn new(method: impl Into<Arc<str>>, params: Arc<RawValue>) -> Self {
92        Self {
93            method: method.into(),
94            params,
95        }
96    }
97}
agent_client_protocol_schema/v2/ext.rs

agent_client_protocol_schema/v2/
ext.rs
