Schema

required

The ID of the session to cancel operations for.

session/close

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

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:

_meta

object | null

sessionId

required

The ID of the session to close.

CloseSessionResponse

Response from closing a session. Type: Object Properties:

_meta

object | null

session/delete

Deletes an existing session from session/list. This method is only available if the agent advertises the session.delete capability.

DeleteSessionRequest

Request parameters for deleting an existing session from session/list. Only available if the Agent supports the session.delete capability. Type: Object Properties:

_meta

object | null

sessionId

required

The ID of the session to delete.

DeleteSessionResponse

Response from deleting a session. Type: Object Properties:

_meta

object | null

session/list

Lists existing sessions known to the agent. This method is only available if the agent advertises the session.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 session.list capability. Type: Object Properties:

_meta

object | null

cursor

string | null

Opaque cursor token from a previous response’s nextCursor field for cursor-based pagination

cwd

string | null

Filter sessions by working directory. Must be an absolute path.

ListSessionsResponse

Response from listing sessions. Type: Object Properties:

_meta

object | null

nextCursor

string | null

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.

sessions

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 session.load 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 session.load capability. See protocol docs: Loading Sessions Type: Object Properties:

_meta

object | null

additionalDirectories

"string"[]

Additional workspace roots to activate for this session. Each path must be absolute.When omitted or empty, no additional roots are activated. When non-empty, this is the complete resulting additional-root list for the loaded session. It may differ from any previously used or reported list as long as the request cwd matches the session’s cwd.

cwd

string

required

The working directory for this session.

mcpServers

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:

_meta

object | null

configOptions

SessionConfigOption[] | null

Initial session configuration options if supported by the Agent.

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:

_meta

object | null

additionalDirectories

"string"[]

Additional workspace roots for this session. Each path must be absolute.These expand the session’s workspace scope without changing cwd, which remains the base for relative paths. When omitted or empty, no additional roots are activated for the new session.

cwd

string

required

The working directory for this session. Must be an absolute path.

mcpServers

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:

_meta

object | null

configOptions

SessionConfigOption[] | null

Initial session configuration options if supported by the Agent.

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:

_meta

object | null

prompt

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:

_meta

object | null

stopReason

StopReason

required

Indicates why the agent stopped processing the turn.

session/resume

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

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:

_meta

object | null

additionalDirectories

"string"[]

Additional workspace roots to activate for this session. Each path must be absolute.When omitted or empty, no additional roots are activated. When non-empty, this is the complete resulting additional-root list for the resumed session. It may differ from any previously used or reported list as long as the request cwd matches the session’s cwd.

cwd

string

required

The working directory for this session.

mcpServers

McpServer[]

List of MCP servers to connect to for this session.

sessionId

required

The ID of the session to resume.

ResumeSessionResponse

Response from resuming an existing session. Type: Object Properties:

_meta

object | null

configOptions

SessionConfigOption[] | null

Initial session configuration options if supported by the Agent.

session/set_config_option

Sets the current value for a session configuration option.

SetSessionConfigOptionRequest

Request parameters for setting a session configuration option. Type: Object Properties:

_meta

object | null

configId

SessionConfigId

required

The ID of the configuration option to set.

sessionId

required

The ID of the session to set the configuration option for.

value

SessionConfigValueId

required

The ID of the configuration option value to set.

SetSessionConfigOptionResponse

Response to session/set_config_option method. Type: Object Properties:

_meta

object | null

configOptions

SessionConfigOption[]

required

The full set of configuration options and their current values.

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.

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:

_meta

object | null

options

PermissionOption[]

required

Available permission options for the user to choose from.

sessionId

required

The session ID for this request.

toolCall

ToolCallUpdate

required

Details about the tool call requiring permission.

RequestPermissionResponse

Response to a permission request. Type: Object Properties:

_meta

object | null

outcome

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 updates, 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:

_meta

object | null

sessionId

required

The ID of the session this update pertains to.

update

SessionUpdate

required

The actual update content.

AgentAuthCapabilities

Authentication-related capabilities supported by the agent. Type: Object Properties:

_meta

object | null

