Expand description
§Agent Client Protocol Schema
Strongly-typed Rust definitions of the Agent Client Protocol (ACP) wire format. ACP is a JSON-RPC based protocol that standardizes communication between code editors (IDEs, text-editors, etc.) and coding agents (programs that use generative AI to autonomously modify code).
This crate is only the schema: the request, response, and
notification types, plus serde plumbing and optional JSON Schema generation.
For the runtime pieces (transport, connection setup, the Agent / Client
traits, etc.) use the higher-level agent-client-protocol crate, which
builds on top of these types.
§What’s in this crate
- Versioned wire-format types for every ACP method: request, response, and
notification structs grouped by which side handles them, currently under
the
v1module. - JSON-RPC envelope and routing types:
v1::JsonRpcMessage,rpc::JsonRpcBatch,v1::Request,v1::Response,v1::Notification,v1::RequestId,v1::Error. - Aggregated routing enums:
v1::AgentRequest,v1::AgentResponse,v1::AgentNotification, and the matching client-side trio used by SDK crates to dispatch incoming JSON-RPC messages.
§Parsing aggregate enums
Do not deserialize an aggregate routing enum directly from a wire payload.
Its untagged Deserialize implementation selects by payload shape, not the
JSON-RPC method, and can silently select an unrelated variant.
Use the enum’s from_method_and_params or from_method_and_result method
instead. Individual payload structs can be deserialized directly once the
method is known.
These helpers only select and deserialize payloads. Use the SDK for connections, request tracking, and JSON-RPC error handling.
use agent_client_protocol_schema::v1::ClientRequest;
use serde_json::json;
let params = json!({"cwd": "/work", "mcpServers": []});
let request = ClientRequest::from_method_and_params("session/new", ¶ms)?;
assert!(matches!(request, ClientRequest::NewSessionRequest(_)));§Maps
Maps keep the order of their keys, so the types hold them in an
IndexMap. The crate re-exports it, so building one needs no direct
indexmap dependency.
use agent_client_protocol_schema::IndexMap;
use agent_client_protocol_schema::v1::{OtherStateUpdate, StateUpdate};
use serde_json::json;
let fields = IndexMap::from([
("reason".to_string(), json!("rate_limited")),
("attempt".to_string(), json!(2)),
]);
let state = StateUpdate::Other(OtherStateUpdate::new("_paused", fields));
assert_eq!(
serde_json::to_string(&state)?,
r#"{"state":"_paused","reason":"rate_limited","attempt":2}"#
);§Cargo features
The schemars feature implements schemars::JsonSchema for the protocol
types. It is enabled by default to preserve the existing default API.
Consumers that only need serialization can disable default features to omit
the dependency and those trait implementations.
The uuid feature adds IdempotencyKey::generate to the v2 module, which
creates a key from a random UUID. It is off by default.
§Versioning
Stable protocol types are exposed through explicit version modules. For
example, use agent_client_protocol_schema::v1::SessionId for ACP protocol
version 1 types.
For the complete protocol specification and documentation, visit https://agentclientprotocol.com.
Modules§
- rpc
- JSON-RPC envelope types shared by ACP clients and agents.
- v1
- Agent Client Protocol version 1 types.
- v2
unstable_protocol_v2 - Agent Client Protocol version 2 types.
Structs§
- Index
Map - A hash table where the iteration order of the key-value pairs is independent of the hash values of the keys.
- Protocol
Version - Protocol version identifier.
Enums§
- Maybe
Undefined - Similar to
Option, but it has three states,undefined,nullandx. - Method
Dispatch Error - A failure to select or deserialize a method’s payload.
Traits§
- Into
Maybe Undefined - Utility trait for builder methods for optional values.
This allows the caller to either pass in the value itself without wrapping it in
Some, or to just pass in an Option if that is what they have, or set it back to undefined. - Into
Option - Utility trait for builder methods for optional values.
This allows the caller to either pass in the value itself without wrapping it in
Some, or to just pass in an Option if that is what they have.
