What is ACP?
ACP (Agent Client Protocol) is an open JSON-RPC protocol for communication between a code editor or other interactive Client and a coding Agent. Stable v1 and draft v2 share this boundary but define different prompt, update, capability, session, filesystem, and terminal contracts.
Quick Facts
| Full Name | Agent Client Protocol |
|---|---|
| Specification | Official Specification |
How It Works
Stable v1 lifecycle
ACP v1 starts with initialize, negotiates an integer protocolVersion and capabilities, then creates or restores sessions. session/prompt remains pending for the turn, progress arrives through session/update, and the response ends the turn with a stop reason. Optional Client filesystem and terminal methods expose editor-owned resources, so path, process, credential, and output limits remain Client responsibilities.
Draft v2 migration
ACP v2 has a published baseline schema, but the protocol surface remains Draft. The prompt response now acknowledges message insertion with an Agent-owned messageId; state_update reports running, requires_action, and final idle. Updates become ID-addressed upserts, capabilities are reorganized, session/load is replaced by replay through session/resume, and Client filesystem and executable-terminal methods are removed.
Extensions and transport status
Capabilities such as elicitation, generic request cancellation, session management, usage updates, and optional programmatic Tool Call names have stabilized through separate RFDs. The programmatic name is metadata, not authorization. Streamable HTTP and WebSocket remain an active transport RFD, so remote support must be pinned and tested between exact implementations.
Security and evaluation boundary
ACP compatibility does not prove that code, commands, paths, or side effects are safe. Bind sessions to authenticated users and workspaces, validate paths and arguments, enforce authorization outside the model, constrain credentials, propagate cancellation, record effect states, and reconcile unknown outcomes. Test every supported version and capability matrix, including duplicate, reordered, partial, and unknown updates.
Key Characteristics
- Bidirectional JSON-RPC 2.0 contract between a user-facing Client and a coding Agent
- Stable v1 and draft v2 negotiate one integer wire version per connection
- v2 separates prompt insertion acknowledgment from foreground completion through state updates
- v2 uses ID-addressed upserts and forward-compatible tagged values
- v1 Client file and terminal methods do not carry into v2; Client-side tools move behind MCP
- Permission, transport, authentication, authorization, and side-effect recovery remain separate contracts
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
- Migrating an integration from stable v1 to draft v2 behind explicit feature flags
- Rendering messages, plans, Tool Calls, diffs, terminal output, usage, and foreground state in a native interface
- Restoring sessions and replaying updates without confusing transport delivery with durable completion
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 JSON-RPC contract for initialization, sessions, prompts, updates, permissions, cancellation, and negotiated features while keeping the model runtime and user interface independently replaceable.
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.
How does ACP v2 differ from v1?
Draft v2 acknowledges prompt insertion immediately and reports completion through `state_update`, uses ID-addressed upserts, reorganizes capabilities, replaces `session/load` with replayable `session/resume`, and removes v1 Client filesystem and executable-terminal methods. Implement both versions separately until the target compatibility matrix proves v2 support.
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?
Cancellation is a request to stop, not a rollback. In v1, the Agent returns a cancelled stop reason from the prompt request. In v2, it reports an idle `state_update` with that stop reason. Both versions still need effect journals and reconciliation for operations that may already have committed.