agent-client-protocol/docs/protocol/draft/schema.mdx at e3c9cbf30ded09d930dffd06f076877f3d37c1a2 · agentclientprotocol/agent-client-protocol

title	Schema
description	Schema definitions for the Agent Client Protocol

Agent

Defines the interface that all ACP-compliant agents must implement.

Agents are programs that use generative AI to autonomously modify code. They handle requests from clients and execute tasks using language models and tools.

authenticate

Authenticates the client using the specified authentication method.

Called when the agent requires authentication before allowing session creation. The client provides the authentication method ID that was advertised during initialization.

After successful authentication, the client can proceed to create sessions with new_session without receiving an auth_required error.

See protocol docs: Initialization

AuthenticateRequest

Request parameters for the authenticate method.

Specifies which authentication method to use.

Type: Object

Properties:

<ResponseField name="_meta" type={"object | null"} > The _meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys.

See protocol docs: Extensibility

The ID of the authentication method to use. Must be one of the methods advertised in the initialize response.

AuthenticateResponse

Response to the authenticate method.

Type: Object

Properties:

See protocol docs: Extensibility

initialize

Establishes the connection with a client and negotiates protocol capabilities.

This method is called once at the beginning of the connection to:

Negotiate the protocol version to use
Exchange capability information between client and agent
Determine available authentication methods

The agent should respond with its supported protocol version and capabilities.

See protocol docs: Initialization

InitializeRequest

Request parameters for the initialize method.

Sent by the client to establish connection and negotiate capabilities.

See protocol docs: Initialization

Type: Object

Properties:

See protocol docs: Extensibility

ClientCapabilities} > Capabilities supported by the client.

- Default: `{"auth":{"terminal":false},"fs":{"readTextFile":false,"writeTextFile":false},"terminal":false}`

Implementation | null} > Information about the Client name and version sent to the Agent.

Note: in future versions of the protocol, this will be required.

ProtocolVersion} required> The latest protocol version supported by the client.

InitializeResponse

Response to the initialize method.

Contains the negotiated protocol version and agent capabilities.

See protocol docs: Initialization

Type: Object

Properties:

See protocol docs: Extensibility

AgentCapabilities} > Capabilities supported by the agent.

- Default: `{"auth":{},"loadSession":false,"mcpCapabilities":{"http":false,"sse":false},"promptCapabilities":{"audio":false,"embeddedContext":false,"image":false},"sessionCapabilities":{}}`

Implementation | null} > Information about the Agent name and version sent to the Client.

Note: in future versions of the protocol, this will be required.

AuthMethod[]} > Authentication methods supported by the agent.

- Default: `[]`

ProtocolVersion} required> The protocol version the client specified if supported by the agent, or the latest protocol version supported by the agent.

The client should disconnect, if it doesn't support this version.

logout

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Logs out of the current authenticated state.

After a successful logout, all new sessions will require authentication. There is no guarantee about the behavior of already running sessions.

LogoutRequest

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Request parameters for the logout method.

Terminates the current authenticated session.

Type: Object

Properties:

See protocol docs: Extensibility

LogoutResponse

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Response to the logout method.

Type: Object

Properties:

See protocol docs: Extensibility

session/cancel

Cancels ongoing operations for a session.

This is a notification sent by the client to cancel an ongoing prompt turn.

Upon receiving this notification, the Agent SHOULD:

Stop all language model requests as soon as possible
Abort all tool call invocations in progress
Send any pending session/update notifications
Respond to the original session/prompt request with StopReason::Cancelled

See protocol docs: Cancellation

CancelNotification

Notification to cancel ongoing operations for a session.

See protocol docs: Cancellation

Type: Object

Properties:

See protocol docs: Extensibility

SessionId} required> The ID of the session to cancel operations for.

session/close

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Closes an active session and frees up any resources associated with it.

This method is only available if the agent advertises the session.close capability.

The agent must cancel any ongoing work (as if session/cancel was called) and then free up any resources associated with the session.

CloseSessionRequest

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Request parameters for closing an active session.

If supported, the agent must cancel any ongoing work related to the session (treat it as if session/cancel was called) and then free up any resources associated with the session.

Only available if the Agent supports the session.close capability.

Type: Object

Properties:

See protocol docs: Extensibility

SessionId} required> The ID of the session to close.

CloseSessionResponse

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Response from closing a session.

Type: Object

Properties:

See protocol docs: Extensibility

session/fork

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Forks an existing session to create a new independent session.

This method is only available if the agent advertises the session.fork capability.

The agent should create a new session with the same conversation context as the original, allowing operations like generating summaries without affecting the original session's history.

ForkSessionRequest

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Request parameters for forking an existing session.

Creates a new session based on the context of an existing one, allowing operations like generating summaries without affecting the original session's history.

Only available if the Agent supports the session.fork capability.

Type: Object

Properties:

See protocol docs: Extensibility

The working directory for this session. McpServer[]} > List of MCP servers to connect to for this session. SessionId} required> The ID of the session to fork.

ForkSessionResponse

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Response from forking an existing session.

Type: Object

Properties:

See protocol docs: Extensibility

SessionConfigOption[] | null} > Initial session configuration options if supported by the Agent. SessionModelState | null} > **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Initial model state if supported by the Agent

SessionModeState | null} > Initial mode state if supported by the Agent

See protocol docs: Session Modes

SessionId} required> Unique identifier for the newly created forked session.

session/list

Lists existing sessions known to the agent.

This method is only available if the agent advertises the sessionCapabilities.list capability.

The agent should return metadata about sessions with optional filtering and pagination support.

ListSessionsRequest

Request parameters for listing existing sessions.

Only available if the Agent supports the sessionCapabilities.list capability.

Type: Object

Properties:

See protocol docs: Extensibility

Opaque cursor token from a previous response's nextCursor field for cursor-based pagination Filter sessions by working directory. Must be an absolute path.

ListSessionsResponse

Response from listing sessions.

Type: Object

Properties:

See protocol docs: Extensibility

Opaque cursor token. If present, pass this in the next request's cursor parameter to fetch the next page. If absent, there are no more results. SessionInfo[]} required> Array of session information objects

session/load

Loads an existing session to resume a previous conversation.

This method is only available if the agent advertises the loadSession capability.

The agent should:

Restore the session context and conversation history
Connect to the specified MCP servers
Stream the entire conversation history back to the client via notifications

See protocol docs: Loading Sessions

LoadSessionRequest

Request parameters for loading an existing session.

Only available if the Agent supports the loadSession capability.

See protocol docs: Loading Sessions

Type: Object

Properties:

See protocol docs: Extensibility

The working directory for this session. McpServer[]} required> List of MCP servers to connect to for this session. SessionId} required> The ID of the session to load.

LoadSessionResponse

Response from loading an existing session.

Type: Object

Properties:

See protocol docs: Extensibility

SessionConfigOption[] | null} > Initial session configuration options if supported by the Agent. SessionModelState | null} > **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Initial model state if supported by the Agent

SessionModeState | null} > Initial mode state if supported by the Agent

See protocol docs: Session Modes

session/new

Creates a new conversation session with the agent.

Sessions represent independent conversation contexts with their own history and state.

The agent should:

Create a new session context
Connect to any specified MCP servers
Return a unique session ID for future requests

May return an auth_required error if the agent requires authentication.

See protocol docs: Session Setup

NewSessionRequest

Request parameters for creating a new session.

See protocol docs: Creating a Session

Type: Object

Properties:

See protocol docs: Extensibility

The working directory for this session. Must be an absolute path. McpServer[]} required> List of MCP (Model Context Protocol) servers the agent should connect to.

NewSessionResponse

Response from creating a new session.

See protocol docs: Creating a Session

Type: Object

Properties:

See protocol docs: Extensibility

SessionConfigOption[] | null} > Initial session configuration options if supported by the Agent. SessionModelState | null} > **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Initial model state if supported by the Agent

SessionModeState | null} > Initial mode state if supported by the Agent

See protocol docs: Session Modes

SessionId} required> Unique identifier for the created session.

Used in all subsequent requests for this conversation.

session/prompt

Processes a user prompt within a session.

This method handles the whole lifecycle of a prompt:

Receives user messages with optional context (files, images, etc.)
Processes the prompt using language models
Reports language model content and tool calls to the Clients
Requests permission to run tools
Executes any requested tool calls
Returns when the turn is complete with a stop reason

See protocol docs: Prompt Turn

PromptRequest

Request parameters for sending a user prompt to the agent.

Contains the user's message and any additional context.

See protocol docs: User Message

Type: Object

Properties:

See protocol docs: Extensibility

**UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

A client-generated unique identifier for this user message.

If provided, the Agent SHOULD echo this value as userMessageId in the PromptResponse to confirm it was recorded. Both clients and agents MUST use UUID format for message IDs.

ContentBlock[]} required> The blocks of content that compose the user's message.

As a baseline, the Agent MUST support ContentBlock::Text and ContentBlock::ResourceLink, while other variants are optionally enabled via PromptCapabilities.

The Client MUST adapt its interface according to PromptCapabilities.

The client MAY include referenced pieces of context as either ContentBlock::Resource or ContentBlock::ResourceLink.

When available, ContentBlock::Resource is preferred as it avoids extra round-trips and allows the message to include pieces of context from sources the agent may not have access to.

SessionId} required> The ID of the session to send this user message to

PromptResponse

Response from processing a user prompt.

See protocol docs: Check for Completion

Type: Object

Properties:

See protocol docs: Extensibility

StopReason} required> Indicates why the agent stopped processing the turn. Usage | null} > **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Token usage for this turn (optional).

**UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

The acknowledged user message ID.

If the client provided a messageId in the PromptRequest, the agent echoes it here to confirm it was recorded. If the client did not provide one, the agent MAY assign one and return it here. Absence of this field indicates the agent did not record a message ID.

session/resume

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Resumes an existing session without returning previous messages.

This method is only available if the agent advertises the session.resume capability.

The agent should resume the session context, allowing the conversation to continue without replaying the message history (unlike session/load).

ResumeSessionRequest

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Request parameters for resuming an existing session.

Resumes an existing session without returning previous messages (unlike session/load). This is useful for agents that can resume sessions but don't implement full session loading.

Only available if the Agent supports the session.resume capability.

Type: Object

Properties:

See protocol docs: Extensibility

The working directory for this session. McpServer[]} > List of MCP servers to connect to for this session. SessionId} required> The ID of the session to resume.

ResumeSessionResponse

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Response from resuming an existing session.

Type: Object

Properties:

See protocol docs: Extensibility

SessionConfigOption[] | null} > Initial session configuration options if supported by the Agent. SessionModelState | null} > **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Initial model state if supported by the Agent

SessionModeState | null} > Initial mode state if supported by the Agent

See protocol docs: Session Modes

session/set_config_option

Sets the current value for a session configuration option.

SetSessionConfigOptionRequest

Request parameters for setting a session configuration option.

Type: Union

A boolean value (`type: "boolean"`).

<ResponseField name="type" type={"string"} required> The discriminator value. Must be "boolean". <ResponseField name="value" type={"boolean"} required> The boolean value.

A `SessionConfigValueId` string value.

This is the default when type is absent on the wire. Unknown type values with string payloads also gracefully deserialize into this variant.

<ResponseField name="value" type={SessionConfigValueId} required

The value ID.

SetSessionConfigOptionResponse

Response to session/set_config_option method.

Type: Object

Properties:

See protocol docs: Extensibility

SessionConfigOption[]} required> The full set of configuration options and their current values.

session/set_mode

Sets the current mode for a session.

Allows switching between different agent modes (e.g., "ask", "architect", "code") that affect system prompts, tool availability, and permission behaviors.

The mode must be one of the modes advertised in availableModes during session creation or loading. Agents may also change modes autonomously and notify the client via current_mode_update notifications.

This method can be called at any time during a session, whether the Agent is idle or actively generating a response.

See protocol docs: Session Modes

SetSessionModeRequest

Request parameters for setting a session mode.

Type: Object

Properties:

See protocol docs: Extensibility

SessionModeId} required> The ID of the mode to set. SessionId} required> The ID of the session to set the mode for.

SetSessionModeResponse

Response to session/set_mode method.

Type: Object

Properties:

See protocol docs: Extensibility

session/set_model

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Select a model for a given session.

SetSessionModelRequest

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Request parameters for setting a session model.

Type: Object

Properties:

See protocol docs: Extensibility

ModelId} required> The ID of the model to set. SessionId} required> The ID of the session to set the model for.

SetSessionModelResponse

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Response to session/set_model method.

Type: Object

Properties:

See protocol docs: Extensibility

Client

Defines the interface that ACP-compliant clients must implement.

Clients are typically code editors (IDEs, text editors) that provide the interface between users and AI agents. They manage the environment, handle user interactions, and control access to resources.

fs/read_text_file

Reads content from a text file in the client's file system.

Only available if the client advertises the fs.readTextFile capability. Allows the agent to access file contents within the client's environment.

See protocol docs: Client

ReadTextFileRequest

Request to read content from a text file.

Only available if the client supports the fs.readTextFile capability.

Type: Object

Properties:

See protocol docs: Extensibility

Maximum number of lines to read.

- Minimum: `0`

Line number to start reading from (1-based).

- Minimum: `0`

Absolute path to the file to read. SessionId} required> The session ID for this request.

ReadTextFileResponse

Response containing the contents of a text file.

Type: Object

Properties:

See protocol docs: Extensibility

fs/write_text_file

Writes content to a text file in the client's file system.

Only available if the client advertises the fs.writeTextFile capability. Allows the agent to create or modify files within the client's environment.

See protocol docs: Client

WriteTextFileRequest

Request to write content to a text file.

Only available if the client supports the fs.writeTextFile capability.

Type: Object

Properties:

See protocol docs: Extensibility

The text content to write to the file. Absolute path to the file to write. SessionId} required> The session ID for this request.

WriteTextFileResponse

Response to fs/write_text_file

Type: Object

Properties:

See protocol docs: Extensibility

session/elicitation

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Requests structured user input via a form or URL.

ElicitationRequest

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Request from the agent to elicit structured user input.

The agent sends this to the client to request information from the user, either via a form or by directing them to a URL.

Type: Union

Form-based elicitation where the client renders a form from the provided schema.

<ResponseField name="mode" type={"string"} required> The discriminator value. Must be "form". <ResponseField name="requestedSchema" type={ElicitationSchema} required

A JSON Schema describing the form fields to present to the user.

URL-based elicitation where the client directs the user to a URL.

<ResponseField name="elicitationId" type={ElicitationId} required

The unique identifier for this elicitation. <ResponseField name="mode" type={"string"} required> The discriminator value. Must be "url". <ResponseField name="url" type={"string"} required> The URL to direct the user to.

ElicitationResponse

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Response from the client to an elicitation request.

Type: Object

Properties:

See protocol docs: Extensibility

ElicitationAction} required> The user's action in response to the elicitation.

session/elicitation/complete

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Notification that a URL-based elicitation has completed.

ElicitationCompleteNotification

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Notification sent by the agent when a URL-based elicitation is complete.

Type: Object

Properties:

See protocol docs: Extensibility

ElicitationId} required> The ID of the elicitation that completed.

session/request_permission

Requests permission from the user for a tool call operation.

Called by the agent when it needs user authorization before executing a potentially sensitive operation. The client should present the options to the user and return their decision.

If the client cancels the prompt turn via session/cancel, it MUST respond to this request with RequestPermissionOutcome::Cancelled.

See protocol docs: Requesting Permission

RequestPermissionRequest

Request for user permission to execute a tool call.

Sent when the agent needs authorization before performing a sensitive operation.

See protocol docs: Requesting Permission

Type: Object

Properties:

See protocol docs: Extensibility

