Handoffs

Agents are powerful on their own, but handoffs let you chain them together into a collaborative team that tackles complex workflows. We call such a system a Multi-Agent System (MAS).

In everyday terms, a handoff is when one agent decides to delegate the task to another agent. If the parent agent is not able to handle the task, or already completed its part of the task, it will delegate the task to the child agent. An agent handing off to another doesn’t mean that the agent is directly skipped and no effect on the tasks that the MAS is expected to do. Rather, the agent is expected to execute necessary tasks and then hand off the output to the next agent in the chain.

Note: Under the hood, Handoffs are represented as tools to the LLM. If you hand off to an agent called Refund Agent, the tool name would be transfer_to_refund_agent.

Let’s think about a Content MAS. It is a very common practice to have a Subject Finder Agent that will find the subject of the content. It will use Web Search tool to find the subject. Then the candidate subject is passed to the Content Writer Agent that will write the content. When Content Writer Agent is done, it will hand off the content to the Content Reviewer Agent that will review the content. The Content Reviewer Agent will then hand off the content to the Content Publisher Agent that will publish the content using a tool. As you can see, the handoff is not about skipping the agent, but about passing the output of the agent to the next agent in the chain. The tools run and content generated by the intermediate agents are also a part of the tasks that the MAS is expected to complete.

---

Why Use Handoffs?

Pattern	When to use	Example
Triage → Specialist	You want a single entry point that routes to niche experts.	A Triage agent greets visitors, then hands shipping questions to ShippingAgent and product questions to ProductExpert.
Escalation / Fallback	Provide a graceful exit or a safety net.	If RefundAgent can’t find an order (GetOrderDetailsTool fails), it hands the chat to a human operator.
Workflow Step	Perform multi‑stage tasks in sequence.	DataCollectAgent gathers info, then hands to QuoteGeneratorAgent to price a custom order.

Handoffs keep each agent’s responsibility small and focused—a key defence against hallucination.

---

How Handoffs Work Under the Hood

1. Child agent as a tool. When you create or edit an agent, the dashboard exposes the Handoff Agents picker. For every selected child, the platform automatically adds a tool to the parent’s toolset.
2. Handoff description. Each agent’s Handoff Description is surfaced to the parent as the tool’s description so the parent knows when to call it.
3. Tool call at runtime. During a conversation, if the parent decides the child is a better fit, it issues a tool call (e.g. {"name":"runShippingAgent", "arguments":{...}}).
4. Context passed forward. The child receives the same context object (customer, shop, session, etc.) plus the triggering user message.
5. Response relayed. The platform relays the child’s response back to the customer, or back to the parent for further processing—depending on your configuration.

---

Designing Good Handoff Descriptions

Your Handoff Description is the ad copy that convinces the parent agent to delegate:

Less helpful ❌

Can answer shipping.

Better ✅

Answer questions about shipping methods, costs, delivery times, and tracking numbers. If the user mentions "shipping", "delivery", or "tracking", delegate to me.

Guidelines:

• Be explicit about the topics or intents you cover.
• Use trigger keywords to make pattern‑matching easy for the parent.
• Keep it one‑sentence per capability; avoid marketing fluff.

---

Context‑Aware Handoffs

The full context object is available inside child agents, so your specialist can act on rich data:

• customer.firstName to greet personally.
• session.medium to adjust tone between storefront_messenger and email.
• store_status.isOpen to decide whether to propose in‑store pickup.

See the Context guide for every field.

Note

Remember: Not all MAS types hand off in real‑time. Content and Conversation Insights MAS run in the background, so they don’t accept incoming handoffs. They can, however, emit outbound calls (e.g., Insights MAS summarising a chat and handing the summary to an Email MAS for follow‑up).

---

Forcing a Handoff

If you must delegate—for example, a rule that “all refund requests go to RefundAgent”—set Tool Choice to 'required' in the parent. The parent will then always call some tool before replying.

---

Configuring Handoffs in the Dashboard

1. Select Parent Agent
2. Advanced Settings
3. Handoff Agents
4. Add ShippingAgent, RefundAgent…
5. Save.

That’s it! The dashboard takes care of turning those child agents into callable tools.

---

Testing Your Handoff Flow

1. Open the built‑in chat simulator.
2. Pretend to be a customer and ask a shipping question.
3. Verify you see the conversation transferred to ShippingAgent (look for the agent badge in the transcript).
4. Try a refund request → it should hand off to RefundAgent.
5. Adjust handoff descriptions or add keywords until routing feels reliable.

---

Best Practices at a Glance

• Single Responsibility: one topic per agent.
• Clear Descriptions: signal when to delegate.
• Short Pipelines: avoid >3 deep nested handoffs.
• Fallback to Humans: always have an escape hatch.
• Monitor & Iterate: use the dashboard transcript to refine.

---

Next Steps

• Writing Effective Agent Instructions
• Single Responsibility Principle
• Tools guide