docs(ai-agents): document AI Router and update default agent references (#732)

* docs(ai-agents): document AI Router and update default agent references

Add a dedicated AI Router page covering enabling the router, per-project
routing instructions, the Auto option, what the router considers, the
disambiguation picker, and Slack multi-agent routing. Add it to the nav
and overview, and clarify how the default agent interacts with the router.

* docs(ai-agents): trim AI Router page per review

Make 'When the router runs' concise (drop the table and empty state),
remove the 'Using Auto', 'What the router considers', and disambiguation
picker sections (screenshots cover them), and simplify the default-agent
FAQ to just link to the AI Router page.

* docs(ai-agents): wire up router screenshots

Use the Ask AI gif, add light/dark variants for the picker and settings
toggle, and drop the routing-instructions image (the settings screenshot
already shows it).

* docs(ai-agents): add light/dark variants for the Auto option screenshot

* docs(ai-agents): note that specialized agents pair well with the router

Author: tatianainama

docs.json

@@ -148,6 +148,7 @@
                   "guides/ai-agents",
                   "guides/ai-agents/getting-started",
                   "guides/ai-agents/using-ai-agents",
+                  "guides/ai-agents/ai-router",
                   "guides/ai-agents/agent-memory",
                   "guides/ai-agents/verified-answers",
                   "guides/ai-agents/evaluations",

guides/ai-agents.mdx

@@ -24,6 +24,9 @@ This guide covers everything you need to know about AI agents in Lightdash:
   </Card>
   <Card title="Using AI agents" icon="comment" horizontal href="/guides/ai-agents/using-ai-agents">
 
+  </Card>
+  <Card title="AI Router" icon="route" horizontal href="/guides/ai-agents/ai-router">
+
   </Card>
   <Card title="Agent memory" icon="brain" horizontal href="/guides/ai-agents/agent-memory">
 
@@ -55,6 +58,7 @@ This guide covers everything you need to know about AI agents in Lightdash:
 
 - **Natural language queries** - Ask questions in plain English and get instant answers
 - **Ask from a chart or dashboard** - Launch a conversation with the chart or dashboard you're viewing already pinned as context
+- **AI Router** - Automatically send each question to the best-fit agent, so users don't have to pick one first
 - **Automatic visualizations** - Get charts, tables, and dashboards generated based on your questions
 - **Slack integration** - Collaborate with your team directly in Slack channels
 - **Memory and learning** - Agents remember corrections and improve over time

guides/ai-agents/ai-router.mdx

@@ -0,0 +1,86 @@
+---
+title: "AI Router"
+sidebarTitle: "AI Router"
+description: "Automatically route questions to the best-fit agent, so users don't have to pick one first."
+---
+
+<Info>
+  The AI Router is part of the AI agents add-on. [View pricing](https://www.lightdash.com/pricing)
+</Info>
+
+When you have more than one AI agent in a project, users have to know which agent to ask. The **AI Router** removes that decision: type a question, and Lightdash picks the agent best suited to answer it.
+
+The router compares each agent's description, instructions, data access, and verified questions to decide where a question should go.
+
+<Note>
+  The router only chooses **between agents the user can already access**. It never widens an agent's data access or bypasses permissions — it only changes *which* of the user's available agents answers a given question.
+</Note>
+
+<Frame>
+  <img src="/images/guides/ai-agents/ai-router-ask-ai.gif" alt="Ask AI router landing page" />
+</Frame>
+
+## When the router runs
+
+The router needs **at least two agents you can access** in a project. With a single accessible agent there's nothing to route between, so Lightdash opens that agent directly.
+
+When the router is confident, it routes your question straight to the best agent and starts the conversation. When it isn't, it shows a short picker with the recommended agent highlighted so you can choose.
+
+<Frame>
+  <img className="block dark:hidden" src="/images/guides/ai-agents/ai-router-picker.png" alt="Picker showing candidate agents" />
+  <img className="hidden dark:block" src="/images/guides/ai-agents/ai-router-picker-dark.png" alt="Picker showing candidate agents" />
+</Frame>
+
+If you've set a [default agent](/guides/ai-agents/using-ai-agents#faqs), it opens first even when the router is enabled. Pick **Auto** from the agent dropdown to let the router decide instead.
+
+<Frame>
+  <img className="block dark:hidden" src="/images/guides/ai-agents/ai-router-auto-option.png" alt="Auto option in the agent selector" />
+  <img className="hidden dark:block" src="/images/guides/ai-agents/ai-router-auto-option-dark.png" alt="Auto option in the agent selector" />
+</Frame>
+
+## Enabling the router
+
+The router is configured at the **organization level** and requires **Organization Admin** permissions.
+
+<Steps>
+  <Step title="Open AI settings">
+    Go to **Settings → Organization Settings → Ask AI → General**.
+  </Step>
+  <Step title="Make sure AI features are on">
+    The router can only be turned on when **Enable AI features for users** is already enabled. If AI features are off, the router toggle is disabled with the hint *"Enable AI features first to use the Router."*
+  </Step>
+  <Step title="Turn on the AI Router">
+    Toggle on **AI Router** — *"Route user questions to the best agent automatically, instead of asking users to pick."*
+  </Step>
+</Steps>
+
+<Frame>
+  <img className="block dark:hidden" src="/images/guides/ai-agents/ai-router-settings-toggle.png" alt="AI Router toggle in Ask AI general settings" />
+  <img className="hidden dark:block" src="/images/guides/ai-agents/ai-router-settings-toggle-dark.png" alt="AI Router toggle in Ask AI general settings" />
+</Frame>
+
+## Routing instructions
+
+By default the router decides on its own, but you can give it **routing instructions** to steer specific kinds of questions toward specific agents — for example, *"send billing questions to the Finance agent."* Instructions are written per project and authored by admins.
+
+<Steps>
+  <Step title="Open routing instructions">
+    With the router enabled, scroll down on the **Ask AI → General** page to the **Routing instructions** card.
+  </Step>
+  <Step title="Pick a project">
+    Choose the project these instructions apply to. Routing instructions are scoped per project.
+  </Step>
+  <Step title="Write your rules">
+    Describe how questions should be directed. Type **@** to tag a specific agent, then click **Save instructions**.
+  </Step>
+</Steps>
+
+A few things to keep in mind:
+
+- **Rules are advisory.** They guide the router's choice but **never override an agent's access restrictions**. A rule can only point to agents the user can already access.
+- **Tagged agents must belong to the project.** You can only tag agents that exist in the selected project.
+- **Fewer than two agents?** You can still write and save instructions, but the router won't run in that project until at least two accessible agents exist. Lightdash shows a note when this is the case.
+
+## Router and Slack
+
+The same routing logic powers **multi-agent Slack channels**. In a multi-agent channel you mention the single Lightdash Slack app and Lightdash automatically picks the best agent for your question — no need to know which agent to address. See [Slack channels: single-agent vs. multi-agent](/guides/ai-agents/getting-started#slack-channels-single-agent-vs-multi-agent) for setup.

guides/ai-agents/best-practices.mdx

@@ -10,6 +10,8 @@ To get the most accurate and useful answers from your AI agents, follow these be
 
 Think of AI agents as your specialized analysts - each one can be configured to focus on specific areas of your business. For example, you might create a "Marketing Assistant" that only has access to marketing data like campaign performance, lead generation, and customer acquisition metrics. This focused approach ensures more accurate, relevant responses and prevents sensitive data from being accessible to the wrong teams. To find out more about how to configure specific access, see [Limiting access to specific explores/fields](/guides/ai-agents/data-access#limiting-access-to-specific-explores-and-fields).
 
+Specialized agents also work best with the [AI Router](/guides/ai-agents/ai-router) enabled: the more distinct each agent's focus, description, and data access, the more reliably the router can send each question to the right one — so users don't have to know which agent to ask.
+
 ## Document your data thoroughly
 
 Good documentation is crucial for AI to understand your data models and provide meaningful insights. The quality of the results depend on the quality of your metadata and documentation.

guides/ai-agents/using-ai-agents.mdx

@@ -124,7 +124,11 @@ You can assign your default agent in Ask AI by clicking the star by your agent's
       alt="Set Default Agent"
     />
   </Frame>
-The default agent setting is per-user, per-project. There's no project-wide default at the moment. If you haven't set a default, there's no predictable way to determine which agent appears first.
+The default agent setting is per-user, per-project. There's no project-wide default at the moment.
+
+When you have a default agent set, Ask AI opens it directly — even if the [AI Router](/guides/ai-agents/ai-router) is enabled.
+
+If you haven't set a default and the AI Router is enabled, Lightdash routes each question to the best-fit agent automatically. If the router is off and you have no default, there's no predictable way to determine which agent appears first.
 
 ## Known limitations