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.

​
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, authenticate 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/load to resume an existing session if supported
3

Prompt Turn

  • Client → Agent: session/prompt to send user message
  • Agent → Client: session/update notifications for progress updates and user-facing notices
  • Agent → Client: File operations or permission requests as needed
  • Client → Agent: session/cancel to interrupt processing if needed
  • Turn ends and the Agent sends the session/prompt response with a stop reason

​
Agent

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

​
Baseline methods

​
Negotiate versions and exchange capabilities..
​
Authenticate with the Agent (if required).
​
Create a new conversation session.
​
Send user prompts to the Agent.

​
Optional methods

​
Load an existing session (requires loadSession capability).
​
End the current authenticated state (requires agentCapabilities.auth.logout capability).
​
Switch between agent operating modes.

​
Notifications

​
Cancel ongoing operations (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 tool calls.

​
Optional methods

​
Read file contents (requires fs.readTextFile capability).
​
Write file contents (requires fs.writeTextFile capability).
​
Create a new terminal (requires terminal capability).
​
Get terminal output and exit status (requires terminal capability).
​
Release a terminal (requires terminal capability).
​
Wait for terminal command to exit (requires terminal capability).
​
Kill terminal command without releasing (requires terminal capability).
​
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:

​
Argument requirements

  • All file paths in the protocol MUST be absolute.
  • 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.

​
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.

​
Next steps