The Problem With One Agent Doing Everything

An agent with instructions covering billing questions, technical troubleshooting, and account changes all at once tends to produce worse results at each individual task than three separate agents, each with narrow, focused instructions covering exactly one area — the same reasoning behind why Unit 8, Lesson 4 grouped related custom functions together (ORDER_TOOLS, POLICY_TOOLS) rather than dumping every available function into one undifferentiated list. A handoff is the Agents SDK's mechanism for a triage agent to recognize which specialized area a request actually belongs to and transfer the conversation to the agent built specifically for that area, rather than trying to be good at everything within a single set of instructions.

Defining Specialist Agents

from agents import Agent, Runner

billing_agent = Agent(
    name="Billing Agent",
    instructions="You help customers with billing questions, charges, and refunds.",
    model="gpt-5.6-terra",
)

technical_agent = Agent(
    name="Technical Agent",
    instructions="You help customers troubleshoot technical issues with the product.",
    model="gpt-5.6-terra",
)

Each specialist agent here is defined exactly as Lesson 2 introduced — a name, a set of instructions, a model — with instructions scoped narrowly to one specific area rather than covering everything the overall system needs to handle.

Defining a Triage Agent With Handoffs

A triage agent is given a list of handoffs — the other agents it's allowed to transfer a conversation to — alongside its own instructions describing how to decide between them.

triage_agent = Agent(
    name="Triage Agent",
    instructions=(
        "Determine whether the customer's question is about billing or a "
        "technical issue, and hand off to the appropriate specialist agent. "
        "Do not attempt to answer billing or technical questions yourself."
    ),
    model="gpt-5.6-terra",
    handoffs=[billing_agent, technical_agent],
)

result = Runner.run_sync(triage_agent, "I was charged twice for my last order.")
print(result.final_output)
print(f"Handled by: {result.last_agent.name}")

Note: The exact parameter name (handoffs here) and the mechanics of how a handoff is triggered and executed can vary by SDK version. Confirm the current interface against the current official documentation.

The triage agent's own instructions explicitly tell it not to answer the underlying question itself, only to route it — this is deliberate: a triage agent that both tries to route and tries to answer tends to do a worse job of each than one that's scoped purely to classification and handoff, mirroring Lesson 3's guidance that narrow, focused instructions generally outperform broad, do-everything ones. result.last_agent.name reports which specialist actually produced the final answer, confirming the handoff to billing_agent occurred as expected.

How a Handoff Actually Works

When the triage agent decides a handoff is appropriate, control of the conversation transfers to the target agent, which then continues the interaction — including using its own tools and its own instructions — as though it had been the one handling the request from that point forward. This is conceptually similar to Unit 8, Lesson 4's dispatch pattern (dispatch_function_call() routing a function call to the right handler), except a handoff transfers the entire ongoing conversation to a different agent with its own distinct instructions and tools, rather than routing a single function call to a specific handler function within one agent's scope.

from agents import function_tool

@function_tool
def issue_refund(order_id: str, amount: float) -> str:
    """Issue a refund for a specific order.

    Args:
        order_id: The order identifier to refund.
        amount: The refund amount in US dollars.
    """
    return f"Refunded ${amount:.2f} for order {order_id}."

billing_agent_with_tools = Agent(
    name="Billing Agent",
    instructions="You help customers with billing questions, charges, and refunds.",
    model="gpt-5.6-terra",
    tools=[issue_refund],
)

triage_agent = Agent(
    name="Triage Agent",
    instructions="Route billing questions to the Billing Agent, technical questions to the Technical Agent.",
    model="gpt-5.6-terra",
    handoffs=[billing_agent_with_tools, technical_agent],
)

Once a handoff to billing_agent_with_tools occurs, that agent's own tools=[issue_refund] become available for the rest of the interaction, even though the triage agent that initially received the message had no access to issue_refund at all — each agent in a handoff chain brings its own distinct capabilities, rather than sharing one combined pool of tools across every agent in the system.

Why Scoping Tools to Specific Agents Matters

