> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Router Agent
> Automatically route user messages to the best specialist agent using AI-powered intent detection
A router agent receives every user message and transparently delegates it to the most appropriate specialist agent. The routing is invisible to the user.
## When to Use Multi-Agent
Use multiple agents when:
* Different topics require different knowledge sources
* Response styles should vary by domain (e.g., technical vs. billing)
> **ℹ️ NOTE**: For most use cases, a single well-configured agent is sufficient. Only add complexity when it provides clear value.
## Step 1: Create Specialist Agents
Create one agent per domain. Each should have:
* **Focused knowledge sources** — only the content relevant to that domain
* **Tailored prompt** — instructions specific to the domain's tone, rules, and escalation
* **Appropriate tools** — only the tools that domain needs
**Example setup:**
| Agent | Knowledge Sources | Key Tools |
| --------------- | ------------------------------------ | ------------------------------- |
| Billing Agent | Pricing docs, billing FAQ | Ticketing (for refund requests) |
| Technical Agent | Product docs, troubleshooting guides | HTTP Request, Ticketing |
| Sales Agent | Feature pages, case studies | Send Email |
Create each agent following the standard process in **AI Studio** > **Agents** > **Create Agent**.
See [Agents](../agent/agents) for configuration details.
***
## Step 2: Create the Router Agent
The router agent receives all user messages and automatically delegates to the right specialist using AI-powered intent detection.
1. Navigate to **AI Studio** > **Agents**
2. Click the dropdown arrow next to **Create Agent** and select **Router**
3. Name it something like `Main Router` or `Support Router`
4. In the **General** tab, select the specialist agents the router can delegate to
5. Optionally set a **Default Fallback Agent** (appears below the agent list when 2+ agents are selected)
The router uses each agent's **description** to make routing decisions — no manual routing rules are needed. Make sure every specialist agent has a clear, detailed description.
***
## Step 3: Write Agent Descriptions
The router selects the right specialist based on agent descriptions. Write descriptions that clearly explain what each agent handles:
| Agent | Example Description |
| --------------- | ------------------------------------------------------------------------------------------------------------- |
| Billing Agent | Handles billing questions including invoices, payments, subscriptions, refund requests, and pricing inquiries |
| Technical Agent | Handles technical issues including bugs, errors, how-to questions, configuration, and troubleshooting |
| Sales Agent | Handles sales inquiries including pricing, feature comparisons, demos, and enterprise plans |
> **💡 TIP**: Be specific about what each agent handles. Vague descriptions like "general support" lead to inconsistent routing.
Optionally, add custom routing instructions in the router's **prompt template** for edge cases:
## Step 4: Configure Permissions
The router respects agent permissions. If a user doesn't have access to a specialist agent, that agent is excluded from the routing options. This means different users may be routed to different agents for the same message, depending on their permissions.
Make sure users have the right permissions to access the specialist agents.
See [Agent Permissions](../users/agent-permissions).
***
## Step 5: Test Routing
Use simulation testing to validate routing accuracy:
1. Navigate to **AI Studio** > **Agent Lab**
2. Create test cases covering each routing path:
| Test Message | Expected Route |
| --------------------------------------------- | ------------------------------ |
| "What's my invoice total?" | Billing Agent |
| "The app crashes when I click settings" | Technical Agent |
| "Do you offer enterprise pricing?" | Sales Agent |
| "Can I get a refund and also fix my account?" | Billing Agent (primary intent) |
3. Run the simulation and verify correct routing
4. Check that specialist agents provide accurate responses
You are good to go.
## How It Works
### Routing Logic
* **Single agent available**: The router skips the LLM call and delegates directly — no latency overhead
* **Multiple agents available**: The router calls the LLM with the list of agents and their descriptions, then delegates to the best match
* **No clear match**: Falls back to the **Default Fallback Agent** if configured, otherwise the first available non-router agent
* **Router-to-router loop prevention**: If the router accidentally selects another router, it automatically falls back to a non-router agent
### Default Fallback Agent
In the **General** tab (below the agent list), optionally set a **Default Fallback Agent**. This agent is used when the router cannot confidently determine the best match. If no fallback is configured, the router uses the first available non-router agent.
### Knowledge Sources for Routing Context
If you assign knowledge sources to the router, retrieved documents are included as context during the routing decision. This is useful when routing depends on domain-specific knowledge that the LLM wouldn't have otherwise.
**Example use case:** A router that needs to distinguish between product lines based on technical terminology found in your documentation.
### Clarification with Suggested Actions
When **Suggested Actions** is enabled on a router, the router can choose to ask the user a clarifying question instead of routing immediately. This happens when the user's intent is ambiguous and could match multiple agents.
Instead of guessing, the router presents clickable suggested actions that help the user clarify their intent. Once the user responds, the router routes to the correct specialist.
***
## Best Practices
* **Write clear agent descriptions** — the router's accuracy depends entirely on how well each agent's role is described
* **Use a fast LLM for routing** — the routing step is a simple classification task; an expensive model adds cost without improving accuracy
* **Set a default fallback** — ensures the user always gets a response, even for unexpected intents
* **Keep the agent list focused** — too many similar agents make routing harder; consolidate agents with overlapping responsibilities
* **Test with simulation** — use [Simulation Testing](../features/simulation-testing) to validate routing accuracy across different message types
* **Monitor routing quality** — review conversations in Analytics to catch mis-routed messages and adjust descriptions or routing instructions
***
## Troubleshooting
**Problem**: All messages go to one agent regardless of intent.
**Solutions**:
1. Check that each agent has a distinct, detailed **description**
2. Review the router's prompt template for rules that may bias toward one agent
3. Ensure multiple agents are selected in the router's configuration
**Problem**: Messages are routed to the wrong specialist.
**Solutions**:
1. Improve agent descriptions — make them more specific about what each agent handles and doesn't handle
2. Add explicit routing rules in the prompt template for ambiguous cases
3. Add knowledge sources to the router if routing depends on domain-specific context
**Problem**: The router fails silently.
**Solutions**:
1. Verify the router has at least one agent configured
2. Check that the user has permission to access at least one of the router's agents
***
## Related
* [Agents](./agents) — Full agent configuration reference
* [Agent Best Practices](../guides/agent-best-practices) — Design patterns and tips
* [Simulation Testing](../features/simulation-testing) — Validate routing accuracy
* [Agent Permissions](../users/agent-permissions) — Control agent access