PermissionOption[]} required> Available permission options for the user to choose from. SessionId} required> The session ID for this request. ToolCallUpdate} required> Details about the tool call requiring permission.

RequestPermissionResponse

Response to a permission request.

Type: Object

Properties:

See protocol docs: Extensibility

RequestPermissionOutcome} required> The user's decision on the permission request.

session/update

Handles session update notifications from the agent.

This is a notification endpoint (no response expected) that receives real-time updates about session progress, including message chunks, tool calls, and execution plans.

Note: Clients SHOULD continue accepting tool call updates even after sending a session/cancel notification, as the agent may send final updates before responding with the cancelled stop reason.

See protocol docs: Agent Reports Output

SessionNotification

Notification containing a session update from the agent.

Used to stream real-time progress and results during prompt processing.

See protocol docs: Agent Reports Output

Type: Object

Properties:

See protocol docs: Extensibility

SessionId} required> The ID of the session this update pertains to. SessionUpdate} required> The actual update content.

terminal/create

Executes a command in a new terminal

Only available if the terminal Client capability is set to true.

Returns a TerminalId that can be used with other terminal methods to get the current output, wait for exit, and kill the command.

The TerminalId can also be used to embed the terminal in a tool call by using the ToolCallContent::Terminal variant.

The Agent is responsible for releasing the terminal by using the terminal/release method.

See protocol docs: Terminals

CreateTerminalRequest

Request to create a new terminal and execute a command.

Type: Object

Properties:

See protocol docs: Extensibility

"string"[]} > Array of command arguments. The command to execute. Working directory for the command (absolute path). EnvVariable[]} > Environment variables for the command. Maximum number of output bytes to retain.

When the limit is exceeded, the Client truncates from the beginning of the output to stay within the limit.

The Client MUST ensure truncation happens at a character boundary to maintain valid string output, even if this means the retained output is slightly less than the specified limit.

- Minimum: `0`

SessionId} required> The session ID for this request.

CreateTerminalResponse

Response containing the ID of the created terminal.

Type: Object

Properties:

See protocol docs: Extensibility

The unique identifier for the created terminal.

terminal/kill

Kills the terminal command without releasing the terminal

While terminal/release will also kill the command, this method will keep the TerminalId valid so it can be used with other methods.

This method can be helpful when implementing command timeouts which terminate the command as soon as elapsed, and then get the final output so it can be sent to the model.

Note: Call terminal/release when TerminalId is no longer needed.

See protocol docs: Terminals

KillTerminalRequest

Request to kill a terminal without releasing it.

Type: Object

Properties:

See protocol docs: Extensibility

SessionId} required> The session ID for this request. The ID of the terminal to kill.

KillTerminalResponse

Response to terminal/kill method

Type: Object

Properties:

See protocol docs: Extensibility

terminal/output

Gets the terminal output and exit status

Returns the current content in the terminal without waiting for the command to exit. If the command has already exited, the exit status is included.

See protocol docs: Terminals

TerminalOutputRequest

Request to get the current output and status of a terminal.

Type: Object

Properties:

See protocol docs: Extensibility

SessionId} required> The session ID for this request. The ID of the terminal to get output from.

TerminalOutputResponse

Response containing the terminal output and exit status.

Type: Object

Properties:

See protocol docs: Extensibility

TerminalExitStatus | null} > Exit status if the command has completed. The terminal output captured so far. Whether the output was truncated due to byte limits.

terminal/release

Releases a terminal

The command is killed if it hasn't exited yet. Use terminal/wait_for_exit to wait for the command to exit before releasing the terminal.

