Enhance Documentation for HandoffInputData Structure and Usage

[abdul-kabir-jawed]

The handoffs documentation mentions HandoffInputData but lacks details such as:

• Exact types and structure of pre_handoff_items and new_items (RunItem subtypes like RunMessageOutputItem, RunHandoffCallItem).
• Explanation of differences between input_history, pre_handoff_items, and new_items.
• How allItems is derived and affected by changes.
• Streaming vs. non-streaming behavior.
• Examples of custom input_filter functions modifying these fields.

This leaves developers uncertain about how to use HandoffInputData effectively, especially for compliance-related filters.

---

Steps to Reproduce

from openai.agents import Agent, handoff, HandoffInputData

def custom_filter(data: HandoffInputData) -> HandoffInputData:
    print(data.pre_handoff_items)  # Structure unclear
    print(data.new_items)          # Structure unclear
    return data

target = Agent(name="Target")
source = Agent(
    name="Source",
    handoffs=[handoff(target, input_filter=custom_filter)]
)

from openai.agents import Runner
Runner.run_sync(source, "Test handoff")

Observed:

• No clear guidance on structure or streaming behavior of HandoffInputData.

---

Expected Behavior

Docs should include:

• Type definitions:
  • input_history: tuple of message dicts
  • pre_handoff_items: tuple of RunItem subtypes (before handoff turn)
  • new_items: tuple of RunItem subtypes (current turn)
  • allItems: concatenation of all above
• Purpose and when to modify each field.
• Streaming behavior details.
• Example of a custom input_filter:

def gdpr_filter(data: HandoffInputData) -> HandoffInputData:
    filtered = [
        msg for msg in data.input_history
        if "account" not in msg.get("content", "").lower()
    ]
    return HandoffInputData(
        input_history=tuple(filtered),
        pre_handoff_items=data.pre_handoff_items,
        new_items=data.new_items
    )

---

Suggested Fix

1. Expand "Handoffs" section with type definitions, field purposes, and streaming notes.
2. Add examples of custom filters in examples/handoffs.
3. Update HandoffInputData docstring in src/agents/handoff.py.
4. Add tests for input_filter field manipulation.

---

Environment

• SDK Version: Latest (July 29, 2025)
• Python Version: 3.8+
• OS: Any

---

Labels: documentation, enhancement

[seratch]

Thanks for taking the time to share this feedback. As you can see on the page, this reference page is linked there, and this reference page has all the things you mentioned here. We'd like to use this auto-generated page over hand-written one. If you see the necessity to have more information in the reference page and you're willing to contribute to it, enriching the docstring of the source code would be welcome. With that, the reference page will be updated.