event-deltas changedmanaged-agents/event-deltas
Nearest release: v2.1.312, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+16added
Lines−16removed
From line
10
where the diff opens
First seen
8 Oct 2026
this site's first read of the page
Recorded edits16to this page, all time
The whole hunk
from line 10, old and new numbered
/
from line 10
1010 betaHeader: managed-agents-2026-04-01
1111---
1212
13By default, the agent's response text reaches the [session event stream](https://platform.claude.com/docs/en/managed-agents/events-and-streaming) as buffered `agent.message` events. Each one is emitted only after the model request that produced it completes. Event deltas let you render that text incrementally, as a live preview, while the model is still generating it.
13By default, the agent’s response text reaches the [session event stream](https://platform.claude.com/docs/en/managed-agents/events-and-streaming) as buffered `agent.message` events. Each one is emitted only after the model request that produced it completes. Event deltas let you render that text incrementally, as a live preview, while the model is still generating it.
1414
1515Previews are a best-effort display aid, and the buffered `agent.message` is always the authoritative record. A client that ignores previews still receives a complete, correct stream.
1616
1717## Opt in to previews
1818
19Previews are opt-in for each stream connection. Add the `event_deltas[]` query parameter to the stream you're reading, and repeat it once for each event type you want previewed. The accepted values are `agent.message` and `agent.thinking`. Any other value returns a 400 error, as does a request with more than 100 values.
19Previews are opt-in for each stream connection. Add the `event_deltas[]` query parameter to the stream you’re reading, and repeat it once for each event type you want previewed. The accepted values are `agent.message` and `agent.thinking`. Any other value returns a 400 error, as does a request with more than 100 values.
2020
2121Both stream endpoints accept the parameter:
2222
from line 23
2323* **Session-level stream:** `GET /v1/sessions/{session_id}/events/stream`
2424* **Session thread stream:** `GET /v1/sessions/{session_id}/threads/{thread_id}/stream`
2525
26A subagent's previews appear on [that subagent's own thread stream](https://platform.claude.com/docs/en/managed-agents/event-deltas#preview-session-thread-events).
26A subagent’s previews appear on [that subagent’s own thread stream](https://platform.claude.com/docs/en/managed-agents/event-deltas#preview-session-thread-events).
2727
2828`[]` is a shell glob pattern, so quote the URL whenever you build the request in a shell. The examples percent-encode the brackets as `%5B%5D`, which also works.
2929
3030### Preview events
3131
32When a previewed event starts, the stream emits an `event_start` carrying the upcoming event's type and `id`:
32When a previewed event starts, the stream emits an `event_start` carrying the upcoming event’s type and `id`:
3333
3434```json
3535{
from line 80
80804. The buffered `agent.message`
81815. [`span.model_request_end`](https://platform.claude.com/docs/en/managed-agents/reference#event-types) (in the **Span events** tab)
8282
83On the wire, this is the previewed portion of that sequence, interleaved with the connection's other buffered events:
83On the wire, this is the previewed portion of that sequence, interleaved with the connection’s other buffered events:
8484
8585```text wrap
8686event_start {"event": {"type": "agent.message", "id": "sevt_01abc..."}}
from line 91
9191
9292The `event_delta` line repeats once for each text fragment. Process each event as it arrives:
9393
941. On `event_start`, note the announced `id`. The identifiers always line up: `event_start.event.id`, every `event_delta.event_id`, and the buffered `agent.message`'s `id` are the same value.
941. On `event_start`, note the announced `id`. The identifiers always line up: `event_start.event.id`, every `event_delta.event_id`, and the buffered `agent.message`’s `id` are the same value.
95952. On each `event_delta`, append `delta.content.text` to the entry at `(event_id, delta.index)` and render the running text. The first delta for an `index` creates that entry.
963. When the buffered `agent.message` arrives, match it by `id`, discard the accumulated preview, and render the message's content instead.
963. When the buffered `agent.message` arrives, match it by `id`, discard the accumulated preview, and render the message’s content instead.
97974. On `span.model_request_end`, close any preview that has not been reconciled by its buffered event. No more deltas are coming for it. If the turn errors or is interrupted, the buffered event might never arrive, but `span.model_request_end` still does.
9898
9999The pattern relies on two guarantees:
100100
101* Concatenating a preview's deltas in arrival order, keyed by `(event_id, index)`, gives a prefix of `content[index].text` in the buffered event. It is not necessarily the whole text, because deltas might be [shed under load](https://platform.claude.com/docs/en/managed-agents/event-deltas#limitations).
101* Concatenating a preview’s deltas in arrival order, keyed by `(event_id, index)`, gives a prefix of `content[index].text` in the buffered event. It is not necessarily the whole text, because deltas might be [shed under load](https://platform.claude.com/docs/en/managed-agents/event-deltas#limitations).
102102* A connection emits at most one `event_start` for each `event_id`, and the buffered event is the last thing that connection delivers for that `id`.
103103
104104### SDK accumulator helpers
105105
106Each SDK's helper handles the `index` (csharp, go: `Index`) bookkeeping. The Go, Java, Ruby, and C# helpers also key the accumulating preview by the event's `id` (csharp, go: `ID`). With the Python, TypeScript, and PHP helpers, keep that map yourself and fold each delta into the entry for its `id` (csharp, go: `ID`).
106Each SDK’s helper handles the `index` (csharp, go: `Index`) bookkeeping. The Go, Java, Ruby, and C# helpers also key the accumulating preview by the event’s `id` (csharp, go: `ID`). With the Python, TypeScript, and PHP helpers, keep that map yourself and fold each delta into the entry for its `id` (csharp, go: `ID`).
107107
108108The following examples opt in to `agent.message` previews and reconcile them with the buffered event:
109109
from line 558
558558
559559In a [multiagent](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration) session, every session thread has its own event stream. It takes the same `event_deltas[]` parameter with the same values.
560560
561A connection previews only the thread it's reading. The session-level stream previews the primary thread, and a child thread's previews are never cross-posted to it. To watch a subagent's text as the model generates it, open that subagent's thread stream.
561A connection previews only the thread it’s reading. The session-level stream previews the primary thread, and a child thread’s previews are never cross-posted to it. To watch a subagent’s text as the model generates it, open that subagent’s thread stream.
562562
563A thread stream's path ends in `/threads/{thread_id}/stream`. `/events/stream` exists only at the session level, so there is no `/threads/{thread_id}/events/stream` endpoint.
563A thread stream’s path ends in `/threads/{thread_id}/stream`. `/events/stream` exists only at the session level, so there is no `/threads/{thread_id}/events/stream` endpoint.
564564
565565`event_start` and `event_delta` have the same shape on a thread stream as on the session-level stream, and the [accumulate and reconcile](https://platform.claude.com/docs/en/managed-agents/event-deltas#accumulate-and-reconcile) pattern applies as written. Run one accumulator instance for each stream connection.
566566
from line 853
853853 ```
854854</CodeGroup>
855855
856The read loop exits on [`session.thread_status_idle`](https://platform.claude.com/docs/en/managed-agents/reference#event-types), the event emitted when the session thread's turn completes and the thread goes idle.
856The read loop exits on [`session.thread_status_idle`](https://platform.claude.com/docs/en/managed-agents/reference#event-types), the event emitted when the session thread’s turn completes and the thread goes idle.
857857
858858## Limitations
859859
from line 860
860860* **Best effort:** Under load, the server might shed deltas for an event. When it does, you receive a contiguous prefix of the text and then no further deltas for that event. The buffered `agent.message` still arrives complete. Never treat an accumulated preview as final.
861861* **No replay on reconnect:** Deltas are delivered only to the connection that opted in, while it is open. This applies to the session-level stream and to each session thread stream alike. A connection opened after a model request started receives no deltas for that in-flight event. There is no way to re-request missed deltas.
862862* **One thread, text only:** Previews cover assistant text on [the thread the connection is reading](https://platform.claude.com/docs/en/managed-agents/event-deltas#preview-session-thread-events). Tool use, tool results, and MCP results are never previewed.
863* **Never persisted:** `event_start` and `event_delta` exist only on the live stream. They do not appear in the session's event history (`GET /v1/sessions/{session_id}/events`) or in any session thread's event history.
863* **Never persisted:** `event_start` and `event_delta` exist only on the live stream. They do not appear in the session’s event history (`GET /v1/sessions/{session_id}/events`) or in any session thread’s event history.
864864
865865## Troubleshoot previews
866866
867867| You see | What it means |
868868| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
869| A stream with buffered events but no `event_start` or `event_delta` | The connection you're reading didn't opt in, or the turn never touched the thread you're streaming. `event_deltas[]` applies per connection, not per session. To find which thread ran, list the session's threads (`GET /v1/sessions/{session_id}/threads`). |
869| A stream with buffered events but no `event_start` or `event_delta` | The connection you’re reading didn’t opt in, or the turn never touched the thread you’re streaming. `event_deltas[]` applies per connection, not per session. To find which thread ran, list the session’s threads (`GET /v1/sessions/{session_id}/threads`). |
870870| A stream that drops during a preview | Deltas are not replayed. Follow the [reconnect procedure](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#reconnect-without-missing-events): reopen the stream and list the event history. The history includes any buffered events emitted while you were disconnected, including the `agent.message` your preview was waiting for. |
871| A 404 on the stream URL | The path or an ID is wrong, or the request carries no managed-agents beta header at all. The thread endpoints are beta-gated, so without the header they don't exist. |
871| A 404 on the stream URL | The path or an ID is wrong, or the request carries no managed-agents beta header at all. The thread endpoints are beta-gated, so without the header they don’t exist. |
872872| A 400 naming `event_deltas` | Only `agent.message` and `agent.thinking` are accepted. |
873873
874874## Next steps
No line in this hunk matches that.