After release, the TerminalId can no longer be used with other terminal/* methods, but tool calls that already contain it, continue to display its output.

The terminal/kill method can be used to terminate the command without releasing the terminal, allowing the Agent to call terminal/output and other methods.

See protocol docs: Terminals

ReleaseTerminalRequest

Request to release a terminal and free its resources.

Type: Object

Properties:

See protocol docs: Extensibility

SessionId} required> The session ID for this request. The ID of the terminal to release.

ReleaseTerminalResponse

Response to terminal/release method

Type: Object

Properties:

See protocol docs: Extensibility

terminal/wait_for_exit

Waits for the terminal command to exit and return its exit status

See protocol docs: Terminals

WaitForTerminalExitRequest

Request to wait for a terminal command to exit.

Type: Object

Properties:

See protocol docs: Extensibility

SessionId} required> The session ID for this request. The ID of the terminal to wait for.

WaitForTerminalExitResponse

Response containing the exit status of a terminal command.

Type: Object

Properties:

See protocol docs: Extensibility

The process exit code (may be null if terminated by signal).

- Minimum: `0`

The signal that terminated the process (may be null if exited normally).

Protocol Level

Defines the interface that ACP-compliant agents and clients must both implement.

Notifications whose methods start with '$/' are messages which are protocol implementation dependent and might not be implementable in all clients or agents. For example if the implementation uses a single threaded synchronous programming language then there is little it can do to react to a $/cancel_request notification. If an agent or client receives notifications starting with '$/' it is free to ignore the notification.

$/cancel_request

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Cancels an ongoing request.

This is a notification sent by the side that sent a request to cancel that request.

Upon receiving this notification, the receiver:

MUST cancel the corresponding request activity and all nested activities
MAY send any pending notifications.
MUST send one of these responses for the original request:

Valid response with appropriate data (partial results or cancellation marker)
Error response with code -32800 (Cancelled)

See protocol docs: Cancellation

CancelRequestNotification

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Notification to cancel an ongoing request.

See protocol docs: Cancellation

Type: Object

Properties:

See protocol docs: Extensibility

RequestId} required> The ID of the request to cancel.

AgentAuthCapabilities

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Authentication-related capabilities supported by the agent.

Type: Object

Properties:

See protocol docs: Extensibility

LogoutCapabilities | null} > Whether the agent supports the logout method.

By supplying \{\} it means that the agent supports the logout method.

AgentCapabilities

Capabilities supported by the agent.

Advertised during initialization to inform the client about available features and content types.

See protocol docs: Agent Capabilities

Type: Object

Properties:

See protocol docs: Extensibility

AgentAuthCapabilities} > **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Authentication-related capabilities supported by the agent.

- Default: `{}`

Whether the agent supports `session/load`.

- Default: `false`

McpCapabilities} > MCP capabilities supported by the agent.

- Default: `{"http":false,"sse":false}`

PromptCapabilities} > Prompt capabilities supported by the agent.

- Default: `{"audio":false,"embeddedContext":false,"image":false}`

SessionCapabilities} >

- Default: `{}`

Annotations

Optional annotations for the client. The client can use annotations to inform how objects are used or displayed

Type: Object

Properties:

See protocol docs: Extensibility

Role[] | null} >

AudioContent

Audio provided to or from an LLM.

Type: Object

Properties:

See protocol docs: Extensibility

Annotations | null} >

AuthCapabilities

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Authentication capabilities supported by the client.

Advertised during initialization to inform the agent which authentication method types the client can handle. This governs opt-in types that require additional client-side support.

Type: Object

Properties:

See protocol docs: Extensibility

Whether the client supports `terminal` authentication methods.

When true, the agent may include terminal entries in its authentication methods.

- Default: `false`

AuthEnvVar

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Describes a single environment variable for an AuthMethodEnvVar authentication method.

Type: Object

Properties:

See protocol docs: Extensibility

Human-readable label for this variable, displayed in client UI. The environment variable name (e.g. `"OPENAI_API_KEY"`). Whether this variable is optional.

Defaults to false.

- Default: `false`

Whether this value is a secret (e.g. API key, token). Clients should use a password-style input for secret vars.

Defaults to true.

- Default: `true`

AuthMethod

Describes an available authentication method.

The type field acts as the discriminator in the serialized JSON form. When no type is present, the method is treated as agent.

Type: Union

**UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

User provides a key that the client passes to the agent as an environment variable.

See protocol docs: Extensibility

Optional description providing more details about this authentication method. Unique identifier for this authentication method. Optional link to a page where the user can obtain their credentials. Human-readable name of the authentication method. The discriminator value. Must be `"env_var"`. AuthEnvVar[]} required> The environment variables the client should set. **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Client runs an interactive terminal for the user to authenticate via a TUI.

See protocol docs: Extensibility

"string"[]} > Additional arguments to pass when running the agent binary for terminal auth. Optional description providing more details about this authentication method. EnvVariable[]} > Additional environment variables to set when running the agent binary for terminal auth. Unique identifier for this authentication method. Human-readable name of the authentication method. The discriminator value. Must be `"terminal"`. Agent handles authentication itself.

This is the default when no type is specified.

See protocol docs: Extensibility

Optional description providing more details about this authentication method. Unique identifier for this authentication method. Human-readable name of the authentication method.

AuthMethodAgent

Agent handles authentication itself.

This is the default authentication method type.

Type: Object

Properties:

See protocol docs: Extensibility

Optional description providing more details about this authentication method. Unique identifier for this authentication method. Human-readable name of the authentication method.

AuthMethodEnvVar

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Environment variable authentication method.

The user provides credentials that the client passes to the agent as environment variables.

Type: Object

Properties:

See protocol docs: Extensibility

Optional description providing more details about this authentication method. Unique identifier for this authentication method. Optional link to a page where the user can obtain their credentials. Human-readable name of the authentication method. AuthEnvVar[]} required> The environment variables the client should set.

AuthMethodTerminal

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Terminal-based authentication method.

The client runs an interactive terminal for the user to authenticate via a TUI.

Type: Object

Properties:

See protocol docs: Extensibility

AvailableCommand

Information about a command.

Type: Object

Properties:

See protocol docs: Extensibility

Human-readable description of what the command does. AvailableCommandInput | null} > Input for the command if required Command name (e.g., `create_plan`, `research_codebase`).

AvailableCommandInput

The input specification for a command.

All text that was typed after the command name is provided as input.

Type: Object

Properties:

See protocol docs: Extensibility

A hint to display when the input hasn't been provided yet

AvailableCommandsUpdate

Available commands are ready or have changed

Type: Object

Properties:

See protocol docs: Extensibility

AvailableCommand[]} required> Commands the agent can execute

BlobResourceContents

Binary resource contents.

Type: Object

Properties:

See protocol docs: Extensibility

BooleanPropertySchema

Schema for boolean properties in an elicitation form.

Type: Object

Properties:

<ResponseField name="default" type={"boolean | null"}> Default value. <ResponseField name="description" type={"string | null"}> Human-readable description. <ResponseField name="title" type={"string | null"}> Optional title for the property.

ClientCapabilities

Capabilities supported by the client.

Advertised during initialization to inform the agent about available features and methods.

See protocol docs: Client Capabilities

Type: Object

Properties:

See protocol docs: Extensibility

AuthCapabilities} > **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Authentication capabilities supported by the client. Determines which authentication method types the agent may include in its InitializeResponse.

- Default: `{"terminal":false}`

ElicitationCapabilities | null} > **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Elicitation capabilities supported by the client. Determines which elicitation modes the agent may use.

FileSystemCapabilities} > File system capabilities supported by the client. Determines which file operations the agent can request.

- Default: `{"readTextFile":false,"writeTextFile":false}`

Whether the Client support all `terminal/*` methods.

- Default: `false`

ConfigOptionUpdate

Session configuration options have been updated.

Type: Object

Properties:

See protocol docs: Extensibility

SessionConfigOption[]} required> The full set of configuration options and their current values.

Content

Standard content block (text, images, resources).

Type: Object

Properties:

See protocol docs: Extensibility

ContentBlock} required> The actual content block.

ContentBlock

Content blocks represent displayable information in the Agent Client Protocol.

They provide a structured way to handle various types of user-facing content—whether it's text from language models, images for analysis, or embedded resources for context.

Content blocks appear in:

User prompts sent via session/prompt
Language model output streamed through session/update notifications
Progress updates and results from tool calls

This structure is compatible with the Model Context Protocol (MCP), enabling agents to seamlessly forward content from MCP tool outputs without transformation.

See protocol docs: Content

Type: Union

Text content. May be plain text or formatted with Markdown.

All agents MUST support text content blocks in prompts. Clients SHOULD render this text as Markdown.

See protocol docs: Extensibility

Annotations | null} > The discriminator value. Must be `"text"`. Images for visual context or analysis.

Requires the image prompt capability when included in prompts.

See protocol docs: Extensibility

Annotations | null} > The discriminator value. Must be `"image"`. Audio data for transcription or analysis.

Requires the audio prompt capability when included in prompts.

See protocol docs: Extensibility

Annotations | null} > The discriminator value. Must be `"audio"`. References to resources that the agent can access.

All agents MUST support resource links in prompts.

See protocol docs: Extensibility

Annotations | null} > The discriminator value. Must be `"resource_link"`. Complete resource contents embedded directly in the message.

Preferred for including context as it avoids extra round-trips.

Requires the embeddedContext prompt capability when included in prompts.

See protocol docs: Extensibility

Annotations | null} > EmbeddedResourceResource} required> The discriminator value. Must be `"resource"`.

ContentChunk

A streamed item of content

Type: Object

Properties:

See protocol docs: Extensibility

ContentBlock} required> A single item of content **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

A unique identifier for the message this chunk belongs to.

All chunks belonging to the same message share the same messageId. A change in messageId indicates a new message has started. Both clients and agents MUST use UUID format for message IDs.

Cost

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Cost information for a session.

Type: Object

Properties:

<ResponseField name="amount" type={"number"} required> Total cumulative cost for session. <ResponseField name="currency" type={"string"} required> ISO 4217 currency code (e.g., "USD", "EUR").

CurrentModeUpdate

The current mode of the session has changed

See protocol docs: Session Modes

Type: Object

Properties:

See protocol docs: Extensibility

SessionModeId} required> The ID of the current mode

Diff

A diff representing file modifications.

Shows changes to files in a format suitable for display in the client UI.

See protocol docs: Content

Type: Object

Properties:

See protocol docs: Extensibility

The new content after modification. The original content (None for new files). The file path being modified.

ElicitationAcceptAction

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

The user accepted the elicitation and provided content.

Type: Object

Properties:

<ResponseField name="content" type={"object | null"}> The user-provided content, if any, as an object matching the requested schema.

ElicitationAction

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

The user's action in response to an elicitation.

Type: Union

The user accepted and provided content.

<ResponseField name="action" type={"string"} required> The discriminator value. Must be "accept". <ResponseField name="content" type={"object | null"}> The user-provided content, if any, as an object matching the requested schema.

The user declined the elicitation.

<ResponseField name="action" type={"string"} required> The discriminator value. Must be "decline".

The elicitation was cancelled.

<ResponseField name="action" type={"string"} required> The discriminator value. Must be "cancel".

ElicitationCapabilities

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Elicitation capabilities supported by the client.

Type: Object

Properties:

See protocol docs: Extensibility

ElicitationFormCapabilities | null} > Whether the client supports form-based elicitation. ElicitationUrlCapabilities | null} > Whether the client supports URL-based elicitation.

ElicitationContentValue

Type: Union

{""} {""} {""} {""} {""}

ElicitationFormCapabilities

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Form-based elicitation capabilities.

Type: Object

Properties:

See protocol docs: Extensibility

ElicitationFormMode

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Form-based elicitation mode where the client renders a form from the provided schema.

Type: Object

Properties:

<ResponseField name="requestedSchema" type={ElicitationSchema} required

A JSON Schema describing the form fields to present to the user.

ElicitationId

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Unique identifier for an elicitation.

Type: string

ElicitationPropertySchema

Property schema for elicitation form fields.

Each variant corresponds to a JSON Schema "type" value. Single-select enums use the String variant with enum or oneOf set. Multi-select enums use the Array variant.

Type: Union

String property (or single-select enum when `enum`/`oneOf` is set).

<ResponseField name="default" type={"string | null"} > Default value. <ResponseField name="description" type={"string | null"} > Human-readable description. <ResponseField name="enum" type={<><>"string"[]</> | null</>} > Enum values for untitled single-select enums. <ResponseField name="format" type={<>StringFormat | null</>} > String format. <ResponseField name="maxLength" type={"integer | null"} > Maximum string length.

- Minimum: `0`

Minimum string length.

- Minimum: `0`

EnumOption[] | null} > Titled enum options for titled single-select enums. Pattern the string must match. Optional title for the property. The discriminator value. Must be `"string"`. Number (floating-point) property.

<ResponseField name="default" type={"number | null"}> Default value. <ResponseField name="description" type={"string | null"}> Human-readable description. <ResponseField name="maximum" type={"number | null"}> Maximum value (inclusive). <ResponseField name="minimum" type={"number | null"}> Minimum value (inclusive). <ResponseField name="title" type={"string | null"}> Optional title for the property. <ResponseField name="type" type={"string"} required> The discriminator value. Must be "number".

Integer property.

<ResponseField name="default" type={"integer | null"}> Default value. <ResponseField name="description" type={"string | null"}> Human-readable description. <ResponseField name="maximum" type={"integer | null"}> Maximum value (inclusive). <ResponseField name="minimum" type={"integer | null"}> Minimum value (inclusive). <ResponseField name="title" type={"string | null"}> Optional title for the property. <ResponseField name="type" type={"string"} required> The discriminator value. Must be "integer".

Boolean property.

Multi-select array property.

<ResponseField name="default" type={<><>"string"[]</> | null</>} > Default selected values. <ResponseField name="description" type={"string | null"} > Human-readable description. <ResponseField name="items" type={MultiSelectItems} required> The items definition describing allowed values. <ResponseField name="maxItems" type={"integer | null"} > Maximum number of items to select.

- Minimum: `0`

Minimum number of items to select.

- Minimum: `0`

Optional title for the property. The discriminator value. Must be `"array"`.

ElicitationSchema

Type-safe elicitation schema for requesting structured user input.

This represents a JSON Schema object with primitive-typed properties, as required by the elicitation specification.

Type: Object

Properties:

<ResponseField name="description" type={"string | null"} > Optional description of what this schema represents. <ResponseField name="properties" type={"object"} > Property definitions (must be primitive types).

- Default: `{}`

<>"string"[] | null} > List of required property names. Optional title for the schema. ElicitationSchemaType} > Type discriminator. Always `"object"`.

- Default: `"object"`

ElicitationSchemaType

Type discriminator for elicitation schemas.

Type: Union

Object schema type.

ElicitationStringType

Items definition for untitled multi-select enum properties.

Type: Union

String schema type.

ElicitationUrlCapabilities

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

URL-based elicitation capabilities.

Type: Object

Properties:

See protocol docs: Extensibility

ElicitationUrlMode

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

URL-based elicitation mode where the client directs the user to a URL.

Type: Object

Properties:

<ResponseField name="elicitationId" type={ElicitationId} required

The unique identifier for this elicitation. <ResponseField name="url" type={"string"} required> The URL to direct the user to.

EmbeddedResource

The contents of a resource, embedded into a prompt or tool call result.

Type: Object

Properties:

See protocol docs: Extensibility

Annotations | null} > EmbeddedResourceResource} required>

EmbeddedResourceResource

Resource content that can be embedded in a message.

Type: Union

{""}

See protocol docs: Extensibility

{""}

See protocol docs: Extensibility

EnumOption

A titled enum option with a const value and human-readable title.

Type: Object

Properties:

<ResponseField name="const" type={"string"} required> The constant value for this option. <ResponseField name="title" type={"string"} required> Human-readable title for this option.

EnvVariable

An environment variable to set when launching an MCP server.

Type: Object

Properties:

See protocol docs: Extensibility

The name of the environment variable. The value to set for the environment variable.

Error

JSON-RPC error object.

Represents an error that occurred during method execution, following the JSON-RPC 2.0 error object specification with optional additional data.

See protocol docs: JSON-RPC Error Object

Type: Object

Properties:

<ResponseField name="code" type={ErrorCode} required> A number indicating the error type that occurred. This must be an integer as defined in the JSON-RPC specification. <ResponseField name="data" type={"object"}> Optional primitive or structured value that contains additional information about the error. This may include debugging information or context-specific details. <ResponseField name="message" type={"string"} required> A string providing a short description of the error. The message should be limited to a concise single sentence.

ErrorCode

Predefined error codes for common JSON-RPC and ACP-specific errors.

These codes follow the JSON-RPC 2.0 specification for standard errors and use the reserved range (-32000 to -32099) for protocol-specific errors.

Type: Union

**Parse error**: Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text. **Invalid request**: The JSON sent is not a valid Request object. **Method not found**: The method does not exist or is not available. **Invalid params**: Invalid method parameter(s). **Internal error**: Internal JSON-RPC error. Reserved for implementation-defined server errors. **Request cancelled**: **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Execution of the method was aborted either due to a cancellation request from the caller or because of resource constraints or shutdown.

**Authentication required**: Authentication is required before this operation can be performed. **Resource not found**: A given resource, such as a file, was not found. **URL elicitation required**: **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

The agent requires user input via a URL-based elicitation before it can proceed.

Other undefined error code.

ExtNotification

Allows the Agent to send an arbitrary notification that is not part of the ACP spec. Extension notifications provide a way to send one-way messages for custom functionality while maintaining protocol compatibility.

See protocol docs: Extensibility

ExtRequest

Allows for sending an arbitrary request that is not part of the ACP spec. Extension methods provide a way to add custom functionality while maintaining protocol compatibility.

See protocol docs: Extensibility

ExtResponse

Allows for sending an arbitrary response to an ExtRequest that is not part of the ACP spec. Extension methods provide a way to add custom functionality while maintaining protocol compatibility.

See protocol docs: Extensibility

FileSystemCapabilities

File system capabilities that a client may support.

See protocol docs: FileSystem

Type: Object

Properties:

See protocol docs: Extensibility

Whether the Client supports `fs/read_text_file` requests.

- Default: `false`

Whether the Client supports `fs/write_text_file` requests.

- Default: `false`

HttpHeader

An HTTP header to set when making requests to the MCP server.

Type: Object

Properties:

See protocol docs: Extensibility

The name of the HTTP header. The value to set for the HTTP header.

ImageContent

An image provided to or from an LLM.

Type: Object

Properties:

See protocol docs: Extensibility

Annotations | null} >

Implementation

Metadata about the implementation of the client or agent. Describes the name and version of an MCP implementation, with an optional title for UI representation.

Type: Object

Properties:

See protocol docs: Extensibility

Intended for programmatic or logical use, but can be used as a display name fallback if title isn’t present. Intended for UI and end-user contexts — optimized to be human-readable and easily understood.

If not provided, the name should be used for display.

Version of the implementation. Can be displayed to the user or used for debugging or metrics purposes. (e.g. "1.0.0").

IntegerPropertySchema

Schema for integer properties in an elicitation form.

Type: Object

Properties:

LogoutCapabilities

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Logout capabilities supported by the agent.

By supplying \{\} it means that the agent supports the logout method.

Type: Object

Properties:

See protocol docs: Extensibility

McpCapabilities

MCP capabilities supported by the agent

Type: Object

Properties:

See protocol docs: Extensibility

Agent supports `McpServer::Http`.

- Default: `false`

Agent supports `McpServer::Sse`.

- Default: `false`

McpServer

Configuration for connecting to an MCP (Model Context Protocol) server.

MCP servers provide tools and context that the agent can use when processing prompts.

See protocol docs: MCP Servers

Type: Union

HTTP transport configuration

Only available when the Agent capabilities indicate mcp_capabilities.http is true.

See protocol docs: Extensibility

HttpHeader[]} required> HTTP headers to set when making requests to the MCP server. Human-readable name identifying this MCP server. The discriminator value. Must be `"http"`. URL to the MCP server. SSE transport configuration

Only available when the Agent capabilities indicate mcp_capabilities.sse is true.

See protocol docs: Extensibility

HttpHeader[]} required> HTTP headers to set when making requests to the MCP server. Human-readable name identifying this MCP server. The discriminator value. Must be `"sse"`. URL to the MCP server. Stdio transport configuration

All Agents MUST support this transport.

See protocol docs: Extensibility

"string"[]} required> Command-line arguments to pass to the MCP server. Path to the MCP server executable. EnvVariable[]} required> Environment variables to set when launching the MCP server. Human-readable name identifying this MCP server.

McpServerHttp

HTTP transport configuration for MCP.

Type: Object

Properties:

See protocol docs: Extensibility

HttpHeader[]} required> HTTP headers to set when making requests to the MCP server. Human-readable name identifying this MCP server. URL to the MCP server.

McpServerSse

SSE transport configuration for MCP.

Type: Object

Properties:

See protocol docs: Extensibility

HttpHeader[]} required> HTTP headers to set when making requests to the MCP server. Human-readable name identifying this MCP server. URL to the MCP server.

McpServerStdio

Stdio transport configuration for MCP.

Type: Object

Properties:

See protocol docs: Extensibility

ModelId

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

A unique identifier for a model.

Type: string

ModelInfo

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Information about a selectable model.

Type: Object

Properties:

See protocol docs: Extensibility

Optional description of the model. ModelId} required> Unique identifier for the model. Human-readable name of the model.

MultiSelectItems

Items for a multi-select (array) property schema.

Type: Union

Untitled multi-select items with plain string values.

<ResponseField name="enum" type={ <> "string" [] </> } required

Allowed enum values. <ResponseField name="type" type={ElicitationStringType} required

Item type discriminator. Must be "string".

Titled multi-select items with human-readable labels.

<ResponseField name="anyOf" type={EnumOption[]} required

Titled enum options.

MultiSelectPropertySchema

Schema for multi-select (array) properties in an elicitation form.

Type: Object

Properties:

- Minimum: `0`

Minimum number of items to select.

- Minimum: `0`

Optional title for the property.

NumberPropertySchema

Schema for number (floating-point) properties in an elicitation form.

Type: Object

Properties:

PermissionOption

An option presented to the user when requesting permission.

Type: Object

Properties:

See protocol docs: Extensibility

PermissionOptionKind} required> Hint about the nature of this permission option. Human-readable label to display to the user. PermissionOptionId} required> Unique identifier for this permission option.

PermissionOptionId

Unique identifier for a permission option.

Type: string

PermissionOptionKind

The type of permission option being presented to the user.

Helps clients choose appropriate icons and UI treatment.

Type: Union

Allow this operation only this time. Allow this operation and remember the choice. Reject this operation only this time. Reject this operation and remember the choice.

Plan

An execution plan for accomplishing complex tasks.

Plans consist of multiple entries representing individual tasks or goals. Agents report plans to clients to provide visibility into their execution strategy. Plans can evolve during execution as the agent discovers new requirements or completes tasks.

See protocol docs: Agent Plan

Type: Object

Properties:

See protocol docs: Extensibility

PlanEntry[]} required> The list of tasks to be accomplished.

When updating a plan, the agent must send a complete list of all entries with their current status. The client replaces the entire plan with each update.

PlanEntry

A single entry in the execution plan.

Represents a task or goal that the assistant intends to accomplish as part of fulfilling the user's request. See protocol docs: Plan Entries

Type: Object

Properties:

See protocol docs: Extensibility

Human-readable description of what this task aims to accomplish. PlanEntryPriority} required> The relative importance of this task. Used to indicate which tasks are most critical to the overall goal. PlanEntryStatus} required> Current execution status of this task.

PlanEntryPriority

Priority levels for plan entries.

Used to indicate the relative importance or urgency of different tasks in the execution plan. See protocol docs: Plan Entries

Type: Union

High priority task - critical to the overall goal. Medium priority task - important but not critical. Low priority task - nice to have but not essential.

PlanEntryStatus

Status of a plan entry in the execution flow.

Tracks the lifecycle of each task from planning through completion. See protocol docs: Plan Entries

Type: Union

The task has not started yet. The task is currently being worked on. The task has been successfully completed.

PromptCapabilities

Prompt capabilities supported by the agent in session/prompt requests.

Baseline agent functionality requires support for ContentBlock::Text and ContentBlock::ResourceLink in prompt requests.

Other variants must be explicitly opted in to. Capabilities for different types of content in prompt requests.

Indicates which content types beyond the baseline (text and resource links) the agent can process.

See protocol docs: Prompt Capabilities

Type: Object

Properties:

See protocol docs: Extensibility

Agent supports `ContentBlock::Audio`.

- Default: `false`

Agent supports embedded context in `session/prompt` requests.

When enabled, the Client is allowed to include ContentBlock::Resource in prompt requests for pieces of context that are referenced in the message.

- Default: `false`

Agent supports `ContentBlock::Image`.

- Default: `false`

ProtocolVersion

Protocol version identifier.

This version is only bumped for breaking changes. Non-breaking changes should be introduced via capabilities.

Type: integer (uint16)

Constraint	Value
Minimum	`0`
Maximum	`65535`

RequestId

JSON RPC Request Id

An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null [1] and Numbers SHOULD NOT contain fractional parts [2]

The Server MUST reply with the same value in the Response object if included. This member is used to correlate the context between the two objects.

[1] The use of Null as a value for the id member in a Request object is discouraged, because this specification uses a value of Null for Responses with an unknown id. Also, because JSON-RPC 1.0 uses an id value of Null for Notifications this could cause confusion in handling.

[2] Fractional parts may be problematic, since many decimal fractions cannot be represented exactly as binary fractions.

Type: Union

{""} {""} {""}

RequestPermissionOutcome

The outcome of a permission request.

Type: Union

The prompt turn was cancelled before the user responded.

When a client sends a session/cancel notification to cancel an ongoing prompt turn, it MUST respond to all pending session/request_permission requests with this Cancelled outcome.

See protocol docs: Cancellation

<ResponseField name="outcome" type={"string"} required> The discriminator value. Must be "cancelled".

The user selected one of the provided options.

See protocol docs: Extensibility

PermissionOptionId} required> The ID of the option the user selected. The discriminator value. Must be `"selected"`.

ResourceLink

A resource that the server is capable of reading, included in a prompt or tool call result.

Type: Object

Properties:

See protocol docs: Extensibility

Annotations | null} >

Role

The sender or recipient of messages and data in a conversation.

Type: Enumeration

Value
`"assistant"`
`"user"`

SelectedPermissionOutcome

The user selected one of the provided options.

Type: Object

Properties:

See protocol docs: Extensibility

PermissionOptionId} required> The ID of the option the user selected.

SessionCapabilities

Session capabilities supported by the agent.

As a baseline, all Agents MUST support session/new, session/prompt, session/cancel, and session/update.

Optionally, they MAY support other session methods and notifications by specifying additional capabilities.

Note: session/load is still handled by the top-level load_session capability. This will be unified in future versions of the protocol.

See protocol docs: Session Capabilities

Type: Object

Properties:

See protocol docs: Extensibility

SessionCloseCapabilities | null} > **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Whether the agent supports session/close.

SessionForkCapabilities | null} > **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Whether the agent supports session/fork.

SessionListCapabilities | null} > Whether the agent supports `session/list`. SessionResumeCapabilities | null} > **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Whether the agent supports session/resume.

SessionCloseCapabilities

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Capabilities for the session/close method.

By supplying \{\} it means that the agent supports closing of sessions.

Type: Object

Properties:

See protocol docs: Extensibility

SessionConfigBoolean

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

A boolean on/off toggle session configuration option payload.

Type: Object

Properties:

<ResponseField name="currentValue" type={"boolean"} required> The current value of the boolean option.

SessionConfigGroupId

Unique identifier for a session configuration option value group.

Type: string

SessionConfigId

Unique identifier for a session configuration option.

Type: string

SessionConfigOption

A session configuration option selector and its current state.

Type: Union

Single-value selector (dropdown).

<ResponseField name="currentValue" type={SessionConfigValueId} required

The currently selected value. <ResponseField name="options" type={SessionConfigSelectOptions} required

The set of selectable options. <ResponseField name="type" type={"string"} required> The discriminator value. Must be "select".

**UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Boolean on/off toggle.

<ResponseField name="currentValue" type={"boolean"} required> The current value of the boolean option. <ResponseField name="type" type={"string"} required> The discriminator value. Must be "boolean".

SessionConfigOptionCategory

Semantic category for a session configuration option.

This is intended to help Clients distinguish broadly common selectors (e.g. model selector vs session mode selector vs thought/reasoning level) for UX purposes (keyboard shortcuts, icons, placement). It MUST NOT be required for correctness. Clients MUST handle missing or unknown categories gracefully.

Category names beginning with _ are free for custom use, like other ACP extension methods. Category names that do not begin with _ are reserved for the ACP spec.

Type: Union

Session mode selector. Model selector. Thought/reasoning level selector. Unknown / uncategorized selector.

SessionConfigSelect

A single-value selector (dropdown) session configuration option payload.

Type: Object

Properties:

<ResponseField name="currentValue" type={SessionConfigValueId} required

The currently selected value. <ResponseField name="options" type={SessionConfigSelectOptions} required

The set of selectable options.

SessionConfigSelectGroup

A group of possible values for a session configuration option.

Type: Object

Properties:

See protocol docs: Extensibility

SessionConfigGroupId} required> Unique identifier for this group. Human-readable label for this group. SessionConfigSelectOption[]} required> The set of option values in this group.

SessionConfigSelectOption

A possible value for a session configuration option.

Type: Object

Properties:

See protocol docs: Extensibility

Optional description for this option value. Human-readable label for this option value. SessionConfigValueId} required> Unique identifier for this option value.

SessionConfigSelectOptions

Possible values for a session configuration option.

Type: Union

A flat list of options with no grouping. A list of options grouped under headers.

SessionConfigValueId

Unique identifier for a session configuration option value.

Type: string

SessionForkCapabilities

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Capabilities for the session/fork method.

By supplying \{\} it means that the agent supports forking of sessions.

Type: Object

Properties:

See protocol docs: Extensibility

SessionId

A unique identifier for a conversation session between a client and agent.

Sessions maintain their own context, conversation history, and state, allowing multiple independent interactions with the same agent.

See protocol docs: Session ID

Type: string

SessionInfo

Information about a session returned by session/list

Type: Object

Properties:

See protocol docs: Extensibility

The working directory for this session. Must be an absolute path. SessionId} required> Unique identifier for the session Human-readable title for the session ISO 8601 timestamp of last activity

SessionInfoUpdate

Update to session metadata. All fields are optional to support partial updates.

Agents send this notification to update session information like title or custom metadata. This allows clients to display dynamic session names and track session state changes.

Type: Object

Properties:

See protocol docs: Extensibility

Human-readable title for the session. Set to null to clear. ISO 8601 timestamp of last activity. Set to null to clear.

SessionListCapabilities

Capabilities for the session/list method.

By supplying \{\} it means that the agent supports listing of sessions.

Type: Object

Properties:

See protocol docs: Extensibility

SessionMode

A mode the agent can operate in.

See protocol docs: Session Modes

Type: Object

Properties:

See protocol docs: Extensibility

SessionModeId} required>

SessionModeId

Unique identifier for a Session Mode.

Type: string

SessionModeState

The set of modes and the one currently active.

Type: Object

Properties:

See protocol docs: Extensibility

SessionMode[]} required> The set of modes that the Agent can operate in SessionModeId} required> The current mode the Agent is in.

SessionModelState

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

The set of models and the one currently active.

Type: Object

Properties:

See protocol docs: Extensibility

ModelInfo[]} required> The set of models that the Agent can use ModelId} required> The current model the Agent is in.

SessionResumeCapabilities

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Capabilities for the session/resume method.

By supplying \{\} it means that the agent supports resuming of sessions.

Type: Object

Properties:

See protocol docs: Extensibility

SessionUpdate

Different types of updates that can be sent during session processing.

These updates provide real-time feedback about the agent's progress.

See protocol docs: Agent Reports Output

Type: Union

A chunk of the user's message being streamed.

See protocol docs: Extensibility

ContentBlock} required> A single item of content **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

A unique identifier for the message this chunk belongs to.

All chunks belonging to the same message share the same messageId. A change in messageId indicates a new message has started. Both clients and agents MUST use UUID format for message IDs.

The discriminator value. Must be `"user_message_chunk"`. A chunk of the agent's response being streamed.

See protocol docs: Extensibility

ContentBlock} required> A single item of content **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

A unique identifier for the message this chunk belongs to.

All chunks belonging to the same message share the same messageId. A change in messageId indicates a new message has started. Both clients and agents MUST use UUID format for message IDs.

The discriminator value. Must be `"agent_message_chunk"`. A chunk of the agent's internal reasoning being streamed.

See protocol docs: Extensibility

ContentBlock} required> A single item of content **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

A unique identifier for the message this chunk belongs to.

All chunks belonging to the same message share the same messageId. A change in messageId indicates a new message has started. Both clients and agents MUST use UUID format for message IDs.

The discriminator value. Must be `"agent_thought_chunk"`. Notification that a new tool call has been initiated.

See protocol docs: Extensibility

ToolCallContent[]} > Content produced by the tool call. ToolKind} > The category of tool being invoked. Helps clients choose appropriate icons and UI treatment. ToolCallLocation[]} > File locations affected by this tool call. Enables "follow-along" features in clients. Raw input parameters sent to the tool. Raw output returned by the tool. The discriminator value. Must be `"tool_call"`. ToolCallStatus} > Current execution status of the tool call. Human-readable title describing what the tool is doing. ToolCallId} required> Unique identifier for this tool call within the session. Update on the status or results of a tool call.

See protocol docs: Extensibility

ToolCallContent[] | null} > Replace the content collection. ToolKind | null} > Update the tool kind. ToolCallLocation[] | null} > Replace the locations collection. Update the raw input. Update the raw output. The discriminator value. Must be `"tool_call_update"`. ToolCallStatus | null} > Update the execution status. Update the human-readable title. ToolCallId} required> The ID of the tool call being updated. The agent's execution plan for complex tasks. See protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/agent-plan)

See protocol docs: Extensibility

PlanEntry[]} required> The list of tasks to be accomplished.

When updating a plan, the agent must send a complete list of all entries with their current status. The client replaces the entire plan with each update.

The discriminator value. Must be `"plan"`. Available commands are ready or have changed

See protocol docs: Extensibility

AvailableCommand[]} required> Commands the agent can execute The discriminator value. Must be `"available_commands_update"`. The current mode of the session has changed

See protocol docs: Session Modes

See protocol docs: Extensibility

SessionModeId} required> The ID of the current mode The discriminator value. Must be `"current_mode_update"`. Session configuration options have been updated.

See protocol docs: Extensibility

SessionConfigOption[]} required> The full set of configuration options and their current values. The discriminator value. Must be `"config_option_update"`. Session metadata has been updated (title, timestamps, custom metadata)

See protocol docs: Extensibility

The discriminator value. Must be `"session_info_update"`. Human-readable title for the session. Set to null to clear. ISO 8601 timestamp of last activity. Set to null to clear. **UNSTABLE**

This capability is not part of the spec yet, and may be removed or changed at any point.

Context window and cost update for the session.

See protocol docs: Extensibility

Cost | null} > Cumulative session cost (optional). The discriminator value. Must be `"usage_update"`. Total context window size in tokens.

- Minimum: `0`

Tokens currently in context.

- Minimum: `0`

StopReason

Reasons why an agent stops processing a prompt turn.

See protocol docs: Stop Reasons

Type: Union

The turn ended successfully. The turn ended because the agent reached the maximum number of tokens. The turn ended because the agent reached the maximum number of allowed agent requests between user turns. The turn ended because the agent refused to continue. The user prompt and everything that comes after it won't be included in the next prompt, so this should be reflected in the UI. The turn was cancelled by the client via `session/cancel`.

This stop reason MUST be returned when the client sends a session/cancel notification, even if the cancellation causes exceptions in underlying operations. Agents should catch these exceptions and return this semantically meaningful response to confirm successful cancellation.

StringFormat

String format types for string properties in elicitation schemas.

Type: Union

Email address format. URI format. Date format (YYYY-MM-DD). Date-time format (ISO 8601).

StringPropertySchema

Schema for string properties in an elicitation form.

When enum or oneOf is set, this represents a single-select enum with "type": "string".

Type: Object

Properties:

- Minimum: `0`

Minimum string length.

- Minimum: `0`

EnumOption[] | null} > Titled enum options for titled single-select enums. Pattern the string must match. Optional title for the property.

Terminal

Embed a terminal created with terminal/create by its id.

The terminal must be added before calling terminal/release.

See protocol docs: Terminal

Type: Object

Properties:

See protocol docs: Extensibility

TerminalExitStatus

Exit status of a terminal command.

Type: Object

Properties:

See protocol docs: Extensibility

The process exit code (may be null if terminated by signal).

- Minimum: `0`

The signal that terminated the process (may be null if exited normally).

TextContent

Text provided to or from an LLM.

Type: Object

Properties:

See protocol docs: Extensibility

Annotations | null} >

TextResourceContents

Text-based resource contents.

Type: Object

Properties:

See protocol docs: Extensibility

TitledMultiSelectItems

Items definition for titled multi-select enum properties.

Type: Object

Properties:

<ResponseField name="anyOf" type={EnumOption[]} required

Titled enum options.

ToolCall

Represents a tool call that the language model has requested.

Tool calls are actions that the agent executes on behalf of the language model, such as reading files, executing code, or fetching data from external sources.

See protocol docs: Tool Calls

Type: Object

Properties:

See protocol docs: Extensibility

ToolCallContent[]} > Content produced by the tool call. ToolKind} > The category of tool being invoked. Helps clients choose appropriate icons and UI treatment. ToolCallLocation[]} > File locations affected by this tool call. Enables "follow-along" features in clients. Raw input parameters sent to the tool. Raw output returned by the tool. ToolCallStatus} > Current execution status of the tool call. Human-readable title describing what the tool is doing. ToolCallId} required> Unique identifier for this tool call within the session.

ToolCallContent

Content produced by a tool call.

Tool calls can produce different types of content including standard content blocks (text, images) or file diffs.

See protocol docs: Content

Type: Union

Standard content block (text, images, resources).

See protocol docs: Extensibility

ContentBlock} required> The actual content block. The discriminator value. Must be `"content"`. File modification shown as a diff.

See protocol docs: Extensibility

The new content after modification. The original content (None for new files). The file path being modified. The discriminator value. Must be `"diff"`. Embed a terminal created with `terminal/create` by its id.

The terminal must be added before calling terminal/release.

See protocol docs: Terminal

See protocol docs: Extensibility

The discriminator value. Must be `"terminal"`.

ToolCallId

Unique identifier for a tool call within a session.

Type: string

ToolCallLocation

A file location being accessed or modified by a tool.

Enables clients to implement "follow-along" features that track which files the agent is working with in real-time.

See protocol docs: Following the Agent

Type: Object

Properties:

See protocol docs: Extensibility

Optional line number within the file.

- Minimum: `0`

The file path being accessed or modified.

ToolCallStatus

Execution status of a tool call.

Tool calls progress through different statuses during their lifecycle.

See protocol docs: Status

Type: Union

The tool call hasn't started running yet because the input is either streaming or we're awaiting approval. The tool call is currently running. The tool call completed successfully. The tool call failed with an error.

ToolCallUpdate

An update to an existing tool call.

Used to report progress and results as tools execute. All fields except the tool call ID are optional - only changed fields need to be included.

See protocol docs: Updating

Type: Object

Properties:

See protocol docs: Extensibility

ToolCallContent[] | null} > Replace the content collection. ToolKind | null} > Update the tool kind. ToolCallLocation[] | null} > Replace the locations collection. Update the raw input. Update the raw output. ToolCallStatus | null} > Update the execution status. Update the human-readable title. ToolCallId} required> The ID of the tool call being updated.

ToolKind

Categories of tools that can be invoked.

Tool kinds help clients choose appropriate icons and optimize how they display tool execution progress.

See protocol docs: Creating

Type: Union

Reading files or data. Modifying files or content. Removing files or data. Moving or renaming files. Searching for information. Running commands or code. Internal reasoning or planning. Retrieving external data. Switching the current session mode. Other tool types (default).

UnstructuredCommandInput

All text that was typed after the command name is provided as input.

Type: Object

Properties:

See protocol docs: Extensibility

A hint to display when the input hasn't been provided yet

UntitledMultiSelectItems

Items definition for untitled multi-select enum properties.

Type: Object

Properties:

<ResponseField name="enum" type={ <> "string" [] </> } required

Allowed enum values. <ResponseField name="type" type={ElicitationStringType} required

Item type discriminator. Must be "string".

Usage

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Token usage information for a prompt turn.

Type: Object

Properties:

<ResponseField name="cachedReadTokens" type={"integer | null"} > Total cache read tokens.

- Minimum: `0`

Total cache write tokens.

- Minimum: `0`

Total input tokens across all turns.

- Minimum: `0`

Total output tokens across all turns.

- Minimum: `0`

Total thought/reasoning tokens

- Minimum: `0`

Sum of all token types across session.

- Minimum: `0`

UsageUpdate

UNSTABLE

This capability is not part of the spec yet, and may be removed or changed at any point.

Context window and cost update for a session.

Type: Object

Properties:

See protocol docs: Extensibility

Cost | null} > Cumulative session cost (optional). Total context window size in tokens.

- Minimum: `0`

Tokens currently in context.

- Minimum: `0`

FilesExpand file tree

schema.mdx

Latest commit

History

schema.mdx

File metadata and controls

Agent

authenticate

AuthenticateRequest

AuthenticateResponse

initialize

InitializeRequest

InitializeResponse

logout

LogoutRequest

LogoutResponse

session/cancel

CancelNotification

session/close

CloseSessionRequest

CloseSessionResponse

session/fork

ForkSessionRequest

ForkSessionResponse

session/list

ListSessionsRequest

ListSessionsResponse

session/load

LoadSessionRequest

LoadSessionResponse

session/new

NewSessionRequest

NewSessionResponse

session/prompt

PromptRequest

PromptResponse

session/resume

ResumeSessionRequest

ResumeSessionResponse

session/set_config_option

SetSessionConfigOptionRequest

SetSessionConfigOptionResponse

session/set_mode

SetSessionModeRequest

SetSessionModeResponse

session/set_model

SetSessionModelRequest

SetSessionModelResponse

Client

fs/read_text_file

ReadTextFileRequest

ReadTextFileResponse

fs/write_text_file

WriteTextFileRequest

WriteTextFileResponse

session/elicitation

ElicitationRequest

ElicitationResponse

session/elicitation/complete

ElicitationCompleteNotification

session/request_permission

RequestPermissionRequest

RequestPermissionResponse

session/update

SessionNotification

terminal/create

CreateTerminalRequest

CreateTerminalResponse

terminal/kill

KillTerminalRequest

KillTerminalResponse

terminal/output

TerminalOutputRequest

TerminalOutputResponse

terminal/release

ReleaseTerminalRequest

ReleaseTerminalResponse

terminal/wait_for_exit

WaitForTerminalExitRequest

WaitForTerminalExitResponse