> ## Documentation Index
> Fetch the complete documentation index at: https://zed-685ed6d6-auto-sync-registry.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Prompt Lifecycle
> How prompts, state updates, and completion fit together
A prompt starts or contributes to foreground work in a session. The [Agent](/protocol/v2/overview#agent) may continue that work until it reports `idle`, including across multiple model exchanges and tool invocations.
`session/prompt` lasts until the Agent inserts the user message into the ACP conversation. This is what acceptance means for a prompt. The response returns that message's `messageId`; the Agent reports its content and placement, foreground state, output, and completion through `session/update` notifications.
Before sending prompts, Clients **MUST** first complete the [initialization](/protocol/v2/initialization) phase and [session setup](/protocol/v2/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:
| `sessionUpdate` value | Description |
| - | - |
| `user_message_chunk` | A streamed chunk of a user message. |
| `user_message` | Creates or updates a user message identified by `messageId`. |
| `agent_message_chunk` | A streamed chunk of the Agent's response. |
| `agent_message` | Creates or updates an Agent message identified by `messageId`. |
| `agent_thought_chunk` | A streamed chunk of the Agent's reasoning. |
| `agent_thought` | Creates or updates an Agent reasoning message identified by `messageId`. |
| `state_update` | A change to the Agent's [foreground work state](#session-states). |
| `tool_call_content_chunk` | Appends a [content chunk to a tool call](/protocol/v2/tool-calls#streaming-content). |
| `tool_call_update` | Creates or updates a [tool call](/protocol/v2/tool-calls#reporting). |
| `terminal_update` | Creates or updates an [Agent-owned terminal](/protocol/v2/tool-calls#display-only-terminals). |
| `terminal_output_chunk` | Appends output bytes to an [Agent-owned terminal](/protocol/v2/tool-calls#display-only-terminals). |
| `plan_update` | Creates or updates the [content of a plan](/protocol/v2/agent-plan) identified by ID. |
| `available_commands_update` | The set of [available slash commands](/protocol/v2/slash-commands) is ready or has changed. |
| `config_option_update` | The session's [configuration options](/protocol/v2/session-config-options#from-the-agent) have changed. |
| `session_info_update` | [Session metadata](/protocol/v2/session-list#updating-session-metadata), such as the title or last update time, has changed. |
| `usage_update` | The session's [context window usage and cumulative cost](#session-usage-updates). |
This is the complete set of standard variants defined in the current [`SessionUpdate` schema](/protocol/v2/schema#sessionupdate), which describes each payload in detail. The walkthrough below illustrates common uses of these updates.
The protocol also supports [custom and future variants](/protocol/v2/extensibility#enum-and-tagged-union-variants). Clients that do not understand an update should preserve its raw payload when storing, replaying, proxying, or forwarding session history, and otherwise ignore it or display it generically.
Session updates are not limited to prompt-driven foreground work. For example, Agents may advertise commands after creating a session, and background activity may emit updates while the Agent is [idle](#session-states).
## Prompt Lifecycle
A typical prompt-driven flow enables rich interactions between the user, Agent, and any connected tools.
```mermaid theme={null}
sequenceDiagram
participant Client
participant Agent
Note over Agent,Client: Session ready
Note left of Client: User sends message
Client->>Agent: session/prompt (user message)
Note right of Agent: Insert user message
Agent-->>Client: "session/prompt response (messageId)"
Agent->>Client: session/update (user_message)
Agent->>Client: session/update (state_update: running)
loop While foreground work is in progress
Note right of Agent: LLM responds with
content/tool calls
Agent->>Client: session/update (plan_update)
Agent->>Client: session/update (agent_message)
opt Tool calls requested
Agent->>Client: session/update (tool_call_update)
opt Permission required
Agent->>Client: session/request_permission
Agent->>Client: session/update (state_update: requires_action)
Note left of Client: User grants/denies
Client-->>Agent: Permission response
Agent->>Client: session/update (state_update: running)
end
Agent->>Client: session/update (tool_call_update status: in_progress)
Note right of Agent: Execute tool
Agent->>Client: session/update (tool_call_content_chunk)
Agent->>Client: session/update (tool_call_update status: completed)
Note right of Agent: Send tool results
back to LLM
end
opt User cancelled during execution
Note left of Client: User cancels work
Client->>Agent: session/cancel
Note right of Agent: Abort operations
Agent->>Client: session/update (state_update: idle, stopReason: cancelled)
end
end
Agent->>Client: session/update (state_update: idle, stopReason)
```
### 1. User Message
The Client sends a user message with `session/prompt`:
```json theme={null}
{
"jsonrpc": "2.0",
"id": 2,
"method": "session/prompt",
"params": {
"sessionId": "sess_abc123def456",
"prompt": [
{
"type": "text",
"text": "Can you analyze this code for potential issues?"
},
{
"type": "resource",
"resource": {
"uri": "file:///home/user/project/main.py",
"mimeType": "text/x-python",
"text": "def process_data(items):\n for item in items:\n print(item)"
}
}
]
}
}
```
The [ID](/protocol/v2/session-setup#session-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](/protocol/v2/initialization#prompt-capabilities) established during [initialization](/protocol/v2/initialization).
Learn more about Content
### 2. Prompt Accepted
**Acceptance means insertion**, not receipt, queueing, or processing completion. The Agent **MUST** respond successfully once it has inserted the user message into the ACP conversation, without waiting for foreground work to finish. It **MUST NOT** send a successful response merely because it has received the input or assigned an ID. Requests rejected before insertion use a JSON-RPC error response.
The response contains the inserted user message's agent-generated `messageId`:
```json theme={null}
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"messageId": "msg_user_8f7a1"
}
}
```
The opaque ID of the inserted user message. This field is a required, non-null
string; omission and explicit `null` are invalid.
The Agent **MUST** also report the inserted user message through a `user_message` update with the full `content` array or streamed `user_message_chunk` updates. All updates for that message **MUST** use the returned `messageId`. The response and updates describe the same insertion, but Clients **MUST** tolerate the updates arriving before or after the response.
```json theme={null}
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123def456",
"update": {
"sessionUpdate": "user_message",
"messageId": "msg_user_8f7a1",
"content": [
{
"type": "text",
"text": "Can you analyze this code for potential issues?"
}
]
}
}
}
```
The Client uses the JSON-RPC response ID to identify its submission, then associates it with `(sessionId, messageId)`. If the message update arrived first, the Client reconciles with that existing message rather than creating a duplicate. Agents **MUST** assign distinct message IDs to distinct inserted submissions, even if their content is identical; Clients must not infer the association from content or arrival order.
Insertion is not a promise of durable storage or model consumption. Every inserted input, including a locally handled command, is reported live, but Agents are not required to persist it or retain it for any minimum period. If the message is retained and replayed, the Agent **MUST** use the same ID. See [Resuming Sessions](/protocol/v2/session-setup#resuming-sessions).
A successful prompt response is not an `idle` signal. Session work and notifications continue independently of the completed prompt request. If the response is lost, the submission's outcome remains uncertain: replay may omit live-only or discarded messages, and a retry can create another submission.
### 3. Agent Reports Output
When foreground work starts or resumes, the Agent **MUST** send a `state_update` notification with `state: "running"`:
```json theme={null}
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123def456",
"update": {
"sessionUpdate": "state_update",
"state": "running"
}
}
}
```
The language model **MAY** respond with text content, tool calls, or both.
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:
```json expandable theme={null}
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123def456",
"update": {
"sessionUpdate": "plan_update",
"plan": {
"type": "items",
"planId": "plan-1",
"entries": [
{
"content": "Check for syntax errors",
"priority": "high",
"status": "pending"
},
{
"content": "Identify potential type issues",
"priority": "medium",
"status": "pending"
},
{
"content": "Review error handling patterns",
"priority": "medium",
"status": "pending"
},
{
"content": "Suggest improvements",
"priority": "low",
"status": "pending"
}
]
}
}
}
}
```
Learn more about Agent Plans
The Agent can report the model's text response as an `agent_message` update with the full `content` array:
```json theme={null}
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123def456",
"update": {
"sessionUpdate": "agent_message",
"messageId": "msg_agent_c42b9",
"content": [
{
"type": "text",
"text": "I'll analyze your code for potential issues. Let me examine it..."
}
]
}
}
}
```
#### Message IDs
The Agent **MUST** include an opaque `messageId` on message updates and message chunks.
User, agent, and thought messages can each be reported either as a message update with a full `content` array or as streamed chunks. `user_message`, `agent_message`, and `agent_thought` updates are upserts keyed by `messageId`: omitted `content` leaves the existing message content unchanged, `content: null` clears it, and concrete `content` arrays replace the previous content. Chunk updates with the same `messageId` append content; a changed `messageId` indicates a new message.
Clients apply message updates and chunks in the order they are received for each `messageId`:
* A message update without `content` leaves the current content unchanged, so Agents can update other optional fields without resending content.
* A message update with `content` replaces all content currently stored for that message, including content accumulated from earlier chunks.
* A message update with `content: []` or `content: null` clears the message content.
* A chunk appends its `content` to whatever content is current for that message, whether that content came from an earlier message update or earlier chunks.
* A chunk's `_meta`, when present, is chunk-scoped.
For example, if an Agent sends `agent_message` with `content: [A]`, then sends `agent_message_chunk` with `B`, the rendered message content is `[A, B]`. If it later sends another `agent_message` with `content: [C]`, the rendered content becomes `[C]`; the earlier full content and chunks are replaced. Subsequent chunks append to `[C]`.
For streaming agent text, the Agent can use `agent_message_chunk` updates:
```json theme={null}
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123def456",
"update": {
"sessionUpdate": "agent_message_chunk",
"messageId": "msg_agent_c42b9",
"content": {
"type": "text",
"text": " Let me examine it..."
}
}
}
}
```
The Agent can report internal reasoning with the same message-update or chunk patterns. `agent_thought` updates patch fields for the same thought `messageId`; `agent_thought_chunk` updates append new content.
```json theme={null}
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123def456",
"update": {
"sessionUpdate": "agent_thought",
"messageId": "msg_thought_a12",
"content": [
{
"type": "text",
"text": "Need to inspect the loop body before suggesting a fix."
}
]
}
}
}
```
If the model requested tool calls, these are also reported immediately:
```json theme={null}
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123def456",
"update": {
"sessionUpdate": "tool_call_update",
"toolCallId": "call_001",
"title": "Analyzing Python code",
"kind": "other",
"status": "pending"
}
}
}
```
#### Session Usage Updates
The Agent **MAY** also report current session context and cumulative cost state with a `usage_update`:
```json theme={null}
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123def456",
"update": {
"sessionUpdate": "usage_update",
"used": 53000,
"size": 200000,
"cost": {
"amount": 0.045,
"currency": "USD"
}
}
}
}
```
`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 an ISO 4217 currency code like `"USD"`.
### 4. Report Completion
When the Agent is ready to process a new prompt, it **MUST** report `idle` with a `state_update` notification. When the transition ends foreground work, the Agent **MUST** include the corresponding [`StopReason`](#stop-reasons):
```json theme={null}
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123def456",
"update": {
"sessionUpdate": "state_update",
"state": "idle",
"stopReason": "end_turn"
}
}
}
```
Agents **MAY** stop foreground work at any point by sending an idle `state_update` session update with the corresponding [`StopReason`](#stop-reasons).
### 5. Tool Invocation and Status Reporting
Before proceeding with execution, the Agent **MAY** request permission from the Client via the `session/request_permission` method.
While foreground work is blocked on a permission response or other user action, the Agent **SHOULD** report `requires_action`. When work resumes, the Agent **SHOULD** report `running`.
Once permission is granted (if required), the Agent **SHOULD** invoke the tool and report a status update marking the tool as `in_progress`:
```json theme={null}
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123def456",
"update": {
"sessionUpdate": "tool_call_update",
"toolCallId": "call_001",
"status": "in_progress"
}
}
}
```
As the tool runs, the Agent **MAY** send additional updates, providing
real-time feedback about tool execution progress. The Agent streams complete
incremental content items with `tool_call_content_chunk`:
```json theme={null}
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123def456",
"update": {
"sessionUpdate": "tool_call_content_chunk",
"toolCallId": "call_001",
"content": {
"type": "content",
"content": {
"type": "text",
"text": "Checked syntax..."
}
}
}
}
}
```
Clients append each `tool_call_content_chunk` to the current content for that `toolCallId`. A later `tool_call_update` with `content` replaces the accumulated content.
Display-only terminal bytes use `terminal_output_chunk`, not
`tool_call_content_chunk`. See [Display-only
Terminals](/protocol/v2/tool-calls#display-only-terminals) for their
per-terminal byte ordering and snapshot semantics.
While tools execute on the Agent, they **MAY** leverage Client capabilities negotiated during initialization.
When the tool completes, the Agent sends another update with the final status and any content:
```json theme={null}
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123def456",
"update": {
"sessionUpdate": "tool_call_update",
"toolCallId": "call_001",
"status": "completed",
"content": [
{
"type": "content",
"content": {
"type": "text",
"text": "Analysis complete:\n- No syntax errors found\n- Consider adding type hints for better clarity\n- The function could benefit from error handling for empty lists"
}
}
]
}
}
}
```
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 3](#3-agent-reports-output), continuing until the language model completes its response without requesting additional tool calls or foreground work is stopped by the Agent or cancelled by the Client.
## Stop Reasons
When an Agent stops foreground work, it must specify the corresponding `StopReason` on an idle `state_update` session update:
The Agent has no more work to perform after the language model finishes
responding without requesting more tools
The maximum token limit is reached
The maximum number of model requests for the foreground work is exceeded
The Agent refuses to continue
The Client cancels active work
Custom or future stop reasons can be used when Clients can display a generic stopped state. Custom stop reasons **MUST** begin with `_`; unknown non-underscore stop reasons are reserved for future ACP variants.
## Session States
`state_update` reports foreground work.
Foreground work is in progress.
The Agent is ready to process a new prompt.
Foreground work is blocked on user action.
Background activity **MAY** continue and emit other `session/update` notifications while the Agent reports `idle`. These notifications do not change the state.
## Cancellation
Clients **MAY** cancel active session work at any time by sending a `session/cancel` notification:
```json theme={null}
{
"jsonrpc": "2.0",
"method": "session/cancel",
"params": {
"sessionId": "sess_abc123def456"
}
}
```
The Client **SHOULD** preemptively mark all non-finished tool calls pertaining to the current active work 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** send an idle `state_update` session update with the `cancelled` [stop reason](#stop-reasons).
API client libraries and tools often throw an exception when their operation is aborted, which may otherwise be surfaced as a generic failure.
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 report the semantically meaningful `cancelled` stop reason on a `state_update` notification, 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 sending the idle `state_update` session update that reports cancellation.
The Client **SHOULD** still accept tool call updates received after sending `session/cancel`.
***
After the Agent reports `idle`, the Client may send another `session/prompt` to continue the conversation, building on the established session context.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.