handoff() returned Handoff objects aren’t recognized by Agent(handoffs=…) without manual .name alias

[davidlapsleyio]

Description:

When using the OpenAI Agents SDK’s handoff() helper with input_type (and even without), the returned Handoff instance populates its internal tool_name property but does not set a .name attribute. The Agent constructor then either:

• Raises AttributeError: 'Handoff' object has no attribute 'name' when you pass it in handoffs=[…], or
• Throws UserError("Unknown tool type: <class 'agents.handoffs.Handoff'>, tool") if you pass it in tools=[…].

The workaround today is to manually do:

hf = handoff(…)
hf.name = hf.tool_name

for every handoff, which is boilerplate and error-prone.

Steps to Reproduce:

1. Install latest openai-agents SDK.
2. Define a simple Agent and a Handoff without aliasing .name:

from agents import Agent, handoff

def on_handoff(ctx):
    return "OK"

my_agent = Agent(name="MyAgent", model="gpt-4", instructions="…")
hf = handoff(agent=my_agent, on_handoff=on_handoff, tool_name_override="custom_tool")

# Option A: Passing under `handoffs` → AttributeError
triage = Agent(
    name="Triage",
    model="gpt-4",
    handoffs=[hf]
)
# Error: AttributeError: 'Handoff' object has no attribute 'name'

# Option B: Passing under `tools` → UserError
triage = Agent(
    name="Triage",
    model="gpt-4",
    tools=[hf]
)
# Error: UserError("Unknown tool type: <class 'agents.handoffs.Handoff'>, tool")

3. Confirm you must manually assign hf.name = hf.tool_name to proceed.

Expected Behavior:

• handoff() should accept an optional name= parameter, or
• SDK should automatically set handoff.name = handoff.tool_name internally,
  so that consumers never need to patch each handoff manually.

Actual Behavior:

• The returned Handoff object lacks a .name attribute.
• Passing it into Agent(handoffs=[…]) or Agent(tools=[…]) fails with confusing errors.

Proposed Fixes:

1. In agents.handoffs.handoff(), after building the Handoff instance, add: hf.name = hf.tool_name
2. Alternatively, accept a name: kwarg and apply it to both tool_name and name.

Environment:

• openai-agents SDK version: 0.0.11
• Python version: 3.13.3
• OS: macOS 15.2

Thank you for looking into this!

[davidlapsleyio]

Not able to reproduce. Closing.