agentclientprotocol/agent-client-protocol

Agent Client Protocol (ACP)

What it is – ACP is a standardized, language‑agnostic protocol that lets a code editor talk to a coding agent – a program that uses generative AI to read, write, and refactor source code automatically. The protocol defines the JSON‑RPC‑style messages (requests, responses, notifications) that flow between the two sides and includes version negotiation so that editors and agents can evolve without breaking each other.

Why it matters – As AI‑powered “pair‑programmer” tools proliferate (e.g., GitHub Copilot, Cursor, Code Llama‑based assistants), each vendor has historically invented its own ad‑hoc API. ACP provides a common contract so that:

• Editors can support many agents with a single integration layer.
• Agents can be written once and run inside any editor that implements ACP.
• SDKs in multiple languages can generate type‑safe client/agent code from the same JSON‑Schema definition.

Core artifacts

• Rust crate agent-client-protocol-schema – the low‑level Rust types that mirror the wire format (messages, envelopes, version info). Use this when you need direct access to the schema or want to generate code for other languages.
• Rust crate agent-client-protocol – a higher‑level runtime that implements the client and agent sides, handling connection setup, message routing, and capability negotiation.
• JSON‑Schema files – versioned schemas live under schema/v1/ and schema/v2/. Each release bundles the .json files as GitHub assets, which SDK generators (Kotlin, Java, Python, TypeScript, etc.) consume to produce language‑specific libraries.

Versioning model

• The protocol version (currently 1) is negotiated at runtime via the initialize request’s protocolVersion field. This determines the shape of the messages that can be exchanged.
• The crate and schema release numbers are independent of wire compatibility; they only reflect changes to the Rust API or to the layout of the JSON‑Schema files. Compatibility is decided by the negotiated protocol version and the capabilities advertised by each side.

Official SDKs

Language	Repo	Highlights
Kotlin	acp-kotlin	JVM support, sample client/agent projects
Java	java-sdk	Maven/Gradle artifacts, examples
Python	python-sdk	pip package, quick‑start scripts
Rust	agent-client-protocol	Crates.io packages, example agent.rs / client.rs
TypeScript	@agentclientprotocol/sdk	npm package, browser & Node examples

Typical workflow

1. Choose a language SDK that matches your editor or agent implementation.
2. Generate or import the SDK (most are published on crates.io, Maven Central, PyPI, npm, etc.).
3. Implement the client side in the editor: register for notifications (e.g., codeChange, applyEdits) and send requests like generateCode or refactor.
4. Implement the agent side: receive requests, invoke a generative‑AI model, and reply with edits or diagnostics.
5. Negotiate capabilities during the initialize exchange so both sides know which optional messages are supported.

Getting started

• Rust: cargo add agent-client-protocol → run the examples in rust-sdk/examples/ to see a minimal client and agent communicating over stdin/stdout.
• Python: pip install agentclientprotocol → follow the examples/ folder in the Python SDK repo.
• Java/Kotlin/TypeScript: clone the respective SDK repo, build with the standard toolchain, and run the provided sample projects.

Community & contributions

• The protocol is deliberately open; anyone can propose extensions via the GitHub issue tracker and the formal contribution process described in CONTRIBUTING.md.
• No CLA is required; contributions are licensed under Apache 2.0.
• A list of community‑maintained libraries is available at the official website.

Who should care?

• Editor developers (VS Code, JetBrains, Neovim, etc.) who want a plug‑and‑play way to add AI coding assistants.
• AI agent builders who want their service to be usable across many development environments without writing a custom editor integration.
• Tooling authors creating code‑analysis, linting, or refactoring utilities that can be driven by AI agents.

---

TL;DR – ACP is a cross‑language protocol that standardizes how code editors and generative‑AI coding agents exchange JSON‑RPC messages. The repo hosts the authoritative Rust schema crate, versioned JSON‑Schema files, and links to official SDKs in Kotlin, Java, Python, Rust, and TypeScript, enabling a unified ecosystem for AI‑assisted programming.