Principle:Openai Openai agents python Streamed Result Access

Overview

Streamed Result Access is the principle of accessing final results from a streamed agent run. After all streaming events have been consumed, the RunResultStreaming object provides the same comprehensive result interface as a non-streamed RunResult. This principle bridges the gap between real-time event streaming and complete result inspection.

Core Theory

RunResultStreaming Extends RunResultBase

The RunResultStreaming class inherits from RunResultBase, which defines the common result interface shared with the non-streamed RunResult. This inheritance ensures that code written to inspect run results works identically regardless of whether the run was streamed.

The base class provides:

input -- The original input provided to the run.
new_items -- All RunItem objects produced during execution.
raw_responses -- The complete raw LLM responses collected during the run.
final_output -- The final text or structured output from the agent.
input_guardrail_results -- Results from input guardrail evaluations.
output_guardrail_results -- Results from output guardrail evaluations.
context_wrapper -- The context wrapper used during the run.

Final Output Availability

A critical aspect of streamed result access is that final_output is only available after the stream completes. The is_complete flag indicates whether all events have been consumed and the run has finished.

Attempting to access final_output before the stream completes may return None or an incomplete value. The correct pattern is:

# Consume all events first
async for event in result.stream_events():
    process(event)

# Now is_complete is True and final_output is available
assert result.is_complete
output = result.final_output

This design enforces a clear temporal contract: stream first, then inspect results.

Current Agent Tracking

During a streamed run, the current_agent property tracks which agent is actively processing. In multi-agent workflows with handoffs, this value changes as control passes between agents. After the stream completes, current_agent reflects the last agent that was active.

This is useful for:

Displaying which agent produced the final output.
Understanding the handoff chain that occurred during execution.
Making decisions based on which agent handled the request.

State Resumption via to_state()

The to_state() method on RunResultStreaming enables resuming interrupted streaming runs. It serializes the current state of the run into a RunState object, which can then be passed as the input parameter to a subsequent Runner.run_streamed() or Runner.run() call.

This capability is important for:

Interruption recovery -- If a streaming run is interrupted (e.g., by network failure or user cancellation), the state can be saved and resumed later.
Multi-step workflows -- Long-running agent tasks can be broken into segments, with state preserved between them.
Approval flows -- When MCP tools require user approval, the run can be paused, approval obtained, and then resumed from the saved state.

Bridging Real-Time and Final Access

The RunResultStreaming class serves as a bridge between two modes of interaction:

Real-time mode -- During streaming, events provide immediate access to partial data as it is generated. UIs can display text deltas, show tool invocations in progress, and track agent handoffs.

Result mode -- After streaming completes, the same object provides a comprehensive snapshot of the entire run, identical in structure to what a non-streamed run would return.

This dual nature means that a single object supports both the "watching it happen" and "inspecting what happened" use cases, without requiring separate APIs or data transformations.

Design Implications

Consistent Result Interface

Because RunResultStreaming and RunResult both extend RunResultBase, downstream code that processes results (e.g., logging, analytics, state persistence) can be written once and applied to both streamed and non-streamed runs. This reduces code duplication and simplifies testing.

Temporal Guarantees

The is_complete flag provides a clear, programmatic way to verify that the stream has finished before accessing final results. This prevents a common class of bugs where partial data is mistakenly treated as complete.

Source Reference

Source: src/agents/result.py, lines 320-654
Import: from agents import RunResultStreaming

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment