ACP protocol: v1 stable, v2 draft
ACP speaks JSON-RPC 2.0. Clients and agents MUST agree on a major version at initialize. New features usually arrive as optional capabilities, not a version bump. v2 is the first planned breaking major since v1.
v1 message flow
A typical local connection looks like this.
Initialize
Client sends initialize with its latest protocolVersion and clientCapabilities. Agent replies with the chosen version, agentCapabilities, agentInfo, and authMethods.
Authenticate
If authMethods is non-empty, the client calls authenticate (v1) before creating a session.
Open a session
session/new, or session/load / session/resume when the agent advertises those capabilities.
Prompt turn
session/prompt starts a turn. The agent streams session/update. The turn ends with a session/prompt result and a stopReason. session/cancel interrupts.
Methods you will actually implement
Names below are v1. File paths in the protocol MUST be absolute. Line numbers are 1-based.
Agent methods
| initialize | Required | Negotiate version, capabilities, and auth methods |
| authenticate | Optional | Authenticate when the agent advertises auth methods |
| logout | Optional | End the current authenticated state |
| session/new | Required | Create a conversation session |
| session/load | Optional | Load an existing session when loadSession is advertised |
| session/resume | Optional | Resume a session (stabilized; capability-gated in v1) |
| session/list | Optional | Discover existing sessions |
| session/close | Optional | Close an active session without deleting history |
| session/delete | Optional | Remove a session from history |
| session/prompt | Required | Send a user turn; response includes stopReason |
| session/cancel | Notification | Interrupt the current turn |
| session/set_mode | Optional | Switch agent operating modes |
| session/set_config_option | Optional | Set model and other session config selectors |
| $/cancel_request | Notification | Cancel any outstanding JSON-RPC request by id |
Client methods
| session/request_permission | Required | Ask the user to authorize a tool call |
| fs/read_text_file | Optional | Read workspace files |
| fs/write_text_file | Optional | Write workspace files |
| terminal/create | Optional | Create a client-hosted terminal |
| elicitation/create | Optional | Collect structured form or URL-mode input |
| session/update | Notification | Stream chunks, tool calls, plans, usage, and commands |
Headline v2 changes
If you only remember five things from the official migration guide:
auth/login + auth/logout
Renamed from authenticate / logout
session/resume
Required; session/load is removed
session/list + session/close
Required baseline session methods
session/prompt
Acknowledges acceptance; completion moves to state_update
fs/* and terminal/*
Removed from the client surface
session/set_mode
Removed; use session/set_config_option
Stabilized since the last site update
ACP now ships features through RFDs without waiting for a major version. These landed in the stable v1 docs.
Transports
Production ACP is still JSON-RPC over stdio to a local subprocess. Full remote-agent support is in progress. A Transports working group is drafting long-lived GET streams plus POST, with WebSocket upgrade on the same endpoint. Until that RFD stabilizes, HTTP layers are vendor-specific.
initialize (v1)
{
"jsonrpc": "2.0",
"id": 0,
"method": "initialize",
"params": {
"protocolVersion": 1,
"clientCapabilities": {
"fs": {
"readTextFile": true,
"writeTextFile": true
},
"terminal": true
},
"clientInfo": {
"name": "my-client",
"title": "My Client",
"version": "1.0.0"
}
}
}