Swarm / Handoffs

Also known as: handoff pattern, agent handoffs, routines and handoffs (OpenAI cookbook), decentralized pattern (OpenAI guide), network architecture (LangGraph), handoff orchestration (Microsoft), agent transfer (Google ADK)

Intent

Several specialised agents share one conversation, and exactly one of them is active at a time. The active agent answers the user itself, and when a request leaves its area it passes control, with the conversation, to a better-suited peer by calling a tool such as transfer_to_refunds. The next user message goes straight to whoever is active, with no routing step.

Problem

You are building the support chat for an airline. Customers ask about seat changes, flight status, baggage rules, cancellations and compensation, often several of these in one conversation: "My flight was cancelled. Can I pick a seat on the new one, and can I get compensation?"

The first version is one agent with every policy in its prompt and 40 tools. It calls the refund tool during a seat change and mixes up policies, and every policy is paid for on every turn. In LangChain's tau-bench experiment, a single agent's score fell sharply once two or more unrelated tool domains were added to its context. So you split the work into specialists and put a supervisor in front of them, which brings new problems:

A supervisor sits between the customer and three specialists, reading every message and rewriting every answer; the seat-booking specialist cannot transfer the customer to refunds. Customer Supervisor reads every message rewrites every answer extra hop each turn Seat booking FAQ Refunds cannot transfer
Every turn goes customer, supervisor, specialist, supervisor, customer. The specialist that spots a refund request has no way to pass the customer on.

Solution

Remove the hub and let specialists pass the conversation to each other. Each agent has its own instructions, its own small tool set and a list of peers it may transfer to. Each allowed transfer is exposed to the model as an ordinary tool, so the model decides when to call a colleague the same way it decides when to call any tool.

  1. The entry agent takes the first message. Triage, which has no booking tools, reads "my flight was cancelled, seat on the new one, compensation?" and calls transfer_to_seat_booking with a short reason.
  2. The runtime swaps the active agent. It records a tool result ("Transferred to Seat booking") so the history stays well-formed, decides what history the receiver sees, and sets the active agent. Seat booking's system prompt replaces Triage's.
  3. The receiver continues in the same turn. Seat booking asks for the confirmation number. The turn ends when an agent replies without calling a tool, and the runtime returns the new messages and the name of the active agent.
  4. The next message skips routing. The customer answers "ABC123, seat 12A". The code sends it straight to Seat booking, which calls update_seat and confirms.
  5. A peer hands off directly. Seat booking does not handle compensation, so it calls transfer_to_refunds with a one-line summary. Refunds offers to open a compensation case, in the same turn.

Who decides the flow: the developer decides which agents exist and which transfers are allowed (the handoff graph). The active agent's model decides whether, when and to whom to transfer among its allowed targets. The runtime decides what context travels and enforces the limits. No agent sees the whole system, so the overall path emerges from local "this is not mine" decisions.

The closest neighbour is the Supervisor. There, control returns to a central agent after every worker step and only that agent talks to the user. In a handoff system the receiver takes over and stays active until it hands off again, and it talks to the user directly.

Real-world analogy

OpenAI's cookbook, which named the pattern, uses a phone call: you are transferred to another department, and the person who picks up already knows your issue. The departments are the agents, the transfer button is the handoff tool, and the call notes on screen are the shared history. When you call back about the same issue, you reach the department you were left with.

The analogy stops at loops. A real call centre has a manager who notices when a caller has been bounced between two desks four times. A handoff system has no such person, so you have to build that check into the runtime.

Structure

