OpenAI Agents SDK Handoffs vs Agents as Tools Explained

Consider a typical first version of an ERP helpdesk agent: a triage agent and two specialists, sales and finance, wired together with handoffs. It routes well. Then an input guardrail is added to the finance agent so it refuses to discuss any account other than the one the customer is signed in with, someone asks about another customer's invoice, and the finance agent answers anyway. The guardrail never ran. Nothing is broken; the composition primitive was chosen without reading its guardrail rules.

The OpenAI Agents SDK gives you two ways to make agents work together. A handoff moves ownership of the conversation to another agent. Agent.as_tool() turns an agent into a callable tool, so the calling agent keeps control and decides what to do with the result. This post compares them on the things that change in production: who answers the user, what history each agent sees, where guardrails fire and how the run shows up in a trace. It uses one sales versus finance triage example throughout, the Python SDK, and the SDK's own documentation and source as the authority.

How OpenAI Agents SDK handoffs transfer control

A handoff is exposed to the model as a tool, named transfer_to_ followed by the agent name by default. When the model calls it, the runner does not return anything to the triage agent. It swaps the current agent, keeps the input, and re-runs the loop, so the specialist becomes the active agent for the rest of the turn and writes the final answer itself. You can pass an Agent straight into handoffs, or wrap it in handoff() to add an on_handoff callback, an input_type schema for model-generated metadata, an input_filter, or an is_enabled switch.

from pydantic import BaseModel
from agents import Agent, Runner, RunContextWrapper, function_tool, handoff
from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX

@function_tool
async def get_invoice(invoice_no: str) -> str:
    """Return status, due date and open amount for one invoice."""
    return await erp.invoices.summary(invoice_no)

@function_tool
async def get_price_list(customer_code: str) -> str:
    """Return the price list and discount tier assigned to a customer."""
    return await erp.pricing.for_customer(customer_code)

class RouteReason(BaseModel):
    reason: str          # model-generated metadata, e.g. "payment_not_matched"
    customer_code: str

async def log_route(ctx: RunContextWrapper[None], data: RouteReason) -> None:
    # Runs BEFORE the specialist takes over. Raise here to stop the transfer;
    # returning normally lets it continue.
    await audit.write("helpdesk.route", reason=data.reason, customer=data.customer_code)

sales_agent = Agent(
    name="Sales agent",
    instructions=f"{RECOMMENDED_PROMPT_PREFIX}\nYou answer price lists, quotations and discounts.",
    tools=[get_price_list],
)
finance_agent = Agent(
    name="Finance agent",
    instructions=f"{RECOMMENDED_PROMPT_PREFIX}\nYou answer invoice status, due dates and payments.",
    tools=[get_invoice],
)

triage_agent = Agent(
    name="Helpdesk triage",
    instructions=f"{RECOMMENDED_PROMPT_PREFIX}\nRoute pricing to sales, invoices and payments to finance.",
    handoffs=[
        sales_agent,                                   # exposed as transfer_to_sales_agent
        handoff(finance_agent, on_handoff=log_route, input_type=RouteReason),
    ],
)

result = await Runner.run(triage_agent, "INV-2026-0912 still shows unpaid, we transferred last week")
print(result.last_agent.name)   # "Finance agent" - it now owns the conversation

Two details matter here. First, result.last_agent is the agent that should usually handle the next user turn, so a chat loop that passes it back into Runner.run keeps the customer talking to finance instead of re-triaging every message. Second, input_type is metadata about the transfer, such as a reason or a priority, and not a way to pick a destination: handoff() always transfers to the agent you wrapped, so you register one handoff per specialist and let the model choose. The receiving agent still sees the conversation history unless you change it.

What agent.as_tool() does instead

Agent.as_tool() returns a FunctionTool. When the orchestrator calls it, the SDK starts a fresh Runner.run with the specialist as the starting agent, feeds it the tool arguments, and hands the final output back to the orchestrator as the tool result. The orchestrator then carries on: it can call another specialist, combine both answers, or ask a follow-up. The SDK docstring states the two differences plainly. In a handoff the new agent receives the conversation history and takes over; as a tool, the new agent receives generated input and the original agent continues.

