Careeroza

Streaming the Reply

Why Stream?

A long reply can take many seconds. With streaming, text arrives piece by piece as it is generated, so users see words appear immediately (like ChatGPT or Claude.ai). Use client.messages.stream(...):

with client.messages.stream(
    model="claude-sonnet-5-5",
    max_tokens=1000,
    messages=[{"role": "user", "content": "Write 3 tips for packing fragile items."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final = stream.get_final_message()

print("\n\noutput tokens:", final.usage.output_tokens)

Run it (text appears gradually)

python stream.py

Example output

1. Wrap each item separately in bubble wrap, taping it securely.
2. Fill empty space in the box with paper or packing peanuts so nothing moves.
3. Mark the box "FRAGILE" on all sides and keep heavy items at the bottom.

output tokens: 52

Stream Events Underneath

Example

The stream is a sequence of server-sent events: message_start, then content_block_delta events with small text pieces, then message_delta (stop reason and usage) and message_stop. A generator stands in for the network here:

def fake_stream():
    yield {"type": "message_start"}
    yield {"type": "content_block_start", "index": 0}
    for piece in ["Your ", "order ", "ships ", "today", "."]:
        yield {"type": "content_block_delta", "delta": {"type": "text_delta", "text": piece}}
    yield {"type": "content_block_stop", "index": 0}
    yield {"type": "message_delta", "delta": {"stop_reason": "end_turn"}, "usage": {"output_tokens": 5}}
    yield {"type": "message_stop"}

full = ""
for event in fake_stream():
    if event["type"] == "content_block_delta":
        full += event["delta"]["text"]
        print(f"delta  -> {full!r}")
    elif event["type"] == "message_delta":
        print("finished:", event["delta"]["stop_reason"], "| tokens:", event["usage"]["output_tokens"])
    else:
        print("event  ->", event["type"])

Output

event  -> message_start
event  -> content_block_start
delta  -> 'Your '
delta  -> 'Your order '
delta  -> 'Your order ships '
delta  -> 'Your order ships today'
delta  -> 'Your order ships today.'
event  -> content_block_stop
finished: end_turn | tokens: 5
event  -> message_stop