Streaming
Runs stream Server-Sent Events (SSE) by default. The SDK wraps these in a RunStream iterator so you can process events as they arrive.
Quick Patterns
Just the text, live:
Python
Text + post-run data (run_id, full text):
Python
Just the final output (no streaming):
Python
Context Manager
Use with to ensure the HTTP connection is closed cleanly:
Python
stream.text (or stream.output) returns all text deltas joined together.
Event Types
Filter by Event Type
Python
Streaming Replies
Follow-up messages also stream by default:
Python
runs.reply() is always non-interactive. It does not enable AskUserQuestion, approval mode, or plan mode.
Non-Streaming Alternative
Pass stream=False to get a Run object directly. The run executes in the background, then poll for completion:
Best Practices
- Use
stream_text()for the simplest live output — no event filtering needed - Use
iter_text()when you also needstream.run_idorstream.textafter iteration - Use the
withcontext manager to ensure connections are cleaned up - Use
stream=False+poll()for simple scripts and background jobs
SSE Frame Format
Response is a stream of SSE frames:
data: {"type": "metadata", "payload": {"run_id": 123}}
data: {"type": "text-delta", "delta": "Here are "}
data: {"type": "text-delta", "delta": "the open tickets..."}
data: {"type": "tool-call-start", "toolName": "gmail_search", "toolCallId": "tc_1"}
data: {"type": "tool-result-end", "toolCallId": "tc_1", "result": "..."}
data: {"type": "done", "stop_reason": "end_turn"}
What's Next
- Runs — run creation, follow-ups, and polling
- Human-in-the-Loop — interactive features guide
- Webhook Events — outbound notifications for run state changes
- See
examples/support-triage.pyfor a real-time streaming event filter example