Configure Handover for an Agent Stack

Handover is how the AI gets out of the way and lets a human take over. By default a new stack has handover off (never). This walks you through turning it on, picking a team, and setting up what the AI collects before handing off.

Before you start

• The stack must exist with at least one specialist.
• The team that should pick up handed-off conversations must exist (Settings → Teams). If it doesn’t, create it first.
• Decide what information the AI must collect before handoff (account email, order ID, etc.). You can add more later.

Steps

1. Turn handover on

1. Open Settings → Agent Stacks → [stack] → Handover.
2. On the Triggers sub-tab, toggle Allow handover to humans on.
3. The handover mode flips from never to by_description automatically. The Prerequisites and Delivery sub-tabs become enabled.

2. Pick a delivery mode and team

1. Click the Delivery sub-tab.
2. Choose a handover mode:
   By description (default) — the AI picks a team based on conversation context. Best when you have multiple teams covering different areas.
   Explicit team — every handover goes to one team. Pick the team from the dropdown.
3. (Optional) Add Handover instructions — free-form text that augments the AI’s prompt when deciding how to hand off. Examples: “Mention loyalty status if the customer is Gold or Platinum,” “Always tell the customer the human’s first name.”
4. Configure Outside opening hours behavior:
   Toggle Check opening hours on if you want the AI to behave differently when the destination team is closed.
   If on, pick which outside-hours options to offer: Email follow-up (default on), Close and return, Ask confirmation.
5. Toggle Ask confirmation before handover if you want the AI to confirm with the customer before queueing them (“Want me to connect you with a human?”). Some stacks prefer to surprise-confirm; others prefer the customer’s explicit consent.
6. Click Save.

3. Add prerequisites (the information the AI must collect)

1. Click the Prerequisites sub-tab.
2. Click Add requirement.
3. Fill in the form:
   Field — pick a conversation field or a contact field. The collected value will be saved there.
   Label — what to call this field internally.
   Ask prompt — what the AI says to the customer to collect it. Example: “What’s the email address on your account?”
   Condition — Always (every handover requires this) or When (only required when a stated condition is met, like “the customer is asking about a refund”).
4. Save the requirement.
5. Add as many as you need. Use the up/down arrows to reorder; the AI checks them in this order.

Verify it worked

• Open the Testing tab.
• Send a message that should trigger handover (“I want to talk to a real person”) or wait for the orchestrator to detect a stall.
• Watch the AI ask for any missing prerequisites in turn.
• Once everything is collected, the conversation should move to handover_pending, then to the destination team’s queue (you’ll see this on the live channel; the testing tab simulates the flow).

Recipe: a simple two-team setup

A common pattern for stacks with two destination teams:

• Set Handover mode to By description.
• Add Handover instructions: “Route billing questions to the Billing Team. Route everything else to General Support.”
• Add prerequisites: account email (always), order ID (when the conversation is about an order).
• Turn on Check opening hours with Email follow-up as the outside-hours option.

Troubleshooting

• Symptom: Toggling handover on does nothing visible. Fix: the page is async — wait a moment for the toast. If no toast appears, refresh and confirm the toggle stayed on.
• Symptom: The AI hands off to the wrong team. Fix: if you’re using By description, sharpen the Handover instructions with specific routing rules. If using Explicit team, only one team is possible — check the dropdown.
• Symptom: Handover triggers before all prerequisites are collected. Fix: prerequisites are best-effort. The orchestrator can still trigger handover under risk-escalation logic if the customer is upset enough. To force every handover to wait, mark every prerequisite as Always and remove any When conditions.
• Symptom: Outside-hours behavior never fires even though the team is closed. Fix: confirm the destination team has Opening Hours configured. The AI checks the team’s hours, not the tenant’s. See Opening Hours.

See also

• Handover to humans
• Handover modes reference
• Recipe: graceful handover to a team