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: Request-response pairs that expect a result or error
  • Notifications: One-way messages that don’t expect a response
ACP follows JSON-RPC 2.0 batch behavior. See Transports for batch handling requirements.

​
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 advisory notices
  • Agent → Client: Permission requests as needed
  • Client → Agent: session/cancel to interrupt processing if needed
  • Agent → Client: An idle state_update when ready for a new prompt, with a stop reason when foreground work ends.

​
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 belong to optional surfaces. An Agent that returns one or more valid entries in authMethods MUST implement both auth/login and auth/logout. If authMethods is omitted or empty, Clients MUST NOT call either method.
​
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.

​
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 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, and config option updates, and advisory notices.

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

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

The protocol provides built-in mechanisms for adding custom functionality while maintaining compatibility:
  • Add custom data using _meta fields
  • Create custom methods by prefixing their name with underscore (_)
  • Advertise custom capabilities during initialization
Learn about protocol extensibility to understand how to use these mechanisms.

​
Next Steps