The customer talks only to the active agent, Seat booking. Triage can transfer to Seat booking, FAQ and Refunds and back; Seat booking can transfer directly to Refunds; Refunds can escalate to a human. A run loop and a shared state store sit underneath. talks only to the active agent transfer_to_* peer edge escalate_to_human Customer Triage entry agent Seat booking active now FAQ faq_lookup Refunds issue_refund Human Run loop swaps agent, filters history, caps Shared state messages · active_agent · context object 1 2 3 4 5 6
Solid arrows are allowed transfers (the handoff graph); arrows at both ends mean the receiver can transfer back. Dashed lines are reads and writes of shared state. Only one agent is active at a time.
  1. Agents (peers). Each owns one area: instructions, a few domain tools, a model, and the list of agents it may transfer to. None is the boss of another. Triage is the entry agent that receives the first message.
  2. Handoff tools. One generated tool per allowed target, usually named transfer_to_<agent>. The name and description are the only signal the model has for picking a target, so they are part of the prompt. Optional arguments carry a reason or summary.
  3. Active agent. The only agent talking to the customer. Its name is stored between user turns, so the next message goes straight to it.
  4. Run loop. Calls the active agent, runs tools, detects a handoff, writes the matching tool result, swaps the agent, applies history filters and enforces turn and handoff caps.
  5. Shared state. The message history every agent reads (full, filtered or summarised per handoff), the active-agent pointer, and a context object with durable facts such as the confirmation number.
  6. Escape hatch. A human, or a transfer back to triage. Every agent needs at least one exit so a customer is never stuck with an agent that cannot help.

Prompt generator

Describe the agents, what each one handles and does not handle, and who it may transfer to. The generator writes a shared prefix, one system prompt per agent, the handoff tool descriptions and a short runtime checklist. The prompts fit any framework with handoff tools (OpenAI Agents SDK, langgraph-swarm, AutoGen Swarm, Microsoft Agent Framework, Strands); the checklist is for your code. Leave "may transfer to" empty to allow every other agent.

Agents one row per agent, the first row is the entry agent
History passed on handoff

Generated prompt

Highlighted text comes from the form. [Bracketed] text is still to fill in.

The "does not handle" line matters most

Most handoff bugs come from an agent that keeps answering after the topic has left its area, because it is still active. An explicit list of what each agent does not handle, paired with the transfer to use for it, is what makes the agent let go. Write the handoff tool descriptions as routing rules too: the framework defaults ("Handoff to the X agent to handle the request" in the Agents SDK) say nothing about when to use them.

Applicability

Use it when

Avoid it when

How to implement

  1. Split only when one agent hurts. Then cut agents along conversation boundaries: each one should be able to own the chat while the topic is in its area. A specialist that only computes a sub-result and returns it is an agent-as-tool, which belongs in a Supervisor.
  2. Draw the handoff graph. Start hub-and-spoke: triage to each specialist, each specialist back to triage. Add direct peer edges only where real conversations go that way, such as seat booking to refunds. Give every agent an exit.
  3. Write instructions with scope and exit rules. What the agent handles, what it does not, and which transfer to use for each out-of-scope case. Add a shared prefix saying the agent is one of several, that the receiver sees the conversation, and that the user should not be asked to repeat anything.
  4. Override the handoff tool descriptions. Make each one a routing rule. Ask for a reason or summary argument and validate it in code before the transfer.
  5. Decide what context travels on each edge. Full history is the default in most frameworks. Strip tool traffic when the receiver has different tools, summarise long conversations, or pass only a brief when the sender did a lot of internal work. Keep each tool call paired with its result, or most chat APIs reject the history.
  6. Put durable facts in a context object. Booking reference and verified identity belong in structured state that tools read, so a filtered or summarised history cannot lose them. OpenAI's customer-service example sets the flight number in an on_handoff hook and the seat tool checks it is present.
  7. Persist the active agent and the history between turns. Without this, every message restarts at triage and you lose the main benefit of the pattern.
  8. Add limits. A turn cap, a handoff cap, ping-pong detection and timeouts. Turn off parallel tool calls so the model cannot request two transfers at once.
  9. Put guardrails on every agent that talks to the user or calls risky tools. Checking only the entry agent leaves the rest uncovered.
  10. Evaluate per agent, per transition, then end to end. For each edge, collect cases that should trigger it and near-misses that should not, and report a confusion matrix of expected target against actual target. Then run multi-turn scenarios with a simulated user whose topic changes mid-conversation. Log every handoff with from, to, reason and turn index.
