> ## Documentation Index
> Fetch the complete documentation index at: https://lightdash-docs-data-app-visualizations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Router

> 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="https://mintcdn.com/lightdash-docs-data-app-visualizations/Cne2o9iNFid3Uiuj/images/guides/ai-agents/ai-router-ask-ai.gif?s=430105e5a9b83f5721554642702e9322" alt="Ask AI router landing page" width="1010" height="720" data-path="images/guides/ai-agents/ai-router-ask-ai.gif" />
</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="https://mintcdn.com/lightdash-docs-data-app-visualizations/Cne2o9iNFid3Uiuj/images/guides/ai-agents/ai-router-picker.png?fit=max&auto=format&n=Cne2o9iNFid3Uiuj&q=85&s=3d76c5bdf8295842f870d61624155ad2" alt="Picker showing candidate agents" width="1153" height="792" data-path="images/guides/ai-agents/ai-router-picker.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/lightdash-docs-data-app-visualizations/Cne2o9iNFid3Uiuj/images/guides/ai-agents/ai-router-picker-dark.png?fit=max&auto=format&n=Cne2o9iNFid3Uiuj&q=85&s=7fd0b9f118fc8bde8f257d12c4e9ae4d" alt="Picker showing candidate agents" width="1151" height="790" data-path="images/guides/ai-agents/ai-router-picker-dark.png" />
</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="https://mintcdn.com/lightdash-docs-data-app-visualizations/Cne2o9iNFid3Uiuj/images/guides/ai-agents/ai-router-auto-option.png?fit=max&auto=format&n=Cne2o9iNFid3Uiuj&q=85&s=bc54e578a968f668369f424d9ec72057" alt="Auto option in the agent selector" width="1203" height="771" data-path="images/guides/ai-agents/ai-router-auto-option.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/lightdash-docs-data-app-visualizations/Cne2o9iNFid3Uiuj/images/guides/ai-agents/ai-router-auto-option-dark.png?fit=max&auto=format&n=Cne2o9iNFid3Uiuj&q=85&s=80d7468770f254e834c74f1ce9a3b9f7" alt="Auto option in the agent selector" width="1203" height="771" data-path="images/guides/ai-agents/ai-router-auto-option-dark.png" />
</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="https://mintcdn.com/lightdash-docs-data-app-visualizations/Cne2o9iNFid3Uiuj/images/guides/ai-agents/ai-router-settings-toggle.png?fit=max&auto=format&n=Cne2o9iNFid3Uiuj&q=85&s=96865aefe8e7d0c78bee4ed452e01d1a" alt="AI Router toggle in Ask AI general settings" width="1604" height="1041" data-path="images/guides/ai-agents/ai-router-settings-toggle.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/lightdash-docs-data-app-visualizations/Cne2o9iNFid3Uiuj/images/guides/ai-agents/ai-router-settings-toggle-dark.png?fit=max&auto=format&n=Cne2o9iNFid3Uiuj&q=85&s=f0df7b6a2fca9cb4c60f90a8dce1b4e8" alt="AI Router toggle in Ask AI general settings" width="1604" height="1041" data-path="images/guides/ai-agents/ai-router-settings-toggle-dark.png" />
</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.

## Router and MCP

The router is also exposed to AI assistants over [Lightdash MCP](/references/integrations/lightdash-mcp) through the **`route_agent`** tool. After setting an active project, the assistant can pass the user's prompt to `route_agent` and Lightdash automatically activates the best-fit agent for the rest of the session — no manual `list_agents` / `set_agent` step required.

Unlike the web experience, MCP routes directly to the best-fit agent even when only one agent is accessible (there's no picker in an MCP client). Routing instructions and access controls behave the same way as in the Lightdash app.