Orchestrate OpenAI Agents with Handoffs and Managers

OpenAI handoffs transfer conversation ownership to a specialist, while agents-as-tools let a manager retain ownership and call specialists for bounded work. Use handoffs when the specialist should control the next response; use manager orchestration when one agent must synthesize. Add specialists only when contracts, tools, context, or policy materially differ.

What will you be able to do?

You will implement a billing/technical router, choose the ownership pattern, and measure whether specialization improves outcomes.

How do you create a handoff?

handoff_demo.py:

python

import asyncio

from agents import Agent, Runner


billing = Agent(
    name="Billing specialist",
    handoff_description="Handles charges, invoices, subscriptions, and refunds.",
    instructions="Explain billing policy. Never claim a refund was executed.",
)

technical = Agent(
    name="Technical specialist",
    handoff_description="Handles errors, access problems, and troubleshooting.",
    instructions="Give safe diagnostic steps and ask for missing evidence.",
)

triage = Agent(
    name="Support triage",
    instructions="Hand off to the specialist whose contract matches the request.",
    handoffs=[billing, technical],
)


async def main() -> None:
    result = await Runner.run(triage, "Why was my card charged twice?")
    print(result.last_agent.name)
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

After a handoff, last_agent identifies the specialist that completed the run. If that specialist should remain in control next turn, preserve it with the chosen continuation strategy.

When should an agent be a tool?

Use specialist.as_tool(...) when a manager needs a classification, translation, or summary but must integrate it into one final outcome. The manager sees specialist output as a tool result and retains responsibility.

Do not use a handoff merely to get a helper result. Do not use a manager when the specialist needs its own user dialogue and approval boundary.

How do you evaluate routing?

Build a labeled set containing clear billing, clear technical, ambiguous, mixed, and out-of-scope requests. Measure correct route, unnecessary handoff, failed handoff, time/cost, and policy exposure. Inspect confusion pairs rather than optimizing aggregate accuracy alone.

Failure injection: Give overlapping handoff descriptions. If routing oscillates or misroutes, narrow the contracts and add deterministic pre-routing for exact cases before adding prompt complexity.

What changes in production?

Limit handoff depth, record ownership changes, control what history crosses boundaries, attach different tool/policy sets per specialist, and ensure approval state survives nested calls. A specialist is a security boundary only if the harness enforces its tool and context isolation.

What mistakes should you avoid?

Using vague specialist names/descriptions.
Giving every specialist the manager’s full history and tools.
Creating circular handoffs.
Ignoring latency added by routing calls.
Adding agents before a single-agent baseline exists.

Check your understanding

Who owns the final response after a handoff?
When is an agent-as-tool more appropriate?
Which metrics show whether specialization helped?

Expert extension

Add a mixed-intent policy: either split into two bounded specialist calls under a manager or ask the user to prioritize. Compare the two approaches using traces and evaluation results.

Official references