Skip to main content
The Agent Client Protocol allows Agents and Clients to communicate by exposing methods that each side can call and sending notifications to inform each other of events.

Communication Model

The protocol follows the JSON-RPC 2.0 specification with two types of messages:
  • Methods are request-response pairs that expect a result or error.
  • Notifications are one-way messages that don’t expect a response.
Unlike base JSON-RPC, request IDs MUST be a string or an integer, never null. An error response has id: null only when the request ID could not be determined. Both sides send requests, and each side chooses IDs for its own requests independently, so the same ID can be in use in both directions. A sender MUST NOT reuse an ID while a request with that ID is still awaiting a response. Unlike base JSON-RPC, ACP does not use batches. See Transports.

Message flow

A typical flow follows this pattern:
1

Initialization Phase

  • Client → Agent: initialize to establish connection
  • Client: completes an advertised authentication flow if required. For example, auth/login for an Agent-handled method or launch and reconnect for a terminal method
2

Session Setup - either:

  • Client → Agent: session/new to create a new session
  • Client → Agent: session/resume to resume an existing session
3

Prompt Lifecycle

  • Client → Agent: session/prompt to send user message
  • Agent → Client: session/prompt response once the prompt is accepted
  • Agent → Client: session/update notifications for accepted messages, state updates, progress updates, and user-facing notices
  • Agent → Client: Permission requests as needed
  • Client → Agent: session/cancel to cancel foreground work if needed
  • Agent → Client: An idle state_update with a stop reason when foreground work ends, even if background activity continues

Agent

Agents are programs that use generative AI to autonomously modify code. They typically run as subprocesses of the Client.

Baseline methods

Some baseline methods are optional as a group. An Agent that returns a non-empty authMethods list MUST implement both auth/login and auth/logout. If authMethods is omitted or empty, Clients MUST NOT call either method. The session/* methods require capabilities.session.
Negotiate versions and exchange capabilities..
Authenticate with the Agent (if required).
End the current authenticated state.
Create a new conversation session.
Send user prompts to the Agent.
List known sessions.
Resume an existing session, optionally replaying history.
Close an active session.

Optional methods

Change a session configuration option (required when the Agent advertises config options).
Delete a session (requires the session.delete capability).

Notifications

Cancel the session’s foreground work (no response expected).

Client

Clients provide the interface between users and agents. They are typically code editors (IDEs, text editors) but can also be other UIs for interacting with agents. Clients manage the environment, handle user interactions, and control access to resources.

Baseline methods

Request user authorization for operations such as tool calls and commands.

Optional methods

Request structured information from the user (requires the matching elicitation mode capability).

Notifications

Report completion of an out-of-band URL interaction (no response expected).
Send session updates to inform the Client of changes (no response expected). This includes message updates and chunks, tool calls, updates, and content chunks, display-only terminal state and output chunks, plans, available commands updates, config option updates, context compactions, user-facing notices, and unstable prompt suggestions.

Request cancellation

Either side can send $/cancel_request to cancel a request it sent (no response expected).

Argument requirements

  • All file paths in the protocol MUST be absolute, in the native syntax of the machine the Agent runs on (for example /home/user/project, C:\Users\user\project, or \\server\share\project), and are not URIs.
  • Line numbers are 1-based

Error handling

All methods follow standard JSON-RPC 2.0 error handling:
  • Successful responses include a result field
  • Errors include an error object with code and message
  • Notifications never receive responses (success or error)
See Errors for the error codes ACP uses and when to use them.

Conventions

Unless explicitly defined otherwise in the schema, ACP-defined JSON object property keys use camelCase. String values carried by discriminator fields use snake_case. The JSON-RPC envelope fields (jsonrpc, id, method, params, result, and error) follow the JSON-RPC 2.0 specification. For an optional field whose schema allows null, omitting it and setting it to null are equivalent, unless the field says otherwise. Optional fields whose schema does not allow null, such as most arrays and objects, are omitted rather than sent as null. Upsert updates are the exception: there an omitted field leaves the stored value unchanged and null clears it. Selected enum-like fields and tagged unions can define custom or future fallbacks. For those fields, _-prefixed values are reserved for implementation-specific extensions, while unknown non-underscore values are reserved for future ACP variants.

Extensibility

Implementations can extend the protocol without breaking compatibility:
  • Add custom data using _meta fields
  • Create custom methods by prefixing their name with underscore (_)
  • Advertise custom capabilities during initialization
See Extensibility for details.

Unstable features

The draft schema also defines experimental features that may change or be removed before they stabilize. Each is negotiated separately, as described in Experimental Features and Negotiation. Where the draft pages don’t describe a feature yet, its RFD is the reference.

Next steps