agent_client_protocol_schema/v1/
ext.rs

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

agent_client_protocol_schema/v1/
ext.rs
