Session updates
Agents sendsession/update notifications to report streamed content, tool activity, and changes to session state. The sessionUpdate field inside params.update identifies the variant:
This is the complete set of variants defined in the current draft
SessionUpdate schema, which describes each payload in detail. Draft-only variants are unstable and may change or be removed. The walkthrough below illustrates common uses of these updates.
Session updates are not limited to active prompt turns. For example, Agents may advertise commands after creating a session, and replay user and Agent messages when loading a session.
Session-directed messages (unstable)
When the Client advertisessubagents: {}, the Agent may report outgoing and
incoming messages between sessions, separately from user-facing responses and
tool calls. The outer params.sessionId identifies the transcript being
updated. Every message and chunk requires a messageId scoped to that
transcript. Optional senderSessionId and recipientSessionId on
session_message identify the participants. Chunks carry only content.
Include them on the first session_message when available, before the first
chunk of a streamed message. Later updates may omit them or add missing
identities.
For example, an incoming message in the child can name its participants, then
stream its content:
ContentBlock. Later chunks append content
for the same messageId. session_message can supply a whole
content array to replace accumulated content. Its optional content and
_meta fields leave prior values unchanged when omitted. null clears them.
content: [] also clears content. Chunk metadata is local to the chunk, not a
message-level patch.
Clients can render “To …” with a recipient link or “From …” with a sender link.
Without sufficient participant metadata, use a generic inter-session
presentation and add links when the metadata arrives. Participant IDs follow the same patch rule as content: omission leaves a known value unchanged and null clears it.
The two views have independent message IDs. Optional senderMessageId on the
incoming view and recipientMessageId on the outgoing view name the other
view’s messageId, so a Client can go from either view to the other. They
follow the participant-ID rules and can arrive in a later session_message. Clients must
not link views by equal IDs alone. The Agent reports each side only
when observed. Clients must not synthesize an incoming entry from an outgoing
one or forward the content themselves. Neither view acknowledges completed
recipient processing. See Subagents
for how sessions are announced, replayed history, and ownership.
A message from a parent to a subagent, including the first one that starts its
work, is a session-directed message. Agents SHOULD report it as an
incoming session_message in the child’s transcript, with senderSessionId
set to the parent, and SHOULD NOT report it as a user_message_chunk.
Clients can then render it as a message from the parent session rather than
from the user. See Messages from a parent to a child.
When the Agent has no evidence of who sent a message the child received, it
omits senderSessionId and MUST NOT assume the parent. It links two views
only when it can establish that they are the same message, and leaves them
unlinked otherwise.
The prompt turn lifecycle
1. User message
The turn begins when the Client sends asession/prompt:
The ID of the session to send this message to.
The contents of the user message, e.g. text, images, files, etc.Clients MUST restrict types of content according to the Prompt Capabilities established during initialization.
Learn more about Content
2. Agent processing
Upon receiving the prompt request, the Agent processes the user’s message and sends it to the language model, which MAY respond with text content, tool calls, or both.3. Agent reports output
The Agent reports the model’s output to the Client viasession/update notifications. This may include the Agent’s plan for accomplishing the task:
Learn more about Agent Plans
Message IDs
The Agent MAY include an opaque, uniquemessageId on message chunks. Chunks with the same messageId belong to the same message. A changed messageId indicates a new message.
If the model requested tool calls, these are also reported immediately:
Session notices
The Agent MUST NOT sendnotice updates unless the Client advertised support
by supplying clientCapabilities.session.notices: {} in its initialize
request. Omitting session or notices, or setting either field to null,
means the Client does not advertise support.
When the capability is absent, the Agent may use an ordinary agent message
instead if the information should still be surfaced to the user. That fallback
is conversation content and follows normal message-history semantics.
When the Client advertises support, the Agent MAY send a live user-facing
notice at any point while a session exists, including outside prompt processing:
severity is required and non-null and initially supports info, warning,
and error.
It is an open string enum: values beginning with _ are reserved for
implementation-specific extensions, while other unknown values are reserved
for future ACP severities. Clients preserve unknown values and use a generic
notice presentation without inferring additional behavior from them.
title is required, non-null, non-empty plain text suitable for a compact
presentation. description is optional, nullable plain text with supporting
detail. Omission and null both mean no description. _meta is an optional,
nullable object scoped to this event. Omission and null both mean no event
metadata. Unlike compaction patch fields, these fields do not update or clear
an earlier notice.
Advertising support does not acknowledge delivery or guarantee display of an
individual notice. Agents must still behave as though a notice may not have
been received, displayed, or seen. A notice must not carry information required
for protocol correctness, authorization, user action, task completion, or
fatal-error reporting.
Clients own presentation and dismissal. They may use a toast, banner, inline
status region, notification center, or another accessible surface, and may
coalesce repeated notices. Severity is only a presentation hint. Even error
does not fail a request, stop foreground work, change session state, or imply a
prompt stop reason. Dismissal is local and produces no acknowledgement or
removal event.
Notices have no ID or Agent-managed lifecycle. Each occurrence is an
independent live event, not conversation history, and SHOULD NOT be included
in session replay. If a condition remains relevant after reconnecting, the
Agent may emit a new notice.
Prompt suggestions (unstable)
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 Agent MUST NOT sendprompt_suggestions_update unless the Client advertised support by supplying clientCapabilities.session.promptSuggestions in its initialize request. Omitting session or promptSuggestions, or setting either field to null, means the Client does not advertise support.
Each update replaces the session’s current list of suggestions:
suggestions is a required, non-null list, ordered most likely first. An empty list withdraws the suggestions the Client is offering. Suggestions have no IDs, and an update cannot append to the list or remove a single entry.
Each suggestion has a required, non-null prompt. It is a list of at least one content block, the same type as the prompt field of session/prompt. A Client can send an accepted suggestion in that field unchanged. _meta is an optional, nullable object on the update and on each suggestion. Omission and null both mean no metadata.
Each suggestion’s prompt MUST be valid as the prompt of a session/prompt request for the session. Agents MUST NOT send a suggestion whose only content is empty or whitespace-only text. Agents MUST only use content types that both sides support:
textandresource_linkare always allowed.image,audio, andresourceblocks are allowed only when the Agent advertised the type in its prompt capabilities and the Client advertised it undersession.promptSuggestions.
suggestions in the most recent update are the current list until the Agent sends another update. The Agent keeps the list up to date:
- Agents MUST predict a list from the conversation as it stands when they send it. If the conversation changes before the Agent has sent a prediction, for example because a
session/promptarrived, the Agent MUST discard that prediction. - When the Agent accepts a
session/promptfor the session, a list it sent earlier is out of date. If the current list is not empty, the Agent MUST replace it or withdraw it withsuggestions: []. - Agents SHOULD replace or withdraw the list when it stops applying for another reason.
session/prompt response. An Agent is never required to send one, so Clients do not wait for an update before they accept the user’s next prompt.
Clients decide how and when to show the current list. A Client MAY stop offering it at any time, for example when the user dismisses it, starts typing, or sends a prompt. The Client does not tell the Agent when it stops offering a list, and the Agent does not learn whether a suggestion was shown, accepted, or edited.
A Client MUST NOT send a suggestion as a prompt without an explicit user action. Receiving or displaying a suggestion is not a user action. Each of the following is:
- The user accepts a suggestion into the composer and then sends it.
- The user selects a suggestion in a UI that sends on selection, such as a row of chips. That UI SHOULD show the full text and identify every other block, such as a linked file, before the user selects the suggestion.
- The user turns on a Client setting that sends suggestions automatically.
session/load completes.
Session compaction
The Agent MUST NOT sendcompaction_update or
compaction_summary_chunk unless the Client advertised support by supplying
clientCapabilities.session.compaction: {} in its initialize request.
Omitting session or compaction, or setting either field to null, means the
Client does not support these updates. This requirement applies to both live
updates and history replay.
When the capability is absent, the Agent may describe compaction through an
ordinary agent message instead. That fallback is conversation content, not an
ID-addressed compaction entity, and follows normal message-history semantics.
When the Client advertises support, the Agent MAY report context compaction
as one persistent, ID-addressed timeline entity. A single compaction_update
with status: "completed" is sufficient. Reporting progress is optional.
Summary content is also optional. It may be sent all at once in the summary
field or streamed using compaction_summary_chunk for the same compactionId.
For example, an Agent can report that compaction has started:
compactionId and status are required and non-null on every
compaction_update. The ID is an opaque, Agent-owned string, unique within the
session, and MUST NOT be reused for another compaction.
Clients initialize a first-seen compaction ID with status in_progress and unset
optional fields, then apply the notification.
The first notification fixes the entity’s timeline position in receive
order: it follows previously received timeline content and precedes content
first received later. Later updates and chunks for an ID-addressed entity patch
it in place. They do not move or split it around the compaction.
The Agent MUST report a terminal status when a reported compaction ends.
status is an open string enum. Values beginning with _ are reserved for
implementation-specific extensions. Other unknown values are reserved for
future ACP statuses. Clients preserve unknown strings and present a generic
state without inferring lifecycle or control behavior.
If the retained summary is available incrementally, the Agent may append one
content block at a time:
compactionId and content are required and non-null on each chunk.
Chunk _meta is optional and nullable, is scoped to that chunk, and has no
patch semantics: omission and null both mean no chunk metadata.
An update may omit summary to retain the streamed content. A
non-streaming Agent can instead supply the complete summary, and a streaming
Agent can use the same field as an authoritative replacement of content received
so far:
compaction_update fields are optional, nullable patches:
For each patch field, omission leaves the stored value unchanged,
null clears
it, and a concrete value replaces it. On a first-seen ID, omission and null
both start with no value. summary: [] also clears the summary.
Clients apply updates and chunks in receive order for each ID. Chunks append
to the current summary. A concrete summary replaces all previously
accumulated content, and any subsequent chunks append to that replacement.
summary: null or summary: [] clears accumulated content, including partial
output before failure or cancellation.
The summary is not the Agent’s complete replacement history or generic status
text such as “Compaction completed”. It should faithfully represent the
retained, user-displayable summary without internal prompt framing or hidden
instructions. Text blocks may contain Markdown. Agents should omit it when no
unencrypted summary is available or when disclosure would reveal context that
was not otherwise user-visible.
During history replay,
compaction updates and summary chunks follow the same semantics as live delivery.
Replay does not implicitly reset omitted patch fields. Agents use replacement
or clearing summary patches as needed to avoid duplicating content the Client
already holds.
Compaction does not instruct the Client to discard earlier conversation
history. Collapsing it is a local presentation choice. It also does not replace
usage_update, which reports current context-window
usage and cost rather than a compaction boundary.
Session cursors (unstable)
A session cursor names one position in the session’s timeline where the Client can run a method, such as forking the session there. The Agent announces a cursor only for a position where at least one method works. A Client can’t act at a position that has no cursor. The Agent MUST NOT sendcursor_update unless the Client advertised support by
supplying clientCapabilities.session.cursors: {} in its initialize request.
Omitting session or cursors, or setting either field to null, means the
Client does not support these updates. This requirement applies to both live
updates and session/load replay. There is no Agent capability. An Agent that
supports cursors announces them.
The Agent announces a cursor with a cursor_update:
cursor_update is an upsert keyed by cursorId:
cursorIdis required and non-null. It is an opaque, Agent-owned string, unique within the session and never reused for another position. Clients MUST NOT parse, change, or construct it.capabilitiesis an optional, nullable patch that says which methods currently accept the cursor. Omitted leaves the stored value unchanged,nullclears it, and an object replaces the whole previous value. A new cursor starts with none.anchorplaces the cursor. The first update for acursorIdMUST include it, and the Agent MUST NOT change it afterwards. A later update can omit it or repeat the same anchor. Omitted andnullare equivalent and leave the stored anchor unchanged._metais an optional, nullable patch. Omitted leaves the stored value unchanged,nullclears it, and an object replaces it.
capabilities, for example to add a method that
became possible at the position or to remove one that no longer is.
Each capability in capabilities is an optional, nullable object. Omitted or null
means unsupported, and {} advertises support. capabilities: null and
capabilities: {} both mean that no method accepts the cursor. Clients ignore
capabilities they don’t recognize. A malformed capabilities value is treated as
omitted.
anchor names an entity the Client holds by its type and ID:
The anchor’s
position field says on which side of the entity the cursor is:
before: the cursor is immediately before the entity. The history before the cursor does not include the entity.after: the cursor is immediately after the entity. The history before the cursor includes the entity and nothing that follows it in the timeline.
cursor_update anchored to it. A malformed anchor
makes the whole update invalid. Unknown type and position values are preserved, so a later version or an extension can add more.
v1 message IDs are optional, but an anchor to a message needs one. An Agent that
announces cursors MUST send a messageId on every message it anchors to.
v1 does not require the Agent to report the user’s prompt as a session update, and
the session/prompt response carries no messageId. The Client then holds no user
message for that prompt, and the Agent can’t anchor before it. The Agent anchors
the same position after the last message, tool call, or compaction before the
prompt. The first prompt of a session has nothing before it, so that position has
no cursor. After session/load, replayed user messages that carry a messageId
can be anchored before or after.
A Client can’t place a cursor in three cases:
- It holds no anchor for the cursor, for example because it missed the first update.
- It does not hold the anchored entity, for example because it resumed without a replay.
- It doesn’t recognize the anchor’s
typeorposition.
cursorId:
- Clients MUST only pass a cursor that the Agent announced on that session and that currently advertises the capability for the method.
- Clients MUST pass the
cursorId. They MUST NOT pass the anchor’s entity ID in its place. - The Agent MUST reject the request with
-32602(Invalid params) when it did not issue thecursorIdfor that session, when it no longer accepts the cursor, or when the cursor does not support that method. It MUST NOT act at a different position, and it MUST NOT handle the request as if thecursorIdhad been omitted.
session/fork is the first method that accepts a cursor. With a cursorId, the new
session’s history is the source session’s history before the cursor:
cursorId is optional. Omitted and null are equivalent and fork the whole
session. The source session does not change, and its cursors stay valid. The new
session does not inherit them. The Client learns the new session’s cursors from
cursor_update notifications on the new session.
A cursor belongs to its session, not to a connection or a Client. It stays valid
until the Agent invalidates it. The end of a connection, session/close, session/load, and session/resume do not
invalidate a cursor. Agents SHOULD accept a cursor for as long as they retain
the history at its position, and Clients MAY store cursors with their copy of
the session. The Agent can stop accepting a cursor at any time. It SHOULD then
send a cursor_update that clears the cursor’s capabilities, if the session is
active on a connection.
Session usage updates
The Agent MAY also report current session context and cumulative cost state with ausage_update:
used and size are required and non-null token counts for the current session context. cost is optional and, if present, amount and currency are required. currency is the unit of amount: an ISO 4217 currency code such as "USD" for money, or another unit such as "credits".
When a session has child sessions, its cost includes the costs of its descendants.
4. Check for completion
If there are no pending tool calls, the turn ends and the Agent MUST respond to the originalsession/prompt request with a StopReason:
StopReason.
5. Tool invocation and status reporting
Before proceeding with execution, the Agent MAY request permission from the Client via thesession/request_permission method.
Once permission is granted (if required), the Agent SHOULD invoke the tool and report a status update marking the tool as in_progress:
fs) methods to access resources within the Client’s environment.
When the tool completes, the Agent sends another update with the final status and any content:
Learn more about Tool Calls
6. Continue conversation
The Agent sends the tool results back to the language model as another request. The cycle returns to step 2, continuing until the language model completes its response without requesting additional tool calls or the turn gets stopped by the Agent or cancelled by the Client.Stop reasons
When an Agent stops a turn, it must specify the correspondingStopReason:
Cancellation
Clients MAY cancel an ongoing prompt turn at any time by sending asession/cancel notification:
cancelled as soon as it sends the session/cancel notification.
The Client MUST respond to all pending session/request_permission requests with the cancelled outcome.
When the Agent receives this notification, it SHOULD stop all language model requests and all tool call invocations as soon as possible.
After all ongoing operations have been successfully aborted and pending updates have been sent, the Agent MUST respond to the original session/prompt request with the cancelled stop reason.
The Agent MAY send session/update notifications with content or tool call updates after receiving the session/cancel notification, but it MUST ensure that it does so before responding to the session/prompt request.
The Client SHOULD still accept tool call updates received after sending session/cancel.
Once a prompt turn completes, the Client may send another
session/prompt to continue the conversation, building on the context established in previous turns.