Inkdown
Start writing

OpenAI Agents Python

21 filesยท0 subfolders

Shared Workspace

OpenAI Agents Python
00_OVERVIEW.md

04_ITEMS_SYSTEM

Shared from "OpenAI Agents Python" on Inkdown

Items System - Comprehensive Deep Dive

Overview

The Items system is the fundamental data structure that represents everything that happens during an agent run. Every message, tool call, handoff, and model response is represented as an "Item". Think of Items as the "ledger" or "transaction log" of an agent run - they record every event in a structured, serializable format.

Core Concepts

What is an Item?

An Item is a structured representation of an event that occurs during an agent run. Items are:

  • Typed - Each item has a specific type (message, tool call, handoff, etc.)
  • Serializable - Can be converted to/from JSON
  • Traceable - Each item can be traced back to the agent that created it
  • Convertible - Can be converted to input items for the model
Why Items Matter
  1. Audit Trail - Complete record of what happened during a run
01_AGENT_SYSTEM.md
02_RUNNER_SYSTEM.md
03_TOOL_SYSTEM.md
04_ITEMS_SYSTEM.md
05_GUARDRAILS.md
06_HANDOFFS.md
07_MEMORY_SESSIONS.md
08_MODEL_PROVIDERS.md
09_SANDBOX_SYSTEM.md
10_TRACING.md
11_RUN_STATE.md
12_CONTEXT.md
13_LIFECYCLE_HOOKS.md
14_CONFIGURATION.md
15_ERROR_HANDLING.md
16_STREAMING.md
17_EXTENSIONS.md
18_MCP_INTEGRATION.md
19_BEST_PRACTICES.md
20_ARCHITECTURE_PATTERNS.md
  • Session Persistence - Items are saved to sessions for conversation history
  • Debugging - Inspect items to understand agent behavior
  • Replay - Items can be replayed to reproduce runs
  • Analysis - Analyze patterns in agent behavior
  • Tracing - Items are the basis for trace spans

    • Item Types

    MessageOutputItem

    Represents a message from the LLM:

    Python

    When it's created:

    • When the LLM generates a message response
    • After tool execution when the LLM responds
    • When an agent produces final output

    Structure:

    • agent - The agent that generated this message
    • raw_item - The raw OpenAI ResponseOutputMessage object
    • type - Always "message_output_item"
    ToolCallItem

    Represents a request to call a tool:

    Python

    When it's created:

    • When the LLM decides to call a tool
    • For each tool call in a multi-tool invocation

    Structure:

    • agent - The agent that made the tool call
    • raw_item - The raw tool call object
    • type - The specific tool type (function, computer, shell, etc.)
    ToolCallOutputItem

    Represents the result of a tool execution:

    Python

    When it's created:

    • After a tool is executed
    • When a tool error occurs
    • When a tool is rejected (approval denied)

    Structure:

    • agent - The agent that called the tool
    • raw_item - The raw output item
    • output - The tool's output (as string)
    HandoffCallItem

    Represents a handoff to another agent:

    Python

    When it's created:

    • When the LLM calls a handoff tool
    • When an agent delegates to another agent

    Structure:

    • agent - The agent making the handoff
    • raw_item - The handoff tool call
    • target_agent - The agent being handed off to
    HandoffOutputItem

    Represents the result of a handoff:

    Python

    When it's created:

    • After a handoff completes
    • When the target agent produces output
    ReasoningItem

    Represents model reasoning (for reasoning models like GPT-5):

    Python

    When it's created:

    • When a reasoning model produces reasoning content
    • Before the final response

    Structure:

    • agent - The agent that produced reasoning
    • raw_item - The raw reasoning item
    • summary - Summary of the reasoning
    ToolApprovalItem

    Represents a tool approval request (human-in-the-loop):

    Python

    When it's created:

    • When a tool requires approval
    • When execution pauses for human review

    Structure:

    • agent - The agent that called the tool
    • tool_name - Name of the tool
    • tool_arguments - Arguments passed to the tool
    • call_id - Unique call ID
    MCPApprovalRequestItem

    Represents an MCP tool approval request:

    Python

    When it's created:

    • When an MCP tool requires approval
    • Before MCP tool execution
    MCPApprovalResponseItem

    Represents the response to an MCP approval request:

    Python

    When it's created:

    • After human approves/rejects MCP tool
    • Before actual MCP tool execution
    ToolSearchCallItem

    Represents a tool search request (Responses API):

    Python

    When it's created:

    • When the model uses tool search
    • To find relevant tools
    ToolSearchOutputItem

    Represents tool search results:

    Python

    When it's created:

    • After tool search completes
    • With search results
    CompactionItem

    Represents conversation compaction (for long conversations):

    Python

    When it's created:

    • When conversation history is compacted
    • To reduce token usage while preserving context

    Item Base Class

    RunItemBase

    All items inherit from RunItemBase:

    Python

    Key Features:

    1. Agent Reference - Every item knows which agent created it
    2. Weak References - Uses weak references to avoid memory leaks
    3. Type Generic - Generic over the raw item type
    4. Convertible - Can convert to input items
    Memory Management

    Items use weak references to agents to prevent memory leaks:

    Python

    Why weak references?

    • Long-running sessions with many items
    • Prevents agents from being kept alive by old items
    • Still allows debugging with agent information

    Item Conversion

    to_input_item()

    Every item can be converted to an input item for the model:

    Python

    Why conversion is needed:

    • Items are output format (what came out)
    • Input items are input format (what goes in)
    • Conversion enables replay and session persistence
    • Different formats for output vs input

    Conversion Rules:

    1. Dict items - Returned as-is (already input format)
    2. Pydantic items - Converted using model_dump(exclude_unset=True)
    3. Custom items - Must implement to_input_item()
    run_items_to_input_items()

    Convert multiple items to input items:

    Python

    Used for:

    • Session persistence
    • Replay functionality
    • Handoff history preparation

    Item Helpers

    ItemHelpers Class

    Utility class for working with items:

    Python

    Key Methods:

    • get_tool_calls(items) - Extract tool call items
    • get_messages(items) - Extract message items
    • get_text_content(item) - Get text from a message
    • to_input_list(items) - Convert items to input list
    • get_function_call_outputs(items) - Get tool outputs

    Model Response

    ModelResponse Class

    Represents a complete model response:

    Python

    When it's created:

    • After each model call
    • Contains all output items from the call
    • Includes usage information

    Structure:

    • response - Full OpenAI Response object
    • request_id - Request identifier
    • usage - Token usage data
    • agent - Agent that made the request

    Item Lifecycle

    Creation Flow
    Python
    Persistence Flow
    Python
    Replay Flow
    Python

    Item Serialization

    JSON Serialization

    Items can be serialized to JSON:

    Python

    Serialization considerations:

    • Raw items are Pydantic models with built-in serialization
    • Agent references are not serialized (use weak references)
    • Context is not serialized (user data)
    • Only the raw item data is serialized
    RunState Serialization

    Items are part of RunState serialization:

    Python

    What gets serialized:

    • All generated items
    • Agent identities (name, handoff description)
    • Tool call metadata
    • Usage information
    • Guardrail results

    Item Filtering

    Filtering by Type
    Python
    Filtering by Agent
    Python
    Filtering by Tool Name
    Python

    Item Analysis

    Analyzing Tool Usage
    Python
    Analyzing Turn Structure
    Python
    Analyzing Agent Handoffs
    Python

    Item and Session Integration

    Session Items

    Sessions store items as conversation history:

    Python
    Compaction Items

    For long conversations, items are compacted:

    Python

    Item and Tracing

    Trace Spans from Items

    Each item can create a trace span:

    Python
    Item Metadata in Traces

    Items include metadata in traces:

    Python

    Best Practices

    1. Use Item Helpers

    Use the provided helper functions:

    Python
    2. Check Item Types

    Always check item types before accessing:

    Python
    3. Release Agent References

    Release agent references when done:

    Python
    4. Convert to Input Items

    Use proper conversion for replay:

    Python
    5. Filter Appropriately

    Filter items based on your needs:

    Python

    Common Patterns

    1. Extract Tool Results
    Python
    2. Count Agent Turns
    Python
    3. Find Handoff Points
    Python
    4. Calculate Token Usage
    Python

    Summary

    The Items system is the foundation of run representation. Key takeaways:

    1. Items represent all events in an agent run
    2. Item types include messages, tool calls, handoffs, reasoning, etc.
    3. RunItemBase is the base class for all items
    4. Weak references prevent memory leaks
    5. Conversion enables replay and persistence
    6. ItemHelpers provide utility functions
    7. ModelResponse wraps a complete model response
    8. Serialization enables state persistence
    9. Filtering allows item analysis
    10. Sessions store items as conversation history
    11. Compaction reduces token usage for long conversations
    12. Tracing uses items for observability
    13. Analysis enables pattern detection
    14. Replay enables reproducing runs
    15. Debugging is easier with item inspection
    16. Agent references track which agent created each item
    17. Tool metadata tracks tool usage
    18. Handoff tracking follows agent delegation
    19. Usage tracking monitors token consumption
    20. Type safety ensures correct item handling

    Understanding Items is essential for debugging, persistence, and analysis of agent runs.