helpdesk_manager = Agent(
    name="Helpdesk manager",
    instructions=(
        "You own the reply to the customer. Ask the specialists for facts, "
        "then answer in one message. Never forward a specialist's text verbatim."
    ),
    tools=[
        sales_agent.as_tool(
            tool_name="ask_sales",
            tool_description="Prices, quotations and discount rules for one customer.",
        ),
        finance_agent.as_tool(
            tool_name="ask_finance",
            tool_description="Invoice status, due dates and open balance for one customer.",
            max_turns=4,                  # the nested run gets its own budget (default is 10)
            failure_error_function=None,  # raise, instead of handing the model an error string
        ),
    ],
)

# The specialist does NOT see this message. It sees whatever the manager
# writes into the tool call, by default {"input": "..."}.
result = await Runner.run(
    helpdesk_manager,
    "Can CUST-0418 get the Q4 distributor discount, and is INV-2026-0912 still open?",
)
print(result.last_agent.name)   # "Helpdesk manager" - control never moved

Because it is a separate run, the nested agent has its own settings. It gets its own max_turns, which falls back to the SDK default of 10 when you do not set one, its own run_config and hooks, and it does not inherit the parent's history unless you pass a session, conversation_id or previous_response_id explicitly. Failure handling also differs from a handoff: by default a failure inside the nested run is turned into an error message for the orchestrator's model through failure_error_function, and passing None makes it raise instead. For a finance lookup I would rather see an exception than a model improvising around one.

Handoffs vs agents as tools: side-by-side

The SDK's multi-agent guide frames the choice in one line each. Agents as tools suit a manager that should own the final answer, combine specialists or enforce shared guardrails. Handoffs suit a triage step whose chosen specialist should respond directly with focused instructions. The table below adds the mechanical consequences.

The guardrail rows deserve their own section, because they are where the two patterns stop being interchangeable. The trace row is worth a sentence too: with handoffs a trace reads as a relay, one agent after another, while with agents as tools it reads as one agent making calls, which is easier to scan when a manager consults three specialists in a single turn.

Guardrails behave differently with handoffs

The guardrails page states both rules in one place. Input guardrails run only for the first agent in the chain, because they are meant to check user input. Output guardrails run only for the agent that produces the final output. In a handoff chain the first agent is the triage agent and the last is whichever specialist answered, so a guardrail attached to the wrong agent is valid code that never executes. That was my bug.

from agents import (
    Agent, GuardrailFunctionOutput, InputGuardrailTripwireTriggered,
    RunContextWrapper, Runner, input_guardrail,
)

@input_guardrail
async def one_customer_only(ctx: RunContextWrapper[None], agent: Agent, input) -> GuardrailFunctionOutput:
    codes = extract_customer_codes(input)          # regex over CUST-xxxx
    allowed = ctx.context.session_customer_code    # who is actually logged in
    leaked = [c for c in codes if c != allowed]
    return GuardrailFunctionOutput(output_info=leaked, tripwire_triggered=bool(leaked))

# Wrong: the guardrail sits on a specialist that is only reached by a handoff.
finance_agent = Agent(name="Finance agent", tools=[get_invoice],
                      input_guardrails=[one_customer_only])
triage_agent = Agent(name="Helpdesk triage", handoffs=[sales_agent, finance_agent])
await Runner.run(triage_agent, text)   # one_customer_only never runs

# Right for handoffs: guard the entry point, and put the output check on
# EVERY agent that can end the turn - any specialist may be the last one.
triage_agent = Agent(name="Helpdesk triage", handoffs=[sales_agent, finance_agent],
                     input_guardrails=[one_customer_only])
finance_agent.output_guardrails = [no_internal_margin]
sales_agent.output_guardrails = [no_internal_margin]

try:
    result = await Runner.run(triage_agent, text, context=ctx)
except InputGuardrailTripwireTriggered:
    reply = "I can only discuss the account you are signed in with."

With agents as tools the coverage looks different. The manager is both the first and the last agent of the outer run, so its input guardrail sees every user message and its output guardrail sees every reply, whichever specialists it consulted. Each specialist also starts its own nested run, so its own guardrails fire against the input the manager generated for it. That is a different string from what the user typed, which matters for a check like one_customer_only: the manager may have paraphrased the customer code away. Put user-facing checks on the manager and data checks on the function tools.

