diff --git a/docs.json b/docs.json index 7b0d2b99..f5b12311 100644 --- a/docs.json +++ b/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", diff --git a/guides/ai-agents.mdx b/guides/ai-agents.mdx index 34edd51c..70580d73 100644 --- a/guides/ai-agents.mdx +++ b/guides/ai-agents.mdx @@ -24,6 +24,9 @@ This guide covers everything you need to know about AI agents in Lightdash: + + + @@ -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 diff --git a/guides/ai-agents/ai-router.mdx b/guides/ai-agents/ai-router.mdx new file mode 100644 index 00000000..119dc942 --- /dev/null +++ b/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." +--- + + + The AI Router is part of the AI agents add-on. [View pricing](https://www.lightdash.com/pricing) + + +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. + + + 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. + + + + Ask AI router landing page + + +## 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. + + + Picker showing candidate agents + Picker showing candidate agents + + +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. + + + Auto option in the agent selector + Auto option in the agent selector + + +## Enabling the router + +The router is configured at the **organization level** and requires **Organization Admin** permissions. + + + + Go to **Settings → Organization Settings → Ask AI → General**. + + + 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."* + + + Toggle on **AI Router** — *"Route user questions to the best agent automatically, instead of asking users to pick."* + + + + + AI Router toggle in Ask AI general settings + AI Router toggle in Ask AI general settings + + +## 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. + + + + With the router enabled, scroll down on the **Ask AI → General** page to the **Routing instructions** card. + + + Choose the project these instructions apply to. Routing instructions are scoped per project. + + + Describe how questions should be directed. Type **@** to tag a specific agent, then click **Save instructions**. + + + +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. diff --git a/guides/ai-agents/best-practices.mdx b/guides/ai-agents/best-practices.mdx index e08823f7..956db42f 100644 --- a/guides/ai-agents/best-practices.mdx +++ b/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. diff --git a/guides/ai-agents/using-ai-agents.mdx b/guides/ai-agents/using-ai-agents.mdx index 4ab65489..484fd11f 100644 --- a/guides/ai-agents/using-ai-agents.mdx +++ b/guides/ai-agents/using-ai-agents.mdx @@ -123,7 +123,11 @@ You can assign your default agent in Ask AI by clicking the star by your agent's alt="Set Default Agent" /> -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 diff --git a/images/guides/ai-agents/ai-router-ask-ai.gif b/images/guides/ai-agents/ai-router-ask-ai.gif new file mode 100644 index 00000000..d0f27195 Binary files /dev/null and b/images/guides/ai-agents/ai-router-ask-ai.gif differ diff --git a/images/guides/ai-agents/ai-router-auto-option-dark.png b/images/guides/ai-agents/ai-router-auto-option-dark.png new file mode 100644 index 00000000..8c07cdc4 Binary files /dev/null and b/images/guides/ai-agents/ai-router-auto-option-dark.png differ diff --git a/images/guides/ai-agents/ai-router-auto-option.png b/images/guides/ai-agents/ai-router-auto-option.png new file mode 100644 index 00000000..d7372e87 Binary files /dev/null and b/images/guides/ai-agents/ai-router-auto-option.png differ diff --git a/images/guides/ai-agents/ai-router-picker-dark.png b/images/guides/ai-agents/ai-router-picker-dark.png new file mode 100644 index 00000000..5ae2f4db Binary files /dev/null and b/images/guides/ai-agents/ai-router-picker-dark.png differ diff --git a/images/guides/ai-agents/ai-router-picker.png b/images/guides/ai-agents/ai-router-picker.png new file mode 100644 index 00000000..83479e8d Binary files /dev/null and b/images/guides/ai-agents/ai-router-picker.png differ diff --git a/images/guides/ai-agents/ai-router-settings-toggle-dark.png b/images/guides/ai-agents/ai-router-settings-toggle-dark.png new file mode 100644 index 00000000..587c176a Binary files /dev/null and b/images/guides/ai-agents/ai-router-settings-toggle-dark.png differ diff --git a/images/guides/ai-agents/ai-router-settings-toggle.png b/images/guides/ai-agents/ai-router-settings-toggle.png new file mode 100644 index 00000000..8548f4fd Binary files /dev/null and b/images/guides/ai-agents/ai-router-settings-toggle.png differ