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

​
Message Flow

A typical flow follows this pattern:
1

Initialization Phase

  • Client → Agent: initialize to establish connection
  • Client → Agent: authenticate if required by the Agent
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
  • 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

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

​
Optional Methods

​
session/load
Schema
Load an existing session (requires loadSession capability).

​
Notifications

​
session/cancel
Schema
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

​
session/request_permission
Schema
Request user authorization for tool calls.

​
Optional Methods

​
fs/read_text_file
Schema
Read file contents (requires fs.readTextFile capability).
​
fs/write_text_file
Schema
Write file contents (requires fs.writeTextFile capability).

​
Notifications

​
session/update
Schema
Send progress updates during prompt processing (no response expected).

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

​
Next Steps