Skip to content

Commit d35800d

Browse files
tatianainamatatianainama
committed
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.
1 parent fa8875a commit d35800d

4 files changed

Lines changed: 134 additions & 1 deletion

File tree

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -148,6 +148,7 @@
148148
"guides/ai-agents",
149149
"guides/ai-agents/getting-started",
150150
"guides/ai-agents/using-ai-agents",
151+
"guides/ai-agents/ai-router",
151152
"guides/ai-agents/agent-memory",
152153
"guides/ai-agents/verified-answers",
153154
"guides/ai-agents/evaluations",

‎guides/ai-agents.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,9 @@ This guide covers everything you need to know about AI agents in Lightdash:
2424
</Card>
2525
<Card title="Using AI agents" icon="comment" horizontal href="/guides/ai-agents/using-ai-agents">
2626

27+
</Card>
28+
<Card title="AI Router" icon="route" horizontal href="/guides/ai-agents/ai-router">
29+
2730
</Card>
2831
<Card title="Agent memory" icon="brain" horizontal href="/guides/ai-agents/agent-memory">
2932

@@ -55,6 +58,7 @@ This guide covers everything you need to know about AI agents in Lightdash:
5558

5659
- **Natural language queries** - Ask questions in plain English and get instant answers
5760
- **Ask from a chart or dashboard** - Launch a conversation with the chart or dashboard you're viewing already pinned as context
61+
- **AI Router** - Automatically send each question to the best-fit agent, so users don't have to pick one first
5862
- **Automatic visualizations** - Get charts, tables, and dashboards generated based on your questions
5963
- **Slack integration** - Collaborate with your team directly in Slack channels
6064
- **Memory and learning** - Agents remember corrections and improve over time

