Fallback & handoff
By the end of this page your system will answer gracefully when nothing matches, and move between specialists without confusing the user.
Prerequisites
- A system with connected agents (Connect agents).
- Admin or Developer role.
The default action
When the router can’t confidently pick an agent, it applies the Default Action instead of guessing. Set it under the Config pill.
Respond to user with message
The router replies with your text and ends the turn. No agent runs.
Write something that helps the user retry:
I can help with sales and revenue questions, or stock and inventory questions.
Could you rephrase your request, or tell me which of those you need?Naming what the system can do turns a dead end into a hint. This is the default, and it’s the safer choice for most systems.
Route to fallback agent
The router hands unmatched messages to a member you nominate in Fallback Agent. Pick your most general specialist — the one whose wrong answer is least harmful.
The fallback agent must be a member of the system. If you remove that agent later, the publish check blocks you until you choose another.
Choose this when a plausible attempt beats a refusal, and the custom message when a wrong answer would be worse than none.
Handoff
A handoff happens when a turn is answered by a different agent than the previous turn. The conversation carries over: the incoming agent receives the messages so far, with each one labelled by the agent that wrote it, so it can pick up mid-thread.
Configure what the user sees under the Config pill, in Handoff.
Show transition message
On by default. The user sees a short line when the conversation moves, so the change of voice isn’t jarring. Turn it off for a single-assistant feel where handoffs are invisible.
Transition template
The line shown on a handoff. Use {agentName} where the incoming agent’s name should appear:
Transferring you to {agentName}...{agentName} is the only placeholder available. Any other braces are left as-is.
Per-agent chat display
Two settings on each agent card override the generic template for that specialist. Expand Chat Display on the card.
| Field | What it does |
|---|---|
| Display Name | The name shown for this agent in chat during transitions. Defaults to the agent’s own display name. |
| Handoff Greeting | A greeting used instead of the transition template when the conversation moves to this agent. |
A greeting in the agent’s own voice reads far better than a generic transfer line:
Hi! I'm the inventory specialist — I can check stock and reorder levels for you.Set a greeting where the specialist’s role isn’t obvious from its name, and leave it empty everywhere else so the template handles the rest.
Common issues
- No transition line appears — Show transition message is off, the same agent answered again (not a handoff), or it’s the first message of the conversation.
- The literal text
{agentName}appears — Check the spelling and capitalisation; it’s case-sensitive. - “Default action is set to route to a fallback agent but no agent is selected” — Pick a Fallback Agent, or switch to Respond to user with message.
- “Fallback agent is not a member of this router” — The nominated agent was removed. Choose a current member.
- Every message hits the fallback — Members have weak or missing skills, so nothing matches confidently. See Connect agents.
Next
- Test the MAS — watch routing and handoffs happen live.