ACP Python SDK

agent-client-protocol is the official Python SDK for the Agent Client Protocol (ACP), the JSON-RPC-based protocol that Zed and other editors use to talk to coding agents. It ships generated Pydantic models that track every upstream ACP schema release, so requests and notifications stay type-safe and valid without hand-maintained bindings.

On top of the generated schema, the SDK provides async connection classes for both sides of the wire — AgentSideConnection for building an agent and ClientSideConnection for building an editor or client integration — plus stdio, HTTP, and WebSocket transport implementations. A helpers module mirrors the API shape of the official Go and TypeScript SDKs, giving Python authors the same builder functions for content blocks, tool calls, and session updates.

The package also includes contrib utilities (session accumulators, tool-call trackers, permission brokers) drawn from real ACP deployments, and a set of runnable examples covering streaming responses, permission flows, a Gemini bridge, and a duet (agent-to-agent) demo. It targets teams building custom coding agents or wiring existing CLIs into ACP-compatible editors like Zed.

What You Get

• Generated Pydantic models in acp.schema that track every upstream ACP protocol release, keeping request/response payloads type-checked and valid.
• AgentSideConnection and ClientSideConnection classes that implement the asyncio JSON-RPC lifecycle for each side of the protocol.
• Multiple transports — stdio (the default for editor-launched agents), plus experimental Streamable HTTP and WebSocket transports for remote setups.
• A helpers module mirroring the Go/TypeScript SDK builder functions for content blocks, tool calls, plan entries, and session updates.
• Contrib utilities — session-state accumulators, tool-call trackers, and permission brokers — extracted from real ACP agent deployments.
• Runnable examples covering streaming, permission requests, a Gemini API bridge, and an agent-to-agent duet demo.

Common Use Cases

• Building a custom coding agent that editors like Zed can launch over stdio and drive through ACP.
• Wrapping an existing CLI-based AI tool so it speaks ACP without rewriting its core logic.
• Implementing the client side of ACP inside a Python-based editor, IDE plugin, or terminal UI.
• Prototyping permission flows, streaming tool-call updates, or multi-agent orchestration against a stable, generated protocol schema.

Under The Hood

Architecture The package mirrors the upstream ACP Rust implementation’s module layout: acp/schema.py holds generated Pydantic models for every protocol message, acp/connection.py implements the shared JSON-RPC Connection/MethodHandler machinery, and acp/agent/connection.py and acp/client/connection.py layer agent- and client-specific dispatch on top via AgentSideConnection and ClientSideConnection. acp/core.py is an explicit compatibility shim that re-exports from these newer homes so older imports keep working. Transport concerns are isolated in acp/_transport.py, acp/stdio.py, acp/http/, and acp/ws/, so swapping stdio for HTTP or WebSocket touches only the transport layer, not the connection or schema code — a clean separation that would make it straightforward to add a new transport without touching protocol logic.

Tech Stack The SDK is pure Python (3.10–3.14) built on Pydantic 2.7+ for schema validation and code generation (datamodel-code-generator regenerates schema.py from the upstream JSON schema via make gen-all). Optional extras add httpx/websockets for the experimental HTTP and WebSocket transports and logfire/opentelemetry-sdk for telemetry. The project builds with pdm-backend and is managed end-to-end with uv, including a committed lockfile.

Code Quality The tests/ directory contains 145+ test functions across dedicated modules for core connection behavior, RPC dispatch, deserialization, unstable-protocol handling, connection recovery, and golden-fixture compatibility checks, run via pytest with pytest-asyncio. make check runs Ruff (formatting and a wide lint rule set including bandit-derived security checks), the ty type checker, and dependency hygiene via deptry, all wired into GitHub Actions CI on push. Error handling is explicit and typed through a dedicated RequestError/exceptions.py module rather than bare exceptions.

What Makes It Unique Rather than hand-maintaining protocol bindings, the SDK treats the upstream ACP JSON schema as the source of truth and regenerates its entire model surface from it, which keeps a Python implementation in lockstep with the Rust/TypeScript/Go SDKs as the protocol evolves. Pairing that generated core with hand-written ergonomic helpers — mirroring the other official SDKs’ builder APIs — and contrib utilities sourced from real deployments gives it a level of practical polish that goes beyond a bare protocol binding.