▸ Agent Skills
6 min read

Documentation Index

Fetch the complete documentation index at: https://agentclientprotocol.com/llms.txt Use this file to discover all available pages before exploring further.

Overview

How the Agent Client Protocol works

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:

<Steps> * Client → Agent: initialize to establish connection * Client → Agent: authenticate if required by the Agent

* Client → Agent: `session/new` to create a new session * Client → Agent: `session/load` to resume an existing session if supported * 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

<ResponseField name=“initialize” post={[Schema]}> Negotiate versions and exchange capabilities..

<ResponseField name=“authenticate” post={[Schema]}> Authenticate with the Agent (if required).

<ResponseField name=“session/new” post={[Schema]}> Create a new conversation session.

<ResponseField name=“session/prompt” post={[Schema]}> Send user prompts to the Agent.

Optional Methods

<ResponseField name=“session/load” post={[Schema]}> Load an existing session (requires loadSession capability).

<ResponseField name=“logout” post={[Schema]}> End the current authenticated state (requires agentCapabilities.auth.logout capability).

<ResponseField name=“session/set_mode” post={[Schema]}> Switch between agent operating modes.

Notifications

<ResponseField name=“session/cancel” post={[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

<ResponseField name=“session/request_permission” post={[Schema]}> Request user authorization for tool calls.

Optional Methods

<ResponseField name=“fs/read_text_file” post={[Schema]}> Read file contents (requires fs.readTextFile capability).

<ResponseField name=“fs/write_text_file” post={[Schema]}> Write file contents (requires fs.writeTextFile capability).

<ResponseField name=“terminal/create” post={[Schema]}> Create a new terminal (requires terminal capability).

<ResponseField name=“terminal/output” post={[Schema]}> Get terminal output and exit status (requires terminal capability).

<ResponseField name=“terminal/release” post={[Schema]}> Release a terminal (requires terminal capability).

<ResponseField name=“terminal/wait_for_exit” post={[Schema]}> Wait for terminal command to exit (requires terminal capability).

<ResponseField name=“terminal/kill” post={[Schema]}> Kill terminal command without releasing (requires terminal capability).

<ResponseField name=“elicitation/create” post={[Schema]}> Request structured information from the user (requires the matching elicitation mode capability).

Notifications

<ResponseField name=“elicitation/complete” post={[Schema]}> Report completion of an out-of-band URL interaction (no response expected).

<ResponseField name=“session/update” post={[Schema]}> Send session updates to inform the Client of changes (no response expected). This includes: - Message chunks (agent, user, thought) - Tool calls and updates - Plans - Available commands updates

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.

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

Last updated Oct 08, 2026