1What if the right specialist only becomes clear partway through?
One agent at a time owns the conversation. When the request turns out to be outside its remit, it calls a transfer: a peer becomes the active agent, receives the whole history and answers the user itself. No manager relays messages and no one merges results.
You may need it if
- A first-line agent discovers after two exchanges that the request belongs to another team.
- A coordinator paraphrases the user to a specialist and the specialist back, and details get lost.
- Users repeat what they already said each time a different agent picks up their request.
2When is passing the conversation along the wrong move?
Use it when
- Requests need different specialists, one at a time, and which one depends on what the exchange reveals.
- Each agent can tell from its own remit when it has reached its limit and who should take over.
- One agent should own the reply, with nobody rewriting it on the way to the user.
Avoid it when
- The right agent can be named from the first message. A classifier that routes once is simpler and does not take part in the work.
Use Meta-Controller instead - Several specialists must contribute to one deliverable, or work at the same time. Only one agent acts here.
Use Supervisor & Specialists instead - The request needs a plan that someone tracks and revises across many steps. No agent here holds the overall picture.
Use Magentic Orchestration instead - Remits overlap so much that agents will keep sending the request to each other. The cap then ends most runs.
What it costs
- Model calls
- 1 per agent that takes the turn: 1 + handoffs (capped, often 1 to 3)
- Latency
- low
- Complexity
- low
3How does control move from one agent to the next?
A relay with no hub. The first agent answers or calls a transfer. A counter checks that handoffs remain, then the named peer becomes the active agent with the full history. Whoever is active when no transfer is called writes the reply. At the cap, the request goes to a person.
- Step 1 of 6
The first agent takes the request
A customer writes that their invoice is wrong. The first agent owns the conversation. A simple question it would answer itself, and the run would end there.
- Step 2 of 6
It reaches the edge of its remit
Correcting an invoice is not its job. Among its tools is one transfer per peer. It calls the transfer to billing with a one-line reason. It does not brief or summarise.
- Step 3 of 6
The counter lets the transfer through
Plain code checks that billing exists and that the limit of three handoffs is not used up. The active agent changes. The message history is passed on as it is.
- Step 4 of 6
The specialist owns the turn
The billing agent reads the whole exchange, uses its own tools and answers the customer directly. Nobody rewrites its reply.
- Step 5 of 6
Or it passes the conversation on
If the wrong amount comes from a technical fault, billing transfers in turn, to a peer or back to the first agent. Each transfer goes through the counter again.
- Step 6 of 6
A person takes over
When the cap is hit, or an agent finds that nobody on the roster fits, the request leaves for a human with the history and the list of transfers.
What each part does
- Request
- The user's request, with the conversation so far when there is one.
- First agent
- Active at the start. Handles common requests itself and transfers what is outside its remit.
- Handoffs left?
- Plain code. Counts transfers and checks that the named agent exists before control moves.
- Specialists
- Peers with their own instructions and tools. The one named in a transfer becomes the active agent.
- Reply
- The answer written by the agent that was active last, with the trail of transfers.
- To a person
- The request handed to a human, with the history and the reason. No automatic answer was given.
- First agent → Reply: answers itself
- First agent → Handoffs left?: calls a transfer
- Handoffs left? → Specialists: handoffs left
- Specialists → Handoffs left?: transfers again
- Handoffs left? → First agent: back to the first agent
- Specialists → Reply: answers the user
- Specialists → To a person: asks for a person
- Handoffs left? → To a person: cap reached
Where it connects
A request whose owner is not known in advance, with the conversation so far. The roster of agents and their remits is already configured.
When: The active agent answers without calling a transfer.
The reply to the user, the name of the agent that wrote it, and the ordered list of transfers with their reasons.
When: The handoff cap is reached, or an agent finds that no peer fits and asks for a person.
A refusal to answer automatically, with the reason, the list of transfers and the full history, ready for a person to pick up.
4What do I ask my assistant to set up?
The agents to launch
First agent
You own this conversation until you transfer it. Answer common requests yourself. If the request is outside your remit, transfer it to the one agent whose remit covers it and give a one-line reason. Do not summarise the conversation for them and do not promise what they will do.
Sees: The full conversation and the roster with each agent's remit. Not the specialists' tools.
Specialist, one per remit on the roster, two to five
You now own this conversation and answer the user directly, using your own tools. Read the whole history first and never ask again for what was already said. If the request is outside your remit, transfer it with a one-line reason. If no agent fits, or the user asks for a person, escalate.
Sees: The full conversation, including earlier agents' turns and transfer notes, and the roster. Its own tools only.
A prompt you can paste
Works with any assistant that can launch sub-agents. It contains the agents, the procedure and the stop rule above.
You are the orchestrator of a multi-agent workflow that follows the "Handoff" architecture. Launch every agent listed below as a separate sub-agent with its own context. Give each agent only the context stated for it. Do not do an agent's work yourself. If you cannot launch sub-agents, play each agent in a clearly separated turn and never let it use what is withheld from it. # Task [Describe your task here] # Handoff The agent in charge passes the whole conversation to a peer. Input: the task above. It must provide: A request whose owner is not known in advance, with the conversation so far. The roster of agents and their remits is already configured. If something essential is missing, ask for it before starting. Agents to launch: - First agent: You own this conversation until you transfer it. Answer common requests yourself. If the request is outside your remit, transfer it to the one agent whose remit covers it and give a one-line reason. Do not summarise the conversation for them and do not promise what they will do. Context for this agent: The full conversation and the roster with each agent's remit. Not the specialists' tools. - Specialist (one per remit on the roster, two to five): You now own this conversation and answer the user directly, using your own tools. Read the whole history first and never ask again for what was already said. If the request is outside your remit, transfer it with a one-line reason. If no agent fits, or the user asks for a person, escalate. Context for this agent: The full conversation, including earlier agents' turns and transfer notes, and the roster. Its own tools only. Procedure: 1. Write the roster. Give each agent a remit of one or two lines that states what it handles and, above all, where it stops. 2. Give every agent one transfer action per peer it may hand over to, and one action that escalates to a person. 3. Launch the first agent on the request. Only the active agent may speak to the user. 4. On a transfer, check that the target is on the roster and that fewer than 3 handoffs have been used. Then make the target the active agent and give it the unchanged history plus a note of the transfer. 5. Record every transfer with its source, target and reason. 6. When the active agent answers without transferring, return its reply. Do not rewrite it. Stop rule: Stop when the active agent answers without a transfer. Stop also at the fourth transfer request or when an agent escalates. In both cases, hand the request to a person. Exits: - `reply`, when: The active agent answers without calling a transfer. Deliver: The reply to the user, the name of the agent that wrote it, and the ordered list of transfers with their reasons. - `escalated`, when: The handoff cap is reached, or an agent finds that no peer fits and asks for a person. Deliver: A refusal to answer automatically, with the reason, the list of transfers and the full history, ready for a person to pick up. # Final deliverable The reply and the name of the agent that wrote it, then the list of transfers with their reasons. If escalated, the reason and the history in place of the reply.
The same thing in code
import operator
from typing import Annotated, Literal, TypedDict
from langchain.chat_models import init_chat_model
from langchain_core.messages import HumanMessage, SystemMessage
from langgraph.graph import END, START, StateGraph
from pydantic import BaseModel
MAX_HANDOFFS = 3
ROSTER = { # one remit per agent; in a real system each one also has its own tools
"first": "You are the first contact. You answer common questions about the service. You do not change invoices or diagnose faults.",
"billing": "You handle invoices, payments and refunds. You do not diagnose technical faults.",
"technical": "You handle outages, configuration and error messages. You do not change invoices.",
}
RULES = ("You now own this conversation and answer the user directly. Read the whole history first and never "
"ask again for what was already said. If the request is outside your remit, transfer it to the one "
"agent whose remit covers it, with a one-line reason. If no agent fits, or the user asks for a "
"person, escalate.")
class Turn(BaseModel):
action: Literal["reply", "transfer", "escalate"]
target: str # transfer: a name from the roster
reason: str # transfer or escalate: one line
text: str # reply: the message to the user
class State(TypedDict):
history: list[str] # travels whole with every handoff
active: str
trail: Annotated[list[str], operator.add]
reply: str
escalated: str
model = init_chat_model("anthropic:claude-sonnet-5-5")
async def active_agent(state: State) -> dict:
name = state["active"]
peers = "\n".join(f"- {n}: {remit}" for n, remit in ROSTER.items() if n != name)
system = f"{ROSTER[name]}\n{RULES}\n\nAgents you can transfer to:\n{peers}"
raw = await model.with_structured_output(Turn).ainvoke([SystemMessage(system), HumanMessage("\n".join(state["history"]))])
turn = Turn.model_validate(raw)
if turn.action == "reply":
return {"reply": turn.text} # the active agent's words reach the user unchanged
if turn.action == "escalate" or turn.target not in ROSTER:
return {"escalated": turn.reason or f"unknown agent: {turn.target}"}
if len(state["trail"]) >= MAX_HANDOFFS: # the gate: nobody owns the route, so a cap ends the bouncing
return {"escalated": f"handoff cap reached at {name} -> {turn.target}: {turn.reason}"}
# transfer of control: same history, plus a note of the transfer; no brief, no summary
note = f"[{name} transferred the conversation to {turn.target}: {turn.reason}]"
return {"active": turn.target, "trail": [f"{name} -> {turn.target}: {turn.reason}"], "history": state["history"] + [note]}
def route(state: State) -> str:
return END if state["reply"] or state["escalated"] else "active_agent"
builder = StateGraph(State)
builder.add_node("active_agent", active_agent)
builder.add_edge(START, "active_agent")
builder.add_conditional_edges("active_agent", route, ["active_agent", END])
graph = builder.compile()
async def run(message: str) -> dict:
s = await graph.ainvoke({"history": [f"User: {message}"], "active": "first", "trail": [], "reply": "", "escalated": ""})
return {"reply": s["reply"] or None, "answered_by": s["active"], "handoffs": s["trail"], "escalated": s["escalated"] or None}
One node runs whichever agent is active; the transfer is a structured reply here. Give each agent its own tools, and wire the escalation to your ticketing system.
from typing import Literal
from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query
from pydantic import BaseModel
MAX_HANDOFFS = 3
ROSTER = { # one remit per agent; give each one its own tools through allowed_tools
"first": "You are the first contact. You answer common questions about the service. You do not change invoices or diagnose faults.",
"billing": "You handle invoices, payments and refunds. You do not diagnose technical faults.",
"technical": "You handle outages, configuration and error messages. You do not change invoices.",
}
RULES = ("You now own this conversation and answer the user directly. Read the whole history first and never "
"ask again for what was already said. If the request is outside your remit, transfer it to the one "
"agent whose remit covers it, with a one-line reason. If no agent fits, or the user asks for a "
"person, escalate.")
class Turn(BaseModel):
action: Literal["reply", "transfer", "escalate"]
target: str # transfer: a name from the roster
reason: str # transfer or escalate: one line
text: str # reply: the message to the user
async def take_turn(name: str, history: list[str]) -> Turn:
# the active agent is a fresh session with its own system prompt and the whole history
peers = "\n".join(f"- {n}: {remit}" for n, remit in ROSTER.items() if n != name)
options = ClaudeAgentOptions(
system_prompt=f"{ROSTER[name]}\n{RULES}\n\nAgents you can transfer to:\n{peers}",
output_format={"type": "json_schema", "schema": Turn.model_json_schema()},
)
async for msg in query(prompt="\n".join(history), options=options):
if isinstance(msg, ResultMessage):
return Turn.model_validate(msg.structured_output)
raise RuntimeError("no result")
async def run(message: str) -> dict:
history, trail, active = [f"User: {message}"], [], "first"
while True:
turn = await take_turn(active, history)
if turn.action == "reply": # the active agent's words reach the user unchanged
return {"reply": turn.text, "answered_by": active, "handoffs": trail, "escalated": None}
if turn.action == "escalate" or turn.target not in ROSTER:
reason = turn.reason or f"unknown agent: {turn.target}"
return {"reply": None, "answered_by": None, "handoffs": trail, "escalated": reason}
if len(trail) >= MAX_HANDOFFS: # the gate: nobody owns the route, so a cap ends the bouncing
reason = f"handoff cap reached at {active} -> {turn.target}: {turn.reason}"
return {"reply": None, "answered_by": None, "handoffs": trail, "escalated": reason}
# transfer of control: same history, plus a note of the transfer; no brief, no summary
trail.append(f"{active} -> {turn.target}: {turn.reason}")
history.append(f"[{active} transferred the conversation to {turn.target}: {turn.reason}]")
active = turn.target
The SDK's sub-agents report back to their caller, which is delegation, not a handoff. Here each active agent is its own session and plain code moves control.
from dataclasses import dataclass, field
from typing import Any
from agents import Agent, RunContextWrapper, Runner, function_tool, handoff
from pydantic import BaseModel
MAX_HANDOFFS = 3
RULES = ("You now own this conversation and answer the user directly. Read the whole history first and never "
"ask again for what was already said. If the request is outside your remit, transfer it to the one "
"agent whose remit covers it, with a one-line reason. If no agent fits, no transfer is available, "
"or the user asks for a person, call escalate.")
@dataclass
class Desk: # run context: the trail of transfers and the escalation, if any
trail: list[str] = field(default_factory=list)
escalated: str = ""
class Transfer(BaseModel):
reason: str # one line, written by the agent that hands over
@function_tool
def escalate(ctx: RunContextWrapper[Desk], reason: str) -> str:
"""Hand the conversation to a person. Use it when no agent fits or the user asks for one."""
ctx.context.escalated = reason # wire this to your ticketing system
return "Recorded. Tell the user that a person will take over, and add nothing else."
def member(name: str, remit: str) -> Agent[Desk]:
return Agent[Desk](name=name, instructions=f"{remit}\n{RULES}", tools=[escalate]) # add this agent's own tools
first = member("First contact", "You answer common questions about the service. You do not change invoices or diagnose faults.")
billing = member("Billing", "You handle invoices, payments and refunds. You do not diagnose technical faults.")
technical = member("Technical", "You handle outages, configuration and error messages. You do not change invoices.")
TEAM = [first, billing, technical]
def transfer_to(target: Agent[Desk]):
async def record(ctx: RunContextWrapper[Desk], data: Transfer) -> None:
ctx.context.trail.append(f"-> {target.name}: {data.reason}")
def handoffs_left(ctx: RunContextWrapper[Desk], _agent: Any) -> bool:
return len(ctx.context.trail) < MAX_HANDOFFS # the gate: at the cap, transfers disappear
# a handoff makes the target the active agent; it receives the conversation history as it is
return handoff(agent=target, on_handoff=record, input_type=Transfer, is_enabled=handoffs_left)
for agent in TEAM: # peers: every agent may hand over to every other one
agent.handoffs = [transfer_to(peer) for peer in TEAM if peer is not agent]
async def run(message: str) -> dict:
desk = Desk()
result = await Runner.run(first, message, context=desk, max_turns=MAX_HANDOFFS + 6)
if desk.escalated:
return {"reply": None, "answered_by": None, "handoffs": desk.trail, "escalated": desk.escalated}
# the reply comes from whichever agent was active last; nobody rewrites it
return {"reply": result.final_output_as(str), "answered_by": result.last_agent.name, "handoffs": desk.trail, "escalated": None}
Handoffs are native here. At the cap the transfer tools are disabled, so the active agent must answer or escalate. Do not add an input filter that trims the history.
import { anthropic } from '@ai-sdk/anthropic';
import { Output, ToolLoopAgent } from 'ai';
import { z } from 'zod';
const MAX_HANDOFFS = 3;
const model = anthropic('claude-sonnet-5-5');
const ROSTER: Record<string, string> = { // one remit per agent; give each one its own tools
first: 'You are the first contact. You answer common questions about the service. You do not change invoices or diagnose faults.',
billing: 'You handle invoices, payments and refunds. You do not diagnose technical faults.',
technical: 'You handle outages, configuration and error messages. You do not change invoices.',
};
const RULES =
'You now own this conversation and answer the user directly. Read the whole history first and never ' +
'ask again for what was already said. If the request is outside your remit, transfer it to the one ' +
'agent whose remit covers it, with a one-line reason. If no agent fits, or the user asks for a ' +
'person, escalate.';
const turnSchema = z.object({
action: z.enum(['reply', 'transfer', 'escalate']),
target: z.string().describe('transfer: a name from the roster'),
reason: z.string().describe('transfer or escalate: one line'),
text: z.string().describe('reply: the message to the user'),
});
const member = (name: string) => {
const peers = Object.entries(ROSTER).filter(([n]) => n !== name).map(([n, remit]) => `- ${n}: ${remit}`).join('\n');
return new ToolLoopAgent({
model,
instructions: `${ROSTER[name]}\n${RULES}\n\nAgents you can transfer to:\n${peers}`,
output: Output.object({ schema: turnSchema }),
});
};
export async function run(message: string) {
const history = [`User: ${message}`];
const handoffs: string[] = [];
let active = 'first';
for (;;) {
// the active agent sees the whole history, whoever wrote it
const { output: turn } = await member(active).generate({ prompt: history.join('\n') });
if (turn.action === 'reply') return { reply: turn.text, answeredBy: active, handoffs, escalated: null };
if (turn.action === 'escalate' || !(turn.target in ROSTER)) {
return { reply: null, answeredBy: null, handoffs, escalated: turn.reason || `unknown agent: ${turn.target}` };
}
if (handoffs.length >= MAX_HANDOFFS) { // the gate: nobody owns the route, so a cap ends the bouncing
return { reply: null, answeredBy: null, handoffs, escalated: `handoff cap reached at ${active} -> ${turn.target}: ${turn.reason}` };
}
// transfer of control: same history, plus a note of the transfer; no brief, no summary
handoffs.push(`${active} -> ${turn.target}: ${turn.reason}`);
history.push(`[${active} transferred the conversation to ${turn.target}: ${turn.reason}]`);
active = turn.target;
}
}
The transfer is a structured reply and plain code swaps the active agent. Give each agent its own tools, and wire the escalation to your ticketing system.
Snippets are generated when the site is built and type-checked against the SDK versions listed in the repository. Treat them as a starting skeleton.
What goes wrong
- Remits that overlap make agents bounce the request. State in each remit what the agent does not handle.
- Trimming the history at a transfer saves tokens and makes the next agent ask the user to repeat. Pass it whole.
- A transfer is not a subtask. If the first agent must get the conversation back to finish something, you want a supervisor.
- Without a cap and a human exit, two agents can exchange the request until the budget runs out.
Chain it
Its result can feed
- Reflection direct
Treat the active agent's reply as an existing answer to improve against quality criteria for the original request, keeping the transfer record as context.
- Chain of Verification direct
Treat the reply as an existing answer whose factual claims must each be checked independently and kept, corrected or removed.
- Debate conditional
Condition: Use only when the original request asks a question or decision with a contestable answer, not a routine service request or procedural reply.
- Constitutional Critique direct
Treat the reply as a draft text to check rule by rule against the stored constitution and fix only the failed rules.
- Textual Backpropagation direct
Give the reply to the first pipeline step as an existing result to improve under the configured evaluation criteria.