The schema file can be downloaded directly from the latest GitHub
release.
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.auth/status
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Queries the agent’s current authentication state. This method is only available if the agent advertises theauth.status capability.
It MUST NOT change any agent state, and agents MUST NOT reject it with auth_required.
AuthStatusRequest
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Request parameters for theauth/status method.
Queries the agent’s current authentication state without changing it.
Agents MUST NOT reject it with auth_required (-32000), since Clients call it to learn
whether authentication is required.
Type: Object
Properties:
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
AuthStatusResponse
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Response to theauth/status method.
Type: Object
Properties:
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 accounts the agent has configured, for display.Optional. Omitted and empty are equivalent and mean no accounts are reported.
Agents that hold credentials for several providers or accounts SHOULD list each
of them and mark the ones in effect with
active.Whether the agent can start sessions without the user signing in first.Clients use this field to decide whether sign-in is needed. Clients MUST treat
values they do not recognize as
unknown.authenticate
Authenticates the client using the specified authentication method. Called when the agent requires authentication before allowing session creation. The client provides an authentication method ID that was advertised during initialization and whose type defines theauthenticate flow.
After successful authentication, the client can proceed to create sessions with
session/new without receiving an auth_required (-32000) error.
See protocol docs: Initialization
AuthenticateRequest
Request parameters for the authenticate method. Specifies which authentication method to use. Type: Object Properties: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 theauthenticate method.
Type: Object
Properties:
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
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
InitializeRequest
Request parameters for the initialize method. Sent by the client to establish connection and negotiate capabilities. See protocol docs: Initialization Type: Object Properties: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
Capabilities supported by the client.
- Default:
{"fs":{"readTextFile":false,"writeTextFile":false},"terminal":false,"auth":{"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.
InitializeResponse
Response to theinitialize method.
Contains the negotiated protocol version and agent capabilities.
See protocol docs: Initialization
Type: Object
Properties:
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
Capabilities supported by the agent.
- Default:
{"loadSession":false,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false},"mcpCapabilities":{"http":false,"sse":false,"acp":false},"sessionCapabilities":{},"auth":{}}
Implementation | null
Information about the Agent name and version sent to the Client.Note: in future versions of the protocol, this will be required.
Authentication methods supported by the agent.
- Default:
[]
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
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
Request parameters for the logout method. Terminates the current authenticated session. Type: Object Properties: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
LogoutResponse
Response to thelogout method.
Type: Object
Properties:
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
mcp/message
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Sends an MCP-over-ACP notification.MessageMcpNotification
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Notification parameters formcp/message.
Sent by the provider to the consumer for an active request (including
subscription acknowledgements and updates). The outer envelope has no id.
Type: Object
Properties:
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
Optional inner MCP params.If omitted or set to
null, the inner MCP message has no params.providers/disable
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Disables a provider.DisableProviderRequest
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Request parameters forproviders/disable.
Type: Object
Properties:
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
DisableProviderResponse
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Response toproviders/disable.
Type: Object
Properties:
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
providers/list
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Lists providers that can be configured by the client.ListProvidersRequest
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Request parameters forproviders/list.
Type: Object
Properties:
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
ListProvidersResponse
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Response toproviders/list.
Type: Object
Properties:
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
providers/set
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Replaces the configuration for a provider.SetProviderRequest
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Request parameters forproviders/set.
Replaces the full configuration for one provider ID.
Type: Object
Properties:
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
Full headers map for this provider.
May include authorization, routing, or other integration-specific headers.
SetProviderResponse
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Response toproviders/set.
Type: Object
Properties:
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
session/archive
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Archives a session, hiding it from defaultsession/list results.
This method is only available if the agent advertises the sessionCapabilities.archive capability.
ArchiveSessionRequest
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Request parameters for archiving a session. Only available if the Agent supports thesessionCapabilities.archive capability.
Archiving hides the session from default session/list results. It keeps the session ID
and saved history. If the session is active, the Agent MUST cancel any ongoing work and
free the session’s resources as if session/close had been called, then archive it.
Archiving an archived session succeeds. A session that does not exist gets -32002.
Type: Object
Properties:
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
ArchiveSessionResponse
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Response from archiving a session. Type: Object Properties: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
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/updatenotifications - Respond to the original
session/promptrequest with thecancelledstop reason
CancelNotification
Notification to cancel ongoing operations for a session. See protocol docs: Cancellation Type: Object Properties: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
session/close
Closes an active session and frees up any resources associated with it. This method is only available if the agent advertises thesessionCapabilities.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 ifsession/cancel was called) and then free up any resources
associated with the session.
Only available if the Agent supports the sessionCapabilities.close capability.
Type: Object
Properties:
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
CloseSessionResponse
Response from closing a session. Type: Object Properties: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
session/delete
Deletes an existing session fromsession/list.
This method is only available if the agent advertises the sessionCapabilities.delete capability.
DeleteSessionRequest
Request parameters for deleting an existing session fromsession/list.
Only available if the Agent supports the sessionCapabilities.delete capability.
Type: Object
Properties:
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
DeleteSessionResponse
Response from deleting a session. Type: Object Properties: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
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 thesession.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.
As with session/new, the forked session is active once the agent responds,
set up with the request’s cwd, additionalDirectories, and mcpServers.
The client can prompt it without calling session/load or session/resume first.
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 thesession.fork capability.
Type: Object
Properties:
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
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 forked
session.
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Initial values for the forked session’s config options.Optional. Omitted and
null are equivalent to an empty list. Clients MUST only send
this when the Agent advertises sessionCapabilities.options.The Agent applies the entries in list order on top of the configuration the fork
starts with, as if the Client had called session/set_config_option for each entry
after the session was set up. Malformed entries and duplicate configId values fail
the request with -32602. The Agent MUST ignore an entry whose configId is unknown,
whose type does not match the option, or whose value is not allowed when it is
applied. The configOptions in the response contain the values the session actually
has. The Agent SHOULD NOT send config_option_update notifications for these entries,
and SHOULD NOT send other session/update notifications caused by applying them
before it responds.CursorId | null
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.The session cursor to fork at. The new session’s history is the source
session’s history before the cursor.Optional. Omitted and
null are equivalent and fork the whole session.
Clients MUST only send the ID of a cursor that the Agent announced on the
source session and that currently advertises capabilities.fork. The Agent
rejects any other ID with -32602. It does not fall back to forking the
whole session.List of MCP servers to connect to for this session.
SystemPrompt | null
System-level instructions for the forked session.Optional. Omitted and
null are equivalent. The Agent may then keep a
system prompt it stored with the source session or use its default
instructions. Clients MUST only send this when the Agent advertises
sessionCapabilities.systemPrompt, and SHOULD send the same value they used
for the source session.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: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
SessionConfigOption[] | null
Initial session configuration options if supported by the Agent.
SessionModeState | null
Initial mode state if supported by the AgentSee protocol docs: Session Modes
session/list
Lists existing sessions known to the agent. This method is only available if the agent advertises thesessionCapabilities.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 thesessionCapabilities.list capability.
Type: Object
Properties:
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
SessionArchiveFilter | null
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Filter sessions by archive state.Optional. Omitted and
null are equivalent and mean exclude. Only send this when
the Agent advertises the sessionCapabilities.archive capability. The filter combines with cwd and
applies before pagination. Clients keep the same value when following nextCursor.Opaque cursor token from a previous response’s nextCursor field for cursor-based pagination
ListSessionsResponse
Response from listing sessions. Type: Object Properties: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
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.
session/load
Loads an existing session to resume a previous conversation. This method is only available if the agent advertises theloadSession 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
LoadSessionRequest
Request parameters for loading an existing session. Only available if the Agent supports theloadSession capability.
See protocol docs: Loading Sessions
Type: Object
Properties:
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
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.UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Initial values for the session’s config options.Optional. Omitted and
null are equivalent to an empty list. Clients MUST only send
this when the Agent advertises sessionCapabilities.options.The Agent applies the entries in list order, as if the Client had called
session/set_config_option for each entry after the session was set up. Malformed
entries and duplicate configId values fail the request with -32602. The Agent MUST
ignore an entry whose configId is unknown, whose type does not match the option,
or whose value is not allowed when it is applied. The configOptions in the response contain the values the session actually
has. The Agent SHOULD NOT send config_option_update notifications for these entries.SystemPrompt | null
System-level instructions for the loaded session.Optional. Omitted and
null are equivalent. The Agent may then keep a
system prompt it stored with the session or use its default instructions.
Clients MUST only send this when the Agent advertises
sessionCapabilities.systemPrompt, and SHOULD send the same value they used
when the session was created.LoadSessionResponse
Response from loading an existing session. Type: Object Properties: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
SessionConfigOption[] | null
Initial session configuration options if supported by the Agent.
SessionModeState | null
Initial mode state if supported by the AgentSee 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
auth_required (-32000) 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: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
Additional workspace roots for this session. Each path must be absolute.These expand the session’s filesystem scope without changing
cwd, which
remains the base for relative paths. When omitted or empty, no
additional roots are activated for the new session.UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Initial values for the session’s config options.Optional. Omitted and
null are equivalent to an empty list. Clients MUST only send
this when the Agent advertises sessionCapabilities.options.The Agent applies the entries in list order, as if the Client had called
session/set_config_option for each entry after the session was set up. Malformed
entries and duplicate configId values fail the request with -32602. The Agent MUST
ignore an entry whose configId is unknown, whose type does not match the option,
or whose value is not allowed when it is applied. The configOptions in the response contain the values the session actually
has. The Agent SHOULD NOT send config_option_update notifications for these entries,
and SHOULD NOT send other session/update notifications caused by applying them
before it responds.SystemPrompt | null
System-level instructions for the new session.Optional. Omitted and
null are equivalent and mean the Agent uses its
own default instructions. Clients MUST only send this when the Agent
advertises sessionCapabilities.systemPrompt.NewSessionResponse
Response from creating a new session. See protocol docs: Creating a Session Type: Object Properties: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
SessionConfigOption[] | null
Initial session configuration options if supported by the Agent.
SessionModeState | null
Initial mode state if supported by the AgentSee protocol docs: Session Modes
Unique identifier for the created session.Used in all subsequent requests for this conversation.
session/options
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Returns the config options a session would start with, without creating or resuming a session. This method is only available if the agent advertises thesessionCapabilities.options capability.
SessionOptionsRequest
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Request parameters forsession/options, which returns the config options a session
would start with, without creating or resuming a session.
Only available if the Agent supports the sessionCapabilities.options capability.
session/options MUST NOT create or resume a session, send session/update
notifications, add an entry to session/list, or change an existing session. Agents
SHOULD NOT connect to MCP servers to answer it. Agents MAY start their runtime to resolve
the options. The rules above still hold for it.
Type: Object
Properties:
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
Additional workspace roots to resolve options for. Each path must be absolute.Optional. Omitted and
null are equivalent to an empty list.SessionId | null
The session to resolve options for.Optional. Omitted and
null are equivalent and mean a new session. When present,
the Agent returns what session/load or session/resume with the same cwd and
additionalDirectories would return, with the same cwd rules. A session the
Agent does not know gets -32002.
Clients MUST only send this when the Agent supports session/load (loadSession)
or session/resume (sessionCapabilities.resume).SessionOptionsResponse
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Response fromsession/options.
The result is a snapshot. The options a session actually starts with are the ones in
the session setup response.
Agents only return type: "boolean" options when the Client advertises
sessionCapabilities.configOptions.boolean.
Type: Object
Properties:
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
SessionConfigOption[] | null
The config options the session would start with, with the same rules as on
NewSessionResponse.Optional. Omitted, null, or empty means no config options are advertised.SessionModeState | null
The mode state the session would start with, if the Agent supports modes.See protocol docs: Session Modes
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
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: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 blocks of content that compose the user’s message.As a baseline, the Agent MUST support
text and resource_link content blocks,
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
resource or resource_link content blocks.When available, 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.PromptResponse
Response from processing a user prompt. See protocol docs: Check for Completion Type: Object Properties: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
Usage | null
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Token usage for this turn (optional).
session/resume
Resumes an existing session without returning previous messages. This method is only available if the agent advertises thesessionCapabilities.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 (unlikesession/load).
This is useful for agents that can resume sessions but don’t implement full session loading.
Only available if the Agent supports the sessionCapabilities.resume capability.
Type: Object
Properties:
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
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.UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Initial values for the session’s config options.Optional. Omitted and
null are equivalent to an empty list. Clients MUST only send
this when the Agent advertises sessionCapabilities.options.The Agent applies the entries in list order, as if the Client had called
session/set_config_option for each entry after the session was set up. Malformed
entries and duplicate configId values fail the request with -32602. The Agent MUST
ignore an entry whose configId is unknown, whose type does not match the option,
or whose value is not allowed when it is applied. The configOptions in the response contain the values the session actually
has. The Agent SHOULD NOT send config_option_update notifications for these entries.List of MCP servers to connect to for this session.
SystemPrompt | null
System-level instructions for the resumed session.Optional. Omitted and
null are equivalent. The Agent may then keep a
system prompt it stored with the session or use its default instructions.
Clients MUST only send this when the Agent advertises
sessionCapabilities.systemPrompt, and SHOULD send the same value they used
when the session was created.ResumeSessionResponse
Response from resuming an existing session. Type: Object Properties: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
SessionConfigOption[] | null
Initial session configuration options if supported by the Agent.
SessionModeState | null
Initial mode state if supported by the AgentSee 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 Shared properties: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
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.SetSessionConfigOptionResponse
Response tosession/set_config_option method.
Type: Object
Properties:
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
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 inavailableModes 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: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
SetSessionModeResponse
Response tosession/set_mode method.
Type: Object
Properties:
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
session/set_title
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Sets the title of a session. This method is only available if the agent advertises thesessionCapabilities.title capability.
The session does not need to be active on the connection. The agent stores the
title and returns the stored title, which may be normalized.
SetSessionTitleRequest
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Request parameters for setting the title of a session. Only available if the Agent supports thesessionCapabilities.title capability.
The session does not need to be active on the connection. Any session the Agent would
return from session/list can be retitled. A session that does not exist gets -32002.
The Agent responds only after it has stored the title. After a successful response, the
Agent SHOULD NOT replace the title with one it generates automatically.
Type: Object
Properties:
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 new title for the session.Required and non-null. Omission and explicit
null are both invalid. The Agent MAY
normalize the title before storing it, for example by trimming whitespace or
truncating it. The Agent rejects a title that fails its validation, including one
that is empty after normalization, with -32602.SetSessionTitleResponse
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Response from setting the title of a session. Type: Object Properties: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 title the Agent stored.This differs from the requested title if the Agent normalized it. Clients SHOULD
display this value rather than the one they sent.
session/status
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Checks whether the Agent has a session in memory, without changing it. This method is only available if the agent advertises thesessionCapabilities.status capability.
SessionStatusRequest
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Request parameters for checking the status of a session. Only available if the Agent supports thesessionCapabilities.status capability.
session/status MUST NOT have side effects. The Agent does not load, resume, create,
close, or change the session, and does not attach the requesting connection to it.
A session the Agent does not know gets -32002 with the requested sessionId in data.
Type: Object
Properties:
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
SessionStatusResponse
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Response from checking the status of a session. The result is a snapshot. A session reportedopen may be closed or evicted before
the Client’s next request.
Type: Object
Properties:
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
Whether the Agent has the session in memory.Required. Clients MUST treat a value they do not recognize as
saved.session/unarchive
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Unarchives a session, returning it to defaultsession/list results.
This method is only available if the agent advertises the sessionCapabilities.archive capability.
UnarchiveSessionRequest
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Request parameters for unarchiving a session. Only available if the Agent supports thesessionCapabilities.archive capability.
Unarchiving returns the session to default session/list results with the same ID and
saved history. It never loads or resumes the session. Clients that want to continue an
archived session SHOULD unarchive it before calling session/load or session/resume.
Unarchiving a session that is not archived succeeds. A session that does not exist
gets -32002.
Type: Object
Properties:
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
UnarchiveSessionResponse
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Response from unarchiving a session. Type: Object Properties: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
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.auth/status_update
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Notification that the agent’s authentication state changed. Only sent by agents that advertise theauth.status capability.
AuthStatusUpdateNotification
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 its authentication status changes. Carries the same fields as theauth/status response. Agents that advertise the
auth.status capability MAY send it at any time after initialize, and SHOULD only
send it when the reported status differs from the last one sent on the connection.
Type: Object
Properties:
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 accounts the agent has configured, for display.Optional. Omitted and empty are equivalent and mean no accounts are reported.
Agents that hold credentials for several providers or accounts SHOULD list each
of them and mark the ones in effect with
active.Whether the agent can start sessions without the user signing in first.Clients use this field to decide whether sign-in is needed. Clients MUST treat
values they do not recognize as
unknown.elicitation/complete
Notification that a URL-based elicitation has completed. See protocol docs: ElicitationCompleteElicitationNotification
Notification sent by the agent when a URL-based elicitation is complete. Type: Object Properties: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.Optional. Omitted and
null are equivalent and mean no metadata.See protocol docs: Extensibilityelicitation/create
Requests structured user input via a form or URL. See protocol docs: ElicitationCreateElicitationRequest
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. Elicitations are tied to a session (optionally a tool call) or a request. Type: Union Shared properties: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.Optional. Omitted and
null are equivalent and mean no metadata.See protocol docs: ExtensibilityForm-based elicitation where the client renders a form from the provided schema.Alternatives (
anyOf):Custom or future elicitation mode.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 mode should preserve the raw payload
when storing, replaying, proxying, or forwarding elicitation requests.
They MUST NOT render it as a known elicitation mode.Alternatives (anyOf):CreateElicitationResponse
Response from the client to an elicitation request. Type: Union Shared properties: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.Optional. Omitted and
null are equivalent and mean no metadata.See protocol docs: ExtensibilityCustom or future elicitation action.Values beginning with
_ are reserved for implementation-specific
extensions. Unknown values that do not begin with _ are reserved for
future ACP variants.Agents that do not understand this action should preserve the raw
payload when storing, replaying, proxying, or forwarding elicitation
responses. They MUST NOT treat it as a known elicitation action.fs/read_text_file
Reads content from a text file in the client’s file system. Only available if the client advertises thefs.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 thefs.readTextFile capability.
Type: Object
Properties:
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
ReadTextFileResponse
Response containing the contents of a text file. Type: Object Properties: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
fs/write_text_file
Writes content to a text file in the client’s file system. Only available if the client advertises thefs.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 thefs.writeTextFile capability.
Type: Object
Properties:
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
WriteTextFileResponse
Response tofs/write_text_file
Type: Object
Properties:
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
mcp/message
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Exchanges an MCP-over-ACP message.MessageMcpRequest
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Request parameters formcp/message.
Type: Object
Properties:
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
Optional inner MCP params.If omitted or set to
null, the inner MCP message has no params.MessageMcpResponse
UNSTABLE The successful outer ACPmcp/message response carries exactly one
inner MCP outcome: an opaque result (including JSON null), or an MCP error.
Outer ACP errors are reserved for binding and runtime failures.
Both branches require their carrier key. An error must be a non-null object.
Unknown outer fields are ignored. Inner result and error fields are preserved.
Carrier _meta is optional. Null or invalid values are treated as absent.
Senders must include exactly one outcome. Receivers prefer result if both are present.
Type: Union
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 viasession/cancel, it MUST
respond to this request with the cancelled outcome.
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: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
RequestPermissionResponse
Response to a permission request. Type: Object Properties: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
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 asession/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: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
terminal/create
Executes a command in a new terminal Only available if theterminal 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 terminal tool call content.
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: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
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
CreateTerminalResponse
Response containing the ID of the created terminal. Type: Object Properties: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
terminal/kill
Kills the terminal command without releasing the terminal Whileterminal/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: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
KillTerminalResponse
Response toterminal/kill method
Type: Object
Properties:
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
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: TerminalsTerminalOutputRequest
Request to get the current output and status of a terminal. Type: Object Properties: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
TerminalOutputResponse
Response containing the terminal output and exit status. Type: Object Properties: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
TerminalExitStatus | null
Exit status if the command has completed.
terminal/release
Releases a terminal The command is killed if it hasn’t exited yet. Useterminal/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: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
ReleaseTerminalResponse
Response to terminal/release method Type: Object Properties: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
terminal/wait_for_exit
Waits for the terminal command to exit and return its exit status See protocol docs: TerminalsWaitForTerminalExitRequest
Request to wait for a terminal command to exit. Type: Object Properties: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
WaitForTerminalExitResponse
Response containing the exit status of a terminal command. Type: Object Properties: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
Proxy
Defines the messages that a conductor and the proxies it manages send each other. Ordinary clients and agents never send or receive these messages. A conductor sendsproxy/initialize to each proxy and forwards messages between proxies with
proxy/successor.
proxy/initialize
Initializes a component as a proxy. Sent by a conductor to each component that has a successor, instead ofinitialize.
The params and response are the same as for initialize.
InitializeProxyRequest
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Request parameters forproxy/initialize.
A conductor sends proxy/initialize instead of initialize to every component that has a
successor, which tells the component to run as a proxy. The params and the response are
the same as for initialize. A conductor sends initialize to the final agent.
The params carry the protocol version the conductor selected: the client’s requested
version, unless the conductor supports only a lower one. Before answering successfully,
the proxy MUST forward an initialize request to its successor through proxy/successor.
See the Proxy Chains RFD.
InitializeProxyResponse
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Response toproxy/initialize.
The same as the initialize response. The proxy builds it from its successor’s
initialize response and answers with the capabilities of the chain from itself onward.
It MUST NOT change protocolVersion.
proxy/successor
Forwards a request to or from a proxy’s successor. A proxy sends it to its conductor to forward a request downstream. The conductor sends it to the proxy to deliver a request from the successor. The wrapped request’s result or error is returned unchanged.ProxySuccessorNotification
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Parameters of aproxy/successor notification.
A proxy sends it to forward a message to its successor, and the conductor sends it to
deliver a message from the successor to the proxy. The envelope wraps one notification: method
and params are the wrapped notification’s method and params.
See the Proxy Chains RFD.
Type: Object
Properties:
Metadata for the
proxy/successor envelope itself, separate from the wrapped
message’s _meta. It is hop-local: the conductor does not copy it into the message
it unwraps.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: ExtensibilityParams of the wrapped notification, forwarded unchanged.Optional. Omitted and
null are equivalent and mean the wrapped notification has no params.
When present, it MUST be a JSON object or array, as JSON-RPC requires.
The wrapped notification’s own _meta stays inside these params.ProxySuccessorRequest
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Parameters of aproxy/successor request.
A proxy sends it to forward a message to its successor, and the conductor sends it to
deliver a message from the successor to the proxy. The envelope wraps one request: method
and params are the wrapped request’s method and params.
The result or error of the wrapped request is returned unchanged, as the same JSON value,
as the result or error of the proxy/successor request. Errors the conductor returns
itself, for example because the successor has exited, are not wrapped results.
To cancel it, the sender sends $/cancel_request with the ID of this proxy/successor
request on the same connection. Cancellation is never forwarded to another hop.
See the Proxy Chains RFD.
Type: Object
Properties:
Metadata for the
proxy/successor envelope itself, separate from the wrapped
message’s _meta. It is hop-local: the conductor does not copy it into the message
it unwraps.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: ExtensibilityParams of the wrapped request, forwarded unchanged.Optional. Omitted and
null are equivalent and mean the wrapped request has no params.
When present, it MUST be a JSON object or array, as JSON-RPC requires.
The wrapped request’s own _meta stays inside these params.ProxySuccessorResponse
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Result of aproxy/successor request: the wrapped request’s result, forwarded unchanged.
Protocol Level
Defines the interface that ACP-compliant agents and clients must both implement. Notifications whose methods start with ‘/cancel_request` notification. If an agent or client receives notifications starting with ’$/’ it is free to ignore the notification.$/cancel_request
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:- MAY 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)
CancelRequestNotification
Notification to cancel an ongoing request. See protocol docs: Cancellation Type: Object Properties: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
AgentAuthCapabilities
Authentication-related capabilities supported by the agent. Type: Object Properties: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
LogoutCapabilities | null
Whether the agent supports the logout method.Optional. Omitted or
null both mean the agent does not advertise support.
Supplying \{\} means the agent supports the logout method.AuthStatusCapabilities | null
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Whether the agent supports the
auth/status method.Optional. Omitted or null both mean the agent does not advertise support.
Supplying \{\} means the agent supports the auth/status 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: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
Authentication-related capabilities supported by the agent.
- Default:
{}
MCP capabilities supported by the agent.
- Default:
{"http":false,"sse":false,"acp":false}
Prompt capabilities supported by the agent.
- Default:
{"image":false,"audio":false,"embeddedContext":false}
ProvidersCapabilities | null
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Provider configuration capabilities supported by the agent.Optional. Omitted or
null both mean the agent does not advertise support.
Supplying \{\} means the agent supports provider configuration methods.Session lifecycle and prompt capabilities advertised by the agent.
- Default:
{}
Annotations
Optional annotations for the client. The client can use annotations to inform how objects are used or displayed Type: Object Properties: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
Role[] | null
Intended recipients for this content, such as the user or assistant.
AudioContent
Audio provided to or from an LLM. Type: Object Properties: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
Annotations | null
Optional annotations that help clients decide how to display or route this content.
AuthAccount
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. An account or credential the agent has configured, such as a signed-in user account or an API key. All fields are display information only. Clients MUST NOT use them as stable account identifiers, and SHOULD NOT log them or send them elsewhere, such as to telemetry. Type: Object Properties: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
Whether the agent currently uses this account by default.Several accounts MAY be active, for example one per provider.Optional. Omitted and
null are equivalent and mean the agent does not indicate whether this account is in effect.Short text shown with the label, such as the credential source, for example
API key helper. MUST NOT contain credentials.Optional. Omitted and null are equivalent and mean no description is reported.Email address of the user.Optional. Omitted and
null are equivalent and mean no email is reported.Human-readable name for the account, suitable for display on its own,
for example
Claude Max, OpenAI API key, or Vertex AI.Display name of the user, such as a username or full name.Optional. Omitted and
null are equivalent and mean no name is reported.Display name of the organization, team, or workspace the account is using.Optional. Omitted and
null are equivalent and mean no organization is reported.AuthCapabilities
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: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
Whether the client supports
terminal authentication methods.The client should set this to true only when it can reproduce the
configured agent invocation in an interactive terminal. When true, the
agent may include terminal entries in its authentication methods.- Default:
false
AuthMethod
Describes an available authentication method. Thetype field acts as the discriminator in the serialized JSON form.
When no type is present, the method is treated as agent.
Type: Union
Client runs the configured agent program as a separate interactive
process, without passing this method to
authenticate.Agent handles authentication itself through
authenticate.This is the default when no type is specified.AuthMethodAgent
Agent handles authentication itself throughauthenticate.
This is the default authentication method type.
Type: Object
Properties:
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
AuthMethodId
Typed identifier used for auth method values on the wire. Type:string
AuthMethodTerminal
Terminal-based authentication method. The client runs the configured agent program as a separate interactive process for the user to authenticate via a TUI. Agents MUST advertise this method only when the client enabled its terminal authentication capability. A zero exit status signals success. Any other termination signals failure. The client MUST NOT pass this method toauthenticate.
Type: Object
Properties:
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
Additional environment variables to set on the configured agent invocation for terminal auth.
These values override same-named variables in the base launch configuration.
AuthState
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. The agent’s overall authentication state. Type: UnionThe user needs to sign in. This includes credentials that are missing,
expired, or known to be invalid.
Custom or future authentication state.Values beginning with
_ are reserved for implementation-specific
extensions. Unknown values that do not begin with _ are reserved for
future ACP variants.AuthStatusCapabilities
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Auth status capabilities supported by the agent. Supplying\{\} means the agent supports the auth/status method.
Type: Object
Properties:
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
AvailableCommand
Information about a command. Type: Object Properties: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
AvailableCommandInput | null
Input for the command if required
AvailableCommandInput
The input specification for a command. All text that was typed after the command name is provided as input. Type: Object Properties: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
AvailableCommandsUpdate
Available commands are ready or have changed Type: Object Properties: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
BlobResourceContents
Binary resource contents. Type: Object Properties: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
BooleanConfigOptionCapabilities
Capabilities for boolean session configuration options. Supplying\{\} means the client supports boolean session configuration options.
Type: Object
Properties:
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
BooleanPropertySchema
Schema for boolean properties in an elicitation form. Type: Object Properties: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.Optional. Omitted and
null are equivalent and mean no metadata.See protocol docs: ExtensibilityDefault value.Optional. Omitted and
null are equivalent and mean no default value is provided.Human-readable description.Optional. Omitted and
null are equivalent and mean no description is provided.Optional title for the property.Optional. Omitted and
null are equivalent and mean no title is provided.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: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
Authentication capabilities supported by the client.
Determines which authentication method types the agent may include
in its
InitializeResponse.- Default:
{"terminal":false}
ElicitationCapabilities | null
Elicitation capabilities supported by the client.
Determines which elicitation modes the agent may use.Optional. Omitted or
null both mean the client does not advertise
elicitation support.File system capabilities supported by the client.
Determines which file operations the agent can request.
- Default:
{"readTextFile":false,"writeTextFile":false}
PlanCapabilities | null
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Whether the client supports
plan_update and plan_removed session updates.Optional. Omitted or null both mean the client does not advertise support.
Supplying \{\} means the client can receive both update types.ClientSessionCapabilities | null
Session-related capabilities supported by the client.Optional. Omitted or
null both mean the client does not advertise any
session-related extensions.SubagentCapabilities | null
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Whether the client understands exposed subagent sessions.Optional and nullable. Omitted or
null both mean the client does not
advertise support.
Supplying \{\} means the client understands child associations, work-state
snapshots, session-directed messages, and restricted-session semantics.ClientSessionCapabilities
Session-related capabilities supported by the client. Type: Object Properties: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
CompactionCapabilities | null
Support for ID-addressed context compaction updates. Omitted or
null
means unsupported. \{\} advertises the complete compaction contract.Config option capabilities supported by the client.Omitted or
null both mean the client does not advertise support for any
config option extensions.SessionCursorsCapabilities | null
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Support for
cursor_update session updates.Optional. Omitted or null both mean the client does not advertise support.
Supplying \{\} means the client handles cursor_update.NoticeCapabilities | null
Support for live user-facing
notice session updates.Optional. Omitted or null both mean the client does not advertise support.
Supplying \{\} means the client can present notices to the user.UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Support for
prompt_suggestions_update session updates.Optional. Omitted or null both mean the client does not advertise support.
Supplying \{\} means the client can offer prompt suggestions made of
text and resource_link content blocks.CompactionCapabilities
Client support for ID-addressed context compaction updates. Type:object
CompactionId
Unique identifier for a context compaction within a session. Type:string
CompactionStatus
Lifecycle state of a context compaction. Type: UnionCustom or future compaction status.Values beginning with
_ are reserved for implementation-specific
extensions. Other unknown values are reserved for future ACP statuses.CompactionSummaryChunk
A content block appended to a compaction’s summary. A first-seen ID creates an in-progress compaction. Chunks append in receive order. Agents MUST only send this update when the Client advertised thesession.compaction Client capability.
Type: Object
Properties:
CompactionUpdate
A context compaction upsert. The first notification fixes the compaction’s timeline position. Later updates with the same ID patch that entity in place. Agents MUST only send this update when the Client advertised thesession.compaction Client capability.
summary, error, and _meta have patch semantics: omission leaves the
stored value unchanged, null clears it, and a concrete value replaces it.
summary: [] also clears the summary.
Type: Object
Properties:
ContentBlock[] | null
Complete replacement user-displayable summary content for the compaction.
ConfigOptionUpdate
Session configuration options have been updated. Type: Object Properties: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
Content
Standard content block (text, images, resources). Type: Object Properties: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
ContentBlock
Content blocks represent displayable information in the Agent Client Protocol. Content blocks appear in:- User prompts sent via
session/prompt - Language model output streamed through
session/updatenotifications - Progress updates and results from tool calls
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.
Images for visual context or analysis.Requires the
image prompt capability when included in prompts.Audio data for transcription or analysis.Requires the
audio prompt capability when included in prompts.References to resources that the agent can access.All agents MUST support resource links in prompts.
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.ContentChunk
A streamed item of content Type: Object Properties: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
MessageId | null
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: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
Unit of
amount: an ISO 4217 currency code (e.g., “USD”, “EUR”) for money, or another
unit such as “credits”.CurrentModeUpdate
The current mode of the session has changed See protocol docs: Session Modes Type: Object Properties: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
CursorAnchor
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Where a session cursor is, relative to an entity the Client holds. The anchor names the entity by its type and ID, andposition says on which
side of that entity the cursor is. A known type with a malformed payload is
an error. It does not fall back to the unknown-type variant.
See the Session Cursors RFD.
Type: Union
Custom or future anchor type.Values beginning with
_ are reserved for implementation-specific
extensions. Unknown values that do not begin with _ are reserved for
future ACP variants.A Client that does not recognize the type cannot place the cursor and
MUST NOT guess a place for it.CursorAnchorPosition
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. On which side of the anchored entity a session cursor is. Type: UnionThe cursor is immediately before the entity. The history before the cursor
does not include the entity.
The cursor is immediately after the entity. The history before the cursor
includes the entity and nothing that follows it in the timeline.
Custom or future position.Values beginning with
_ are reserved for implementation-specific
extensions. Other unknown values are reserved for future ACP positions.
A Client that does not recognize the value cannot place the cursor.CursorCapabilities
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. The methods that currently accept a session cursor. A malformed value falls back to no capabilities, so the Client never passes a cursor to a method the Agent did not advertise. See the Session Cursors RFD. Type: Object Properties:The _meta property is reserved by ACP to allow clients and agents to attach additional
metadata to their interactions. Omitted and
null are equivalent and mean no metadata.
Implementations MUST NOT assign meaning to keys they do not recognize.See protocol docs: ExtensibilityCursorForkCapabilities | null
Permits the Client to fork the session at this cursor with
session/fork.Omitted and null are equivalent and mean unsupported. An object (including \{\})
means supported.CursorCompactionAnchor
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. A session cursor anchor to a compaction. Type: Object Properties:The _meta property is reserved by ACP to allow clients and agents to attach additional
metadata to their interactions. Omitted and
null are equivalent and mean no metadata.
Implementations MUST NOT assign meaning to keys they do not recognize.See protocol docs: ExtensibilityCursorForkCapabilities
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Capability to fork the session at a cursor withsession/fork.
Supplying \{\} advertises support. An omitted or null fork does not.
Type: Object
Properties:
The _meta property is reserved by ACP to allow clients and agents to attach additional
metadata to their interactions. Omitted and
null are equivalent and mean no metadata.
Implementations MUST NOT assign meaning to keys they do not recognize.See protocol docs: ExtensibilityCursorId
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Unique identifier for a session cursor within a session. The Agent generates it, and it is never reused for another position in the session. Clients MUST NOT parse, change, or construct it. See the Session Cursors RFD. Type:string
CursorMessageAnchor
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. A session cursor anchor to a message. The anchor’stype names the kind of message.
Type: Object
Properties:
The _meta property is reserved by ACP to allow clients and agents to attach additional
metadata to their interactions. Omitted and
null are equivalent and mean no metadata.
Implementations MUST NOT assign meaning to keys they do not recognize.See protocol docs: ExtensibilityCursorToolCallAnchor
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. A session cursor anchor to a tool call. Type: Object Properties:The _meta property is reserved by ACP to allow clients and agents to attach additional
metadata to their interactions. Omitted and
null are equivalent and mean no metadata.
Implementations MUST NOT assign meaning to keys they do not recognize.See protocol docs: ExtensibilityCursorUpdate
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. A session cursor upsert. A cursor names one position in the session’s timeline. The first update for acursorId MUST include anchor. The anchor is fixed
after that, and later updates change only capabilities.
Agents MUST only send this update when the Client advertised
the session.cursors Client capability.
capabilities and _meta have patch semantics: omission leaves the stored
value unchanged, null clears it, and a concrete value replaces it.
See the Session Cursors RFD.
Type: Object
Properties:
CursorAnchor | null
Where the cursor is, relative to an entity the Client holds.Required on the first update for a cursor. The Agent MUST NOT change it afterwards.
A later update can omit it or repeat the same anchor. Omitted and
null are
equivalent and leave the stored anchor unchanged.CursorCapabilities | null
The methods that currently accept this cursor.Omission leaves the capabilities unchanged,
null clears them, and an object replaces
the whole previous value. A new cursor starts with none.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: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
ElicitationAcceptAction
The user accepted the elicitation and provided content. Type: Object Properties:ElicitationCapabilities
Elicitation capabilities supported by the client. Type: Object Properties: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.Optional. Omitted and
null are equivalent and mean no metadata.See protocol docs: ExtensibilityElicitationFormCapabilities | null
Whether the client supports form-based elicitation.Optional. Omitted and
null are equivalent and mean form support is not advertised.
Supplying \{\} explicitly advertises form support.ElicitationUrlCapabilities | null
Whether the client supports URL-based elicitation.Optional. Omitted or
null both mean the client does not advertise support.
Supplying \{\} means the client supports URL-based elicitation.ElicitationContentValue
Allowed wire representations forElicitationContentValue.
Type: Union
ElicitationFormCapabilities
Form-based elicitation capabilities. Supplying\{\} means the client supports form-based elicitation.
Type: Object
Properties:
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.Optional. Omitted and
null are equivalent and mean no metadata.See protocol docs: ExtensibilityElicitationFormMode
Form-based elicitation mode where the client renders a form from the provided schema. Type: Union Shared properties: Variants:Tied to a specific JSON-RPC request outside of a session
(e.g., during auth/configuration phases before any session is started).
ElicitationId
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 type: "string" with enum or oneOf set.
Multi-select enums use type: "array".
Type: Union
Custom or future elicitation property schema.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 property schema type should preserve
the raw schema when storing, replaying, proxying, or forwarding
elicitation requests. They MUST NOT render it as a known input control.ElicitationRequestScope
Request-scoped elicitation, tied to a specific JSON-RPC request outside of a session (e.g., during auth/configuration phases before any session is started). Type: Object Properties: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: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.Optional. Omitted and
null are equivalent and mean no metadata.See protocol docs: ExtensibilityOptional description of what this schema represents.Optional. Omitted and
null are equivalent and mean no schema description is provided.List of required property names.Optional. Omitted and
null are equivalent and mean no property names are required.Optional title for the schema.Optional. Omitted and
null are equivalent and mean no title is provided.Type discriminator. Always
"object".- Default:
"object"
ElicitationSchemaType
Type discriminator for elicitation schemas. Type: UnionElicitationSessionScope
Session-scoped elicitation, optionally tied to a specific tool call. WhentoolCallId is set, the elicitation is tied to a specific tool call.
This is useful when an agent receives an elicitation from an MCP server
during a tool call and needs to redirect it to the user.
Type: Object
Properties:
ToolCallId | null
Optional tool call within the session.Optional. Omitted and
null are equivalent and mean the elicitation is scoped to the
session without a specific tool call.ElicitationUrlCapabilities
URL-based elicitation capabilities. Supplying\{\} means the client supports URL-based elicitation.
Type: Object
Properties:
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.Optional. Omitted and
null are equivalent and mean no metadata.See protocol docs: ExtensibilityElicitationUrlMode
URL-based elicitation mode where the client directs the user to a URL. Type: Union Shared properties: Variants:Tied to a specific JSON-RPC request outside of a session
(e.g., during auth/configuration phases before any session is started).
EmbeddedResource
The contents of a resource, embedded into a prompt or tool call result. Type: Object Properties: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
Annotations | null
Optional annotations that help clients decide how to display or route this content.
EmbeddedResourceResource
Resource content that can be embedded in a message. Type: UnionEnumOption
A titled enum option with a const value, human-readable title, and optional description. Type: Object Properties: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.Optional. Omitted and
null are equivalent and mean no metadata.See protocol docs: ExtensibilityHuman-readable description.Optional. Omitted and
null are equivalent and mean no description is provided.EnvVariable
An environment variable to set when launching an MCP server. Type: Object Properties: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
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:A number indicating the error type that occurred. This must be an integer as
defined in the JSON-RPC specification.
Optional primitive or structured value that contains additional information
about the error. This may include debugging information or context-specific
details.
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. Standard errors use the JSON-RPC 2.0 codes. ACP-specific errors use the JSON-RPC server-error range (-32000 to -32099), and request cancellation uses -32800 from the range LSP reserves (-32899 to -32800). Type: UnionParse error: Invalid JSON was received by the server. An error occurred on
the server while parsing the JSON text.
Request cancelled: Execution of the method was aborted either due to a
cancellation request from the caller or because of resource constraints or
shutdown.
ErrorStopReason
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Details of a failure that ended a child’s foreground work. Type: Object Properties:Error | null
The failure, as a JSON-RPC error object.Optional. Omitted or
null both mean the agent is not reporting failure details.
Agents SHOULD include it.ExtNotification
Allows either side 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: ExtensibilityExtRequest
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: ExtensibilityExtResponse
Allows for sending an arbitrary response to an extension 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: ExtensibilityFileSystemCapabilities
File system capabilities that a client may support. See protocol docs: FileSystem Type: Object Properties: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
HttpHeader
An HTTP header to set when making requests to the MCP server. Type: Object Properties: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
IdleStateUpdate
The child is ready to process another prompt. An omitted,null, or malformed stopReason means not reported.
Type: Union
Shared properties:
The _meta property is reserved by ACP for additional metadata.
Implementations MUST NOT make assumptions about values at these keys.
Optional. Omitted and
null mean no metadata for this state snapshot.Why foreground work stopped. The value selects one of this type’s variants, which may add fields of their own.Optional. Omitted or
null both mean the agent is not reporting a stop reason; a malformed value is treated the same way.See protocol docs: Work stateUsage | null
UNSTABLE Token usage for completed foreground work.Optional. Omitted or
null means not reported.Custom or future stop reason.Values beginning with
_ are reserved for implementation-specific
extensions. Other unknown values are reserved for future ACP variants.ImageContent
An image provided to or from an LLM. Type: Object Properties: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
Annotations | null
Optional annotations that help clients decide how to display or route this content.
Implementation
Metadata about the implementation of the client or agent. Describes the name and version of an ACP implementation, with an optional title for UI representation. Type: Object Properties: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
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 and 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”).
InitialSessionConfigOption
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. An initial value for a config option, sent on session setup requests. Same shape assession/set_config_option without sessionId. Unlike
session/set_config_option, an unknown configId, a type that does not match the
option, or a value that is not allowed is ignored instead of rejected.
Clients only send type: "boolean" entries when they advertise
sessionCapabilities.configOptions.boolean.
Type: Union
Shared properties:
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
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.IntegerPropertySchema
Schema for integer properties in an elicitation form. Type: Object Properties: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.Optional. Omitted and
null are equivalent and mean no metadata.See protocol docs: ExtensibilityDefault value.Optional. Omitted and
null are equivalent and mean no default value is provided.Human-readable description.Optional. Omitted and
null are equivalent and mean no description is provided.Maximum value (inclusive).Optional. Omitted and
null are equivalent and mean there is no inclusive upper bound.Minimum value (inclusive).Optional. Omitted and
null are equivalent and mean there is no inclusive lower bound.Optional title for the property.Optional. Omitted and
null are equivalent and mean no title is provided.LlmProtocol
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Well-known API protocol identifiers for LLM providers. Agents and clients MUST handle unknown protocol identifiers gracefully. Protocol names beginning with_ are free for custom use, like other ACP extension methods.
Protocol names that do not begin with _ are reserved for the ACP spec.
Type: Union
LogoutCapabilities
Logout capabilities supported by the agent. Supplying\{\} means the agent supports the logout method.
Type: Object
Properties:
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
McpCapabilities
MCP capabilities supported by the agent Type: Object Properties: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
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Agent supports
acp MCP servers.- Default:
false
McpError
UNSTABLE An inner MCP error, distinct from an outer ACP binding or runtime error.code and message are required and non-null. data is optional.
Explicit null is preserved separately from an omitted key.
Type: Object
Properties:
McpRequestId
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Identifies an inner MCP request active against a server on this ACP connection. Generated by the caller and preserved unchanged by proxies. This is distinct from the outer ACP JSON-RPC request ID. Type:string
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: UnionHTTP transport configurationOnly available when the Agent capabilities indicate
mcp_capabilities.http is true.SSE transport configurationOnly available when the Agent capabilities indicate
mcp_capabilities.sse is true.UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.ACP transport configurationOnly available when the Agent capabilities indicate
mcp_capabilities.acp is true.
The MCP server is provided by an ACP component and communicates over the ACP channel.McpServerAcp
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. ACP transport configuration for MCP. The MCP server is provided by an ACP component and communicates over the ACP channel usingmcp/message.
Type: Object
Properties:
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
Unique identifier for this MCP server, generated by the component providing it.Providers MUST NOT reuse an ID for multiple ACP-transport MCP servers that are visible
on the same ACP connection.
McpServerAcpId
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Unique identifier for an MCP server using the ACP transport. The value is opaque and generated by the ACP component providing the MCP server. It is used bymcp/message to route requests to the component that declared the server.
Type: string
McpServerHttp
HTTP transport configuration for MCP. Type: Object Properties: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
McpServerSse
SSE transport configuration for MCP. Type: Object Properties: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
McpServerStdio
Stdio transport configuration for MCP. Type: Object Properties: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
MessageId
Unique identifier for a message within a session. Type:string
MultiSelectItems
Items for a multi-select (array) property schema. Type: UnionTitled multi-select items with human-readable labels.As in MCP, titled items omit
type and are identified by anyOf.MultiSelectPropertySchema
Schema for multi-select (array) properties in an elicitation form. Type: Object Properties: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.Optional. Omitted and
null are equivalent and mean no metadata.See protocol docs: ExtensibilityDefault selected values.Optional. Omitted and
null are equivalent and mean no default selections are provided.Human-readable description.Optional. Omitted and
null are equivalent and mean no description is provided.Maximum number of items to select.Optional. Omitted and
null are equivalent and mean there is no maximum selection count.- Minimum:
0
Minimum number of items to select.Optional. Omitted and
null are equivalent and mean there is no minimum selection count.- Minimum:
0
Optional title for the property.Optional. Omitted and
null are equivalent and mean no title is provided.Notice
Fire-and-forget information for the user. Notices are live events rather than session history. Agents must not rely on a notice being received, displayed, or seen by the user. Agents MUST only send notices when the Client advertised thesession.notices Client capability. Otherwise, Agents may use an agent
message when the information should still be surfaced to the user.
See RFD: Session Notices
Type: Object
Properties:
Metadata scoped to this notice.Omitted and
null are equivalent and mean no metadata was supplied.Optional plain-text detail or guidance.Omitted and
null are equivalent and mean no description was supplied.NoticeCapabilities
Client support for presenting live notices to the user. Type:object
NoticeSeverity
Severity hint for a session notice. Type: UnionCustom or future notice severity.Values beginning with
_ are reserved for implementation-specific
extensions. Other unknown values are reserved for future ACP severities.NumberPropertySchema
Schema for number (floating-point) properties in an elicitation form. Type: Object Properties: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.Optional. Omitted and
null are equivalent and mean no metadata.See protocol docs: ExtensibilityDefault value.Optional. Omitted and
null are equivalent and mean no default value is provided.Human-readable description.Optional. Omitted and
null are equivalent and mean no description is provided.Maximum value (inclusive).Optional. Omitted and
null are equivalent and mean there is no inclusive upper bound.Minimum value (inclusive).Optional. Omitted and
null are equivalent and mean there is no inclusive lower bound.Optional title for the property.Optional. Omitted and
null are equivalent and mean no title is provided.PermissionOption
An option presented to the user when requesting permission. Type: Object Properties: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
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: UnionPlan
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: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 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.
PlanCapabilities
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Capabilities for receivingplan_update and plan_removed session updates.
Type: Object
Properties:
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
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: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 relative importance of this task.
Used to indicate which tasks are most critical to the overall goal.
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: UnionPlanEntryStatus
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: UnionPlanId
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Unique identifier for a plan within a session. Type:string
PlanItems
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. A plan represented as structured entries. Type: Object Properties: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 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.
PlanMarkdown
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. A plan represented as raw markdown content. Type: Object Properties: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 absolute path of the file that holds this plan.This field is optional. Omitting it or sending
null both mean that the plan
has no file. content is the plan to display whether or not path is set.
Clients can use path to open the file.PlanRemoved
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Removal notice for a plan identified by ID. Type: Object Properties: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
PlanUpdate
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. A content update for a plan identified by ID. Type: Object Properties: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
PlanUpdateContent
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Updated content for a plan. Type: UnionPromptCapabilities
Prompt capabilities supported by the agent insession/prompt requests.
Baseline agent functionality requires support for text
and resource_link content blocks 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:
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
Agent supports embedded context in
session/prompt requests.When enabled, the Client is allowed to include resource content blocks
in prompt requests for pieces of context that are referenced in the message.- Default:
false
PromptSuggestion
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. A prompt the Agent predicts the user will send next. Type: Object Properties: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 content of the suggested prompt.Required and non-null. Must contain at least one content block. This is
the same type as the
prompt field of session/prompt, and the Client
can send it in that field unchanged.Agents MUST only use text and resource_link content blocks, and
other content block types that both the Agent’s prompt capabilities
and the Client’s session.promptSuggestions capability advertise.
Agents MUST NOT send a prompt whose only content is empty or
whitespace-only text.PromptSuggestionsAudioCapabilities
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Capabilities for audio content in prompt suggestions. Supplying\{\} means the client can offer suggestions that include audio.
Type: Object
Properties:
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
PromptSuggestionsCapabilities
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Client support forprompt_suggestions_update session updates.
Supplying \{\} means the client can offer prompt suggestions made of text
and resource_link content blocks. The client opts in to other content
block types with the fields below. They have the same names as the agent’s
prompt capabilities.
Type: Object
Properties:
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
Whether prompt suggestions may include
audio content blocks.Optional. Omitted or null both mean the client does not advertise support.
Supplying \{\} means the client can offer suggestions that include audio.Whether prompt suggestions may include
resource content blocks.Optional. Omitted or null both mean the client does not advertise support.
Supplying \{\} means the client can offer suggestions that include
embedded resources.Whether prompt suggestions may include
image content blocks.Optional. Omitted or null both mean the client does not advertise support.
Supplying \{\} means the client can offer suggestions that include images.PromptSuggestionsEmbeddedContextCapabilities
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Capabilities for embedded resources in prompt suggestions. Supplying\{\} means the client can offer suggestions that include
resource content blocks.
Type: Object
Properties:
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
PromptSuggestionsImageCapabilities
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Capabilities for image content in prompt suggestions. Supplying\{\} means the client can offer suggestions that include images.
Type: Object
Properties:
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
PromptSuggestionsUpdate
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Replaces the session’s current list of prompt suggestions. A prompt suggestion is a prompt the Agent predicts the user will send next. The Client offers suggestions where the user writes the next prompt. The list in the most recent update is the current list until the Agent sends another update. A session starts with an empty list. Suggestions are not part of session history. Agents SHOULD NOT include this update when they replay a session. Agents MUST only send this update when the Client advertised thesession.promptSuggestions Client capability.
Type: Object
Properties:
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 suggestions the Client can offer, ordered most likely first.Required and non-null. An empty list withdraws the suggestions the
Client is offering. A Client skips an entry it cannot parse and keeps
the rest.
ProtocolVersion
Protocol version identifier. This version is only bumped for breaking changes. Non-breaking changes should be introduced via capabilities. Type:integer (uint16)
ProviderCurrentConfig
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Current effective non-secret routing configuration for a provider. Type: Object Properties: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
ProviderId
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Unique identifier for a configurable LLM provider. Type:string
ProviderInfo
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Information about a configurable LLM provider. Type: Object Properties: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
ProviderCurrentConfig | null
Current effective non-secret routing config.
Null or omitted means provider is disabled.
Whether this provider is mandatory and cannot be disabled via
providers/disable.
If true, clients must not call providers/disable for this provider ID.ProvidersCapabilities
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Provider configuration capabilities supported by the agent. Supplying\{\} means the agent supports provider configuration methods.
Type: Object
Properties:
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
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: UnionRequestPermissionOutcome
The outcome of a permission request. Type: UnionThe 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: CancellationRequiresActionStateUpdate
Foreground work is blocked on user action. Type: Object Properties:The _meta property is reserved by ACP for additional metadata. Implementations
MUST NOT make assumptions about values at these keys. Optional. Omitted and
null mean no metadata for this state snapshot.ResourceLink
A resource that the server is capable of reading, included in a prompt or tool call result. Type: Object Properties: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
Annotations | null
Optional annotations that help clients decide how to display or route this content.
Role
The sender or recipient of messages and data in a conversation. Type: UnionRunningStateUpdate
Foreground work is in progress. Type: Object Properties:The _meta property is reserved by ACP for additional metadata. Implementations
MUST NOT make assumptions about values at these keys. Optional. Omitted and
null mean no metadata for this state snapshot.SelectedPermissionOutcome
The user selected one of the provided options. Type: Object Properties: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
SessionAdditionalDirectoriesCapabilities
Capabilities for additional session directories support. Supplying\{\} means 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:
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
SessionArchiveCapabilities
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Capabilities forsession/archive and session/unarchive.
Supplying \{\} means the agent supports both methods, the archived filter on
session/list, and SessionInfo.archived.
Type: Object
Properties:
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
SessionArchiveFilter
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Which sessionssession/list returns based on their archive state.
Unknown values are preserved so they can be stored, proxied, or forwarded. An Agent MUST
return -32602 for a value it does not support rather than treating it as exclude.
Type: Union
Custom or future archive filter.Values beginning with
_ are reserved for implementation-specific
extensions. Unknown values that do not begin with _ are reserved for
future ACP variants.SessionCancelCapabilities
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Capability to cancel work in a subagent session without ending that session. Supplying\{\} advertises support. An omitted or null cancel does not.
Type: Object
Properties:
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
SessionCapabilities
Session capabilities supported by the agent. As a baseline, all Agents MUST supportsession/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 loadSession capability. This will be unified in future versions of the protocol.
See protocol docs: Session Capabilities
Type: Object
Properties:
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
Whether the agent supports
additionalDirectories on supported session lifecycle requests.Optional. Omitted or null both mean the agent does not advertise support.
Supplying \{\} means 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.SessionArchiveCapabilities | null
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Whether the agent supports
session/archive and session/unarchive.Optional. Omitted or null both mean the agent does not advertise support.
Supplying \{\} means the agent supports both methods, the archived filter on
session/list, and SessionInfo.archived. Agents that advertise it MUST also advertise sessionCapabilities.list.SessionCloseCapabilities | null
Whether the agent supports
session/close.Optional. Omitted or null both mean the agent does not advertise support.
Supplying \{\} means the agent supports closing sessions.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.SessionForkCapabilities | null
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Whether the agent supports
session/fork.Optional. Omitted or null both mean the agent does not advertise support.
Supplying \{\} means the agent supports forking sessions.SessionListCapabilities | null
Whether the agent supports
session/list.Optional. Omitted or null both mean the agent does not advertise support.
Supplying \{\} means the agent supports listing sessions.SessionOptionsCapabilities | null
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Whether the agent supports
session/options.Optional. Omitted or null both mean the agent does not advertise support.
Supplying \{\} means the agent supports session/options and accepts initial
config option values on session setup requests.SessionResumeCapabilities | null
Whether the agent supports
session/resume.Optional. Omitted or null both mean the agent does not advertise support.
Supplying \{\} means the agent supports resuming sessions.SessionStatusCapabilities | null
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Whether the agent supports
session/status.Optional. Omitted or null both mean the agent does not advertise support.
Supplying \{\} means the agent supports checking session status.Whether the agent supports
systemPrompt on session lifecycle requests.Optional. Omitted or null both mean the agent does not advertise support.
Supplying \{\} means the agent supports systemPrompt in append mode.SessionTitleCapabilities | null
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Whether the agent supports
session/set_title.Agents report titles through session/list and session_info_update without this
capability. It only advertises that Clients can set titles.Optional. Omitted or null both mean the agent does not advertise support.
Supplying \{\} means the agent supports setting session titles.SessionCloseCapabilities
Capabilities for thesession/close method.
Supplying \{\} means the agent supports closing sessions.
Type: Object
Properties:
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
SessionConfigBoolean
A boolean on/off toggle session configuration option payload. Type: Object Properties: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: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
SessionConfigOptionCategory | null
Optional semantic category for this option (UX only).
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
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Response speed selector, such as a fast mode toggle.
SessionConfigOptionsCapabilities
Session configuration option capabilities supported by the client. Type: Object Properties: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
Whether the client supports boolean session configuration options.Optional. Omitted or
null both mean the client does not advertise support.
Supplying \{\} means agents may include type: "boolean" entries in
configOptions, and the client may send session/set_config_option
requests with type: "boolean" and a boolean value.SessionConfigSelect
A single-value selector (dropdown) session configuration option payload. Type: Object Properties:SessionConfigSelectGroup
A group of possible values for a session configuration option. Type: Object Properties: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
SessionConfigSelectOption
A possible value for a session configuration option. Type: Object Properties: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
SessionConfigSelectOptions
Possible values for a session configuration option. Type: UnionSessionConfigValueId
Unique identifier for a session configuration option value. Type:string
SessionCursorsCapabilities
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Client support forcursor_update session updates.
See the Session Cursors RFD.
Type: object
SessionDeleteCapabilities
Capabilities for thesession/delete method.
Supplying \{\} means the agent supports deleting sessions from session/list.
Type: Object
Properties:
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
SessionForkCapabilities
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Capabilities for thesession/fork method.
Supplying \{\} means the agent supports forking sessions.
Type: Object
Properties:
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
SessionId
A unique identifier for a conversation session between a client and agent. Each session has its own context, conversation history, and state, so one agent can run several independent sessions. See protocol docs: Session ID Type:string
SessionInfo
Information about a session returned by session/list Type: Object Properties: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
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.
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Whether the session is archived.Optional. Omitted and
null are equivalent and mean the archive state is not reported.
Agents that advertise the sessionCapabilities.archive capability MUST include it on every listed session.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. Clients can use it to keep session titles and state current. Type: Object Properties: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
SessionListCapabilities
Capabilities for thesession/list method.
Supplying \{\} means the agent supports listing sessions.
Type: Object
Properties:
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
SessionMessage
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. An upsert for an inter-session message. Type: Object Properties:Omitted leaves metadata unchanged.
null removes it.Implementations MUST NOT make assumptions about values in _meta.ContentBlock[] | null
Omitted leaves content unchanged.
null or [] clears it.
A non-empty array replaces all content.MessageId | null
On an outgoing view, the
messageId of the same message’s incoming view in the
recipient’s transcript.Omitted leaves the stored value unchanged. null clears it. A value replaces it. It can arrive
after the message starts streaming.SessionId | null
The receiving session.Omitted leaves the stored value unchanged.
null clears it. A value replaces it.MessageId | null
On an incoming view, the
messageId of the same message’s outgoing view in the
sender’s transcript.Omitted leaves the stored value unchanged. null clears it. A value replaces it. It can arrive
after the message starts streaming.SessionId | null
The sending session.Omitted leaves the stored value unchanged.
null clears it. A value replaces it.SessionMessageChunk
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. A streamed content block of an inter-session message. A chunk carries only content. The message’s participants and references come fromsession_message upserts, which can arrive before, between, or after its chunks.
Type: Object
Properties:
Optional and nullable chunk-scoped metadata. Omitted or
null means none.Implementations MUST NOT make assumptions about values in _meta.SessionMode
A mode the agent can operate in. See protocol docs: Session Modes Type: Object Properties: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
SessionModeId
Unique identifier for a Session Mode. Type:string
SessionModeState
The set of modes and the one currently active. Type: Object Properties: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
SessionOptionsCapabilities
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Capabilities for thesession/options method.
Supplying \{\} means the agent supports session/options and accepts initial config
option values on session setup requests.
Type: Object
Properties:
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
SessionReference
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. A display-only reference to another session that this tool call operates on, such as a subagent it created, delegated to, or is waiting on. The referenced session must already be known to the Client through ordinary session setup or asubagent_update announcement. The reference does not
establish ownership, grant any Client-initiated controls, or report that the
referenced session received or finished any work.
Type: Object
Properties:
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
SessionResumeCapabilities
Capabilities for thesession/resume method.
Supplying \{\} means the agent supports resuming sessions.
Type: Object
Properties:
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
SessionStatus
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Whether the Agent has a session in memory, as reported bysession/status.
Type: Union
The Agent has the session in memory, for any connection.This does not mean the requesting connection is attached to it. A Client that did
not create or resume the session on its own connection MUST still call
session/load or session/resume before sending session/prompt or expecting
session/update notifications.The Agent knows the session and can resume it, but does not have it in memory.The Client can call
session/load or session/resume to start it.Custom or future session status.Values beginning with
_ are reserved for implementation-specific
extensions. Unknown values that do not begin with _ are reserved for
future ACP variants. Clients MUST treat a value they do not recognize as
saved.SessionStatusCapabilities
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Capabilities for thesession/status method.
Supplying \{\} means the agent supports checking session status.
Type: Object
Properties:
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
SessionSystemPromptCapabilities
Capabilities for client-provided system prompts. Supplying\{\} means the agent supports systemPrompt on session lifecycle
requests in append mode.
Type: Object
Properties:
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
Delivery modes the agent supports in addition to
append.Optional. Omitted or null both mean the agent supports only append.SessionSystemPromptModeCapabilities
System prompt delivery modes the agent supports in addition toappend.
append has no entry because every agent advertising
sessionCapabilities.systemPrompt supports it.
Type: Object
Properties:
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
Whether the agent supports
override mode.Optional. Omitted or null both mean the agent does not advertise support.
Supplying \{\} means the agent supports replacing its built-in default
instructions with the client-provided system prompt.SessionSystemPromptOverrideCapabilities
Capabilities for theoverride system prompt mode.
Supplying \{\} means the agent supports replacing its built-in default
instructions with the client-provided system prompt.
Type: Object
Properties:
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
SessionTitleCapabilities
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Capabilities for Client-set session titles. Supplying\{\} means the agent supports session/set_title. Agents report titles
through session/list and session_info_update without this capability.
Type: Object
Properties:
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
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: UnionThe agent’s execution plan for complex tasks.
See protocol docs: Agent Plan
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.A content update for a plan identified by ID.
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Removal notice for a plan identified by ID.
The current mode of the session has changedSee protocol docs: Session Modes
Information for the user that is not part of session history.Agents MUST only send this update when the Client advertised
the
session.notices Client capability.A context compaction has been created or updated.Agents MUST only send this update when the Client advertised
the
session.compaction Client capability.A content block appended to a context compaction’s retained summary.Agents MUST only send this update when the Client advertised
the
session.compaction Client capability.UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Replaces the session’s current list of prompt suggestions.Agents MUST only send this update when the Client advertised
the
session.promptSuggestions Client capability.UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.A session cursor has been announced or its capabilities have changed.Agents MUST only send this update when the Client advertised
the
session.cursors Client capability.UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.Announces a child session created and owned by this session, or updates
that ownership association’s metadata.
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.A message upsert observed in this session’s transcript, sent to or
received from another session.
UNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.One content block appended to a sent or received session message.
StateUpdate
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Current foreground-work state of a reusable child session. Each update is a whole-object snapshot. Idle does not terminate the child. The parent can message it again, transitioning it back to running. Background activity may still emit other session updates while idle. Type: UnionThe child is ready to process another prompt.Alternatives (
anyOf):Custom or future stop reason.Values beginning with
_ are reserved for implementation-specific
extensions. Other unknown values are reserved for future ACP variants.The Agent cannot currently determine foreground activity.This replaces previously confirmed activity without ending the work or session.
Custom or future state.Values beginning with
_ are reserved for implementation-specific
extensions. Other unknown values are reserved for future ACP variants.StopReason
Reasons why an agent stops processing a prompt turn. See protocol docs: Stop Reasons Type: UnionThe 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: UnionStringMultiSelectItems
String item schema for multi-select enum properties. Type: Object Properties: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.Optional. Omitted and
null are equivalent and mean no metadata.See protocol docs: ExtensibilityStringPropertySchema
Schema for string properties in an elicitation form. Whenenum or oneOf is set, this represents a single-select enum
with "type": "string".
Type: Object
Properties:
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.Optional. Omitted and
null are equivalent and mean no metadata.See protocol docs: ExtensibilityDefault value.Optional. Omitted and
null are equivalent and mean no default value is provided.Human-readable description.Optional. Omitted and
null are equivalent and mean no description is provided.Enum values for untitled single-select enums.
Optional. Omitted and
null are equivalent and mean no untitled single-select choices are
declared by enum.StringFormat | null
String format.Optional. Omitted and
null are equivalent and mean there is no format constraint.Maximum string length.Optional. Omitted and
null are equivalent and mean there is no maximum length constraint.- Minimum:
0
Minimum string length.Optional. Omitted and
null are equivalent and mean there is no minimum length constraint.- Minimum:
0
EnumOption[] | null
Titled enum options for titled single-select enums.
Optional. Omitted and
null are equivalent and mean no titled single-select choices are
declared by oneOf.Pattern the string must match.Optional. Omitted and
null are equivalent and mean there is no pattern constraint.Optional title for the property.Optional. Omitted and
null are equivalent and mean no title is provided.SubagentCapabilities
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Capability marker for exposing reusable child sessions as restricted ACP sessions. Supplying\{\} advertises support for child association and state updates,
session-directed messages, and restricted-session semantics. The client
must advertise this capability before the agent sends subagent updates or
session-directed messages.
Type: Object
Properties:
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.
SubagentSessionCapabilities
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Client-initiated session mutations permitted for a specific subagent session. A mutation requires an explicit per-child capability. Support for the method on ordinary sessions does not grant support on a child. Type: Object Properties: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.
SessionCancelCapabilities | null
Permits the client to cancel this child’s current work without ending
the session. Omitted or
null means unsupported. An object (including
\{\}) means supported.SubagentUpdate
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. Notification that the enclosing parent session created and owns a child session. Later updates modify the existing association’s metadata, not its ownership. Sent on the immediate parent session. The first update for an unknownsessionId announces the child and MUST be sent
before any live child traffic or live message naming the child as sender
or recipient. Parents may message and reuse an announced child across
multiple operations.
Child events are delivered automatically on the same connection. No child
load, resume, or subscription is needed.
Only the subagent session ID is required. Omitted patch fields keep their
previous values. null clears them. Clearing capabilities disables child
mutations. Clearing state leaves current activity unset/unconfirmed: it does
not imply idle, stop work, or create an unknown state snapshot. A concrete
state replaces the entire previous state object, not the session.
The title and description provide the parent’s display metadata for the
child. They do not replace the content of individual messages or operations.
cwd and additionalDirectories report where the Agent placed the child.
While unset, each inherits the immediate parent’s effective value.
Type: Object
Properties:
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
Omitted means unchanged.
null removes the metadata.Additional workspace roots for the child. Each path must be absolute.Optional and nullable. Omitted means unchanged.
null clears the
reported value. While unset, the child inherits its immediate parent’s
effective additional directories, independently of cwd. A concrete
array replaces the whole list. [] reports no additional directories.
Clients use these values for the child’s root set.SubagentSessionCapabilities | null
Client-initiated session mutations permitted for this subagent session.Omitted means unchanged.
null clears the capability set and disables
child mutations. If never supplied, no session mutations are permitted.
Read-only operations retain their normal protocol semantics and capability
requirements. A concrete object replaces the whole capability set.The child’s working directory. Must be an absolute path.Optional and nullable. Omitted means unchanged.
null clears the
reported value. While unset, the child inherits its immediate parent’s
effective working directory. Clients use this value for the child’s
root set and as the default terminal working directory.The parent’s human-readable description of the child’s role or purpose.Omitted means unchanged.
null clears it. If unset, the Client chooses
a fallback presentation. This is current display metadata, not the
history of instructions sent to the child.StateUpdate | null
Current state snapshot for the child session.Omitted means unchanged.
null clears the current activity without
asserting idle or sending an unknown snapshot. A concrete state
replaces the previous state object wholesale. If never supplied, the
current activity is unset/unconfirmed.The parent’s human-readable display title for this child. It need not be unique.Omitted means unchanged.
null clears it. If unset, the Client chooses
a fallback presentation.SystemPrompt
Client-provided system-level instructions for a session. Clients MUST only send this when the Agent advertisessessionCapabilities.systemPrompt. Agents that cannot apply it, for example
because of an unadvertised mode or an unsupported content block type, MUST
return an error instead of creating, loading, or resuming the session.
Type: Object
Properties:
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 system prompt content.Agents advertising the capability MUST accept
text content blocks.
Clients MUST NOT send other content block types until a future
capability allows them, and Agents MUST return an error for content
blocks they do not support.Clients MUST NOT send an empty array. Agents MAY reject one with
-32602 without creating, loading, or resuming the session.How the Agent combines
content with its own instructions.Required. Agents MUST return an error for a mode they do not support rather than
treating it as append or override.SystemPromptMode
How the Agent combines a client-provided system prompt with its own instructions. Unknown modes are preserved so they can be stored, proxied, or forwarded. An Agent MUST return an error for a mode it does not support rather than treating it asappend or override.
Type: Union
Add the content to the Agent’s own instructions rather than replacing them.Every Agent that advertises
sessionCapabilities.systemPrompt supports this mode.
Agents SHOULD give the content system-level precedence, for example in the
model’s system prompt or developer instructions rather than in user-turn
content. Where it is placed and how it is formatted is implementation-defined.Replace the Agent’s built-in default instructions with the content.This does not change tool availability, MCP servers, permissions, or session
configuration. Context the Agent supplies from the workspace or environment
MAY still be included. Clients that use this mode take responsibility for any
tool guidance or safety instructions the Agent’s default instructions
provided, and MUST only use it when the Agent advertises
sessionCapabilities.systemPrompt.mode.override.Custom or future system prompt mode.Values beginning with
_ are reserved for implementation-specific
extensions. Unknown values that do not begin with _ are reserved for
future ACP variants.Terminal
Embed a terminal created withterminal/create by its id.
The terminal must be added before calling terminal/release.
See protocol docs: Terminal
Type: Object
Properties:
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
TerminalExitStatus
Exit status of a terminal command. Type: Object Properties: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
TerminalId
Typed identifier used for terminal values on the wire. Type:string
TextContent
Text provided to or from an LLM. Type: Object Properties: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
Annotations | null
Optional annotations that help clients decide how to display or route this content.
TextResourceContents
Text-based resource contents. Type: Object Properties: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
TitledMultiSelectItems
Items definition for titled multi-select enum properties. Type: Object Properties: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.Optional. Omitted and
null are equivalent and mean no metadata.See protocol docs: ExtensibilityToolCall
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: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
Content produced by the tool call.
The category of tool being invoked.
Helps clients choose appropriate icons and UI treatment.
File locations affected by this tool call.
Enables “follow-along” features in clients.
Programmatic name of the tool being invoked.This field is optional. Omitting it or sending
null both mean that no
tool name is available.Current execution status of the tool call.
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: UnionEmbed a terminal created with
terminal/create by its id.The terminal must be added before calling terminal/release.See protocol docs: TerminalUNSTABLEThis capability is not part of the spec yet, and may be removed or changed at any point.A display-only reference to another session, such as a subagent.
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: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
ToolCallStatus
Execution status of a tool call. Tool calls progress through different statuses during their lifecycle. See protocol docs: Status Type: UnionThe tool call hasn’t started running yet because the input is either streaming
or we’re awaiting approval.
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: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
ToolCallContent[] | null
Replace the content collection.
ToolKind | null
Update the tool kind.
ToolCallLocation[] | null
Replace the locations collection.
Update the programmatic name of the tool being invoked.This field is optional. Omitting it or sending
null both mean that
the existing name is left unchanged.ToolCallStatus | null
Update the execution status.
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: UnionUnknownStateUpdate
UNSTABLE This capability is not part of the spec yet, and may be removed or changed at any point. The Agent cannot currently determine foreground activity. Report this when activity becomes unobservable, not merely because the child has been quiet. The Client MUST stop presenting the previous state as confirmed current activity, but may retain it as last known. A later state replaces this snapshot normally. This is not a task outcome or session closure. It does not cancel work, resolve pending requests, or revoke capabilities. If a control is no longer available, the Agent updates the capabilities explicitly. Unfinished tool calls and terminals stay as last reported. The Agent does not invent a final status for them, and Clients do not present them as confirmed live activity. Type: Object Properties:The _meta property is reserved by ACP for additional metadata. Implementations
MUST NOT make assumptions about values at these keys. Optional. Omitted and
null mean no metadata for this state snapshot.UnstructuredCommandInput
All text that was typed after the command name is provided as input. Type: Object Properties: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
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: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
UsageUpdate
Context window and cost update for a session. Type: Object Properties: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
Cost | null
Cumulative session cost (optional).