python-sdk/docs/agent/streaming.md

Streaming

Stream agent responses for real-time output.

Basic Streaming

from agents import Agent, Runner

agent = Agent(name="assistant", instructions="Be helpful.")

async def stream_response():
    async for event in Runner.run_streamed(agent, "Tell me a story"):
        if event.type == "raw_response_event":
            # Token-by-token output
            print(event.data, end="", flush=True)
        elif event.type == "agent_updated_event":
            # Agent changed (handoff)
            print(f"\n[Agent: {event.new_agent.name}]")

Stream Events

Event Type	Description
raw_response_event	Raw LLM response chunks
agent_updated_event	Agent changed (handoff)
tool_call_event	Tool being called
tool_output_event	Tool returned result
run_item_event	New run item added

Processing Events

from agents import Runner
from agents.stream_events import (
    RawResponsesStreamEvent,
    AgentUpdatedStreamEvent,
)

async for event in Runner.run_streamed(agent, user_input):
    match event:
        case RawResponsesStreamEvent(data=chunk):
            # Handle text chunk
            print(chunk, end="")
        
        case AgentUpdatedStreamEvent(new_agent=new_agent):
            # Handle agent switch
            print(f"\n[Switched to: {new_agent.name}]")

Streaming with Context

from dataclasses import dataclass
from agents import Agent, Runner

@dataclass
class MyContext:
    user_id: str

context = MyContext(user_id="123")

async for event in Runner.run_streamed(
    agent,
    "Hello!",
    context=context,
):
    print(event)

Streaming Result

Get the final result after streaming:

from agents import Runner, RunResultStreaming

stream = Runner.run_streamed(agent, "Hello!")
result: RunResultStreaming = None

async for event in stream:
    print(event)
    result = stream.result

# After streaming completes
print(f"Final output: {result.final_output}")
print(f"Usage: {result.usage}")

Buffered Streaming

Collect output while streaming:

from agents import Runner

buffer = []

async for event in Runner.run_streamed(agent, "Hello!"):
    if event.type == "raw_response_event":
        buffer.append(event.data)
        print(event.data, end="")

full_response = "".join(buffer)

Streaming with Tools

Tool calls appear as events:

from agents import Runner

async for event in Runner.run_streamed(agent, "What's the weather?"):
    match event.type:
        case "tool_call_event":
            print(f"Calling: {event.tool_name}")
        case "tool_output_event":
            print(f"Result: {event.output}")
        case "raw_response_event":
            print(event.data, end="")

Streaming with Handoffs

from agents import Runner

current_agent = None

async for event in Runner.run_streamed(main_agent, "Help me"):
    if event.type == "agent_updated_event":
        current_agent = event.new_agent
        print(f"\n--- Transferred to {current_agent.name} ---\n")
    elif event.type == "raw_response_event":
        print(event.data, end="")

Error Handling in Streams

from agents import Runner, AgentsException

try:
    async for event in Runner.run_streamed(agent, user_input):
        print(event)
except AgentsException as e:
    print(f"Stream error: {e}")

See Also

• Running Agents - Non-streaming execution
• Tracing - Debug streams
• Results - Result handling