When to use
- You want to understand the difference between the Supervisor and the Specialist Agents
- A conversation was transferred to the wrong specialist (or was not transferred when it should have been)
- You adjusted an instruction in the Supervisor and it did not change the specialist's behavior
- You want to know why ClaudIA triggered (or did not trigger) a Specialist Agent in a specific conversation
About this article
In projects that use Specialist Agents, the conversation is not handled by a single generic agent: there is a Supervisor, which leads the conversation, and one or more Specialist Agents, each focused on a topic (for example, cancellation, order status, billing). When it identifies that the topic belongs to a specialist, the Supervisor transfers the handling of the response to it.
How it works
How the Supervisor decides which specialist to trigger
The Supervisor does not follow a fixed list of rules like "if the customer says X, call specialist Y". The decision is made based on the description of each Specialist Agent — it is this text that tells the Supervisor when that specialist should be called. That is why the quality of the description directly impacts routing accuracy: a vague or ambiguous description leads to incorrect triggers or to specialists that are never called.
:::info If two specialists have similar descriptions, the Supervisor may confuse the two. Keep each description as specific and exclusive as possible. :::
Why an adjustment in the Supervisor does not change the specialist's response
A common question is adding an instruction to the Supervisor configuration (for example, "always transfer to a human when the customer asks") and noticing that the Specialist Agent keeps responding the old way. This happens because the Supervisor configuration only influences the decision of who to transfer to — it is not passed on as an instruction to the chosen specialist.
If the behavior that needs to change happens inside the specialist's response (the text it sends, when it escalates to a human, etc.), the rule must be added to the configuration of that specific Specialist Agent, and not to the Supervisor's.
Using the AI Companion to write a specialist's description
On the Agents screen in the Hub, the AI Companion helps you write and refine a Specialist Agent's description/instruction from a natural-language explanation of what it should do. It is the recommended tool when the Supervisor's routing is ambiguous or when a specialist is responding outside of what is expected: instead of editing the text manually by trial and error, describe the desired behavior to the AI Companion and review the generated suggestion.
Checking the Supervisor's decision in a conversation
Each conversation has a reasoning audit available in the Hub, showing whether the Supervisor triggered a specialist in that conversation and what reason was considered in the decision. Use this audit to confirm, conversation by conversation, whether the routing happened as expected before deciding to adjust a specialist's description.
Notes
- To test routing changes before publishing, use the Playground — it lets you simulate the Supervisor and each Sub-agent in isolation, without impacting real customers.
- For the step-by-step on creating, linking, and publishing a Specialist Agent, see "How to create, edit, and publish a Specialist Agent".