Define Routing Topics for a Specialist

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

Before you start

• Confirm the problem is actually mis-routing. Open the Testing tab, send the misrouted message, and look at the routing decision. If a different specialist would have been correct, that’s a routing problem.
• 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: use the catch-all designation

If the router still occasionally finds messages that don’t match any specialist, designate one specialist as the catch-all. The router falls back to it when nothing else matches, instead of refusing.

1. Pick the specialist that should be the catch-all (often a friendly “I’ll find someone who can help” specialist that triggers handover).
2. From the orchestrator canvas, set its catch-all flag (a star icon will appear on the canvas card).
3. Save.

Catch-all is set on the stack’s catchAllSpecialistId field; only one specialist per stack can hold it.

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.
• Watch the routing summary at the top of each turn in the test panel — it shows which specialist was picked and why.

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: Catch-all specialist gets every message, even ones that match other specialists. Fix: the other specialists likely have empty Scope. Fill in their Scopes — the router can’t pick a specialist with no signal.
• Symptom: Routing rules from a tenant or global default override your stack-level rules unexpectedly. Fix: the panel shows “Inheriting routing rules from the [tenant/global] default” when there’s no stack-level override. Add your own stack-level rules to take precedence; the inherited rules will still apply unless you explicitly override them.

See also

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