logout

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:

_meta

object | null

auth

AgentAuthCapabilities

Authentication-related capabilities supported by the agent.

Default: {}

session

SessionCapabilities | null

Session capabilities supported by the agent.Optional. Omitted or null both mean the agent does not support the session/* method surface. Supplying \{\} means the agent supports the baseline session methods: session/new, session/prompt, session/cancel, and session/update.

AgentMessage

An agent message upsert. Only AgentMessage::message_id is required. Other fields have patch semantics: omitted fields leave the existing message value unchanged, null clears or unsets the value, and concrete values replace the previous value. For a new messageId, omitted fields use client defaults. content is replaced as a whole array; send [] or null to clear it. Message updates and chunks are applied in the order they are received. When an agent_message update includes content, that array replaces any content previously accumulated for the message, including content from earlier chunks. Later chunks with the same messageId append to the current content. Type: Object Properties:

_meta

object | null

content

ContentBlock[] | null

Complete replacement content for this message.

messageId

required

A unique identifier for the message.

AgentThought

An agent thought or reasoning message upsert. Only AgentThought::message_id is required. Other fields have patch semantics: omitted fields leave the existing thought value unchanged, null clears or unsets the value, and concrete values replace the previous value. For a new messageId, omitted fields use client defaults. content is replaced as a whole array; send [] or null to clear it. Message updates and chunks are applied in the order they are received. When an agent_thought update includes content, that array replaces any content previously accumulated for the thought, including content from earlier chunks. Later chunks with the same messageId append to the current content. Type: Object Properties:

_meta

object | null

content

ContentBlock[] | null

Complete replacement content for this thought message.

messageId

required

A unique identifier for the thought message.

Annotations

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

_meta

object | null

audience

Role[] | null

lastModified

string | null

priority

number | null

AudioContent

Audio provided to or from an LLM. Type: Object Properties:

_meta

object | null

annotations

Annotations | null

data

string

required

mimeType

string

required

AuthMethod

Describes an available authentication method. The type field acts as the discriminator in the serialized JSON form. Type: Union

agent

object

Agent handles authentication itself.The type discriminator value is agent.

Show Properties

_meta

object | null

description

string | null

Optional description providing more details about this authentication method.

string

required

Unique identifier for this authentication method.

name

string

required

Human-readable name of the authentication method.

type

string

required

The discriminator value. Must be "agent".

other

object

Custom or future authentication method.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.Clients that do not understand this method type should preserve the raw payload when storing, replaying, proxying, or forwarding initialization data, and otherwise ignore the method or display it generically.

Show Properties

_meta

object | null

description

string | null

Optional description providing more details about this authentication method.

string

required

Unique identifier for this authentication method.

name

string

required

Human-readable name of the authentication method.

type

string

required

Custom or future authentication method type.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

AuthMethodAgent

Agent handles authentication itself. The type discriminator value is agent. Type: Object Properties:

_meta

object | null

description

string | null

Optional description providing more details about this authentication method.

string

required

Unique identifier for this authentication method.

name

string

required

Human-readable name of the authentication method.

AvailableCommand

Information about a command. Type: Object Properties:

_meta

object | null

description

string

required

Human-readable description of what the command does.

input

AvailableCommandInput | null

Input for the command if required

name

string

required

Command name (e.g., create_plan, research_codebase).

AvailableCommandInput

The input specification for a command. Type: Union

unstructured

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

Show Properties

_meta

object | null

hint

string

required

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

other

object

Custom or future command input specification.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.Clients that do not understand this input type should preserve the raw payload when storing, replaying, proxying, or forwarding command metadata, and otherwise ignore the input specification or display the command without structured input.

Show Properties

type

string

required

Custom or future command input type.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

AvailableCommandsUpdate

Available commands are ready or have changed Type: Object Properties:

_meta

object | null

availableCommands

AvailableCommand[]

required

Commands the agent can execute

BlobResourceContents

Binary resource contents. Type: Object Properties:

_meta

object | null

blob

string

required

mimeType

string | null

uri

string

required

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:

_meta

object | null

ConfigOptionUpdate

Session configuration options have been updated. Type: Object Properties:

_meta

object | null

configOptions

SessionConfigOption[]

required

The full set of configuration options and their current values.

Content

Standard content block (text, images, resources). Type: Object Properties:

_meta

object | null

content

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 reported through session/update notifications as message updates or streamed chunks
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

object

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.

Show Properties

_meta

object | null

annotations

Annotations | null

text

string

required

type

string

required

The discriminator value. Must be "text".

image

object

Images for visual context or analysis.Requires the image prompt capability when included in prompts.

Show Properties

_meta

object | null

annotations

Annotations | null

data

string

required

mimeType

string

required

type

string

required

The discriminator value. Must be "image".

uri

string | null

audio

object

Audio data for transcription or analysis.Requires the audio prompt capability when included in prompts.

Show Properties

_meta

object | null

annotations

Annotations | null

data

string

required

mimeType

string

required

type

string

required

The discriminator value. Must be "audio".

resource_link

object

References to resources that the agent can access.All agents MUST support resource links in prompts.

Show Properties

_meta

object | null

annotations

Annotations | null

description

string | null

mimeType

string | null

name

string

required

size

integer | null

title

string | null

type

string

required

The discriminator value. Must be "resource_link".

uri

string

required

resource

object

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.

Show Properties

_meta

object | null

annotations

Annotations | null

resource

EmbeddedResourceResource

required

type

string

required

The discriminator value. Must be "resource".

other

object

Custom or future content block.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.Receivers that do not understand this content block type should preserve the raw payload when storing, replaying, proxying, or forwarding content, and otherwise ignore it or display it generically.

Show Properties

type

string

required

Custom or future content block type.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

ContentChunk

A streamed item of content Type: Object Properties:

_meta

object | null

content

required

A single item of content

messageId

SessionConfigSelectOptions

required

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.

Cost

Cost information for a session. Type: Object Properties:

amount

number

required

Total cumulative cost for session.

currency

string

required

ISO 4217 currency code (e.g., “USD”, “EUR”).

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:

_meta

object | null

newText

string

required

The new content after modification.

oldText

string | null

The original content (None for new files).

path

string

required

The file path being modified.

EmbeddedResource

The contents of a resource, embedded into a prompt or tool call result. Type: Object Properties:

_meta

object | null

annotations

Annotations | null

resource

EmbeddedResourceResource

required

EmbeddedResourceResource

Resource content that can be embedded in a message. Type: Union

TextResourceContents

Show Properties

_meta

object | null

mimeType

string | null

text

string

required

uri

string

required

BlobResourceContents

Show Properties

_meta

object | null

blob

string

required

mimeType

string | null

uri

string

required

EnvVariable

An environment variable to set when launching an MCP server. Type: Object Properties:

_meta

object | null

name

string

required

The name of the environment variable.

value

string

required

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:

code

ErrorCode

required

A number indicating the error type that occurred. This must be an integer as defined in the JSON-RPC specification.

data

object

Optional primitive or structured value that contains additional information about the error. This may include debugging information or context-specific details.

message

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

-32700

int32

Parse error: Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.

-32600

int32

Invalid request: The JSON sent is not a valid Request object.

-32601

int32

Method not found: The method does not exist or is not available.

-32602

int32

Invalid params: Invalid method parameter(s).

-32603

int32

Internal error: Internal JSON-RPC error. Reserved for implementation-defined server errors.

-32000

int32

Authentication required: Authentication is required before this operation can be performed.

-32002

int32

Resource not found: A given resource, such as a file, was not found.

Other

int32

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

HttpHeader

An HTTP header to set when making requests to the MCP server. Type: Object Properties:

_meta

object | null

name

string

required

The name of the HTTP header.

value

string

required

The value to set for the HTTP header.

ImageContent

An image provided to or from an LLM. Type: Object Properties:

_meta

object | null

annotations

Annotations | null

data

string

required

mimeType

string

required

uri

string | 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:

_meta

object | null

name

string

required

Intended for programmatic or logical use, but can be used as a display name fallback if title isn’t present.

title

string | null

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

string

required

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

LogoutCapabilities

Logout capabilities supported by the agent. By supplying \{\} it means that the agent supports the logout method. Type: Object Properties:

_meta

object | null

McpCapabilities

MCP capabilities supported by the agent for session lifecycle requests. Type: Object Properties:

_meta

object | null

http

McpHttpCapabilities | null

Agent supports McpServer::Http.Optional. Omitted or null both mean the agent does not advertise support. Supplying \{\} means the agent supports HTTP MCP server transports.

stdio

McpStdioCapabilities | null

Agent supports McpServer::Stdio.Optional. Omitted or null both mean the agent does not advertise support. Supplying \{\} means the agent supports stdio MCP server transports.

McpHttpCapabilities

Capabilities for HTTP MCP server transports. Supplying \{\} means the agent supports HTTP MCP server transports. Type: Object Properties:

_meta

object | null

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

object

HTTP transport configurationOnly available when the Agent capabilities include session.mcp.http.

Show Properties

_meta

object | null

headers

HttpHeader[]

required

HTTP headers to set when making requests to the MCP server.

name

string

required

Human-readable name identifying this MCP server.

type

string

required

The discriminator value. Must be "http".

url

string

required

URL to the MCP server.

stdio

object

Stdio transport configurationOnly available when the Agent capabilities include session.mcp.stdio.

Show Properties

_meta

object | null

args

"string"[]

required

Command-line arguments to pass to the MCP server.

command

string

required

Path to the MCP server executable.

env

EnvVariable[]

required

Environment variables to set when launching the MCP server.

name

string

required

Human-readable name identifying this MCP server.

type

string

required

The discriminator value. Must be "stdio".

other

object

Custom or future MCP server transport configuration.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.Receivers that do not understand this transport should preserve the raw payload when storing, replaying, proxying, or forwarding session setup data, and otherwise ignore it or reject the server configuration.

Show Properties

type

string

required

Custom or future MCP server transport type.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

McpServerHttp

HTTP transport configuration for MCP. Type: Object Properties:

_meta

object | null

headers

HttpHeader[]

required

HTTP headers to set when making requests to the MCP server.

name

string

required

Human-readable name identifying this MCP server.

url

string

required

URL to the MCP server.

McpServerStdio

Stdio transport configuration for MCP. Type: Object Properties:

_meta

object | null

args

"string"[]

required

Command-line arguments to pass to the MCP server.

command

string

required

Path to the MCP server executable.

env

EnvVariable[]

required

Environment variables to set when launching the MCP server.

name

string

required

Human-readable name identifying this MCP server.

McpStdioCapabilities

Capabilities for stdio MCP server transports. Supplying \{\} means the agent supports stdio MCP server transports. Type: Object Properties:

_meta

object | null

MessageId

Unique identifier for a message within a session. Type: string

PermissionOption

An option presented to the user when requesting permission. Type: Object Properties:

_meta

object | null

kind

PermissionOptionKind

required

Hint about the nature of this permission option.

name

string

required

Human-readable label to display to the user.

optionId

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_once

string

Allow this operation only this time.

allow_always

string

Allow this operation and remember the choice.

reject_once

string

Reject this operation only this time.

reject_always

string

Reject this operation and remember the choice.

other

string

Custom or future permission option kind.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

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:

_meta

object | null

content

string

required

Human-readable description of what this task aims to accomplish.

priority

PlanEntryPriority

required

The relative importance of this task. Used to indicate which tasks are most critical to the overall goal.

status

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

string

High priority task - critical to the overall goal.

medium

string

Medium priority task - important but not critical.

low

string

Low priority task - nice to have but not essential.

other

string

Custom or future plan entry priority.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

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

pending

string

The task has not started yet.

in_progress

string

The task is currently being worked on.

completed

string

The task has been successfully completed.

other

string

Custom or future plan entry status.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

PlanId

Unique identifier for a plan within a session. Type: string

PlanItems

A plan represented as structured entries. Type: Object Properties:

_meta

object | null

entries

PlanEntry[]

required

The list of tasks to be accomplished.When updating an item-based plan, the agent must send a complete list of all entries with their current status. The client replaces that plan with each update.

PlanId

required

The plan ID to update.

PlanUpdate

A content update for a plan identified by ID. Type: Object Properties:

_meta

object | null

plan

PlanUpdateContent

required

The updated plan content.

PlanUpdateContent

Updated content for a plan. Type: Union

items

object

Structured plan entries.

Show Properties

_meta

object | null

entries

PlanEntry[]

required

The list of tasks to be accomplished.When updating an item-based plan, the agent must send a complete list of all entries with their current status. The client replaces that plan with each update.

PlanId

required

The plan ID to update.

type

string

required

The discriminator value. Must be "items".

other

object

Custom or future plan update content.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.Receivers that do not understand this content type should preserve the raw payload when storing, replaying, proxying, or forwarding plans, and otherwise ignore it or display it generically.

Show Properties

PlanId

required

The plan ID to update.

type

string

required

Custom or future plan update content type.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

PromptAudioCapabilities

Capabilities for audio content in prompt requests. Supplying \{\} means the agent supports audio content in prompts. Type: Object Properties:

_meta

object | null

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:

_meta

object | null

audio

PromptAudioCapabilities | null

Agent supports ContentBlock::Audio.Optional. Omitted or null both mean the agent does not advertise support. Supplying \{\} means the agent supports audio content in prompts.

embeddedContext

PromptEmbeddedContextCapabilities | null

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.Optional. Omitted or null both mean the agent does not advertise support. Supplying \{\} means the agent supports embedded context in prompts.

image

PromptImageCapabilities | null

Agent supports ContentBlock::Image.Optional. Omitted or null both mean the agent does not advertise support. Supplying \{\} means the agent supports image content in prompts.

PromptEmbeddedContextCapabilities

Capabilities for embedded context in prompt requests. Supplying \{\} means the agent supports embedded context in prompts. Type: Object Properties:

_meta

object | null

PromptImageCapabilities

Capabilities for image content in prompt requests. Supplying \{\} means the agent supports image content in prompts. Type: Object Properties:

_meta

object | null

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

cancelled

object

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

Show Properties

outcome

string

required

The discriminator value. Must be "cancelled".

selected

object

The user selected one of the provided options.

Show Properties

_meta

object | null

optionId

PermissionOptionId

required

The ID of the option the user selected.

outcome

string

required

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:

_meta

object | null

annotations

Annotations | null

description

string | null

mimeType

string | null

name

string

required

size

integer | null

title

string | null

uri

string

required

Role

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

assistant | user

enum

Values: "assistant", "user"

other

string

Custom or future role.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

SelectedPermissionOutcome

The user selected one of the provided options. Type: Object Properties:

_meta

object | null

optionId

PermissionOptionId

required

The ID of the option the user selected.

SessionAdditionalDirectoriesCapabilities

Capabilities for additional session directories support. By supplying \{\} it means that the agent supports the additionalDirectories field on supported session lifecycle requests. Agents that also support session/list may return SessionInfo.additionalDirectories to report the complete ordered additional-root list associated with a listed session. Type: Object Properties:

_meta

object | null

SessionCapabilities

Session capabilities supported by the agent. Supplying \{\} means the agent supports the baseline session methods: session/new, session/prompt, session/cancel, and session/update. Agents that support sessions MAY support additional session methods, prompt content types, and MCP transports by specifying additional capabilities. See protocol docs: Session Capabilities Type: Object Properties:

_meta

object | null

additionalDirectories

SessionAdditionalDirectoriesCapabilities | null

Whether the agent supports additionalDirectories on supported session lifecycle requests.Agents that also support session/list may return SessionInfo.additionalDirectories to report the complete ordered additional-root list associated with a listed session.

SessionCloseCapabilities | null

Whether the agent supports session/close.

delete

SessionDeleteCapabilities | null

Whether the agent supports session/delete.Optional. Omitted or null both mean the agent does not advertise support. Supplying \{\} means the agent supports deleting sessions from session/list.

list

SessionListCapabilities | null

Whether the agent supports session/list.

load

SessionLoadCapabilities | null

Whether the agent supports session/load.Optional. Omitted or null both mean the agent does not advertise support. Supplying \{\} means the agent supports loading sessions.

mcp

McpCapabilities | null

MCP capabilities supported by the agent for session lifecycle requests.Optional. Omitted or null both mean the agent does not advertise MCP server transport support for sessions.

prompt

PromptCapabilities | null

Prompt capabilities supported by the agent in session/prompt requests.Optional. Omitted or null both mean the agent does not advertise any prompt extensions beyond the baseline text and resource-link content required by session/prompt.

resume

SessionResumeCapabilities | null

Whether the agent supports session/resume.

SessionCloseCapabilities

Capabilities for the session/close method. By supplying \{\} it means that the agent supports closing of sessions. Type: Object Properties:

_meta

object | null

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 Shared properties:

_meta

object | null

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

mode

string

Session mode selector.

model

string

Model selector.

thought_level

string

Thought/reasoning level selector.

other

string

Custom or future category.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

SessionConfigSelect

A single-value selector (dropdown) session configuration option payload. Type: Object Properties:

currentValue

SessionConfigValueId

required

The currently selected value.

options

required

The set of selectable options.

SessionConfigSelectGroup

A group of possible values for a session configuration option. Type: Object Properties:

_meta

object | null

group

SessionConfigGroupId

required

Unique identifier for this group.

name

string

required

Human-readable label for this group.

options

SessionConfigSelectOption[]

required

The set of option values in this group.

SessionConfigSelectOption

A possible value for a session configuration option. Type: Object Properties:

_meta

object | null

description

string | null

Optional description for this option value.

name

string

required

Human-readable label for this option value.

value

SessionConfigValueId

required

Unique identifier for this option value.

SessionConfigSelectOptions

Possible values for a session configuration option. Type: Union

Ungrouped

array

A flat list of options with no grouping.

Grouped

array

A list of options grouped under headers.

SessionConfigValueId

Unique identifier for a session configuration option value. Type: string

SessionDeleteCapabilities

Capabilities for the session/delete method. Supplying \{\} means the agent supports deleting sessions from session/list. Type: Object Properties:

_meta

object | null

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:

_meta

object | null

additionalDirectories

"string"[]

Additional workspace roots reported for this session. Each path must be absolute.When present, this is the complete ordered additional-root list reported by the Agent. Omitted and empty values are equivalent: the response reports no additional roots.

cwd

string

required

The working directory for this session. Must be an absolute path.

sessionId

required

Unique identifier for the session

title

string | null

Human-readable title for the session

updatedAt

string | null

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:

_meta

object | null

title

string | null

Human-readable title for the session. Set to null to clear.

updatedAt

string | null

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:

_meta

object | null

SessionLoadCapabilities

Capabilities for the session/load method. Supplying \{\} means the agent supports loading sessions. Type: Object Properties:

_meta

object | null

SessionResumeCapabilities

Capabilities for the session/resume method. By supplying \{\} it means that the agent supports resuming of sessions. Type: Object Properties:

_meta

object | null

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

user_message_chunk

object

A chunk of the user’s message being streamed.

Show Properties

_meta

object | null

content

required

A single item of content

messageId

required

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.

sessionUpdate

string

required

The discriminator value. Must be "user_message_chunk".

user_message

object

A user message has been created or updated.Agents can send this when they accept or replay a user message. When a client receives another user_message update with the same messageId, fields in the new update patch the previous fields for that message.

Show Properties

_meta

object | null

content

ContentBlock[] | null

Complete replacement content for this message.

messageId

required

A unique identifier for the message.

sessionUpdate

string

required

The discriminator value. Must be "user_message".

agent_message_chunk

object

A chunk of the agent’s response being streamed.

Show Properties

_meta

object | null

content

required

A single item of content

messageId

required

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.

sessionUpdate

string

required

The discriminator value. Must be "agent_message_chunk".

agent_message

object

An agent message has been created or updated.Agents can send this in addition to streamed chunks. When a client receives another agent_message update with the same messageId, fields in the new update patch the previous fields for that message.

Show Properties

_meta

object | null

content

ContentBlock[] | null

Complete replacement content for this message.

messageId

required

A unique identifier for the message.

sessionUpdate

string

required

The discriminator value. Must be "agent_message".

agent_thought_chunk

object

A chunk of the agent’s internal reasoning being streamed.

Show Properties

_meta

object | null

content

required

A single item of content

messageId

required

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.

sessionUpdate

string

required

The discriminator value. Must be "agent_thought_chunk".

agent_thought

object

An agent thought or reasoning message has been created or updated.Agents can send this in addition to streamed chunks. When a client receives another agent_thought update with the same messageId, fields in the new update patch the previous fields for that message.

Show Properties

_meta

object | null

content

ContentBlock[] | null

Complete replacement content for this thought message.

messageId

required

A unique identifier for the thought message.

sessionUpdate

string

required

The discriminator value. Must be "agent_thought".

tool_call_content_chunk

object

A chunk of tool-call content being streamed.

Show Properties

_meta

object | null

content

ToolCallContent

required

A single item of content produced by the tool call.

sessionUpdate

string

required

The discriminator value. Must be "tool_call_content_chunk".

toolCallId

required

The ID of the tool call this content belongs to.

tool_call_update

object

A tool call has been created or updated.

Show Properties

_meta

object | null

content

ToolCallContent[] | null

Content produced by the tool call.

kind

ToolKind | null

The category of tool being invoked. Helps clients choose appropriate icons and UI treatment.

locations

ToolCallLocation[] | null

File locations affected by this tool call. Enables “follow-along” features in clients.

rawInput

object

Raw input parameters sent to the tool.

rawOutput

object

Raw output returned by the tool.

sessionUpdate

string

required

The discriminator value. Must be "tool_call_update".

status

ToolCallStatus | null

Current execution status of the tool call.

title

string | null

Human-readable title describing what the tool is doing.

toolCallId

required

Unique identifier for this tool call within the session.

plan_update

object

A content update for a plan identified by ID. See protocol docs: Agent Plan

Show Properties

_meta

object | null

plan

PlanUpdateContent

required

The updated plan content.

sessionUpdate

string

required

The discriminator value. Must be "plan_update".

available_commands_update

object

Available commands are ready or have changed

Show Properties

_meta

object | null

availableCommands

AvailableCommand[]

required

Commands the agent can execute

sessionUpdate

string

required

The discriminator value. Must be "available_commands_update".

config_option_update

object

Session configuration options have been updated.

Show Properties

_meta

object | null

configOptions

SessionConfigOption[]

required

The full set of configuration options and their current values.

sessionUpdate

string

required

The discriminator value. Must be "config_option_update".

session_info_update

object

Session metadata has been updated (title, timestamps, custom metadata)

Show Properties

_meta

object | null

sessionUpdate

string

required

The discriminator value. Must be "session_info_update".

title

string | null

Human-readable title for the session. Set to null to clear.

updatedAt

string | null

ISO 8601 timestamp of last activity. Set to null to clear.

usage_update

object

Context window and cost update for the session.

Show Properties

_meta

object | null

cost

Cost | null

Cumulative session cost (optional).

sessionUpdate

string

required

The discriminator value. Must be "usage_update".

size

uint64

required

Total context window size in tokens.

Minimum: 0

used

uint64

required

Tokens currently in context.

Minimum: 0

other

object

Custom or future session update.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.Receivers that do not understand this update type should preserve the raw payload when storing, replaying, proxying, or forwarding session history, and otherwise ignore it or display it generically.

Show Properties

sessionUpdate

string

required

Custom or future session update type.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

StopReason

Reasons why an agent stops processing a prompt turn. See protocol docs: Stop Reasons Type: Union

end_turn

string

The turn ended successfully.

max_tokens

string

The turn ended because the agent reached the maximum number of tokens.

max_turn_requests

string

The turn ended because the agent reached the maximum number of allowed agent requests between user turns.

refusal

string

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.

cancelled

string

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.

other

string

Custom or future stop reason.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

TextContent

Text provided to or from an LLM. Type: Object Properties:

_meta

object | null

annotations

Annotations | null

text

string

required

TextResourceContents

Text-based resource contents. Type: Object Properties:

_meta

object | null

mimeType

string | null

text

string

required

uri

string

required

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

content

object

Standard content block (text, images, resources).

Show Properties

_meta

object | null

content

required

The actual content block.

type

string

required

The discriminator value. Must be "content".

diff

object

File modification shown as a diff.

Show Properties

_meta

object | null

newText

string

required

The new content after modification.

oldText

string | null

The original content (None for new files).

path

string

required

The file path being modified.

type

string

required

The discriminator value. Must be "diff".

other

object

Custom or future tool call content.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.Receivers that do not understand this content type should preserve the raw payload when storing, replaying, proxying, or forwarding tool call output, and otherwise ignore it or display it generically.

Show Properties

type

string

required

Custom or future tool call content type.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

ToolCallContentChunk

A streamed item of tool-call content. Tool-call content chunks append one ToolCallContent item to the current content for the matching ToolCallId. Agents can use ToolCallUpdate::content when they need to replace the whole content collection instead. Type: Object Properties:

_meta

object | null

content

ToolCallContent

required

A single item of content produced by the tool call.

toolCallId

required

The ID of the tool call this content belongs to.

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:

_meta

object | null

line

integer | null

Optional line number within the file.

Minimum: 0

path

string

required

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

pending

string

The tool call hasn’t started running yet because the input is either streaming or we’re awaiting approval.

in_progress

string

The tool call is currently running.

completed

string

The tool call completed successfully.

failed

string

The tool call failed with an error.

other

string

Custom or future tool call status.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

ToolCallUpdate

Represents an upsert for 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. Only ToolCallUpdate::tool_call_id is required. Other fields have patch semantics: omitted fields leave the existing tool call value unchanged, null clears or unsets the value, and concrete values replace the previous value. For collection fields, concrete arrays replace the previous collection, and both null and [] clear the collection. When a client receives a tool call ID it has not seen before, omitted fields use client defaults. See protocol docs: Tool Calls Type: Object Properties:

_meta

object | null

content

ToolCallContent[] | null

Content produced by the tool call.

kind

ToolKind | null

The category of tool being invoked. Helps clients choose appropriate icons and UI treatment.

locations

ToolCallLocation[] | null

File locations affected by this tool call. Enables “follow-along” features in clients.

rawInput

object

Raw input parameters sent to the tool.

rawOutput

object

Raw output returned by the tool.

status

ToolCallStatus | null

Current execution status of the tool call.

title

string | null

Human-readable title describing what the tool is doing.

toolCallId

required

Unique identifier for this tool call within the session.

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

read

string

Reading files or data.

edit

string

Modifying files or content.

delete

string

Removing files or data.

move

string

Moving or renaming files.

string

Searching for information.

execute

string

Running commands or code.

think

string

Internal reasoning or planning.

fetch

string

Retrieving external data.

switch_mode

string

Switching the current session mode.

other

string

Other tool types (default).

unknown

string

Custom or future tool kind.Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

UnstructuredCommandInput

All text that was typed after the command name is provided as input. Type: Object Properties:

_meta

object | null

hint

string

required

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

UsageUpdate

Context window and cost update for a session. Type: Object Properties:

_meta

object | null

cost

Cost | null

Cumulative session cost (optional).

size

uint64

required

Total context window size in tokens.

Minimum: 0

used

uint64

required

Tokens currently in context.

Minimum: 0

UserMessage

A user message upsert. Only UserMessage::message_id is required. Other fields have patch semantics: omitted fields leave the existing message value unchanged, null clears or unsets the value, and concrete values replace the previous value. For a new messageId, omitted fields use client defaults. content is replaced as a whole array; send [] or null to clear it. Message updates and chunks are applied in the order they are received. When a user_message update includes content, that array replaces any content previously accumulated for the message, including content from earlier chunks. Later chunks with the same messageId append to the current content. Type: Object Properties:

_meta

object | null

content

ContentBlock[] | null

Complete replacement content for this message.

messageId