Handoffs

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.
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.

ℹ️ 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.

🧠 Example: A Content MAS

A common Content MAS might look like this:

Subject Finder Agent uses a web search tool to identify trending topics.
It hands off the subject to Content Writer Agent.
Once written, the draft is handed to Content Reviewer Agent.
After review, it’s passed to Content Publisher Agent, which uses a tool to publish the result.

Every agent contributes to the final outcome. Handoffs allow coordination, not skipping.

Why Use Handoffs?

Pattern	When to Use	Example
Triage → Specialist	Route to the right expert from a central entry point	A Triage Agent routes shipping questions to ShippingAgent and refund issues to RefundAgent
Escalation / Fallback	Escalate gracefully or recover from failure	If OrderAgent fails to find an order, it hands off to a human via LiveAgent
Workflow Step	Break down complex tasks into stages	CollectorAgent gathers input, then hands to GeneratorAgent 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.

Configuring Handoffs in the Dashboard

Create child agents with clear handoff descriptions
Create a parent agent
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.

Best Practices

✅ Single Responsibility – One topic per agent
✅ Clear Delegation Rules – Help the LLM decide when to hand off
✅ Avoid Long Chains – No more than 3 handoff levels
✅ Add Human Fallbacks – Use LiveAgent for edge cases
✅ Iterate Regularly – Watch transcripts and adjust