Skip to main content

OpenAI Agents SDK Handoffs

Handoffs are the SDK’s built‑in mechanism for transferring execution responsibility from one agent to another. They enable multi‑agent collaboration while keeping the conversation state intact—the receiving agent continues the dialogue as if it had been there from the start. This article is your implementation‑focused guide: you’ll learn how to define handoffs, how the runner manages the transfer, how context is preserved, and how to design robust, production‑grade agent routing workflows.

What Are Handoffs in the OpenAI Agents SDK​

A handoff is a special type of model action where the current agent delegates the remainder of the conversation to another agent. Unlike a tool call that fetches data and returns control to the calling agent, a handoff permanently transfers the dialogue to the target agent. The original agent’s turn ends, and the new agent’s instructions, personality, and capabilities take over.

Key characteristics:

  • Responsibility transfer – The receiving agent now owns the conversation and will produce the final response (or hand off yet again).
  • Context transfer – The full message history—user messages, assistant replies, tool results—is passed along so the new agent sees everything.
  • Execution continuation – The runner seamlessly switches to the new agent and continues the reasoning loop without any developer intervention.

A minimal example:

from agents import Agent, Runner

billing = Agent(
    name="Billing Agent",
    instructions="You handle billing inquiries. Be polite and helpful.",
    model="gpt-4o",
)

support = Agent(
    name="Support Agent",
    instructions="You handle general support. If the user asks about billing, hand off to Billing Agent.",
    model="gpt-4o",
    handoffs=[billing],
)

result = await Runner.run(support, "I have a question about my invoice.")
print(result.final_output)  # the billing agent's response

Under the hood, the Support Agent’s model emitted a handoff call targeting Billing Agent. The runner paused the support agent, loaded the billing agent, and resumed the conversation. The user never knows about the switch—unless you design the instructions to announce it.

Why Handoffs Matter​

  • Agent specialisation – Each agent can be an expert in a narrow domain (billing, tech support, sales), leading to more accurate and concise answers.
  • Responsibility separation – Rules, tools, and guardrails can be tailored per agent, simplifying maintenance.
  • Cleaner workflows – Triage → Specialist pattern makes complex customer journeys easy to follow and debug.
  • Better maintainability – You can update or replace a specialist agent without touching the router.
  • Improved output quality – Specialised agents with focused instructions outperform generalists on domain‑specific tasks.

Handoffs transform a monolithic agent into a team of cooperating specialists.

How Handoffs Work​

The execution flow when a handoff occurs is:

User Request → Agent A (triage) → Handoff Decision → Agent B (specialist) → Task Completion → Final Output

The runner handles the entire process:

  1. The user sends a message.
  2. The runner invokes Agent A with its handoff list.
  3. If the model decides to hand off, it emits a handoff call (which looks like a tool call internally, but the runner treats it specially).
  4. The runner saves the current conversation, switches to Agent B, and feeds the full history—including the handoff event—to Agent B.
  5. Agent B’s system instructions are prepended (or merged). Agent B then continues exactly where Agent A left off, possibly using its own tools.
  6. Agent B produces the final answer, which is returned to the user.

If Agent B has its own handoffs, the chain can continue.

Core Handoff Concepts​

ConceptRole
Source AgentThe agent that initiates the handoff.
Target AgentThe agent that receives the conversation and takes over.
Context TransferThe mechanism that passes the complete message history, including tools results and metadata, to the target agent.
Handoff TriggerThe condition under which the source agent decides to hand off. Defined by the model’s reasoning based on instructions.
Execution ContinuationThe runner seamlessly resumes the reasoning loop with the target agent.

Handoff Lifecycle​

Every handoff follows a structured lifecycle:

  1. Request received – User input arrives; the runner selects the source agent.
  2. Agent reasoning – The source agent evaluates the input with its instructions.
  3. Handoff decision – The model determines that a different agent is better suited, generates a handoff call with the target agent’s name.
  4. Context packaging – The runner captures the entire message list and any run metadata.
  5. Target agent activation – The target agent’s system instructions are inserted, and the conversation history (including the handoff call and a synthetic handoff message) is passed to the target.
  6. Execution continuation – The target agent begins reasoning, may call tools, and eventually produces a final response.
  7. Final response – The output is returned to the user.

Context Transfer During Handoffs​

When a handoff occurs, the following information is automatically transferred to the target agent:

  • Full conversation history – all user messages, previous assistant messages, and tool results.
  • Session metadata – session ID, user identifiers (if any), and any custom RunContext data.
  • Tool call history – the target agent knows what tools have already been called and what data has been retrieved.
  • Run configuration – max_turns, temperature, etc., are preserved unless overridden.

Best practices for context transfer:

  • Keep instructions modular – don’t rely on the source agent’s system prompt; the target agent only sees its own instructions prepended to the conversation.
  • Be explicit about handoff expectations – instruct the source agent when to hand off (e.g., “If the user mentions billing, hand off to Billing Agent”).
  • Include necessary summary – if the source agent gathered important data, it should include that data in its handoff message (the model can emit a final response that includes a summary before handing off, though it’s not required; the full history is already available).

Types of Handoffs​

Direct Handoff​

One agent unconditionally transfers to another (often after completing a preliminary step).

triage = Agent(
    name="Triage",
    instructions="Always hand off to Sales Agent after greeting.",
    handoffs=[sales]
)

Conditional Handoff​

Handoff occurs only when a specific condition is met, determined by the model based on instructions.

support = Agent(
    name="Support",
    instructions="If the user has a billing question, hand off to Billing; otherwise, help them.",
    handoffs=[billing]
)

Specialised Handoff​

A general agent routes to a domain expert based on intent (e.g., a “Front Desk” agent that hands off to HR, IT, or Finance).

front_desk = Agent(
    name="Front Desk",
    instructions="Route user to the right department: HR for leave, IT for laptop issues, Finance for payroll.",
    handoffs=[hr_agent, it_agent, finance_agent]
)

Escalation Handoff​

A front‑line agent transfers to a senior agent when confidence is low or the issue is complex.

junior = Agent(
    name="Junior Support",
    instructions="Help with basic issues. If you are unsure, hand off to Senior Support.",
    handoffs=[senior]
)

Each type uses the same handoff mechanism; the difference is in the instructions that guide the model’s decision.

Handoff Decision Strategies​

How does the model choose the right target? It relies on the agent’s instructions and the natural language description of the target agents. The SDK does not enforce a specific routing algorithm; the model’s understanding of language does the routing.

StrategyHow it works
Intent‑Based RoutingThe model analyzes the user’s message and matches it to the target agent’s name or implied domain.
Domain‑Based RoutingThe source agent’s instructions explicitly map topics to agents (e.g., “If billing → Billing Agent”).
Confidence‑Based RoutingThe agent can be instructed to hand off only if it lacks the information or confidence to answer.
Rule‑Based RoutingYou can combine handoffs with guardrails or input checks that programmatically force a handoff (advanced).

In practice, clear instructions like “If the user asks about orders, hand off to Order Agent” produce reliable routing. The better the target agent’s name reflects its role, the more accurate the handoff.

Handoffs vs Tool Calling​

FeatureHandoffTool Calling
TargetAnother agentExternal function / API
PurposeTransfer conversational responsibilityExtend the current agent’s capabilities
ExecutionThe new agent continues the conversationThe calling agent remains in charge
StateFull conversation history is handed overOnly tool result is injected
ResultThe final answer comes from the target agentThe answer comes from the original agent, enriched by the tool output

Use handoffs when you want a different personality, a different set of tools, or a different policy to handle the request. Use tool calling when the current agent just needs to look something up or perform an action before continuing.

Handoffs and Workflow Design​

Common workflow patterns that leverage handoffs:

  • Triage‑to‑Specialist – A front‑line agent classifies the request and hands off to the appropriate domain expert.
  • Delegation – A supervisor agent breaks down a task and hands off sub‑tasks to worker agents (though the SDK currently works best with sequential handoffs; for true delegation, you may chain multiple runs).
  • Escalation – A junior agent handles simple queries; complex or sensitive ones are handed off to a senior agent.
  • Specialist execution flows – A content generation pipeline: Outliner → Writer → Editor, each handing off to the next.

These patterns keep each agent focused and testable.

Error Handling in Handoffs​

Handoffs can fail. Robust workflows account for this.

  • Failed handoffs – If the target agent’s name is misspelled in the handoff request, the runner will raise an error. Use clear, unique names and test the handoff path.
  • Invalid targets – If the source agent requests a handoff to an agent that isn’t in its handoffs list, the runner rejects it. Always list all possible targets.
  • Context corruption – Unlikely with the SDK, but if you modify the session manually between handoffs, ensure the message list is consistent.
  • Retry strategies – If a handoff fails because of a temporary model error, you can re‑run the conversation with the same session ID; the runner will replay from the last successful point.
  • Fallback agents – Design a “fallback” agent that the triage agent hands off to when no other specialist fits. This prevents dead ends.

