Inkdown
Start writing

OpenAI Agents Python

21 files·0 subfolders

Shared Workspace

OpenAI Agents Python
00_OVERVIEW.md

16_STREAMING

Shared from "OpenAI Agents Python" on Inkdown

Streaming - Comprehensive Deep Dive

Overview

Streaming in the OpenAI Agents SDK enables real-time delivery of agent execution events. Think of Streaming as "live updates" or "progressive rendering" - instead of waiting for the entire agent run to complete before seeing results, you receive events as they happen. This is essential for responsive user interfaces, real-time feedback, and long-running operations.

Core Concepts

What is Streaming?

Streaming is the process of delivering events incrementally as they occur during agent execution:

  • Real-time updates - Receive events as they happen
  • Progressive output - Show results as they're generated
  • Event-driven - React to specific events
  • Non-blocking - Don't wait for completion
Why Streaming Matters
  1. Responsiveness - Provide immediate feedback to users
01_AGENT_SYSTEM.md
02_RUNNER_SYSTEM.md
03_TOOL_SYSTEM.md
04_ITEMS_SYSTEM.md
05_GUARDRAILS.md
06_HANDOFFS.md
07_MEMORY_SESSIONS.md
08_MODEL_PROVIDERS.md
09_SANDBOX_SYSTEM.md
10_TRACING.md
11_RUN_STATE.md
12_CONTEXT.md
13_LIFECYCLE_HOOKS.md
14_CONFIGURATION.md
15_ERROR_HANDLING.md
16_STREAMING.md
17_EXTENSIONS.md
18_MCP_INTEGRATION.md
19_BEST_PRACTICES.md
20_ARCHITECTURE_PATTERNS.md
  • User Experience - Show progress during long operations
  • Interactivity - Allow users to see what's happening
  • Efficiency - Start processing partial results early
  • Transparency - Show agent reasoning and tool usage
  • Real-time Applications - Enable live chat interfaces

    • Streaming Methods

    run_streamed()

    The main streaming method:

    Python

    Parameters:

    • Same as run() - agent, input, context, etc.
    • Returns an async iterator of stream events
    Stream Events

    Types of stream events:

    1. RunItemStreamEvent - A new run item was created
    2. AgentUpdatedStreamEvent - The current agent changed
    3. RawResponsesStreamEvent - A raw model stream event

    RunItemStreamEvent

    Event Structure
    Python
    Handling RunItem Events
    Python
    Message Output

    Stream message content as it arrives:

    Python
    Tool Call Streaming

    Stream tool call events:

    Python
    Tool Output Streaming

    Stream tool results:

    Python

    AgentUpdatedStreamEvent

    Event Structure
    Python
    Handling Agent Updates
    Python
    Handoff Detection

    Detect handoffs via agent updates:

    Python

    RawResponsesStreamEvent

    Event Structure
    Python
    Handling Raw Events
    Python
    Delta Streaming

    Stream content deltas:

    Python

    Streaming Patterns

    1. Text Streaming

    Stream text output character by character:

    Python
    2. Progress Indicator

    Show progress during execution:

    Python
    3. Structured Output Streaming

    Stream structured output as it's built:

    Python
    4. Multi-Agent Streaming

    Track multiple agents:

    Python
    5. Tool Execution Visualization

    Visualize tool execution:

    Python

    Streaming and WebSockets

    WebSocket Streaming

    Stream to WebSocket clients:

    Python
    Server-Sent Events

    Stream via Server-Sent Events:

    Python

    Streaming and UI

    React Component

    Stream to React component:

    JavaScript
    Terminal UI

    Stream to terminal with rich output:

    Python

    Streaming Performance

    Event Batching

    Batch events for efficiency:

    Python
    Event Filtering

    Filter events to reduce overhead:

    Python
    Backpressure Handling

    Handle backpressure:

    Python

    Streaming and State

    Streaming with State

    Stream while maintaining state:

    Python
    Streaming to State

    Accumulate streaming results:

    Python

    Streaming Errors

    Handling Streaming Errors

    Handle errors during streaming:

    Python
    Error Events

    Errors may be sent as events:

    Python

    Streaming and Cancellation

    Cancellation

    Cancel streaming operations:

    Python
    Graceful Cancellation

    Cancel gracefully:

    Python

    Streaming Best Practices

    1. Use Async Iterators

    Use async iterators properly:

    Python
    2. Handle All Event Types

    Handle all event types:

    Python
    3. Flush Output

    Flush output for real-time display:

    Python
    4. Handle Backpressure

    Handle backpressure:

    Python
    5. Clean Up Resources

    Clean up streaming resources:

    Python

    Common Streaming Patterns

    1. Chat Interface

    Streaming chat interface:

    Python
    2. Progress Bar

    Show progress during tool execution:

    Python
    3. Multi-Stream Aggregation

    Aggregate multiple streams:

    Python
    4. Conditional Streaming

    Stream based on conditions:

    Python
    5. Streaming with Callbacks

    Use callbacks for event handling:

    Python

    Streaming and Testing

    Testing Streaming

    Test streaming behavior:

    Python
    Mock Streaming

    Mock streaming for tests:

    Python

    Summary

    Streaming enables real-time agent execution. Key takeaways:

    1. run_streamed() is the main streaming method
    2. RunItemStreamEvent - new run item created
    3. AgentUpdatedStreamEvent - agent changed
    4. RawResponsesStreamEvent - raw model event
    5. Text streaming - stream output character by character
    6. Progress indicators - show execution progress
    7. Structured output - stream as it's built
    8. Multi-agent - track multiple agents
    9. Tool visualization - show tool execution
    10. WebSocket - stream to WebSocket clients
    11. SSE - stream via Server-Sent Events
    12. React - stream to React components
    13. Terminal UI - stream to rich terminal
    14. Batching - batch events for efficiency
    15. Filtering - filter events to reduce overhead
    16. Backpressure - handle slow consumers
    17. State - maintain state during streaming
    18. Errors - handle streaming errors
    19. Cancellation - cancel streaming operations
    20. Best practices - async iterators, flush, cleanup

    Streaming is essential for building responsive, real-time agent interfaces.