Skip to main content
Agents are powerful on their own, but handoffs allow you to chain them into a collaborative system that solves complex tasks—this is what we call a Multi-Agent System (MAS). In simple terms, a handoff is when one agent delegates a task to another. This could happen when the parent agent completes its part of the task or the task requires expertise the parent doesn’t have. A handoff does not skip the parent agent—it simply extends the workflow. Each agent is still expected to do its job before passing control to the next.

​
🧠 Example: An Email MAS

A common Content MAS might look like this:
  1. Customer wants to refund their order
  2. Triage Agenthands off execution to Orders Agent
  3. Orders Agent uses Get Customer Orders and Get Order Details tools to retrieve details of the order of concern and hands off execution to Refund Agent
  4. Refund Agent checks the details of the order retrieved by Orders Agent and takes the necessary action
Every agent contributes to the final outcome. Handoffs allow coordination, not skipping. All the handoffs, tool calls, outputs from start agent to current agent in control stays always in the context of MAS. That being said, the data retrieved by Get Customer Orders is always available to all agents in the run. You can check Trace of an execution to see all the data LLM took into consideration (System instruction, agent instruction, tool call results, handoffs, agent reasoning summaries, old executions) during an execution.
Internally, handoffs are implemented as tools. If you hand off to an agent named Refund Agent, the LLM sees a tool named transfer_to_refund_agent. This is why you can force a handoff by setting Tool Choice in Model Settings to required.

​
Why Use Handoffs?

PatternWhen to UseExample
Triage → SpecialistRoute to the right expert from a central entry pointA Triage Agent routes shipping questions to ShippingAgent and refund issues to RefundAgent
Escalation / FallbackEscalate gracefully or recover from failureIf OrderAgent fails to find an order, it hands off to a human via LiveAgent
Workflow StepBreak down complex tasks into stagesOrders Agent gathers input, then hands to Refund Agent for a custom quote
✅ Handoffs reduce complexity by keeping each agent small, focused, and specialized—helping prevent hallucinations.

​
How Handoffs Work Internally

Every handoff is a tool call. When the parent agent is running, it will automatically select(if needed) the child agent based on the handoff description. The child is able to see the results of tool calls of parent agents but the input to the child agent will be the same as the input to the parent agent. And the full control of the execution is now delegated to the child agent.

​
Designing Great Handoff Descriptions

The Handoff Description is what helps the parent decide when to delegate. Think of it as a one-line job post for the child. Bad ❌ 
Can answer shipping.
Good ✅ 
Answer questions about shipping methods, costs, delivery times, and tracking numbers. If the user mentions "shipping", "delivery", or "tracking", delegate to me.
Tips:
  • Be explicit about what you cover.
  • Use keywords the user might mention.
  • Stick to clear, one-sentence statements—avoid fluff.

​
Context-Aware Handoffs

Just like you can use context variables in the instructions of an agent, you can also use context variables in the handoff description of a child agent. This is useful when you want to delegate to a child agent based on the context. See Context Variables for the full reference.
Note: Not all MAS types support incoming handoffs.
Content MAS and Insights MAS run in the background and can’t receive handoffs—but they can hand off results to a conversational MAS (e.g., Email MAS).

​
Configuring Handoffs in the Dashboard

  1. Create child agents with clear handoff descriptions
  2. Create a parent agent
  3. Assign child agents to the parent agent as handoff agents
That’s it 🎉. When the parent agent is running, it will automatically delegate to the child agents based on the handoff descriptions.