What is ACP?
ACP (Agent Client Protocol) is an open protocol that standardizes bidirectional communication between a code editor or other interactive Client and a coding Agent, including session lifecycle, streamed updates, permission requests, and optional filesystem and terminal operations.
Quick Facts
| Full Name | Agent Client Protocol |
|---|---|
| Specification | Official Specification |
How It Works
ACP defines the integration boundary between a user-facing Client and a coding Agent. The Client is usually an IDE or editor that owns the interface and access to local resources. The Agent receives prompts, coordinates model and tool work, and reports messages, plans, tool calls, diffs, terminal output, and completion state. ACP uses JSON-RPC 2.0 methods for request-response exchanges and notifications for one-way events.
Every v1 connection starts with initialize. The peers negotiate the integer wire-protocol version and advertise optional capabilities; an omitted capability is unsupported. The Client then creates a session with session/new or, when advertised, restores one with session/load or session/resume. A prompt turn starts with session/prompt, streams progress through session/update, and ends when the original request returns a stop reason such as end_turn, refusal, or cancelled.
ACP is bidirectional. The Client calls Agent methods for initialization and session work, while the Agent can call Client methods such as session/request_permission, fs/read_text_file, fs/write_text_file, and terminal/create when the corresponding capabilities were negotiated. This lets an Agent read unsaved editor content, present native permission choices, display structured diffs, and attach live terminal output without making the Agent process the owner of the editor UI.
ACP does not define model behavior, guarantee safe code, or turn a permission dialog into backend authorization. Clients should bind every session to an explicit absolute working directory, restrict additional roots, validate all paths, cap terminal output, isolate subprocess credentials, and display the real operation before consequential changes. Agents must still validate tool inputs, enforce budgets, propagate cancellation, record effects, and reconcile writes whose result becomes unknown after a timeout or process failure.
ACP and MCP solve different interoperability problems. ACP connects the coding interface to the Agent runtime; MCP connects an AI application or Agent to tools, resources, and prompts. ACP can pass MCP server configurations during session setup, but that does not merge the protocols or transfer authorization. A2A addresses communication between independently operated Agents, while LSP serves language intelligence such as diagnostics and symbol navigation. These boundaries can be composed, but none substitutes for the others.
Key Characteristics
- Bidirectional JSON-RPC 2.0 contract between a user-facing Client and a coding Agent
- Version and capability negotiation through the mandatory initialize method
- Session lifecycle with creation, prompting, streaming updates, cancellation, and optional load or resume
- Client-provided filesystem, terminal, elicitation, and permission interfaces gated by advertised capabilities
- Structured Agent output for messages, plans, tool status, file locations, diffs, usage, and terminal streams
- Extensibility through namespaced custom methods, metadata, and explicitly advertised capabilities
Common Use Cases
- Connecting one coding-agent runtime to multiple IDEs without maintaining a bespoke integration for every editor
- Embedding a local command-line coding Agent in an editor through a supervised subprocess
- Rendering Agent plans, tool progress, file diffs, and terminal output in a native development interface
- Allowing an Agent to read unsaved buffers or write files through Client-controlled filesystem methods
- Restoring or resuming independent coding sessions when both implementations advertise the required capability
Example
Loading code...Frequently Asked Questions
What problem does ACP solve?
ACP removes the need for a separate integration between every coding Agent and every editor. It gives both sides a shared contract for initialization, sessions, prompts, streamed updates, permissions, files, terminals, and cancellation while allowing implementations to negotiate optional features.
How is ACP different from MCP?
ACP connects an IDE or other interactive Client to a coding Agent and carries the user-facing session. MCP connects an AI application or Agent to external tools, resources, and prompts. An ACP session may provide MCP server configurations to the Agent, but ACP permission choices do not replace authorization inside an MCP Server.
Does ACP v1 require every Client to expose files and terminals?
No. Filesystem, terminal, elicitation, session-loading, and other features are capability-gated. An implementation must treat an omitted capability as unsupported and must not call the associated optional method.
Does an ACP permission response make a tool call secure?
No. A Client permission choice communicates user intent for the displayed operation. The Agent and downstream service must still validate arguments, authenticate the principal, authorize the tenant and object, constrain credentials, handle duplicate effects, and preserve an audit record.
How should ACP cancellation be implemented?
The Client sends the `session/cancel` notification, resolves pending permission requests as cancelled, and marks unfinished tool calls accordingly. The Agent should stop model and tool work as soon as possible, send any final updates before completing the prompt request, and return the `cancelled` stop reason rather than an opaque transport error.