Skip to main content
A prompt turn represents a complete interaction cycle between the Client and Agent, starting with a user message and continuing until the Agent completes its response. This may involve multiple exchanges with the language model and tool invocations. Before sending prompts, Clients MUST first complete the initialization phase and session setup.

Session updates

Agents send session/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 advertises subagents: {}, 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:
Every chunk carries one normal 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 a session/prompt:
SessionId
required
The ID of the session to send this message to.
ContentBlock[]
required
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 via session/update notifications. This may include the Agent’s plan for accomplishing the task:
Learn more about Agent Plans
The Agent then reports text responses from the model:

Message IDs

The Agent MAY include an opaque, unique messageId 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 send notice 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 send prompt_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: A Client skips a suggestion it cannot use and keeps the rest, for example one with a block it cannot parse. The Client SHOULD skip the whole suggestion rather than offer the remaining blocks, because dropping a block changes what the prompt asks for. The Agent owns the list. A session starts with an empty list. The 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/prompt arrived, the Agent MUST discard that prediction.
  • When the Agent accepts a session/prompt for 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 with suggestions: [].
  • Agents SHOULD replace or withdraw the list when it stops applying for another reason.
Agents MAY send the update at any time, including outside a prompt turn. An Agent typically sends it after the 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.
Suggestions are not conversation history. Agents SHOULD NOT include them in session replay. A loaded session starts with an empty list, and the Agent may send a new update after session/load completes.

Session compaction

The Agent MUST NOT send compaction_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:
The following 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 send cursor_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:
  • cursorId is 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.
  • capabilities is an optional, nullable patch that says which methods currently accept the cursor. Omitted leaves the stored value unchanged, null clears it, and an object replaces the whole previous value. A new cursor starts with none.
  • anchor places the cursor. The first update for a cursorId MUST include it, and 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.
  • _meta is an optional, nullable patch. Omitted leaves the stored value unchanged, null clears it, and an object replaces it.
A cursor never moves. To offer a different position, the Agent announces a new cursor. Later updates change only 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.
The entity MUST belong to the same session, and the Agent MUST report it on that session before it sends a 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 type or position.
The Client MUST NOT guess a place for such a cursor. A replay delivers each entity before the cursors anchored to it. A method that accepts a cursor takes its 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 the cursorId for 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 the cursorId had 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 a usage_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 original session/prompt request with a StopReason:
Agents MAY stop the turn at any point by returning the corresponding StopReason.

5. Tool invocation and status reporting

Before proceeding with execution, the Agent MAY request permission from the Client via the session/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:
As the tool runs, the Agent MAY send additional updates, providing real-time feedback about tool execution progress. While tools execute on the Agent, they MAY use Client capabilities such as the file system (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 corresponding StopReason:
The language model finishes responding without requesting more tools
The maximum token limit is reached
The maximum number of model requests in a single turn is exceeded
The Agent refuses to continue
The Client cancels the turn

Cancellation

Clients MAY cancel an ongoing prompt turn at any time by sending a session/cancel notification:
The Client SHOULD preemptively mark all non-finished tool calls pertaining to the current turn as 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.
API client libraries and tools often throw an exception when their operation is aborted, which may propagate as an error response to session/prompt.Clients often display unrecognized errors from the Agent to the user, which would be undesirable for cancellations as they aren’t considered errors.Agents MUST catch these errors and return the semantically meaningful cancelled stop reason, so that Clients can reliably confirm the cancellation.
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.