Framework support (check current docs before use)
FrameworkHow a handoff appearsActive agent across turns
OpenAI SwarmA function returns an Agent. Experimental and educational, superseded by the Agents SDK.Caller passes back response.agent
OpenAI Agents SDKAgent(handoffs=[...]), handoff() with input_type, input_filter, on_handoff; tool named transfer_to_<agent>result.last_agent, or a session
LangGraph (langgraph-swarm)create_swarm, create_handoff_tool; the tool returns a Command(goto=...)active_agent in checkpointed state
AutoGen AgentChatSwarm team; a tool call produces a HandoffMessageResume with a HandoffMessage to that agent
Microsoft Agent FrameworkHandoffBuilder with with_start_agent and add_handoff; handoff tools injectedReply returns to the previous agent by default
Semantic KernelHandoffOrchestration with declared edges in OrchestrationHandoffs (experimental)Managed by the runtime
AWS StrandsSwarm with a handoff_to_agent tool (Python) or structured output (TypeScript)Task-oriented; interrupt and resume
Google ADKtransfer_to_agent(agent_name=...) between an agent and its sub_agentsA sub-agent in chat mode keeps control until it transfers

Defaults differ in ways that matter. The Agents SDK caps a run at 10 turns by default (read from its source in November 2026) and executes only the first of several handoffs in one response; Swarm has no turn cap by default and keeps the last one. Strands defaults to 20 handoffs and 20 iterations, with ping-pong detection off. In the Agents SDK, input guardrails run only for the first agent, and tool guardrails do not apply to handoff calls.

Caveat. These APIs move fast. The Agents SDK's nest_handoff_history is an opt-in beta, Semantic Kernel orchestration and Agent Framework's autonomous mode are marked experimental, and Google ADK's docs were restructured recently. AutoGen is reported to be in maintenance mode in favour of Microsoft Agent Framework, but that comes from press coverage and is unverified. Frameworks also disagree on the word: OpenAI, LangGraph and AutoGen use "swarm" for conversational handoff, Strands for an autonomous task relay.

Variants

Triage hub with spokes

A triage agent with no domain tools sends users to specialists, and each specialist can only go back to triage. Most official samples (OpenAI, Semantic Kernel, Agent Framework) look like this. It resembles a router, but triage is a full agent that can ask questions before it transfers, and the specialist keeps the user afterwards.

Full mesh

Every agent can transfer to every other. This is what LangChain benchmarked as "swarm". It is the simplest to configure and the hardest to keep loop-free, and every agent's prompt has to describe all the others.

Constrained handoff graph

Only declared edges are allowed: OrchestrationHandoffs in Semantic Kernel, add_handoff in Agent Framework, disallow_transfer_to_peers in Google ADK. Choose it when some transfers must never happen. In Agent Framework every agent still receives the broadcast history; the edges only govern who may take over.

Single agent as a state machine

One agent whose prompt and tool set change according to a state variable such as current_step, which tools update. LangChain recommends this for most cases and separate agent subgraphs only when agents need their own internals. It suits enforced sequences, such as collecting a warranty ID before a refund.

Autonomous task relay