Controlling what the specialist sees

A handoff forwards the whole conversation by default, which is convenient and is also how a sales agent ends up reading finance tool output it has no business with. The SDK gives you four levers, and they interact.

• input_filter on a handoff, or handoff_input_filter on RunConfig as a global default, receives a HandoffInputData with input_history, pre_handoff_items, new_items and run_context, and returns the version the next agent should see.
• handoff_filters.remove_all_tools is the ready-made filter. It strips structured tool items, but not tool arguments or results already copied into ordinary messages.
• nest_handoff_history is an opt-in beta, off by default, that compacts earlier history into assistant summary segments marked CONVERSATION HISTORY. It only applies when no input filter is set, and handoff_history_mapper lets you supply the exact item list instead.
• Server-managed history through conversation_id or previous_response_id does not support handoff input filters at all, so a specialist that must not inherit it needs a separate run with explicitly selected input.

from agents import RunConfig, handoff
from agents.extensions import handoff_filters

# Handoff: drop structured tool items the triage agent produced. This does NOT
# redact tool text that was already copied into ordinary messages.
faq_handoff = handoff(faq_agent, input_filter=handoff_filters.remove_all_tools)

# Opt-in beta: summarise earlier history into <CONVERSATION HISTORY> segments.
# Ignored when an input_filter is set on the handoff or on the RunConfig.
config = RunConfig(nest_handoff_history=True)

# Agent as tool: the specialist only ever sees the arguments, so make them typed.
class InvoiceQuery(BaseModel):
    invoice_no: str
    customer_code: str

ask_finance = finance_agent.as_tool(
    tool_name="ask_finance",
    tool_description="Look up one invoice for one customer.",
    parameters=InvoiceQuery,
    include_input_schema=True,
)

Agents as tools sidestep most of this, because the specialist sees only what the orchestrator writes into the call. The cost is that the orchestrator's model decides what to write. Giving the tool a typed schema with parameters and include_input_schema turns a free-text request into fields the specialist can rely on, and the nested agent can read the parsed value from RunContextWrapper.tool_input.

Approvals, authorisation and dynamic routing

The two patterns put the authorisation hook in different places. For a handoff, is_enabled is evaluated while the SDK prepares the available handoffs, before the model has produced any arguments, so it can hide the finance route for a user without finance access but it cannot inspect the customer code in the request. The docs say to perform that check at the start of on_handoff and to raise rather than return, because the transfer continues once on_handoff returns successfully.

An agent tool takes needs_approval, a boolean or a callable policy. When it triggers, the run pauses and the pending call appears in result.interruptions, and you resume it with the run state's approve or reject. That is a better fit for an ERP action with consequences, such as a specialist that drafts a credit note, because a human can see the exact arguments before the nested run starts. Both patterns accept is_enabled, so you can show a specialist only to the roles that should reach it.

How I choose between the two

After rebuilding the helpdesk both ways, I settled on a short decision procedure. It assumes you already decided the task needs more than one agent, which is not a given: one agent with good tools is often enough.

1. If one request may need two specialists, such as a discount question and an invoice question in one message, use agents as tools. A handoff can only go to one place.
2. If the specialist should hold the conversation over several turns with its own focused instructions, such as a long payment reconciliation, use a handoff and pass result.last_agent back on the next turn.
3. If a single output policy must cover every reply, such as never quoting internal margin, put it on a manager that calls agents as tools, or duplicate it on every possible handoff target.
4. If an action needs human approval with visible arguments, expose it as an agent tool with needs_approval rather than as a handoff.
5. Whichever you pick, put data-access checks on the function tools, where they run regardless of which agent is active.

The two are not exclusive. The version I kept is a manager that calls sales and finance as tools for ordinary questions, plus one handoff to a human-escalation agent that takes over the conversation when a dispute needs a person. Routing that is part of the workflow is a handoff; borrowing expertise for a sub-question is a tool call.

Choose the primitive by who should own the reply. If the specialist should speak to the user and keep the conversation, hand off, then guard the first agent and every agent that can end the turn. If the specialist only supplies facts, call it as a tool and let one manager own the answer and its guardrails. Either way, put the checks that must never be skipped on the function tools.