Principle:Openai Openai agents python Result Extraction
| Property | Value |
|---|---|
| Principle Name | Result Extraction |
| SDK | OpenAI Agents Python |
| Repository | openai-agents-python |
| Documentation | Running Agents Guide |
| Source Reference | src/agents/result.py:L213-317
|
| Import | from agents import RunResult
|
Overview
The Result Extraction principle describes how the output of an agent run is captured, structured, and made available for consumption. After the Runner completes execution, it produces a RunResult that encapsulates the final output, all generated items, the last agent that ran, guardrail results, and metadata needed for multi-turn conversations or resuming interrupted runs.
Description
When Runner.run() completes, it returns a RunResult object that serves as the complete record of the execution. The result provides access to several categories of information:
Final Output
The final_output field contains the agent's final answer. Its type depends on the agent's configuration:
- If the agent has no
output_typeset (the default),final_outputis a plainstr. - If the agent specifies an
output_type(e.g., a Pydantic model or dataclass),final_outputis an instance of that type, automatically parsed from the model's structured output.
The final_output_as(cls) convenience method provides type-safe casting of the final output to a specific type, with an optional runtime type check.
Generated Items
The new_items field contains a list of RunItem objects representing everything generated during the run: assistant messages, tool calls and their outputs, handoff events, and more. These items provide a complete audit trail of the agent's execution.
Last Agent
The last_agent property returns the agent that produced the final output. In single-agent runs, this is always the starting agent. In multi-agent workflows with handoffs, this reveals which specialized agent ultimately handled the request. This is important for understanding execution flow and for continuing conversations with the correct agent.
Guardrail Results
The result includes both input_guardrail_results and output_guardrail_results, providing transparency into which guardrails were evaluated and their outcomes. Additionally, tool_input_guardrail_results and tool_output_guardrail_results capture guardrail evaluations for tool invocations.
Multi-Turn Conversation Support
The to_input_list() method converts the result back into an input format that can be passed to a subsequent Runner.run() call. This enables multi-turn conversations by merging the original input with all generated items, allowing the next turn to have full context of the conversation so far.
Resumable State
The to_state() method creates a RunState from the result, enabling interrupted runs to be resumed. This is essential for human-in-the-loop workflows where tool calls require explicit approval. The state captures the full execution context including the current turn number, pending interruptions, and conversation history.
Interruptions
The interruptions field contains a list of ToolApprovalItem objects representing tool calls that require human approval before execution. When interruptions are present, the run paused before completing, and the caller must approve or reject each interruption before resuming via to_state().
Theoretical Basis
The Result Extraction principle embodies:
- Value Object Pattern:
RunResultis an immutable record of the completed execution, providing a clear contract for what information is available after a run. - Memento Pattern: The
to_state()method captures the internal execution state into an externalized form (RunState) that can be used to restore and resume execution. - Iterator/Collection Pattern:
new_itemsprovides an ordered collection of execution artifacts that can be inspected, filtered, or replayed. - Type Safety: The generic context type and
final_output_as()method enable compile-time and runtime type checking for structured outputs.
Usage
Accessing the Final Output
result = await Runner.run(agent, "What is 2 + 2?")
print(result.final_output) # "4" (or a more verbose answer)
Typed Output Extraction
from pydantic import BaseModel
class MathAnswer(BaseModel):
answer: float
explanation: str
agent = Agent(name="math", instructions="Solve math problems.", output_type=MathAnswer)
result = await Runner.run(agent, "What is 2 + 2?")
answer = result.final_output_as(MathAnswer)
print(answer.answer) # 4.0
print(answer.explanation) # "2 + 2 equals 4"
Multi-Turn Conversation
result = await Runner.run(agent, "My name is Alice.")
next_input = result.to_input_list()
next_input.append({"role": "user", "content": "What is my name?"})
result2 = await Runner.run(agent, next_input)