Example of a fallback agent:

fallback = Agent(name="Fallback", instructions="Say you can’t help and provide contact info.")
triage = Agent(..., handoffs=[billing, tech, fallback])

Security Considerations​

  • Context leakage prevention – Handoffs pass the full conversation history. Ensure that sensitive data collected by one agent is necessary for the target. Use guardrails to scrub or mask PII before handoffs if required.
  • Agent permissions – Different agents may have different tool access. Never include a sensitive tool in a general agent that might hand off to an untrusted context.
  • Sensitive data transfer – Be aware that the entire message list, including tool results, is visible to the receiving agent.
  • Validation mechanisms – Use output guardrails on the source agent to validate that a handoff is appropriate before it occurs.

Performance Considerations​

  • Handoff overhead – Each handoff introduces a small latency: the model must generate the handoff call, the runner switches context, and the target’s system prompt is sent. Keep chains short.
  • Context size optimization – Long conversations with many tool results can exceed the model’s context window after several handoffs. Trim or summarise history if needed.
  • Routing efficiency – Very large handoff lists (10+ agents) can confuse the model. Group agents by category and use a two‑step routing: first triage to a category agent, then to a specific specialist.
  • Latency reduction – Use a faster model for triage (e.g., gpt-4o-mini) and the full model only for specialist work.

Common Beginner Mistakes​

  1. Excessive handoffs – Creating a handoff for every micro‑step increases latency and complexity. Combine steps where possible.
  2. Poor specialisation boundaries – Overlapping agent roles cause the model to make ambiguous handoff decisions.
  3. Large context transfers – Not managing conversation length leads to token‑limit errors after multiple handoffs.
  4. Circular handoff chains – Agent A hands off to B, B hands off back to A. Always design a terminating condition.
  5. Missing fallback logic – If no specialist matches, the user gets no answer.
  6. Forgetting to list handoff agents – An agent can only hand off to agents in its handoffs list. Forgetting to add one leads to a runtime error.

Best Practices​

  • Use handoffs only when needed – Not every task requires multiple agents.
  • Keep agent responsibilities focused – Each agent should have a clear, non‑overlapping domain.
  • Minimize transferred context – If the source agent gathered a large volume of data, summarise it before handing off (via a tool or final message) to keep the context lean.
  • Validate target agents – Use meaningful names and test that the model maps intents correctly.
  • Monitor handoff frequency – Unexpected spikes may indicate misrouting or a prompt that is too eager to hand off.
  • Avoid routing loops – Design a directed acyclic graph of handoffs. Use a fallback agent as a terminal node.

Practical Example: Customer Support Agent Workflow​

We’ll build a triage system with three specialists: Front Desk (router), Billing Agent, and Technical Support Agent.

1. Define the agents​

from agents import Agent

billing = Agent(
    name="Billing Agent",
    instructions="You handle all billing and invoice inquiries. Be precise and polite.",
    model="gpt-4o",
    # maybe a tool to look up invoices
)

tech_support = Agent(
    name="Tech Support Agent",
    instructions="You help with product troubleshooting and technical issues. Provide step-by-step guidance.",
    model="gpt-4o",
)

front_desk = Agent(
    name="Front Desk Agent",
    instructions=(
        "You are the first point of contact. "
        "If the user asks about billing or invoices, hand off to Billing Agent. "
        "If the user has a technical problem, hand off to Tech Support Agent. "
        "Otherwise, handle the request yourself if possible, or politely say you can't help."
    ),
    model="gpt-4o-mini",
    handoffs=[billing, tech_support],
)

2. Run the workflow​

from agents import Runner
import asyncio

async def main():
    queries = [
        "I need a copy of my last invoice.",
        "My laptop won't turn on, what should I do?",
        "Hello, what are your opening hours?"
    ]
    for q in queries:
        result = await Runner.run(front_desk, q)
        print(f"Q: {q}\nA: {result.final_output}\n---")

asyncio.run(main())

Execution flow for the first query (“invoice”):

  1. The runner calls front_desk with the message.
  2. The Front Desk model reads its instructions, recognises a billing topic, and emits a handoff call to Billing Agent.
  3. The runner switches to billing, feeding the full conversation.
  4. The Billing Agent answers: “Sure, I can help with that. Could you provide your account ID?” (or if it has a tool, it might look up the invoice directly).
  5. The final output is returned.

Flow for the second query (“technical”): similar handoff to tech_support.

