How routing works
By the end of this page you will understand exactly how each message reaches an agent — which makes every other setting in this section obvious.
Prerequisites
- A system with two or more connected agents (Connect agents).
One turn, step by step
Every message goes through the same sequence. The router stops at the first step that resolves.
Small talk stays put
Greetings, thanks, acknowledgements and goodbyes are recognised without any model call. They go to the agent already handling the conversation — or, if the conversation has just started, to the first agent in your Connected Agents list.
This keeps “hi” and “thanks” from bouncing the user between specialists. It also means list order matters a little: put your most general specialist first, so an opening “hello” lands somewhere sensible. The default action is not used for small talk.
A single member answers directly
If the system has exactly one enabled member, that agent takes every message. There’s no classification and no model call.
Otherwise, the router classifies
With two or more members, the router asks a model to pick the best agent. It’s given:
- every member’s skills — names, descriptions, tags, example queries
- your Router Prompt, if set
- your few-shot examples, if any
- the last five turns of the conversation
- which agent is currently handling the conversation, and whether it just asked a question
The model returns one agent, a confidence score, the matched skill, and a one-line reason.
Low confidence falls back
If the router can’t pick an agent confidently, it stops and applies your default action instead of guessing.
The chosen agent answers
If the answer comes from a different agent than last turn, that’s a handoff — the user may see a transition message first. The new agent receives the conversation so far, with each earlier message labelled by the agent that wrote it.
Follow-up affinity
When an agent asks the user a question, the router biases the next turn towards that same agent. A bare “yes”, “A-123” or “the second one” stays with the agent waiting for it, instead of being re-classified as a fresh topic.
The router switches away mid-question only when the user clearly changes subject.
This is why conversations feel continuous even though every turn is classified independently.
What the router card summarises
The card above Connected Agents shows the settings that shape routing at a glance — the current Default action, Handoff behaviour, and LLM Config — with the pills that open each editor.
What you can tune, in order of impact
| Lever | Use it when | Page |
|---|---|---|
| Member skills | Always start here. Most routing problems are skill problems. | Connect agents |
| Router Prompt | You need a rule skills can’t express — a priority, a tie-break, a policy. | Router Prompt |
| Few-shot overrides | A specific phrasing keeps landing on the wrong agent. | Few-shot examples |
| LLM configuration | You want a different model, or steadier decisions. | LLM settings |
| Default action | Nothing matched and you’d rather reply than guess. | Fallback & handoff |
Common issues
- A question reaches the wrong specialist — The skills of two members overlap. Sharpen the descriptions, then add an example query to the right skill.
- My few-shots and Router Prompt seem ignored — Check whether classification actually ran. One member, or a greeting-type message, skips it entirely.
- Everything falls back — No member has usable skills, so nothing scores highly enough to win.
- The conversation won’t leave one agent — That agent’s last reply ended in a question, so follow-up affinity is holding the turn. Ask a clearly different question.
Next
- Router Prompt — add rules the skills can’t express.