Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

docs - AI controls (#72998)

Jeff Bruemmer6504fef394ee
diff --git a/docs/README.md b/docs/README.md
index aaef69235e4..dc108429604 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -151,8 +151,12 @@ Metabase's reference documentation.
- [AI overview](./ai/start.md)
- [Metabot](./ai/metabot.md)
- [AI settings](./ai/settings.md)
+- [AI usage controls](./ai/usage-controls.md)
+- [AI customization](./ai/customization.md)
+- [AI system prompts](./ai/system-prompts.md)
- [Agent API](./ai/agent-api.md)
- [MCP server](./ai/mcp.md)
+- [Metabot in Slack](./ai/metabot-slack.md)
### Exploration and organization
diff --git a/docs/ai/customization.md b/docs/ai/customization.md
new file mode 100644
index 00000000000..965194c50e5
--- /dev/null
+++ b/docs/ai/customization.md
@@ -0,0 +1,43 @@
+---
+title: AI customization
+summary: "Change how Metabot appears in Metabase for a branded look."
+---
+
+# AI customization
+
+{% include plans-blockquote.html feature="AI customization" %}
+
+_Admin > AI > Customization_
+
+Admins can change how Metabot displays itself in Metabase.
+
+To navigate to the AI customization settings:
+
+1. Click the **grid** icon in the upper right.
+2. Click **Admin**.
+3. Go to the **AI** tab.
+4. Click on the **Customization* tab.
+
+These customizations are just surface-level. If you want to change the AI's behavior, check out [System prompts](./system-prompts.md).
+
+## Metabot's name
+
+Rename Metabot. The new name shows up everywhere Metabase refers to Metabot (sidebar, buttons, suggested prompts, empty states).
+
+## Metabot's icon
+
+Upload a custom icon. SVG or PNG with a transparent background gives the cleanest result. Max size is 1MB.
+
+## Show Metabot illustrations
+
+![Metabot illustrations](./images/metabot-illustrations.png)
+
+Once you've uploaded a custom icon, this toggle appears and controls whether the default decorative illustrations show in the Metabot chat sidebar and on the AI exploration page.
+
+## Further reading
+
+- [AI settings](./settings.md)
+- [AI usage controls](./usage-controls.md)
+- [AI system prompts](./system-prompts.md)
+- [Metabot](./metabot.md)
+
diff --git a/docs/ai/images/ai-usage-limits.png b/docs/ai/images/ai-usage-limits.png
new file mode 100644
index 00000000000..ef8ed24148b
Binary files /dev/null and b/docs/ai/images/ai-usage-limits.png differ
diff --git a/docs/ai/images/metabot-illustrations.png b/docs/ai/images/metabot-illustrations.png
new file mode 100644
index 00000000000..4a1b8b787a4
Binary files /dev/null and b/docs/ai/images/metabot-illustrations.png differ
diff --git a/docs/ai/metabot-slack.png b/docs/ai/images/metabot-slack.png
similarity index 100%
rename from docs/ai/metabot-slack.png
rename to docs/ai/images/metabot-slack.png
diff --git a/docs/ai/images/pythia-oracle-of-delphi-response.png b/docs/ai/images/pythia-oracle-of-delphi-response.png
new file mode 100644
index 00000000000..b5ec4ce16ca
Binary files /dev/null and b/docs/ai/images/pythia-oracle-of-delphi-response.png differ
diff --git a/docs/ai/metabot-slack.md b/docs/ai/metabot-slack.md
index 74b2d2a4c80..13c94829fc2 100644
--- a/docs/ai/metabot-slack.md
+++ b/docs/ai/metabot-slack.md
@@ -5,7 +5,7 @@ summary: Chat with Metabot directly in Slack to ask questions about your data, g
# Metabot in Slack
-![Metabot in Slack](./metabot-slack.png)
+![Metabot in Slack](./images/metabot-slack.png)
Chat with [Metabot](./metabot.md) in Slack. Direct message Metabot for private analysis, or mention @Metabot in a channel to collaborate with your team.
@@ -13,7 +13,7 @@ Chat with [Metabot](./metabot.md) in Slack. Direct message Metabot for private a
From Slack you can ask Metabot to:
-- **Find existing content**: Search your Metabase for questions, and dashboards. Metabot links you directly to the content in your Metabase.
+- **Find existing content**: Search your Metabase for questions and dashboards. Metabot links you directly to the content in your Metabase.
- **Answer questions**: Create ad-hoc queries from natural language to answer your questions on the spot. You can click the link to save the question in Metabase.
- **Show charts and tables**: Render static visualizations or tabular results in Slack. You can copy table results or download them as TSV.
- **Work with CSVs**: [Upload a CSV](../databases/uploads.md) to Metabase, then ask follow-up questions about the data.
@@ -61,7 +61,7 @@ Some caveats:
- For goal-based alerts, the goal line must already be configured and saved on the question. Metabot can't add goal lines.
- Metabot can't modify or delete existing alerts or subscriptions.
- Alerts and subscriptions are delivered to the Slack channel where the conversation takes place. You can't redirect them to a different channel or to email.
-- Alerts can only be set on questions not metrics or ad-hoc queries.
+- Alerts can only be set on questions, not metrics or ad-hoc queries.
## Notes on privacy
diff --git a/docs/ai/settings.md b/docs/ai/settings.md
index a362c29bfeb..d921b3aaf45 100644
--- a/docs/ai/settings.md
+++ b/docs/ai/settings.md
@@ -11,7 +11,7 @@ redirect_from:
_Admin > AI_
-This page covers admin settings for AI features in Metabase, including [Metabot](./metabot.md).
+This page covers admin settings for AI features in Metabase, including [Metabot](./metabot.md). To limit _who_ can use Metabot, see [AI controls](./usage-controls.md).
## Enable AI features
@@ -59,7 +59,7 @@ _Internal tab._
Toggle [Metabot](./metabot.md) on or off for your Metabase. Metabot is enabled by default.
-When enabled, Metabot is available to help people create questions, analyze data, and answer questions about your data. When disabled, the Metabot icon and keyboard shortcuts are hidden. Currently, Metabot is available to everyone who uses your Metabase. There's no way to scope Metabot usage per person.
+When enabled, Metabot is available to help people create questions, analyze data, and answer questions about your data. When disabled, the Metabot icon and keyboard shortcuts are hidden. To scope Metabot to specific user or tenant groups, or to cap token usage, see [AI controls](./usage-controls.md).
Toggling off Metabot only turns off in-app Metabot features. People can still use the [MCP server](./mcp.md) and [Agent API](./agent-api.md) if those are enabled.
@@ -140,6 +140,8 @@ The **Disable all AI features** toggle at the bottom of the AI features page is
Use this toggle for an instance-wide shut-off without having to disconnect your provider or change each feature's own toggle. Turn it off again to restore your previous configuration.
+For more granular options, check out [AI usage controls](./usage-controls.md).
+
## Tips for making the most of Metabot
The best thing you can do to improve Metabot's performance is to prep your data like you would for onboarding a new (human) hire to your data. In practice, this means you should:
diff --git a/docs/ai/start.md b/docs/ai/start.md
index b2e484499c6..9349f3e9e3a 100644
--- a/docs/ai/start.md
+++ b/docs/ai/start.md
@@ -14,6 +14,18 @@ Metabot is an AI assistant that helps you explore and analyze your data.
Connect an AI provider and configure AI features like Metabot.
+## [AI usage controls](./usage-controls.md)
+
+Control who can use Metabot, and set token and message limits.
+
+## [AI customization](./customization.md)
+
+Customize Metabot's name, icon, and illustrations.
+
+## [AI system prompts](./system-prompts.md)
+
+Add standing instructions for Metabot's tools.
+
## [Agent API](./agent-api.md)
A REST API for building headless, agentic BI applications on top of Metabase's semantic layer.
diff --git a/docs/ai/system-prompts.md b/docs/ai/system-prompts.md
new file mode 100644
index 00000000000..37b486d51a7
--- /dev/null
+++ b/docs/ai/system-prompts.md
@@ -0,0 +1,42 @@
+---
+title: AI system prompts
+summary: Write custom instructions for Metabot to match your organization's tone, terminology, and conventions.
+---
+
+# AI system prompts
+
+{% include plans-blockquote.html feature="AI system prompts" is_plural=true%}
+
+_Admin > AI > System prompts_
+
+System prompts let you customize instructions for Metabot. You can write a separate prompt for each of Metabot's three main tools:
+
+- **Metabot chat**: the general chat sidebar.
+- **Natural language queries**: query-builder questions generated from natural language.
+- **SQL generation**: SQL written from prompts (sidebar or [inline](./metabot.md#inline-sql-editing)).
+
+Like text cards on dashboards, prompts support [Markdown](https://www.metabase.com/learn/metabase-basics/querying-and-dashboards/dashboards/markdown).
+
+## Prompt tips
+
+Be specific, give examples, and describe your organization's conventions. You can include whatever: preferred tone, business terms and acronyms, response format expectations. For example:
+
+```
+You are Pythia, Oracle of Delphi.
+
+Our fiscal year starts on February 1. "Last quarter" means the previous fiscal quarter, not the calendar quarter.
+
+...
+```
+
+![System prompts](./images/pythia-oracle-of-delphi-response.png)
+
+System prompts can only influence Metabot's behavior, not its access. A prompt can't grant Metabot permissions it doesn't already have. The person's [data](../permissions/data.md) and [collection](../permissions/collections.md) permissions still apply.
+
+## Further reading
+
+- [AI settings](./settings.md)
+- [AI controls](./usage-controls.md)
+- [AI customization](./customization.md)
+- [Metabot](./metabot.md)
+
diff --git a/docs/ai/usage-controls.md b/docs/ai/usage-controls.md
new file mode 100644
index 00000000000..f1dda061ed7
--- /dev/null
+++ b/docs/ai/usage-controls.md
@@ -0,0 +1,80 @@
+---
+title: AI usage controls
+summary: Control who can use Metabot, and cap token or message usage by instance, group, or tenant.
+---
+
+# AI usage controls
+
+{% include plans-blockquote.html feature="AI controls" is_plural=true%}
+
+_Admin > AI > Usage controls_
+
+Once you've connected an AI provider (see [AI settings](./settings.md)), you can can control who can use Metabot and set usage budgets.
+
+- [AI feature access](#ai-feature-access): which groups can use Metabot, and which of its tools.
+- [AI usage limits](#ai-usage-limits): token or message caps by instance, group, or tenant.
+
+## AI feature access
+
+_Admin > AI > Usage controls > AI feature access_
+
+The AI feature access table lets you toggle Metabot on or off per group, and pick what Metabot can do for each group. Rows are your [internal groups](../people-and-groups/managing.md) and [tenant groups](../embedding/tenants.md); columns are Metabot capabilities.
+
+- **AI features** — the master toggle for the group. When off, people in that group won't see the Metabot icon, keyboard shortcuts, or any inline AI affordances.
+- **Chat and NLQ** — access to the Metabot [chat sidebar](./metabot.md#the-metabot-chat-sidebar) and [natural language querying](./metabot.md#how-metabot-uses-the-query-builder).
+- **SQL generation** — permission to have Metabot write or edit SQL ([from the sidebar](./metabot.md#metabot-in-the-native-editor) or [inline](./metabot.md#inline-sql-editing)).
+- **Other tools** — other AI tools like error-fixing and chart analysis.
+
+These controls are granular. If you uncheck SQL generation but leave Chat and NLQ checked, Metabot will try to answer SQL-shaped prompts with a [query builder](../questions/query-builder/editor.md) result.
+
+[Tenant](../embedding/tenants.md) groups follow the same model as regular groups.
+
+## AI usage limits
+
+_Admin > AI > Usage controls > AI usage limits_
+
+![AI usage limits](./images/ai-usage-limits.png)
+
+By default, AI usage is unlimited.
+
+These limits let you cap how much Metabot traffic Metabase allows — either across your whole instance, or for people in specific groups.
+
+### Settings and general limits
+
+- **How do you want to limit AI usage?** Choose between:
+ - **By token usage** in millions of tokens, so `2` would be 2 million tokens.
+ - **By message count**. Each message someone sends to Metabot counts as one message (not a conversation, but a single message).
+- **When should usage limits reset?** The counter resets automatically; the limit values stay put. Pick from:
+ - **Daily** (resets at midnight).
+ - **Weekly** (resets on Monday).
+ - **Monthly** (resets the 1st).
+
+You can also set:
+
+- **Total instance limit**: the total pool of tokens or messages across every person and group. Once this limit is hit, Metabot stops responding to requests until the next reset.
+- **Quota-reached message**: the error Metabot shows when someone hits a limit. Write whatever makes sense for your Metabase (like a Slack channel to ping, or a link to a request form).
+
+### Group limits
+
+Group limits set a per-_person_ cap for everyone in a user group. So, each person in the group gets the limit, not the group as a whole.
+
+If a person belongs to multiple groups, Metabase gives them the highest limit across those groups (_not_ the cumulative number across all of their groups). So if someone is in two groups, one group capped to 100 messages per week, and another group capped to 500, that person would enjoy 500 per week (not 600).
+
+### Tenant group limits
+
+You can set a limit for each [tenant group](../embedding/tenants.md#create-tenant-groups). They work just like the group limits described above.
+
+### Specific tenant limits
+
+This specific tenant limit is an aggregate pool shared by everyone in a single tenant. When the pool is empty, no one in that tenant can use Metabot for the rest of the period, regardless of how generous their tenant-group limits are.
+
+Per-tenant limits are handy for billing scenarios. Say you have a customer, Megafauna Analytics, who pays you for 100 million tokens a month. Set Megafauna Analytics's tenant limit to 100, and Metabase enforces that cap across every seat they provision.
+
+## Further reading
+
+- [AI settings](./settings.md)
+- [Metabot](./metabot.md)
+- [AI customization](./customization.md)
+- [AI system prompts](./system-prompts.md)
+- [Tenants](../embedding/tenants.md)
+- [Permissions overview](../permissions/start.md)
diff --git a/docs/configuring-metabase/slack.md b/docs/configuring-metabase/slack.md
index b4fa28314ec..7b9b51cdc8e 100644
--- a/docs/configuring-metabase/slack.md
+++ b/docs/configuring-metabase/slack.md
@@ -111,7 +111,7 @@ To check or edit your OAuth settings:
> Natural language questions in Slack require [Metabot](../ai/metabot.md).
-![Natural language questions in Slack](../ai/metabot-slack.png)
+![Natural language questions in Slack](../ai/images/metabot-slack.png)
Once you've connected Slack, you can let people chat with [Metabot](../ai/metabot.md) directly in Slack channels. For more on what Metabot can do in Slack, see [Metabot in Slack](../ai/metabot-slack.md).