‎guides/ai-agents/ai-router.mdx‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: "AI Router"
3+
sidebarTitle: "AI Router"
4+
description: "Automatically route questions to the best-fit agent, so users don't have to pick one first."
5+
---
6+
7+
<Info>
8+
The AI Router is part of the AI agents add-on. [View pricing](https://www.lightdash.com/pricing)
9+
</Info>
10+
11+
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.
12+
13+
The router looks at each agent's description, instructions, data access, and verified questions to decide where a question should go. When it's confident, it routes the question straight to the right agent and starts the conversation. When it isn't, it shows a short picker so the user can choose — with the recommended agent highlighted.
14+
15+
<Note>
16+
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.
17+
</Note>
18+
19+
{/* TODO: add screenshot of the "Ask AI" router landing page (hero input + "Finding the right agent…" state) */}
20+
<Frame>
21+
<img src="/images/guides/ai-agents/ai-router-ask-ai.png" alt="Ask AI router landing page" />
22+
</Frame>
23+
24+
## When the router runs
25+
26+
The router needs **at least two agents the user can access** in a project. With a single accessible agent there's nothing to route between, so Lightdash opens that agent directly.
27+
28+
Where a user lands when they open **Ask AI** depends on their setup:
29+
30+
| Situation | What happens |
31+
| --- | --- |
32+
| No agents accessible | Welcome / empty state |
33+
| Exactly one agent | That agent opens directly |
34+
| A [default agent](/guides/ai-agents/using-ai-agents#faqs) is set | The default agent opens (takes precedence over the router) |
35+
| Two or more agents, no default set, router enabled | The **Ask AI** router page opens |
36+
37+
If you've set a default agent but want the router to decide instead, choose **Auto** from the agent dropdown — see [Using Auto](#using-auto) below.
38+
39+
## Enabling the router
40+
41+
The router is configured at the **organization level** and requires **Organization Admin** permissions.
42+
43+
<Steps>
44+
<Step title="Open AI settings">
45+
Go to **Settings → Organization Settings → Ask AI → General**.
46+
</Step>
47+
<Step title="Make sure AI features are on">
48+
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."*
49+
</Step>
50+
<Step title="Turn on the AI Router">
51+
Toggle on **AI Router** — *"Route user questions to the best agent automatically, instead of asking users to pick."*
52+
</Step>
53+
</Steps>
54+
55+
{/* TODO: add screenshot of the Ask AI → General settings page showing the "Enable AI features for users" and "AI Router" toggles */}
56+
<Frame>
57+
<img src="/images/guides/ai-agents/ai-router-settings-toggle.png" alt="AI Router toggle in Ask AI general settings" />
58+
</Frame>
59+
60+
## Routing instructions
61+
62+
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.
63+
64+
<Steps>
65+
<Step title="Open routing instructions">
66+
With the router enabled, scroll down on the **Ask AI → General** page to the **Routing instructions** card.
67+
</Step>
68+
<Step title="Pick a project">
69+
Choose the project these instructions apply to. Routing instructions are scoped per project.
70+
</Step>
71+
<Step title="Write your rules">
72+
Describe how questions should be directed. Type **@** to tag a specific agent, then click **Save instructions**.
73+
</Step>
74+
</Steps>
75+
76+
{/* TODO: add screenshot of the Routing instructions editor with an @-tagged agent */}
77+
<Frame>
78+
<img src="/images/guides/ai-agents/ai-router-instructions.png" alt="Routing instructions editor" />
79+
</Frame>
80+
81+
A few things to keep in mind:
82+
83+
- **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.
84+
- **Tagged agents must belong to the project.** You can only tag agents that exist in the selected project.
85+
- **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.
86+
87+
## Using Auto
88+
89+
Once the router is enabled and a project has more than one agent, an **Auto** option appears in the agent dropdown, labelled *"We'll route to the best-fit agent."*
90+
91+
Pick **Auto** to hand the next question to the router instead of a specific agent. This is also how you reach the router when you've set a default agent — the default opens first, and selecting **Auto** lets the router decide instead.
92+
93+
{/* TODO: add screenshot of the agent selector dropdown showing the "Auto" option */}
94+
<Frame>
95+
<img src="/images/guides/ai-agents/ai-router-auto-option.png" alt="Auto option in the agent selector" />
96+
</Frame>
97+
98+
## What the router considers
99+
100+
When deciding which agent should answer, the router compares the candidate agents on:
101+
102+
- **Description and instructions** — what each agent is set up to do
103+
- **Data access** — which explores and tables each agent can reach
104+
- **Verified questions** — the example questions marked as [verified answers](/guides/ai-agents/verified-answers)
105+
- **Specialization** — how focused an agent is on a particular domain
106+
107+
If you've written [routing instructions](#routing-instructions), those take priority over the router's own judgement whenever they apply.
108+
109+
For meta-questions like *"which agents are available?"*, the router skips routing and shows the picker so the user can browse and choose.
110+
111+
## The disambiguation picker
112+
113+
When the router isn't confident enough to route automatically, it shows a **"Which agent should answer?"** picker listing the candidate agents, with the suggested one badged **Recommended**. A **Why these agents?** popover explains the router's reasoning.
114+
115+
The user's choice is remembered as part of the conversation, which also feeds the analytics that show how often the router routes automatically versus falling back to the picker.
116+
117+
{/* TODO: add screenshot of the "Which agent should answer?" disambiguation picker with the Recommended badge */}
118+
<Frame>
119+
<img src="/images/guides/ai-agents/ai-router-picker.png" alt="Disambiguation picker showing candidate agents" />
120+
</Frame>
121+
122+
## Router and Slack
123+
124+
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/using-ai-agents.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,11 @@ You can assign your default agent in Ask AI by clicking the star by your agent's
123123
alt="Set Default Agent"
124124
/>
125125
</Frame>
126-
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.
126+
The default agent setting is per-user, per-project. There's no project-wide default at the moment.
127+
128+
When you have a default agent set, Ask AI opens it directly — even if the [AI Router](/guides/ai-agents/ai-router) is enabled. To let the router choose instead, pick **Auto** from the agent dropdown.
129+
130+
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.
127131

128132
## Known limitations
129133

0 commit comments

Comments
 (0)