Streaming responses via SSE

## The shape of a delta event A streamed Anthropic message is a list of content blocks, and each block is filled in by a run of `content_block_delta` events. A delta event has two fields that matter: `index`, the position of the block it belongs to, and `delta`, an object with its own `type` discriminator. The events for a block are bracketed by `content_block_start` at that index and `content_block_stop` at the same index. Blocks are emitted sequentially, but you should still key on `index` rather than assuming a single current block — that assumption is exactly what breaks when a message answers in text and then opens a tool-use block. ## Delta types and how each accumulates **`text_delta`** carries a `text` field: the newly generated fragment, not the text so far. You append it. Fragments split at token boundaries, which means they can cut through the middle of a word, a Markdown fence, or a multi-byte character sequence at the transport level — never assume a delta is a whole word or a whole line. **`input_json_delta`** carries a `partial_json` field and appears inside a `tool_use` block. The model's tool arguments are serialised to JSON and then chopped up; a single fragment is very often not valid JSON on its own (`{"loc`, `ation": "Par`, `is"}`). The rule is: concatenate every `partial_json` fragment for that index into one string, and parse it exactly once, at `content_block_stop`. Trying to `json.loads` each fragment, or to re-parse the growing buffer on every delta so you can render arguments early, is the single most common bug in hand-rolled accumulators. If you genuinely need to show arguments as they arrive, use a streaming/partial JSON parser that is designed to tolerate truncation — do not point a strict parser at half a document. **`thinking_delta` and `signature_delta`** appear when extended thinking is enabled: the first accumulates the reasoning text, the second the cryptographic signature attached to the thinking block. They accumulate by the same append rule. ## The assembled result When the stream reaches `message_stop`, you should be able to reconstruct precisely the JSON body you would have received from a non-streaming call: the shell from `message_start`, `content` populated from your per-index buffers, and `stop_reason`, `stop_sequence` and output usage patched in from `message_delta`. That equivalence is a useful design target and an even better test — run the same prompt with and without streaming at temperature 0 and assert your accumulator produces the same structure. ## Let the SDK do it The official SDKs ship a streaming helper that maintains this state for you: it exposes a text-only iterator for the common "print tokens as they arrive" case, and a call that returns the fully assembled final message once the stream drains. Reach for the raw event iterator only when you are building a relay or need per-event control; even then, the helper's assembled message is usually what you persist to your conversation history, because the next turn needs whole blocks, not fragments. ## Where it goes wrong in production *Rendering partial JSON.* Users see a flicker of malformed arguments, or your parser throws mid-stream and kills the request. *Flattening indices.* Concatenating all deltas into one string works fine in demos with a single text block and corrupts the first time a message contains two blocks. *Persisting fragments.* Writing individual deltas into your conversation store, then replaying them as history, produces a message the API cannot interpret; store the assembled blocks. *Assuming cumulative deltas.* Some other streaming protocols resend the whole value each time. Anthropic's do not — a client that replaces instead of appending ends up with only the last fragment of every block. *Trusting a buffer before its stop event.* A block is only complete at `content_block_stop`; acting on a tool call before then means acting on truncated arguments.