Before a Session can be created, Clients MUST initialize the connection by calling the
initialize method with:
- The latest protocol version supported
- The capabilities supported
Protocol version
The protocol versions that appear in theinitialize requests and responses are a single integer that identifies a MAJOR protocol version. This version is only incremented when breaking changes are introduced.
Clients and Agents MUST agree on a protocol version and act according to its specification.
See Capabilities to learn how non-breaking features are introduced.
Version negotiation
Theinitialize request MUST include the latest protocol version the Client supports.
If the Agent supports the requested version, it MUST respond with the same version. Otherwise, the Agent MUST respond with the latest version it supports.
If the Client does not support the version specified by the Agent in the initialize response, the Client SHOULD close the connection and inform the user about it.
Capabilities
Capabilities describe features supported by the Client and the Agent. All capabilities included in theinitialize request are OPTIONAL. Clients and Agents SHOULD support all possible combinations of their peer’s capabilities.
The introduction of new capabilities is not considered a breaking change. Therefore, Clients and Agents MUST treat all capabilities omitted in the initialize request as UNSUPPORTED.
Capabilities are high-level and are not attached to a specific base protocol concept.
Capabilities may specify the availability of protocol methods, notifications, or a subset of their parameters. They may also signal behaviors of the Agent or Client implementation.
Implementations can also advertise custom capabilities using the _meta field to indicate support for protocol extensions.
Client capabilities
The Client SHOULD specify whether it supports the following capabilities:Terminal authentication
The Client can reproduce the configured Agent invocation in an interactive
terminal. When
true, the Agent may advertise type: "terminal"
authentication methods.Learn more about Terminal Authentication
File system
Learn more about File System methods
Terminal
All
terminal/* methods are available, allowing the Agent to execute and
manage shell commands.Learn more about Terminals
Elicitation
The Client advertises its supported
elicitation/create modes. Omitted or
null means no modes are advertised. A present object advertises each mode
only through its corresponding non-null form or url field. Empty and
all-null objects are valid but advertise no supported modes. Unlike MCP, ACP
does not treat {} as form support.Learn more about Elicitation
Plan operations
The Client can receive
plan_update and plan_removed session updates.
Omitted or null means the Client does not advertise support, and the Agent
sends plans with the plan update instead. Supplying {} means the Client
can receive both update types.Learn more about Plan operations
Boolean config options
The Client supports
boolean session configuration options. Omitted or null
at any level means the Client does not advertise support. Supplying {} means
Agents may include type: "boolean" options in v1 configOptions payloads.Learn more about Session Config Options
Session compaction
The Client supports ID-addressed
compaction_update and
compaction_summary_chunk session updates, including their lifecycle,
placement, patch, and replay semantics. Omitted or null at either level
means unsupported. Supplying {} advertises the complete contract. Agents
must not send these updates to a v1 Client that does not advertise it.Learn more about Session Compaction
Session notices
The Client can present live
notice session updates to the user. This field
is optional and nullable. Omitting session or notices, or setting either
to null, means unsupported. Supplying {} advertises notice support. Agents
must not send notices without this capability and may instead use an agent
message when the information should still be surfaced to the user.Learn more about Session Notices
Prompt suggestions (unstable)
The Client can offer the suggestions in
prompt_suggestions_update session
updates to the user. This field is optional and nullable. Omitting session
or promptSuggestions, or setting either to null, means unsupported.
Supplying {} means the Client can offer suggestions made of text and
resource_link content blocks. Agents must not send
prompt_suggestions_update without this capability.null means unsupported. Supplying {} means supported.
Learn more about Prompt Suggestions
Session cursors (unstable)
The Client handles
cursor_update session updates. This field is optional and
nullable. Omitting session or cursors, or setting either to null, means
unsupported. Supplying {} means supported. Agents must not send
cursor_update without this capability.Learn more about Session Cursors
Subagents (unstable)
The Client handles
subagent_update, session_message, and
session_message_chunk session updates, and applies the restrictions on what
it sends for a child session. This field is optional and nullable. Omitted or
null means unsupported. Supplying {} means supported. Agents must not send
these updates without this capability.Learn more about Subagents
Agent capabilities
The Agent SHOULD specify whether it supports the following capabilities:The
session/load method
is available.Object indicating the different types of content
that may be included in
session/prompt requests.Prompt capabilities
As a baseline, all Agents MUST supporttext and resource_link content blocks in session/prompt requests.
Optionally, they MAY support richer types of content by specifying the following capabilities:
MCP capabilities
The Agent supports connecting to MCP servers over SSE.Note: This transport has been deprecated by the MCP spec.
Authentication capabilities
The
logout method is
available.Unstable. The
auth/status method and the
auth/status_update notification are available. Omitted or null both mean
the Agent does not advertise support. Supplying an empty object means the
Agent supports them.Learn more about Authentication
Session capabilities
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.
The
session/delete method is available.
Omitted or null both mean the Agent does not advertise support. Supplying an
empty object means the Agent supports deleting sessions from session/list.Unstable. The
session/archive and session/unarchive methods, the
archived filter on session/list, and archived on listed sessions are
available. Omitted or null both mean the Agent does not advertise support.
Supplying an empty object means the Agent supports them. See Archived
Sessions.The Agent supports
additionalDirectories on supported session lifecycle
requests. Omitted or null both mean the Agent does not advertise support.
Supplying {} means the Agent supports additional workspace roots.The Agent supports
systemPrompt on session
lifecycle requests. Omitted or null both mean the Agent does not
advertise support. Supplying {} means the Agent supports append mode.
Supplying { "mode": { "override": {} } } also advertises override mode.Unstable. The
session/options method and
configOptions on session setup requests are available. Omitted or null
both mean the Agent does not advertise support. Supplying an empty object
means the Agent supports both.Unstable. The
session/status method is
available. Omitted or null both mean the Agent does not advertise support.
Supplying an empty object means the Agent supports checking session status.Unstable. The
session/set_title method is
available. Omitted or null both mean the Agent does not advertise support.
Supplying an empty object means Clients can set session titles. Agents report
titles through session/list and session_info_update without this
capability.session/load is still handled by the top-level load_session capability.
This will be unified in future versions of the protocol.Implementation information
Both Clients and Agents SHOULD provide information about their implementation in theclientInfo and agentInfo fields respectively. Both take the following three fields:
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. Optional. Omitted and
null are equivalent. 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.
Note: in future versions of the protocol, this information will be required.
Once the connection is initialized, you’re ready to create a session and begin the conversation with the Agent.