Agent Handoffs
Transferring control of a conversation from one agent to another via a transfer tool call, as opposed to calling an agent as a tool; mechanics in OpenAI Agents SDK, LangGraph, ADK and Agent Framework, context passing and failure modes.
Contents
An agent handoff transfers control of an ongoing conversation from one agent to another: the receiving agent becomes the active agent, answers the user directly and keeps control on later turns until it hands off again or the run ends. The model triggers it by calling a transfer tool (transfer_to_<agent> in OpenAI’s naming, transfer_to_agent in Google ADK), and the runtime, not the tool body, performs the switch. The contrast is agent-as-tool (the subagent shape): a caller invokes a specialist, gets a result back and stays in charge. OpenAI introduced the term in its October 2024 cookbook, where a handoff was likened to a phone transfer in which the new person already knows what was said (cookbook, LangChain).
Mechanics
Every framework below implements the same three steps on top of function calling:
- Expose each permitted target as a tool, with the target’s description telling the model when to pick it.
- Intercept the call. The runtime recognises the handoff tool and does not treat its output as an ordinary tool result.
- Switch and re-prompt. The runtime sets the active agent, decides what history the new agent sees, and runs the new agent’s loop with its own instructions and tools.
flowchart LR U["User message"] --> A["Active agent: triage"] A -- "ordinary tool call" --> T["Tool result returns to the same agent"] T --> A A -- "transfer_to_billing()" --> R["Runtime: set active agent, filter history"] R --> B["Active agent: billing (own prompt and tools)"] B -- "final answer" --> U2["User"] B -. "next user turn goes to billing" .-> B
Synthesis: the diagram generalises the loops described in the OpenAI cookbook and Agents SDK docs.
OpenAI Agents SDK
- Origin. In the 2024 cookbook (and the Swarm sample library), a transfer function simply returned an
Agentobject. The loop saw that, swappedcurrent_agent, and all agents shared onemessageslist, each swapping in its own system prompt (cookbook). The Agents SDK formalised this. - Declaration.
Agent(handoffs=[...])accepts agents orhandoff()objects. Each is a tool namedtransfer_to_<agent_name>by default;handoff_descriptionon the target is appended to the tool description (handoffs docs). handoff()options.tool_name_override,tool_description_override,on_handoff(callback),input_type(a schema for arguments the model fills in at handoff time, such as a reason or priority),input_filter,is_enabled(bool or callable, checked at runtime) andnest_handoff_history.input_typeis metadata foron_handoff; it does not replace the next agent’s input or choose the destination. Becauseis_enabledruns before the model supplies arguments, argument-level checks belong at the start ofon_handoff, which can raise to block the transfer (handoffs docs).- Runner semantics. Each turn ends in a final output, a handoff (switch agent and loop again) or tool calls (running agents). If the model emits several handoff calls in one turn, only the first runs; the others get the tool output “Multiple handoffs detected, ignoring this one.” Each handoff is recorded as a
handoff_spanin traces (runtime source, tracing). - Prompting.
RECOMMENDED_PROMPT_PREFIXorprompt_with_handoff_instructionsadds standard handoff guidance to an agent’s instructions (handoffs docs).
LangGraph and LangChain
- Handoff as state update. LangChain’s v1 docs define a handoff as a tool that writes a persisted state variable (
active_agent,current_step), after which the graph routes on it. Two implementations: one agent whose prompt and tools are swapped per state by@wrap_model_callmiddleware (recommended for most cases), or separate agent subgraphs (LangChain); see agent hooks and middleware. Command. In the subgraph form, the handoff tool returnsCommand(goto="sales_agent", update={...}, graph=Command.PARENT).graph=Command.PARENTsends the routing to the parent graph, which is how a tool inside one agent’s subgraph moves control to a sibling node (LangChain, graph API). See LangGraph.- Message hygiene. If the tool updates
messages, it must append aToolMessagematchingruntime.tool_call_id, otherwise the receiving model sees a tool call with no response (LangChain). - Persistence. A checkpointer keeps
active_agentacross turns, so the next user message goes straight to the specialist (LangChain).
Google ADK
- Single transfer tool. An
LlmAgentwith transfer targets gets onetransfer_to_agent(agent_name)tool whoseagent_nameis a JSON Schema enum of valid targets (the code comment says this prevents hallucinated names), optionally with atransfer_reason. The function only setstransfer_to_agenton the tool context’s actions; the runtime does the switch (ADK source). See Google ADK. - Targets come from the agent tree. Valid targets are the agent’s sub-agents, its parent (unless
disallow_transfer_to_parent) and its peers (unlessdisallow_transfer_to_peers). ADK injects instructions listing each target’sdescriptionand telling the model to transfer to the parent if no one fits (ADK source). - ADK 2.0 modes. Sub-agents in default
chatmode are true handoffs: they talk to the user and return control only via an explicit transfer.taskmode agents may ask clarifying questions and return automatically onfinish_task;single_turnagents return immediately and can run in parallel. These two run in an isolated session branch and are excluded fromtransfer_to_agenttargets, which makes them agent-as-tool, not handoff (collaborative workflows, ADK source).
Microsoft Agent Framework
HandoffBuilder builds a mesh of agents with no central orchestrator; handoff tools are injected per the add_handoff rules (all-to-all by default). Agents keep separate sessions, so each broadcasts user and agent messages to every participant, with tool content, including handoff calls, filtered out. An agent that replies without handing off pauses the workflow for user input, unless experimental autonomous mode is on (default cap 50 turns per agent) (Agent Framework). See Microsoft Agent Framework.
Handoff vs agent-as-tool
| Handoff | Agent-as-tool | |
|---|---|---|
| Who owns the task | Receiver takes full ownership | Caller keeps responsibility |
| Control after the specialist finishes | Stays with the receiver until it transfers again | Returns to the caller in the same run |
| Who talks to the user | The active specialist, directly | Only the caller |
| Context the specialist sees | Conversation so far, by default (filterable) | Only what the caller passes (OpenAI default: one input string) |
| What the caller sees back | Nothing; it is no longer running | The specialist’s output (extractable) |
| Parallelism | Sequential | Several specialists can run at once |
| Topology | Mesh or tree of peers | Hub and spoke |
Sources: Agent Framework, LangChain, OpenAI tools, OpenAI handoffs.
Cost profile. LangChain’s worked example counts model calls per pattern. For a one-shot request, handoffs take 3 calls and subagents 4. When the same request repeats in turn 2, handoffs total 5 calls against 8 for subagents, because the specialist is already active. For a three-domain comparison, handoffs need 7+ calls and ~14K+ tokens against 5 calls and ~9K tokens for subagents, because handoffs run sequentially and carry history, while subagents work in parallel with isolated context (LangChain). See cost and latency optimization.
Context passing
What the receiver sees is the main design decision, and the defaults differ:
- OpenAI Agents SDK: everything. The receiver sees the full prior conversation.
input_filtergets aHandoffInputData(input_history,pre_handoff_items,new_items, …) and returns a trimmed one;handoff_filters.remove_all_toolsstrips tool items. Opt-in betanest_handoff_historycollapses earlier turns into a summary block in a<CONVERSATION HISTORY>wrapper (handoffs docs); compare context compaction. - LangChain subgraphs: almost nothing. The docs recommend passing only the
AIMessageholding the handoff call and itsToolMessage, summarising prior work into theToolMessageif needed (LangChain). - Agent Framework: messages, not tools. User and agent text is synced to all participants; function calls, results and approval payloads are dropped (Agent Framework).
- Agent-as-tool: nothing unless passed. An OpenAI
as_tool()run does not inherit the parent’s conversation; you share asessionexplicitly or pass structuredparameters(OpenAI tools). - Application state is separate. In the OpenAI SDK the run
contextobject (database handles, user IDs) is available to tools, hooks and handoffs but never sent to the model (agents docs);input_typecarries model-chosen metadata (handoffs docs).
Synthesis: full history maximises continuity but inherits every earlier tool output, including untrusted content, and grows token cost on each hop. Minimal history is cheap and clean but loses decisions the user already made. Cognition’s argument that agents must share full traces because actions carry implicit decisions (Cognition) favours the first; LangChain’s guidance favours the second. A structured handoff payload (an input_type summary or a ToolMessage brief) plus filtered history is the usual middle ground. See context engineering.
Failure modes
- Malformed history. A handoff that writes messages without a matching
ToolMessageleaves a dangling tool call (LangChain). Parallel tool calls in the same turn need explicit handling; LangChain’s examples assume one call, and the OpenAI SDK silently executes only the first handoff (runtime source). - Wrong or invented target. Routing depends on tool and agent descriptions. ADK constrains names with an enum and tells agents to make descriptions distinguish them from peers (ADK source).
- Ping-pong and runaway loops. Mutual handoff edges (specialist back to triage) can cycle. Budgets are the backstop:
max_turnsraisesMaxTurnsExceededin the OpenAI SDK (running agents); LangGraph’srecursion_limitcaps super-steps (graph API); Agent Framework caps autonomous turns per agent (Agent Framework). - Stuck in a specialist. ADK
chatsub-agents only return via an explicit transfer, and Agent Framework hands back to the user whenever an agent answers without a handoff; its docs note you cannot force every turn to be a handoff without stopping the agent from giving real answers (collaborative workflows, Agent Framework). - Lost context and conflicting decisions. Aggressive filtering drops facts the receiver needs. MAST, a taxonomy built from multi-agent traces, records loss of conversation history (2.8%), conversation reset (2.2%), information withholding (0.85%) and ignoring another agent’s input (1.9%) among its failure modes (MAST). See error analysis.
- Guardrail gaps. In the OpenAI SDK, input guardrails run only for the first agent and output guardrails only for the agent producing the final output; tool guardrails do not cover handoff calls (handoffs docs, guardrails). See agent guardrails.
- Leaking data across agents.
remove_all_toolsdoes not redact tool data already restated in normal messages, and nested history summaries can keep tool arguments and outputs (handoffs docs). Synthesis: a specialist with sensitive tools that receives unfiltered history also receives any prompt injection earlier agents read, which can complete a lethal trifecta. - Platform incompatibilities. With server-managed conversation state (
conversation_id,previous_response_id), the OpenAI SDK rejects handoff input filters with aUserErrorand disables nested history (runtime source). Agent Framework workflows rebuilt from checkpoints need stable agent IDs and names, because routing depends on them (Agent Framework). - Side effects in the handoff tool. LangChain advises being explicit about whether a handoff tool only changes routing state or also acts, for example creating a ticket (LangChain).
Practical guidance
- Start with one agent. OpenAI’s guide advises getting the most out of a single agent before splitting into several (OpenAI guide). LangChain’s single-agent middleware form gives handoff-like behaviour (changing prompt and tools by state) without separate agents (LangChain).
- Choose handoffs for conversational routing. They fit triage-to-specialist flows where the specialist must talk to the user over several turns, such as customer support. Choose agent-as-tool when you need parallel work, a single voice to the user, or the caller to combine results (LangChain, Agent Framework). Many systems mix both; see agent design patterns.
- Restrict the graph. Allow only the edges you need (
add_handoff,disallow_transfer_to_peers,is_enabled), and always give a way back to a router or a human (Agent Framework, ADK source, handoffs docs). See human-in-the-loop. - Decide the context contract per edge. Filter tool items by default and pass a structured brief (reason, summary, IDs) through
input_typeor theToolMessage(handoffs docs, LangChain). - Enforce policy outside the handoff. Put checks on the tools each specialist can call, not only on the entry agent (guardrails).
- Trace and evaluate routing. Handoffs appear as spans in OpenAI SDK traces (tracing). Synthesis: treat “routed to the right agent with the right context” as its own eval target, separate from final-answer quality; see agent evaluation, LLM observability and OpenTelemetry GenAI.
- Across organisations, use a protocol. For agents owned by another team or vendor, delegate over A2A rather than an in-process handoff.
Sources
- Orchestrating Agents: Routines and Handoffs (OpenAI Cookbook)
- OpenAI Agents SDK: handoffs · tools / agents as tools · handoff runtime source · running agents · agents · guardrails · tracing
- LangChain multi-agent docs (overview and handoffs) · LangGraph graph API
- ADK agent transfer source · ADK collaborative workflows
- Microsoft Agent Framework handoff orchestration
- A Practical Guide to Building Agents (OpenAI)
- Don’t Build Multi-Agents (Cognition)
- MAST multi-agent failure taxonomy