Skip to main content

agent_client_protocol_schema/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2
3//! [![Agent Client Protocol](https://zed.dev/img/acp/banner-dark.webp)](https://agentclientprotocol.com/)
4//!
5//! # Agent Client Protocol Schema
6//!
7//! Strongly-typed Rust definitions of the Agent Client Protocol (ACP) wire
8//! format. ACP is a JSON-RPC based protocol that standardizes communication
9//! between code editors (IDEs, text-editors, etc.) and coding agents
10//! (programs that use generative AI to autonomously modify code).
11//!
12//! This crate is **only** the schema: the request, response, and
13//! notification types, plus serde plumbing and optional JSON Schema generation.
14//! For the runtime pieces (transport, connection setup, the `Agent` / `Client`
15//! traits, etc.) use the higher-level [`agent-client-protocol`] crate, which
16//! builds on top of these types.
17//!
18//! [`agent-client-protocol`]: https://crates.io/crates/agent-client-protocol
19//!
20//! ## What's in this crate
21//!
22//! - Versioned wire-format types for every ACP method: request, response, and
23//!   notification structs grouped by which side handles them, currently under
24//!   the [`v1`] module.
25//! - JSON-RPC envelope and routing types: [`v1::JsonRpcMessage`],
26//!   [`rpc::JsonRpcBatch`], [`v1::Request`], [`v1::Response`],
27//!   [`v1::Notification`], [`v1::RequestId`], [`v1::Error`].
28//! - Aggregated routing enums: [`v1::AgentRequest`], [`v1::AgentResponse`],
29//!   [`v1::AgentNotification`], and the matching client-side trio used by SDK
30//!   crates to dispatch incoming JSON-RPC messages.
31//!
32//! ## Parsing aggregate enums
33//!
34//! Do not deserialize an aggregate routing enum directly from a wire payload.
35//! Its untagged `Deserialize` implementation selects by payload shape, not the
36//! JSON-RPC method, and can silently select an unrelated variant.
37//! Use the enum's `from_method_and_params` or `from_method_and_result` method
38//! instead. Individual payload structs can be deserialized directly once the
39//! method is known.
40//!
41//! These helpers only select and deserialize payloads. Use the SDK for
42//! connections, request tracking, and JSON-RPC error handling.
43//!
44//! ```
45//! use agent_client_protocol_schema::v1::ClientRequest;
46//! use serde_json::json;
47//!
48//! let params = json!({"cwd": "/work", "mcpServers": []});
49//! let request = ClientRequest::from_method_and_params("session/new", &params)?;
50//! assert!(matches!(request, ClientRequest::NewSessionRequest(_)));
51//! # Ok::<(), agent_client_protocol_schema::MethodDispatchError>(())
52//! ```
53//!
54//! ## Cargo features
55//!
56//! The `schemars` feature implements `schemars::JsonSchema` for the protocol
57//! types. It is enabled by default to preserve the existing default API.
58//! Consumers that only need serialization can disable default features to omit
59//! the dependency and those trait implementations.
60//!
61//! The `uuid` feature adds `IdempotencyKey::generate` to the `v2` module, which
62//! creates a key from a random UUID. It is off by default.
63//!
64//! ## Versioning
65//!
66//! Stable protocol types are exposed through explicit version modules. For
67//! example, use `agent_client_protocol_schema::v1::SessionId` for ACP protocol
68//! version 1 types.
69//!
70//! For the complete protocol specification and documentation, visit
71//! <https://agentclientprotocol.com>.
72
73#[macro_use]
74mod dispatch;
75pub mod rpc;
76mod serde_util;
77pub mod v1;
78#[cfg(feature = "unstable_protocol_v2")]
79pub mod v2;
80mod version;
81
82// The `uuid` feature only adds API to the `v2` module. With `uuid` on and
83// `unstable_protocol_v2` off, the dependency is enabled and nothing uses it.
84// That combination is valid, so reference the crate to say so. Remove this
85// once the `v2` module is no longer behind `unstable_protocol_v2`.
86#[cfg(all(feature = "uuid", not(feature = "unstable_protocol_v2")))]
87use uuid as _;
88
89pub use dispatch::MethodDispatchError;
90pub use serde_util::{IntoMaybeUndefined, IntoOption, MaybeUndefined};
91pub use version::*;
92
93#[cfg(test)]
94mod serde_json_feature_tests {
95    #[cfg(feature = "schemars")]
96    use schemars::JsonSchema;
97    use serde_json::Value;
98
99    #[cfg(feature = "schemars")]
100    #[test]
101    fn protocol_types_implement_json_schema_when_enabled() {
102        fn assert_json_schema<T: JsonSchema>() {}
103
104        assert_json_schema::<crate::ProtocolVersion>();
105        assert_json_schema::<crate::v1::InitializeRequest>();
106    }
107
108    #[test]
109    fn serde_json_values_preserve_object_key_order() {
110        let Value::Object(object) =
111            serde_json::from_str::<Value>(r#"{"z":1,"a":2,"m":3}"#).unwrap()
112        else {
113            panic!("expected JSON object");
114        };
115
116        let keys = object.keys().map(String::as_str).collect::<Vec<_>>();
117        assert_eq!(keys, ["z", "a", "m"]);
118    }
119}