Agent Client Protocol: schema crates, version negotiation and what initialize actually settles

A wire format between editors and agents, hosted as a schema repository

The problem ACP addresses is narrow and real: an editor wants to drive a coding agent, and both sides are written by different teams. Without a shared format, every editor carries an adapter for every agent.

What this repository holds is the definition, not the implementation. The root Rust crate is agent-client-protocol-schema, sitting on crates.io, and it carries the data model for ACP wire messages: request, response, notification, the JSON-RPC envelope, and protocol-version types. A README line worth reading twice says to use that crate when you need direct access to ACP protocol types, schema-oriented tooling, or code generation inputs. Implementors of a Rust agent or client are pointed elsewhere, to the higher-level agent-client-protocol crate, which is described as the runtime API layer.

The repository layout mirrors that split. Alongside the schema crate you find schema/v1, schema/v2 and a schema-generator crate, and the Cargo.toml lists all four as default workspace members. Generated JSON Schema files live in the versioned schema directories, and the same .json files are attached to the schema-v* tags on GitHub, which the README calls the recommended download surface for SDK generators and automation. So the files a non-Rust implementor actually fetches are those attachments, not crates.

initialize negotiates the protocol version, and it is not the crate version

The stable ACP protocol version is 1. That number is negotiated at runtime during initialize through the protocolVersion field, and it is the only thing that settles wire compatibility.

The crate number tells a different story. The Rust crate is at v1.15.1, released on 2026-11-02 alongside Schema v1.29.1 and Schema v2.0.0-alpha.13, and the repository is not archived, with the last push on 2026-11-02. Those numbers describe the Rust crate and the JSON Schema artifacts, and the README states plainly that consumers should not infer wire compatibility from the crate or schema artifact version alone. Artifact versions manage compatibility with the repository's Rust and schema outputs; protocolVersion decides the shape of the messages on the wire.

The detail a skim misses is that two schema artifacts can describe the same wire-compatible protocol version while carrying different schema structure. One of them may reorganise, rename or re-emit definitions in a way that matters to a code generator without changing anything a client and agent exchange. The version field inside the versioned schema/*/meta*.json files tracks the protocol version that schema represents, not the schema's own layout.

Four generator combinations behind one npm script set

package.json names the generator combinations. The stable target is a cargo run -p schema-generator. The unstable and unstable_protocol_v2 cargo features produce alternative outputs:

npm run generate:json-schema
npm run generate:json-schema:v2

The generate script chains all four targets together, then runs prettier --write --log-level warn. and cargo fmt. Two further scripts cover registry documentation and spelling: generate:registry runs scripts/generate_registry_docs.py through python3, and spellcheck calls ./scripts/spellcheck.sh, with a --write-changes variant. format:check is the CI-facing pair, prettier --check. plus cargo fmt -- --check.

The check script is where the project's own lint policy shows up. It runs cargo clippy, then a narrower pass with --no-default-features --features unstable,unstable_protocol_v2,tracing on the schema crate alone, then cargo clippy --all-targets --all. Cargo.toml enforces that policy as workspace lints: exhaustive_enums, exhaustive_structs and the pedantic group are warnings, not suggestions, and missing_docs and missing_debug_implementations are too. A contributor adding a variant to an enum will meet the linter before the reviewer does.

Where to get ACP when the README carries no install command

The README has no install snippet. What the README gives instead is a set of named destinations.

For direct protocol types in Rust, the crate is agent-client-protocol-schema on crates.io. For a Rust agent or client, the runtime crate is agent-client-protocol, also on crates.io, with runnable examples at examples/agent.rs and examples/client.rs in the rust-sdk repository. Java, Kotlin, Python and TypeScript each have their own official SDK repository: acp-kotlin, java-sdk, python-sdk and the npm package @agentclientprotocol/sdk. The Kotlin entry adds a platform caveat, JVM supported with other targets in progress.

For a language with no official SDK, the download surface is the schema artifact. Take the versioned .json files from schema/v1 or schema/v2, or from the matching schema-v* attachments on GitHub, and point a generator at them. Lists of agents and clients that already implement ACP live on the agentclientprotocol.com site under overview, alongside a community libraries page, which is the place to check whether a maintainer is already shipping the binding you were about to write.

Capabilities, not the version number, decide which optional messages arrive

Once initialize settles the protocol version, the second half of the negotiation does the practical work. The README instructs consumers to use the exchanged capabilities to decide which optional ACP messages and features are supported, and to reserve the negotiated protocolVersion for the breaking-compatibility level.

That ordering matters because a pair of endpoints can agree on protocol version 1 and still expose entirely different message sets. Version answers whether the grammar matches; capabilities answer whether the optional half of the grammar exists. An editor that relies on an optional message has to gate that code on what initialize actually returned, not on a constant in the source.

This is also the part with no tooling behind it in this repository. The npm scripts generate schema and registry files, and clippy governs the Rust side. Nothing in package.json produces a capability matrix, and the repository has no test fixture directory at its top level to tell an implementor what a well-behaved capability response looks like beyond the schema definition itself.

Where ACP stops and Model Context Protocol begins

The difference in approach is scope, not quality. ACP standardises one edge: the conversation between a code editor and a coding agent. Model Context Protocol addresses a different edge, tool and data access for models. An editor can speak ACP to an agent while that agent reaches external resources over MCP,. They are not competing layers.

The boundary shows up in the type surface. agent-client-protocol-schema describes request, response, notification, the JSON-RPC envelope and protocol-version types. That is a session contract between two processes the user is looking at. A tool-calling protocol has to describe schemas for arbitrary external data, which is a different and much wider problem.

For teams already committed to a direct, in-process agent API, the honest cost of ACP is real: you take on version negotiation, capability handling and a cadence you do not control. The compensating benefit is the agent and client listings on agentclientprotocol.com, which is only worth something because more than one side agreed to the same edge.

The registry and the SDKs live outside this repository

A repository that defines a protocol usually does not ship the ecosystem. This one does not. The root Cargo.toml workspace holds the schema crate, schema/v1, schema/v2 and the generator, nothing else, and the languages listed as official each have a separate repository: acp-kotlin, java-sdk, python-sdk, the rust-sdk carrying agent-client-protocol, and the npm package @agentclientprotocol/sdk.

The agent and client directories live on the website instead, at agentclientprotocol.com under overview, with a community libraries page beside them. That split has a practical consequence. If you are evaluating whether a language has an ACP binding, the crates.io and npm pages do not tell you, and neither does the Cargo.toml. You have to look at the website or at the language repository.

The same split shows up in what gets versioned. This repository guarantees the message definitions. The Kotlin SDK says JVM is supported and other targets are in progress, a status the schema crate cannot express and cannot fix. Treat the schema as the contract and everything pointing at it as something you verify on your own.

Editorial conclusion

Adopt the schema artifacts if you are generating a client or agent SDK in a language the official list does not cover, and verify first that your generator handles the definitions layout in the schema release you pin, because a schema bump can reorganise definitions without changing a single wire message. Do not adopt it if you need an off-the-shelf runtime; the README points Rust implementors to the separate agent-client-protocol crate on crates.io, and the other official SDKs live in their own repositories. First check the capabilities exchanged during initialize against the optional ACP messages your editor already expects, since the negotiated protocolVersion alone does not tell you which features are present.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes