Define Routing Topics for a Specialist

The router decides which specialist takes each customer message. It reads three signals — each specialist’s Responsibility text, any routing topics attached to that specialist, and the orchestrator-level routing rules — and picks the best match. Most stacks don’t need anything beyond a clear Responsibility per specialist. This article is for the cases where they do.

Routing topics themselves are not editable in the app. One is generated from the Responsibility text when a specialist is added to a stack — it reaches the router’s prompt, but it is filed against the stack’s router, so the specialist’s own topic counters keep reading 0 / “inferred from responsibility”. Adding or editing a topic requires the public API (POST /api/v1/specialists/{id}/routing-rules). Everything below is a UI fix.

Before you start

• Confirm the problem is actually mis-routing. Open the Testing tab and send the misrouted message. The routing decision — the specialist picked, its confidence and the router’s stated reason — only renders for Super Admins; without that role you are judging by the answer’s content alone.
• Decide what kind of fix you need: sharpen the Scope (if a specialist’s responsibility text is vague), or add a routing rule to the orchestrator config (if you need a global preference like “for refund questions, prefer Billing”).

Option 1: sharpen the Scope (fastest fix)

The first thing to try, every time.

1. Open Settings → Agent Stacks → [stack] → Orchestrator.
2. Click the specialist node that should have handled the message.
3. On the Setup sub-tab, look at the Responsibility field. Is it specific enough? “Customer help” is too vague. “Billing, invoices, refunds, subscription changes” is good. “Refund processing for orders within 30 days, plus subscription cancellations” is best.
4. Edit the Responsibility, click Save Changes.
5. Re-test with the same misrouted message in the Testing tab.

90% of routing problems are Scope problems.

Option 2: append a routing rule to the orchestrator (global preference)

Use this for cross-cutting rules that don’t belong to any one specialist’s scope.

1. From Settings → Agent Stacks → [stack] → Orchestrator, click the orchestrator node (top of the canvas, not a specialist).
2. The slide-out panel shows a free-form text box for routing rules. Anything you type here is appended to the built-in default prompt — your additions don’t replace defaults.
3. Add rules like:
   “For refund questions, prefer the Billing specialist over the Tech specialist.”
   “If the customer mentions delivery delays of more than 14 days, route to the Returns specialist.”
   “Always route Spanish-language messages to the Bilingual Support specialist if they’re enabled.”
4. Click Save.

Use {{TENANT_NAME}} as a placeholder; it’s replaced at runtime with your team’s name.

Option 3: check which specialist is the catch-all (voice stacks)

Every stack with specialists has exactly one catch-all, and it is assigned automatically to the first specialist added to the stack. The canvas marks it with a star icon and a “Catch-all” badge. It matters on voice: a spoken turn the router didn’t decide — a routing call that timed out or returned nothing — is answered by the catch-all. In chat there is no fallback to it; when the orchestrator matches no specialist it answers the turn itself.

There is no control in the app for moving the designation. If the wrong specialist holds it, change it through the public API: PATCH /api/v1/agent-stacks/{id} with catchAllSpecialistId, pointing at a specialist that is a member of the same stack.

Verify it worked

• Re-test the originally misrouted message in the Testing tab.
• Send 5–10 variations of the same intent (“I want a refund,” “Can I get my money back,” “Send my money back please”) and confirm they all route to the right specialist.
• As a Super Admin, expand the debug panel that appears under each reply in the test panel: its Routing section names the specialist that was picked, its confidence as a percentage, and the router’s one-clause reason.

Troubleshooting

• Symptom: A routing rule you added isn’t taking effect. Fix: routing rules are appended to the prompt, not enforced as code. The LLM still has to interpret them. Try wording the rule more directly (“Prefer Billing” rather than “Maybe consider routing to Billing”). Save and re-test.
• Symptom: On a voice stack, the catch-all specialist answers turns that match other specialists. Fix: the other specialists likely have empty Responsibility. Fill them in — the router can’t pick a specialist with no signal, and on a call an undecided turn goes to the catch-all.
• Symptom: Routing rules you didn’t write are in effect. Fix: the panel shows “Inheriting routing rules from the tenant default” (or global) when there’s no stack-level override. Saving your own stack-level rules replaces the inherited text — only one set of extra rules is ever appended to the orchestrator prompt, so copy across anything from the inherited rules you still want.

See also

• The orchestrator
• What is a specialist agent?
• Add a specialist agent