Implementation:Openai Openai agents python ItemHelpers

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

Overview

ItemHelpers is a utility class in the OpenAI Agents Python SDK that provides class methods for extracting and processing content from agent run items. It is the primary interface for extracting text from message outputs, creating tool call output items, and converting input formats.

Import

from agents import ItemHelpers

Key Methods

text_message_outputs

@classmethod
def text_message_outputs(cls, items: list[RunItem]) -> str:
    """Concatenates all text content from message output items."""

Filters the provided items list to include only MessageOutputItem instances, then extracts and concatenates all text content from each message. This is the recommended method for getting the "final answer" text from an agent run.

text_message_output

@classmethod
def text_message_output(cls, message: MessageOutputItem) -> str:
    """Extracts all text content from a single message output item."""

Processes a single MessageOutputItem by iterating over its content parts and extracting text from OutputText parts. Non-text content (images, refusals) is skipped.

extract_last_content

@classmethod
def extract_last_content(cls, message: TResponseOutputItem) -> str:
    """Extracts the last text content or refusal from a message."""

Returns the last text content or refusal string from a response output item. Useful when only the final piece of a multi-part message matters.

input_to_new_input_list

@classmethod
def input_to_new_input_list(cls, input: str | list[TResponseInputItem]) -> list[TResponseInputItem]:
    """Converts a string or list of input items into a list of input items."""

Normalizes input into list format. If a string is provided, it is wrapped in a user message input item. If a list is provided, it is returned as-is. This is useful for building multi-turn conversations.

tool_call_output_item

@classmethod
def tool_call_output_item(cls, tool_call, output) -> FunctionCallOutput:
    """Creates a tool call output item from a tool call and its output."""

Constructs a FunctionCallOutput from a tool call object and its string output. Used internally by the SDK and available for custom tool execution pipelines.

Usage Examples

Extract Text from Agent Run

from agents import Agent, Runner, ItemHelpers

agent = Agent(name="assistant", instructions="Be helpful.")
result = await Runner.run(agent, "Tell me about Python.")

# Get just the text output
text = ItemHelpers.text_message_outputs(result.new_items)
print(text)

Inspect Individual Items

from agents import Agent, Runner, ItemHelpers
from agents.items import MessageOutputItem, ToolCallItem, HandoffOutputItem

result = await Runner.run(agent, "What is 2 + 2?")

for item in result.new_items:
    if isinstance(item, MessageOutputItem):
        text = ItemHelpers.text_message_output(item)
        print(f"Message from {item.agent.name}: {text}")
    elif isinstance(item, ToolCallItem):
        print(f"Tool call: {item.raw_item.name}({item.raw_item.arguments})")
    elif isinstance(item, HandoffOutputItem):
        print(f"Handoff: {item.source_agent.name} -> {item.target_agent.name}")

Multi-Turn Conversation with Input Conversion

from agents import Agent, Runner, ItemHelpers

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

# First turn
result = await Runner.run(agent, "Hello!")
conversation = result.to_input_list()

# Second turn - append new user message
conversation.append({"role": "user", "content": "Tell me more."})
result = await Runner.run(agent, conversation)

# Extract final text
print(ItemHelpers.text_message_outputs(result.new_items))

Processing Items in a Multi-Agent Run

from agents import Agent, Runner, ItemHelpers
from agents.items import MessageOutputItem, HandoffOutputItem

result = await Runner.run(triage_agent, "I need help with billing.", context=my_ctx)

# Track which agents participated
agents_involved = set()
for item in result.new_items:
    agents_involved.add(item.agent.name)
    if isinstance(item, HandoffOutputItem):
        print(f"Handoff: {item.source_agent.name} -> {item.target_agent.name}")

# Get all message text
full_response = ItemHelpers.text_message_outputs(result.new_items)
print(f"Agents involved: {agents_involved}")
print(f"Response: {full_response}")

Item Types Reference

The following item types can appear in RunResult.new_items:

Item Type	Description
MessageOutputItem	A message generated by an agent (text, images, refusals).
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).

Source Reference

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

Related Pages

• Principle: Openai_Openai_agents_python_Output_Processing -- theory of output processing and item extraction.
• Workflow: Openai_Openai_agents_python_Basic_Agent_Execution -- demonstrates basic output extraction.
• Workflow: Openai_Openai_agents_python_Multi_Agent_Handoff -- shows item inspection in multi-agent runs.

GitHub URL

Source: items.py