Giving the triage agent access to every tool every specialist might need would defeat much of the purpose of triage in the first place — it would need instructions broad enough to know when to use each one, reintroducing the "one agent doing everything" problem this lesson opened with. Scoping tools narrowly to the specific agent that needs them follows the same least-privilege reasoning Unit 8, Lesson 5 established for custom function access generally: the billing agent can issue a refund; the triage agent, whose entire job is classification and routing, has no ability to do so at all, which is also a meaningful safety property — a routing mistake in triage can misdirect a conversation, but it can't accidentally trigger a consequential action a narrowly-scoped triage agent was never given the tools to perform.

Handoffs Can Chain

A handoff isn't limited to a single triage-to-specialist transfer; a specialist agent can itself have handoffs to further, more specific agents, when a domain benefits from more than one level of routing.

refund_specialist = Agent(
    name="Refund Specialist",
    instructions="You handle refund requests specifically, applying the full refund policy.",
    model="gpt-5.6-terra",
    tools=[issue_refund],
)

billing_agent = Agent(
    name="Billing Agent",
    instructions=(
        "You handle general billing questions. Hand off refund requests "
        "specifically to the Refund Specialist."
    ),
    model="gpt-5.6-terra",
    handoffs=[refund_specialist],
)

triage_agent = Agent(
    name="Triage Agent",
    instructions="Route billing questions to the Billing Agent, technical questions to the Technical Agent.",
    model="gpt-5.6-terra",
    handoffs=[billing_agent, technical_agent],
)

This produces a two-level routing structure: triage decides billing-versus-technical, and the billing agent itself decides whether a specific request needs the more specialized refund agent. Chaining handoffs like this is worth the added structure specifically when a domain has meaningfully distinct sub-areas with different instructions or tools — introducing a chain purely for its own sake, when a single specialist agent would have handled the whole domain perfectly well, adds complexity without a corresponding benefit.

Improving Routing Accuracy With Examples

A triage agent's routing decision is only as reliable as its instructions are clear about how to distinguish between the specialists it can hand off to. For a genuinely ambiguous case — a question that could plausibly be either billing or technical — a few concrete examples in the instructions, following Unit 3, Lesson 3's few-shot guidance, typically improves routing accuracy more than a purely abstract description of each category.

triage_agent = Agent(
    name="Triage Agent",
    instructions=(
        "Route the customer's message to the correct specialist agent.\n\n"
        "Examples:\n"
        "- 'I was charged twice' -> Billing Agent\n"
        "- 'The app crashes on startup' -> Technical Agent\n"
        "- 'My subscription renewed but I want a refund' -> Billing Agent\n"
        "- 'I can't log in after the last update' -> Technical Agent\n\n"
        "Do not attempt to answer the question yourself."
    ),
    model="gpt-5.6-terra",
    handoffs=[billing_agent, technical_agent],
)

This applies Unit 3's few-shot principle to a routing decision specifically: rather than trusting the triage agent to correctly infer the boundary between "billing" and "technical" from category names alone, a handful of concrete examples spanning the genuinely ambiguous cases — a refund request that's really about a subscription renewal, a login failure that's really an application bug — gives it something more concrete to generalize from than the category labels by themselves.

Common Mistakes

Giving a triage agent instructions to both route and answer questions itself, producing worse routing decisions than a triage agent scoped purely to classification and handoff.

Giving every agent in a handoff chain access to every tool any agent might need, rather than scoping tools narrowly to the specific agent responsible for using them, which undermines both clarity and the least-privilege safety property handoffs can otherwise provide.

Introducing multiple levels of handoff chaining for a domain that doesn't actually have meaningfully distinct sub-areas, adding structural complexity without a real routing benefit.

Failing to check result.last_agent after a run involving handoffs, losing track of which specialist actually produced the final answer.

Best Practices

Keep a triage agent's instructions narrowly scoped to classification and routing, explicitly telling it not to attempt to answer questions outside its routing role.

Scope each specialist agent's tools to only what that specific agent needs, following the same least-privilege reasoning Unit 8, Lesson 5 applied to custom function access.

Introduce handoff chaining only when a domain genuinely has distinct sub-areas that benefit from separate instructions or tools, rather than adding routing levels without a clear corresponding need.

Check result.last_agent when debugging or logging a multi-agent interaction, to confirm which specialist ultimately handled a given request.