> ## Documentation Index
> Fetch the complete documentation index at: https://lightdash-mintlify-ca973f84.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Getting started with AI agents
> Learn how to create and configure your first AI agent in Lightdash
Getting started with AI agents is simple - you can begin using them right away on any project in your Lightdash instance.
Organization admins must first enable AI features for users, [follow the guide](#enable-ai-features)
Set up a new AI agent in your Lightdash project, [follow the guide](#create-a-new-agent)
Use tags to control which data the agent can access, [follow the guide](#configure-your-agent).
Enable team collaboration through Slack, [follow the guide](#slack-integration)
## Enable AI features
Before users can see the **Ask AI** button and interact with AI agents, an organization admin must enable AI features. By default, AI features may not be visible to users until this step is completed.
This step requires **Organization Admin** permissions. If you're not an admin, ask your organization admin to enable AI features.
### How to enable AI features
1. Navigate to the **AI Agents Admin Panel** by going to `/ai-agents/admin/agents` in your Lightdash instance
2. In the top-right corner of the admin panel, you'll see a toggle labeled **Enable AI features for users**
3. Turn on the toggle to make AI features visible across your organization
When enabled:
* The **Ask AI** button appears on the homepage and in the navbar
* Users can interact with AI Agents
* Admins can view and manage AI threads
**Free trial available:** New organizations may see a "Free trial" badge next to this toggle, allowing you to try AI features before committing to a paid plan.
***
## Creating your first AI agent
## Go to Ask AI
This will be your entry point to working with the AI agent
## Create a new agent
Go to the agent dropdown and click ***Create new agent*** at the bottom
## Configure your agent
### Name and image
Give your agent a memorable name and visual identity
### Instructions
Provide context to guide your agent’s reasoning and ensure responses match your expectations. Your instructions can include any of the following components. Each one helps the agent understand your data, your business, and how you want insights delivered:
* **Domain knowledge** -
Describe the industry or subject area the AI should think within. Include relevant terminology, methodologies, frameworks, and technical concepts.
* **Company context** -
Explain the business background behind your analysis. Add details about your goals, product, target audience, strategy, or any constraints that influence how insights should be generated.
* **Analysis preferences** -
Clarify how you want the AI to approach analysis. Specify preferred metrics, dimensions, chart types, visualization styles, and reporting formats so results match your expectations.
* **Role & expertise** -
Tell the AI what role it should adopt (e.g., “Senior Marketing Analyst”). Include the communication style, depth of explanation, and level of decision-making authority you expect.
The more context you provide, the more accurate, relevant, and predictable your agent’s responses will be.
### Enable Data Access (optional)
Enable data access to allow your agent to analyze actual query results and provide insights based on the data. When disabled, agents work with metadata only. Learn [how to enable data access](/guides/ai-agents/data-access#how-to-enable-data-access)
### User and Group Access (optional)
Control which users and groups can access your agent through the agent settings. For detailed guidance on how to configure data access control, see [here](/guides/ai-agents/data-access#user-attributes-and-permissions)
### Tags (optional)
Use tags in the Lightdash metadata to control which metrics and dimensions the agent can access. Tags help you restrict your agent to a specific slice of your semantic layer.
1. Tag your dbt model dimensions and metrics with the tags you want - your agent will only have access to those dimensions or metrics that have matching tags.
```yaml dbt 1.10+ theme={null}
models:
- name: orders
columns:
- name: status
config:
meta:
dimension:
tags: ["ai", "sales"] # <--------- tagging the dimension
- name: location
config:
meta:
dimension:
tags: ["ai", "operations"] # <--------- tagging the dimension
- name: amount
description: Total amount of the order
config:
meta:
metrics:
total_order_amount:
type: sum
format: usd
round: 2
tags: ["ai", "finance"] # <--------- tagging the metric
```
```yaml dbt <=1.9 theme={null}
- name: orders
columns:
- name: status
meta:
dimension:
tags: ['ai', 'sales'] # <--------- tagging the dimension
- name: location
meta:
dimension:
tags: ['ai', 'operations'] # <--------- tagging the dimension
- name: amount
description: Total amount of the order
meta:
metrics:
total_order_amount:
type: sum
format: usd
round: 2
tags: ['ai', 'finance'] # <--------- tagging the metric
```
2. Add the corresponding tags to your agent settings under the Tags field. This tells the agent which tagged dimensions and metrics it should access.
3. For more technical users who want to configure tagging rules in more detail - including how tags interact with permissions and schema visibility - see the [Data access control section.](/guides/ai-agents/data-access#limiting-access-to-specific-explores-and-fields)
### Enable Self-Improvement (optional, Beta)
Allow your agent to propose changes to your semantic layer, including updating descriptions and creating new metrics. Changes are tracked in changesets for review. Read more on [self-improvement (beta)](/guides/ai-agents/self-improvement) feature.
## Setting up multiple agents
You can create multiple AI agents, each configured for different tasks, tones, languages, or teams. Each agent can have access to different datasets to focus results and give more accurate answers.
## Slack Integration
Connect your agent to Slack channels so users can interact directly from Slack. Check out all the cool ways to integrate your agent into slack [here](/guides/using-slack-integration#using-the-slack-integration)
1. Add Slack to your organization in organization settings. An admin needs to complete this step. See the [how-to guide](/references/workspace/adding-slack-integration).
2. Add the desired slack channel to your agent integration settings.
3. Add the `Lightdash for analytics` app to your desired slack channel by going to ***#channel*** --> ***Edit settings*** --> ***Integrations***:
4. Now you can interact with your AI agent in slack just as you would in the Lightdash UI. Start asking questions like "What kind of data can you access?" or "Show me total order amount over time".
5. You can also summon the bot on a thread to continue the conversation. In order for the bot to be able to respond, you need to enable this context sharing in your Lightdash Integrations settings.
Once you're set up - whether in the UI or in Slack - you can start asking questions immediately! Try asking "What kind of data can you access?" to get started:
### Slack channels: single-agent vs. multi-agent
By default, each AI agent can only be connected to one Slack channel. If you try to configure two agents in the same Slack channel via the per-agent integration path, you'll receive an error.
If you want multiple agents in the same channel, set up a **multi-agent channel** at the organization level instead. In a multi-agent channel, you don't need to specify which agent to talk to — there's only one Lightdash Slack app name to mention, and Lightdash automatically picks the best agent for your question.
#### Setting up a multi-agent Slack channel
Multi-agent channels are configured at the **organization level**, not per-agent:
1. Go to **Organization Settings → Integrations → Slack**
2. Find the **Multi-agent channel** setting in the AI Agents configuration panel
3. Select the Slack channel you want to designate as the multi-agent channel
4. Click **Save**
Once a channel is designated as the multi-agent channel, all eligible agents in your organization are automatically available in that channel. You do **not** need to add each agent individually via its own **AI Agent → Integrations → Slack** settings.
**Scoping which agents appear:** by default, agents from every project in your organization are eligible. To restrict the channel to agents from specific projects, toggle off **Allow all project agents to appear** and pick the projects you want to include.
If you see the error **"This Slack channel is already assigned to another AI agent"** while trying to attach a second agent via the per-agent integration path, that path only supports single-agent channels. Switch to the org-level multi-agent channel setup described above instead.