Flow for the third query (“opening hours”): the Front Desk Agent decides it can answer without handoff, and replies directly.

This triage pattern is the backbone of many production support systems. It keeps each agent’s instructions simple and lets the runner manage the routing transparently.

Handoffs and Other SDK Concepts​

Handoffs integrate deeply with the other SDK components:

  • Core Concepts – Agents, Runner, and Sessions form the foundation. Handoffs are a built‑in agent action.
  • Tool Calling – A source agent can first call tools (e.g., a classifier) and then decide to hand off based on the result.
  • Guardrails – Input guardrails on the source agent can prevent handoffs based on content safety. Output guardrails on the target agent validate its final answer.
  • Observability – Tracing captures every handoff event, including the source, target, and context, providing full audit trails.

For cross‑framework delegation patterns, see LangGraph Human‑in‑the‑Loop and CrewAI Delegation. For a high‑level comparison, visit the framework comparison. To standardize tool integration, check the MCP Guide.

FAQ​

1. What is a Handoff in the OpenAI Agents SDK?​

A handoff is an agent action that transfers the conversation from one agent to another. The new agent takes over with the full conversation history.

2. How do Handoffs work?​

The source agent’s model emits a handoff call naming the target. The Runner pauses the source agent, loads the target, and passes the conversation. The target continues where the source left off.

3. What gets transferred during a handoff?​

The complete message history—user messages, assistant responses, tool outputs—plus session metadata and run configuration.

4. How are target agents selected?​

The model chooses based on the source agent’s instructions, the user’s intent, and the target agents’ names/descriptions. There’s no hard‑coded routing; it’s all natural language.

5. What is the difference between Handoffs and Tool Calling?​

Tool calling fetches data or performs an action for the same agent. Handoffs transfer the entire conversation to a different agent, which then owns the response.

6. Can multiple handoffs occur in one conversation?​

Yes. An agent can hand off to another, which can hand off to yet another, forming a chain. The runner supports this seamlessly.

7. Are Handoffs production‑ready?​

Absolutely. They are core to the SDK’s design and used in production systems. Ensure proper error handling and naming conventions.

8. How do I prevent infinite handoff loops?​

Design a directed acyclic graph: agents should not hand off back to a previous agent unless there’s a clear termination condition (e.g., a maximum number of handoffs tracked via session state).

9. Can I pass additional data during a handoff?​

The entire conversation history is available. If you need to pass structured data, have the source agent include it in a final message (e.g., a summary) before handing off.

10. How do I test a handoff workflow?​

Use the SDK’s tracing to observe handoff decisions. Write tests that simulate user queries and assert that the final output came from the correct agent (by checking the agent name in the result).

11. What happens if the target agent is not in the handoffs list?​

The Runner will raise a ModelBehaviorError. Always list all target agents in the source agent’s handoffs parameter.

12. Can I use handoffs with streaming?​

Yes. Streaming continues across handoffs; the final streamed tokens come from the last agent in the chain.

13. How do guardrails interact with handoffs?​

Input guardrails run before the source agent processes the message; output guardrails run on the final answer produced by the last agent in the handoff chain.

14. Is there a limit to the number of handoffs?​

No hard limit, but each handoff adds context size. Excessive chaining can hit the model’s context limit. Keep chains reasonable (2–4 deep).

15. How do I force a handoff programmatically?​

You can’t directly force a handoff from Python; the model decides. But you can design the source agent’s instructions to always hand off for certain inputs. Alternatively, you can inspect the user input yourself and call the specialist agent directly via the Runner, bypassing the triage.

Conclusion​

The OpenAI Agents SDK’s handoff mechanism provides a clean, scalable way to build multi‑agent systems. By letting agents transfer responsibility, you can create modular, specialist teams that are easier to develop, test, and maintain. The Runner ensures that context flows seamlessly, and tracing gives you full visibility into every transfer.

Key takeaways:

  • Handoffs transfer conversation ownership from one agent to another.
  • The full message history is carried over, so the new agent is fully informed.
  • Use handoffs for specialisation, escalation, and routing.
  • Clear instructions and naming conventions are the key to reliable routing.
  • Combine handoffs with guardrails and tracing for production safety.

Now, deepen your skills with these related guides:

For cross‑framework delegation patterns, explore the LangGraph Human‑in‑the‑Loop guide and the CrewAI Tools & Delegation article. For the complete picture, see the framework comparison. And to integrate standardised tools, visit the MCP Guide.

Now, design your agent teams—and let them pass the baton with confidence.