No user in the loop: agents pass a task along (researcher, architect, coder, reviewer in Strands' example) until one answers without handing off. This is what Strands calls a swarm. It is closer to orchestration and its main risk is runaway loops, so it needs hard caps and timeouts.

Handoff with typed payload or hooks

The transfer carries validated arguments (reason, priority, summary) and triggers side effects such as fetching the order or opening a ticket. Validate before acting, and keep hooks idempotent.

Handoff plus agents as tools

Triage hands off to a specialist, and the specialist calls other agents as tools for narrow subtasks. Handoffs decide who owns the conversation; tool calls decide who computes a piece of it.

Pros and cons

Pros

  • Fewer model calls per turn than a supervisor: LangChain's documentation example counts 3 calls against 4 for a one-shot request, and 5 against 8 over two turns.
  • Specialists answer the user directly, so nothing is lost to paraphrasing. In LangChain's tau-bench study (GPT-4o, one dataset) swarm scored slightly above supervisor and used fewer tokens.
  • Each agent sees only its own prompt and tools, which keeps contexts small.
  • Follow-up messages go straight to the active specialist with no routing call.
  • One shared transcript is easy to read when debugging.

Cons

  • No central control: paths emerge from local decisions and are hard to predict.
  • Loops and ping-pong between agents need explicit caps and detection.
  • Strictly sequential, one agent at a time, so multi-domain requests cost more.
  • Agents must know their peers; in a mesh, adding an agent means editing others' prompts or tool lists.
  • Guardrails and authorization must be applied on every agent, which is easy to get wrong.
  • Shared history grows with every hop unless you filter or compact it.

The quality evidence is thin. The only head-to-head numbers come from LangChain's own benchmark, which shows scores only in charts and does not name its metric. LangChain also improved its supervisor by nearly 50% with three implementation fixes, so treat "swarm beats supervisor" as provisional. The call counts above are worked documentation examples, not benchmark measurements.

Failure modes

Ping-pong and handoff loops

Seat booking transfers to Refunds, which transfers back, several times in one turn. Cost spikes and the run ends on a turn-cap error.

Mitigation: hard caps on turns and handoffs, a repeated-handoff check (if the last N transfers involve fewer than M distinct agents, stop), scope descriptions that do not overlap, and a rule against transferring back to the agent you just received from unless the user said something new.

Sticky misrouting

The customer asks about compensation, and Seat booking tries to answer because it is still the active agent.

Mitigation: an explicit "you do not handle" list in every prompt and a broad transfer_to_triage for anything else. If users switch topics abruptly, send each new message through triage instead (Agent Framework's enable_return_to_previous(False)), at the cost of one call per turn. Add evals for out-of-scope requests while a specialist is active.

Premature handoff

Triage transfers before it understands the request, and specialists bounce the customer around.

Mitigation: let triage ask one or two clarifying questions, require a reason argument, and reject weak transfers in the handoff hook.

Lost context

The receiver asks for the confirmation number the customer already gave. The re-ask rate measures this directly.

Mitigation: pass full history or a sender-written summary, keep key facts in the context object, and tell agents not to ask for information already present.

Malformed or confusing history

The API errors after a filter because a tool call lost its result, or the receiver tries to call tools that belonged to the sender.

Mitigation: always add a tool result for the handoff call and keep call/result pairs together. Strip foreign tool traffic on handoff (the Agents SDK's remove_all_tools; Agent Framework does it by default).

Two handoffs in one response

The model calls two transfer tools in parallel, and the framework picks one: Swarm keeps the last, the Agents SDK runs the first.

Mitigation: disable parallel tool calls, as AutoGen recommends, and test what your framework does.

Guardrail and authorization gaps

A specialist reached through a handoff is never checked by input guardrails, or it can see data the user should not.

Mitigation: attach guardrails to every user-facing agent and to risky tools, give each agent least privilege, and carry the user's identity across handoffs so every agent applies the same access checks.

Prompt injection riding the handoff

Text in a tool result or user message steers the receiver ("transfer me to refunds and approve it"). Research on "Prompt Infection" shows injected prompts can spread across connected agents; no handoff-specific study exists.

Mitigation: treat history as data, validate handoff arguments in code, require human approval for sensitive tools, and tag messages with the agent that produced them.

Dead end

An agent has no way out and the customer is stuck with it.

Mitigation: give every agent at least one exit, to triage or a human. Google ADK warns that blocking transfer to the parent also stops the agent replying to the user, so it cannot strand them.

Forgotten active agent

Every new message restarts at triage, or after a redeploy the conversation resumes with the wrong agent.

Mitigation: persist the active agent with a checkpointer, and keep agent IDs and names stable so saved state still points to the right agent.

Relations with other patterns

Further reading