Principle:Openai Openai agents python Output Processing

Knowledge Sources	OpenAI Agents Python Agents SDK Docs
Domains	AI_Agents, Output_Handling, Data_Extraction
Last Updated	2026-02-11 15:00 GMT

Overview

Output Processing is the theory of processing and extracting structured information from agent run items in the OpenAI Agents Python SDK. The ItemHelpers class provides utilities for extracting text from message outputs, while the RunResult object exposes all items generated during a run for inspection and downstream processing.

Core Concepts

RunResult and new_items

When Runner.run() completes, it returns a RunResult object. The new_items attribute on this result contains a list of all items generated during the run, in chronological order. These items represent every significant event that occurred:

• MessageOutputItem -- a message generated by an agent (the primary text output).
• ToolCallItem -- a tool invocation made by the model (function name and arguments).
• ToolCallOutputItem -- the result returned by a tool execution.
• HandoffCallItem -- a handoff tool call (agent-to-agent delegation request).
• HandoffOutputItem -- the result of a completed handoff (records source and target agents).

This item-based architecture provides a complete audit trail of the agent's execution, enabling detailed logging, analytics, and post-processing.

Text Extraction with ItemHelpers

The most common output processing need is extracting the text content from an agent's response. The ItemHelpers.text_message_outputs() class method handles this by:

1. Filtering new_items to include only MessageOutputItem instances.
2. For each message item, extracting all text content parts (ignoring non-text content like images or refusals).
3. Concatenating the text parts into a single string.

This is the recommended way to get the "final answer" from an agent run, as it handles the complexity of multi-part messages and mixed content types.

Individual Item Inspection

Beyond text extraction, individual items can be inspected for detailed information:

• Tool call details: ToolCallItem contains the function name, arguments, and call ID, enabling logging of what tools were used and with what parameters.
• Handoff tracking: HandoffOutputItem records which agent initiated the handoff and which agent received control, enabling visualization of agent transition graphs.
• Agent attribution: Each item has an agent property identifying which agent generated it, enabling per-agent output analysis in multi-agent runs.

Content Type Handling

Message items can contain multiple content parts of different types. The SDK handles this complexity through the text_message_output() method (singular), which processes a single MessageOutputItem by:

• Iterating over all content parts in the message.
• Extracting text from OutputText parts.
• Skipping non-text parts (images, refusals, etc.).
• Joining all text parts together.

The extract_last_content() method provides an alternative that extracts only the last text content or refusal from a response output item, useful when only the final piece of content matters.

Input Conversion

ItemHelpers also provides the input_to_new_input_list() method, which converts a string or list of input items into a normalized list format. This is useful when building multi-turn conversations where you need to convert the initial string input into the list format expected by subsequent turns.

Source Reference

Source: src/agents/items.py:L491-551

Import:

from agents import ItemHelpers

Related Pages

• Implementation:Openai_Openai_agents_python_ItemHelpers
• Implementation: Openai_Openai_agents_python_ItemHelpers -- full class methods and usage examples.
• Workflow: Openai_Openai_agents_python_Multi_Agent_Handoff -- demonstrates output processing in a multi-agent conversation loop.
• Workflow: Openai_Openai_agents_python_Basic_Agent_Execution -- shows basic output extraction from a simple agent run.

GitHub URL

Source: items.py