diff --git a/docs.json b/docs.json
index bab32159..ef04307c 100644
--- a/docs.json
+++ b/docs.json
@@ -49,7 +49,6 @@
"group": "BI feature guides",
"icon": "person-chalkboard",
"pages": [
- "guides/ai-agents",
"guides/metrics-catalog",
"references/chart-types",
"guides/how-to-create-scheduled-deliveries",
@@ -79,6 +78,20 @@
]
}
]
+ },
+ {
+ "group": "AI agents",
+ "icon": "robot",
+ "pages": [
+ "guides/ai-agents",
+ "guides/ai-agents/getting-started",
+ "guides/ai-agents/using-ai-agents",
+ "guides/ai-agents/agent-memory",
+ "guides/ai-agents/self-improvement",
+ "guides/ai-agents/best-practices",
+ "guides/ai-agents/data-access",
+ "guides/ai-agents/evaluations"
+ ]
}
]
},
diff --git a/guides/ai-agents.mdx b/guides/ai-agents.mdx
index 7c6d9853..e7b856e0 100644
--- a/guides/ai-agents.mdx
+++ b/guides/ai-agents.mdx
@@ -1,428 +1,36 @@
---
title: "AI agents"
+sidebarTitle: "Overview"
+description: "No code, no complex tools, just type what you want to know. AI Agents use your saved dashboards and the metrics you've defined in Lightdash semantic layer, so your whole team can find answers faster."
---
AI agents are available as an add-on for all plans. [View pricing](https://www.lightdash.com/pricing)
-AI agents transform the way you interact with your data by allowing you to ask questions in natural language and get answers back. Whether you're exploring data in Lightdash or collaborating with your team in Slack, AI agents make data analysis as simple as having a conversation.
-
-
-
-
-
AI agents automatically select the most relevant data models and metrics to answer your questions, build and execute queries with appropriate dimensions, metrics, and filters, and present results in the most insightful format.
-
-AI Agents in the Lightdash app will follow row-level, column-level, and table-level data access based on [user attributes](/references/user-attributes).
-
-In Slack, the AI will have the user attributes of the user who set up the agent. We plan to respect user attributes based on Slack user email in the future, reach out if you need that feature!
-
-
-
-## Get started
-
-Getting started with AI agents is simple - you can begin using them right away on any project in your Lightdash instance.
-
-### Creating your first AI agent
-
-
- 
-
-
-1. **Find the "Ask AI" button** in your project - this will be your entry point to AI agents
-2. **Create a new agent** (only admins and developers can create new AI agents)
-3. **Configure your agent:**
-
- - **Name and image** - Give your agent a memorable name and visual identity
- - **Instructions (optional)** - Provide context about your models, tables, or specific use cases to help the AI give more relevant responses. Some templates are provided to get you started.
- - **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
- - **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
- - **User and Group Access (optional)** - Control which users and groups can access your agent through the agent settings
- - **Tags (optional)** - Use dbt tags to control which metrics and dimensions the agent can access
- - **Slack Integration (optional)** - Connect your agent to Slack channels so users can interact directly from Slack
-
-Once set up, you can start asking questions immediately! Try asking "What kind of data can you access?" to get started.
-
-
- 
-
-
-## What agents can do
-
-### Core capabilities
-
-AI agents in Lightdash allow you to:
-- **Ask questions in natural language** - Simply type what you want to know about your data, like "What's our total revenue by region?" or "Show me user growth over the last 6 months"
-- **Get instant visualizations** - Receive bar charts, time series, and tables automatically generated based on your questions
-- **Explore interactively** - Follow up with additional questions, drill down into specific data points, or request different chart types
-- **Maintain conversation context** - AI agents remember your conversation history, so you can build on previous questions and refine your analysis
-- **Provide text-only responses** - Get answers in natural language when visualizations aren't needed
-- **Guide you to the right data** - Direct you to the most relevant explores or tables for your questions
-- **Discover existing content** - Find and share relevant charts and dashboards that have already been created in your project
-- **Generate complete dashboards** - Create multiple related visualizations at once that tell a cohesive story about your data, perfect for executive summaries or thematic analyses
+## What you'll learn
-As mentioned earlier, Lightdash agents use the **semantic layer** defined in your dbt models to understand your data structure, relationships, and business logic.
-This ensures that the AI generates accurate queries and visualizations based on your specific data context.
-So, *when an Agent generates an answer, the output is a semantic query, **not SQL!*** This means that you can easily swap between the conversational AI interface and the standard Lightdash exploration experience.
+This guide covers everything you need to know about AI agents in Lightdash:
-### Using AI agents in Slack
+
+
+
+
+
+
+
+
+
-Connect your AI agents to Slack for collaborative data analysis and team-wide insights sharing, here's how:
-
-1. Select or create an AI agent in your Lightdash instance
-2. Add the [Slack integration](https://docs.lightdash.com/guides/using-slack-integration#using-the-slack-integration) in your organization settings
-3. Under 'Integrations', add the channel you want to use
- {" "}
-
- 
-
-4. Tag your **Slack App** in the channel you want to use
-5. Start asking questions like "What kind of data can you access?" or "Show me total order amount over time"
-6. Get instant results directly in Slack
-
-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 enable this context sharing in your Lightdash Integrations settings.
-
-
- 
-
-
-#### Demo
-
-Watch this comprehensive demo to see AI agents in action:
-
-
-## Agent memory and learning
-
-Agent memory can be modified by admins and developers only
-
-AI agents can now learn from your corrections and feedback. When you correct an agent's response or guide it to better understand your data, the agent can automatically update its own instructions to remember these preferences for future conversations. The memory will only be saved if you approve the agent's suggested learning.
-
-### How it works
-
-- When an agent makes a mistake or you provide clarification, it can capture this feedback
-- The agent updates its instructions field with the new learning
-- All future conversations with that agent will benefit from this accumulated knowledge
-- Memories are stored directly in the agent's instructions, which you can view and edit in agent settings
-
-### What agents can learn
-
-Agents can learn various types of corrections and preferences:
-
-- **Which tables or explores to use** for specific types of queries
-- **Field selection preferences** like "always use net_revenue instead of gross_revenue when generating revenue charts"
-- **Filter logic** such as "exclude test accounts when counting customers"
-- **General preferences** about formatting, ordering, or analysis approaches
-
-## Self-Improvement
-
-
- This feature is currently in Beta. Enable it in your agent settings to start
- testing with your team.
-
-
-AI agents can now improve your semantic layer by proposing changes to your data models. When enabled, agents can update field descriptions, create new metrics, and refine your data documentation based on conversations and user feedback. All changes are tracked in changesets and can be reviewed or reverted at any time.
-
-### How it works
-
-When self-improvement is enabled, your AI agent can:
-
-1. **Propose changes** to your semantic layer during conversations
-2. **Apply changes immediately** to a changeset (batch of changes)
-3. **Track all modifications** with full history and attribution
-4. **Allow review and rejection** of changes by authorized users
-
-Changes are visible in the chat interface and can be managed through the Project Settings > Changesets page.
-
-
-
- 
-
-
- 
-
-
-
-### What agents can improve
-
-**Update descriptions** for better documentation:
-
-- Explore descriptions to clarify data sources and use cases
-- Metric descriptions to explain calculations and business logic
-- Dimension descriptions to provide field context
-
-**Create new metrics** based on conversations:
-
-- Custom aggregations derived from existing dimensions
-
-### Enabling self-improvement
-
-To enable self-improvement for an agent:
-
-1. Go to your agent settings
-2. Toggle the "Enable Self-Improvement" switch
-3. Save your changes
-
-
-
- 
-
-
-
-Only admins and developers can enable and use self-improvement
-
-### Managing changes
-
-All proposed changes are tracked in changesets, which you can access from Project Settings:
-
-**View all changes:**
-
-- Navigate to Project Settings > Changesets
-- See a complete list of proposed changes with details about what was modified
-- View who proposed each change and when
-
-
-
- 
-
-
-
-**Review changes in chat:**
-
-- Each proposed change appears as a card in the conversation
-- Click "View Changeset" to see the full details
-- Use the "Reject" button to revert changes you don't want
-
-**Revert changes:**
-
-- Individual changes can be rejected directly from the chat interface
-- Use "Revert" in the changesets page to undo specific changes
-- Use "Revert All" to undo multiple changes at once
-- If a project is re-deployed, the changeset will be applied if possible
-
-
- Once a change is reverted, the action cannot be undone. The semantic layer
- will return to its previous state for that field or metric.
-
-
-## Best practices
-
-To get the most accurate and useful answers from your AI agents, follow these best practices for preparing your data and configuring your agents.
-
-### Think specialized, not general
-
-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](#limiting-access-to-specific-explores/fields).
-
-### 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.
-
-- **Write clear, descriptive names** for metrics and dimensions
-- **Add detailed descriptions** to all metrics and dimensions explaining what they represent
-- **Include example questions** in descriptions that AI could answer with the metric
-- **Use AI hints** to provide additional context specifically for AI agents
-
-Remember: If your colleague wouldn't understand your documentation, neither will the AI agent. The more context you provide, the better the AI can interpret and analyze your data.
-
-#### Using AI hints
-
-AI hints are specialized metadata fields that provide additional context specifically for AI agents. These hints help the AI better understand your data models, business logic, and how to interpret your metrics and dimensions.
-
-
- AI hints are internal metadata used only by AI agents and are not displayed to
- users in the Lightdash interface. When both AI hints and descriptions are
- present, AI hints take precedence for AI agent prompts.
-
-
-AI hints support both string and array of strings formats. The array format allows you to organize multiple distinct pieces of information as separate hints, making them easier to read and maintain.
-
-You can add AI hints at three levels:
-
-**Model-level hints** - Provide context about the entire table:
-
-
-
-```yaml dbt 1.10+
-models:
- - name: customers
- config:
- meta:
- ai_hint:
- - This is a customers table containing customer information and derived facts
- - Use this for customer demographics, behavior analysis, and segmentation
-```
-
-```yaml dbt <=1.9
-models:
- - name: customers
- meta:
- ai_hint:
- - This is a customers table containing customer information and derived facts
- - Use this for customer demographics, behavior analysis, and segmentation
-```
-
-
-
-String format:
-
-
-
-```yaml dbt 1.10+
-models:
- - name: customers
- config:
- meta:
- ai_hint: |
- This is a customers table containing customer information and derived facts.
- Use this for customer demographics, behavior analysis, and segmentation.
-```
-
-```yaml dbt <=1.9
-models:
- - name: customers
- meta:
- ai_hint: |
- This is a customers table containing customer information and derived facts.
- Use this for customer demographics, behavior analysis, and segmentation.
-```
-
-
-
-**Dimension-level hints** - Explain individual columns:
-
-
-
-```yaml dbt 1.10+
-columns:
- - name: last_name
- config:
- meta:
- dimension:
- ai_hint:
- - Customer's last name
- - Contains PII data - use for identification but be mindful of privacy
-```
-
-```yaml dbt <=1.9
-columns:
- - name: last_name
- meta:
- dimension:
- ai_hint:
- - Customer's last name
- - Contains PII data - use for identification but be mindful of privacy
-```
-
-
-
-**Metric-level hints** - Clarify what metrics measure:
-
-
-
-```yaml dbt 1.10+
-columns:
- - name: customer_id
- config:
- meta:
- metrics:
- unique_customer_count:
- type: count_distinct
- ai_hint:
- - Unique customer count for business reporting
- - Use this for customer acquisition and retention analysis
-```
-
-```yaml dbt <=1.9
-columns:
- - name: customer_id
- meta:
- metrics:
- unique_customer_count:
- type: count_distinct
- ai_hint:
- - Unique customer count for business reporting
- - Use this for customer acquisition and retention analysis
-```
-
-
-
-### Writing effective instructions
-
-Think of your instructions as teaching your AI agent about your world. The better you explain your business context and preferences, the more useful and relevant your agent's responses will be.
-
-Focus on four key areas: what your agent should know about your industry, your team's goals and constraints, how you like data analyzed, and how results should be communicated.
-
-#### What to include
-
-- **Industry terminology and key metrics** including acronyms your team uses regularly (e.g., "CPM means Cost Per Mille, not cost per mile" or "Our ARR calculations exclude one-time setup fees")
-- **Communication style** for how results should be presented to your team (e.g., "Keep explanations simple for non-technical stakeholders" or "Always include actionable next steps")
-- **Business constraints** like regulatory requirements or budget limitations that affect decision-making
-- **Analysis preferences** your team relies on (e.g., "Always compare month-over-month growth" or "Flag any churn rates above 5% as concerning")
-- **Context for interpreting your data** (e.g., "Our Q4 always shows higher sales due to holiday promotions" or "Weekend traffic is typically 40% lower")
-
-
- **Good example - Sales Team Agent:**
- You analyze sales performance for our SaaS company. Focus on MRR, churn, and pipeline
- health. When MRR growth drops below 10% month-over-month, flag it as concerning.
- Present insights in simple terms that our sales managers can act on immediately.
- Always include trend explanations and next steps.
-
-
-#### What to avoid
-
-- **Contradictory instructions** that create confusion about priorities
-- **Overly complex rules** that are hard to follow consistently
-- **Vague guidance** like "be helpful" without explaining what that means for your situation
-- **Too many different focus areas** in one agent, remember to keep each agent focused, there are no limits on the number of agents you can create!
-- **Restating basic features**, don't tell the AI to "create charts" since it already does that
-
-
- **Poor example - Too vague:**
- Be helpful and analyze data well. Create good charts and explain things clearly.
-
-
-## Set 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.
-
-
-
-### Limiting access to specific explores and fields
-
-For each AI agent, you can configure which fields are used to answer questions using the tags you've defined in your YAML files. You can add one or many tags - fields with **any** of the tags in the list will be considered by the AI agent.
-Use tags to control which metrics and dimensions each AI agent can access. This helps focus the AI on the most relevant data for analysis and ensures agents only work with appropriate datasets. You can add tags at the model level to give access to entire explores, or at the individual metric and dimension level for more granular control.
-
-#### Adding tags at the model level
-
-Tag entire models to give your AI agent access to all metrics and dimensions within that explore:
-
-
-
-```yaml dbt 1.10+
-models:
- - name: marketing_campaigns
- config:
- meta:
- tags: ["marketing", "ai"] # <--------- tagging the entire model
- columns:
- - name: campaign_name
- config:
- meta:
- dimension:
- type: string
- - name: impressions
- config:
- meta:
- metrics:
- total_impressions:
- type: sum
-```
-
-```yaml dbt <=1.9
-models:
- - name: marketing_campaigns
- meta:
- tags: ["marketing", "ai"] # <--------- tagging the entire model
- columns:
- - name: campaign_name
- meta:
- dimension:
- type: string
- - name: impressions
- meta:
- metrics:
- total_impressions:
- type: sum
-```
-
-
-
-#### Adding tags to individual metrics & dimensions
-
-For more granular control, tag specific metrics and dimensions:
-
-
-
-```yaml dbt 1.10+
-models:
- - name: orders
- columns:
- - name: status
- config:
- meta:
- dimension:
- tags: ["ai", "sales"] # <--------- tagging the dimension
- - name: location
- config:
- meta:
- dimension:
- tags: ["ai", "operations"] # <--------- taggint 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
-- name: orders
- columns:
- - name: status
- meta:
- dimension:
- tags: ['ai', 'sales'] # <--------- tagging the dimension
- - name: location
- meta:
- dimension:
- tags: ['ai', 'operations'] # <--------- taggint 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
-```
-
-
-
-## Data Access Control
-
-AI agents offer flexible data access control to balance insights with privacy and security. By default, agents work with metadata only, but you can optionally enable data access for deeper analysis.
-
-### Data access modes
-
-**Metadata-only mode (default):**
-
-- Agents can see your data structure, field names, and model definitions
-- They can generate appropriate queries and visualizations
-- No actual data values (except for one-row query results) are shared with the agent
-- Perfect for exploring data structure and creating initial analyses
-
-**Data access enabled:**
-
-- Agents receive actual query results in addition to metadata
-- Can provide specific insights, identify trends, and analyze patterns in your data
-- Offers detailed summaries and data-driven recommendations
-- Can search for actual field values to ensure accurate filters when building visualizations
-- Only shares data when explicitly enabled per agent
-
-
- Data access is optional and controlled per agent. When disabled, agents only
- work with your data model structure and cannot see actual data values. This
- ensures sensitive information is only shared when you explicitly choose to
- enable this capability.
-
-
-
- To enable data access, go to your agent settings and toggle the "Data Access"
- option.
-
- 
-
-
-
-## User-defined evaluations
-
-Create custom evaluation suites to batch test your agent's performance and ensure consistent, high-quality responses across different scenarios.
-
-
- 
-
-
-### How evaluations work
-
-1. **Define evaluation questions** - Build a set of test questions for each agent. You can either:
- - Manually create questions that represent common use cases
- - Select responses from existing agent conversations in the admin page to add to your evaluation set
-
-
- 
-
-
-2. **Run batch tests** - Execute all prompts in your evaluation set against the agent to see how it responds
-
-3. **Review results** - Manually review the agent's responses to ensure they meet your quality standards and expectations
-
-### Using feedback to improve evaluations
-
-Encourage your team to actively use the thumbs-up/thumbs-down feature when interacting with AI agents. This feedback helps admins in two key ways:
-
-- **Identify improvement areas** - Thumbs-down responses highlight where the agent needs work
-- **Build better evaluation sets** - Filter and easily add thumbs-down responses to your evaluation suite to test fixes and prevent regressions
-
-This systematic testing approach helps you:
-
-- Verify agent performance before deploying changes
-- Ensure consistency across common queries
-
-## FAQs
-
-1. Does Lightdash store the query data?
-
-Lightdash only stores simple one-line answers so you can look back at your conversation history. We also save the basic query info to recreate these when needed. The actual data and detailed results stays in your warehouse and gets pulled fresh when the results are revisited (unless data access is enabled).
-
-2. Why can't I set multiple Agents for the same Slack channel?
-
-Since you have to mention the Slack App for your organization, and to avoid unexpected results, we don't allow multiple agents for the same slack channel. To align with best practices, we recommend one slack channel per project, so you prompt with confidence.
-
-## Known limitations
-
-
- These limitations reflect the current state of AI agents as we continue
- developing and improving the feature. Many of these constraints will be
- addressed in future releases, so stay tuned! Your feedback and feature
- requests help us prioritize what to build next.
-
+AI agents automatically select the most relevant data models and metrics to answer your questions, build and execute queries with appropriate dimensions, metrics, and filters, and present results in the most insightful format.
-### Data analysis and calculations
-As mentioned in the [FAQs](#faqs), AI Agents currently work with your dbt model metadata rather than actual data values. This means they can't perform forecasting, predictive analytics or custom statistical calculations. They also can't create [table calculations](https://docs.lightdash.com/guides/table-calculations) or [custom fields](https://docs.lightdash.com/references/custom-fields) on-the-fly.
+## Quick start
-### Query and visualizations constraints
+Ready to get started? Follow these steps:
-Results are limited by configurable query limits set at server level to ensure good performance. These limits can only be adjusted through environment variables at the moment.
-Agents can create bar charts, time series charts and tables, but don't yet support Lighdash's [full range of chart types](https://docs.lightdash.com/references/chart-types) including [custom visualizations](https://docs.lightdash.com/references/custom-charts), heat maps or bubble plots.
+
+
+ Set up a new AI agent in your Lightdash project, [read the guide]((/guides/ai-agents/getting-started)).
+
+
+ Use tags to control which data the agent can access, [read the guide]((/guides/ai-agents/getting-started#limiting-access-to-specific-explores-and-fields)).
+
+
+ Provide context to help the agent understand your business, [read the guide](/guides/ai-agents/best-practices#writing-effective-instructions).
+
+
+ Enable team collaboration through Slack, [read the guide]((/guides/ai-agents/using-ai-agents#using-ai-agents-in-slack)).
+
+
-### Data access and context
-Agent access to your data is controlled thorugh tags in your dbt models. If certain fields aren't accessible, check that they have the appropiate tags assigned to your agent.
+## Key features
-Agents don't remember context between different conversation sessions. Each chat start fresh.
+- **Natural language queries** - Ask questions in plain English and get instant answers
+- **Automatic visualizations** - Get charts and tables 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
+- **Self-improvement** - Agents can propose changes to your semantic layer (Beta)
+- **Access control** - Fine-grained control over data access and permissions
+- **Multiple agents** - Create specialized agents for different teams or use cases
diff --git a/guides/ai-agents/agent-memory.mdx b/guides/ai-agents/agent-memory.mdx
new file mode 100644
index 00000000..52a6623d
--- /dev/null
+++ b/guides/ai-agents/agent-memory.mdx
@@ -0,0 +1,24 @@
+---
+title: Agent memory and learning
+description: How AI agents learn from your corrections and feedback
+---
+
+Agent memory can be modified by admins and developers only
+
+AI agents can now learn from your corrections and feedback. When you correct an agent's response or guide it to better understand your data, the agent can automatically update its own instructions to remember these preferences for future conversations. The memory will only be saved if you approve the agent's suggested learning.
+
+## How it works
+
+- When an agent makes a mistake or you provide clarification, it can capture this feedback
+- The agent updates its instructions field with the new learning
+- All future conversations with that agent will benefit from this accumulated knowledge
+- Memories are stored directly in the agent's instructions, which you can view and edit in agent settings
+
+## What agents can learn
+
+Agents can learn various types of corrections and preferences:
+
+- **Which tables or explores to use** for specific types of queries
+- **Field selection preferences** like "always use net_revenue instead of gross_revenue when generating revenue charts"
+- **Filter logic** such as "exclude test accounts when counting customers"
+- **General preferences** about formatting, ordering, or analysis approaches
diff --git a/guides/ai-agents/best-practices.mdx b/guides/ai-agents/best-practices.mdx
new file mode 100644
index 00000000..defb07f0
--- /dev/null
+++ b/guides/ai-agents/best-practices.mdx
@@ -0,0 +1,185 @@
+---
+title: Best practices for AI agents
+sidebarTitle: Best practices
+description: Learn how to configure and optimize your AI agents for the best results
+---
+
+To get the most accurate and useful answers from your AI agents, follow these best practices for preparing your data and configuring your agents.
+
+## Think specialized, not general
+
+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/getting-started#limiting-access-to-specific-explores-and-fields).
+
+## 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.
+
+- **Write clear, descriptive names** for metrics and dimensions
+- **Add detailed descriptions** to all metrics and dimensions explaining what they represent
+- **Include example questions** in descriptions that AI could answer with the metric
+- **Use AI hints** to provide additional context specifically for AI agents
+
+Remember: If your colleague wouldn't understand your documentation, neither will the AI agent. The more context you provide, the better the AI can interpret and analyze your data.
+
+## Using AI hints
+
+AI hints are specialized metadata fields that provide additional context specifically for AI agents. These hints help the AI better understand your data models, business logic, and how to interpret your metrics and dimensions.
+
+
+ AI hints are internal metadata used only by AI agents and are not displayed to
+ users in the Lightdash interface. When both AI hints and descriptions are
+ present, AI hints take precedence for AI agent prompts.
+
+
+AI hints support both string and array of strings formats. The array format allows you to organize multiple distinct pieces of information as separate hints, making them easier to read and maintain.
+
+You can add AI hints at three levels:
+
+### Model-level hints
+
+Provide context about the entire table:
+
+
+
+```yaml dbt 1.10+
+models:
+ - name: customers
+ config:
+ meta:
+ ai_hint:
+ - This is a customers table containing customer information and derived facts
+ - Use this for customer demographics, behavior analysis, and segmentation
+```
+
+```yaml dbt <=1.9
+models:
+ - name: customers
+ meta:
+ ai_hint:
+ - This is a customers table containing customer information and derived facts
+ - Use this for customer demographics, behavior analysis, and segmentation
+```
+
+
+
+String format:
+
+
+
+```yaml dbt 1.10+
+models:
+ - name: customers
+ config:
+ meta:
+ ai_hint: |
+ This is a customers table containing customer information and derived facts.
+ Use this for customer demographics, behavior analysis, and segmentation.
+```
+
+```yaml dbt <=1.9
+models:
+ - name: customers
+ meta:
+ ai_hint: |
+ This is a customers table containing customer information and derived facts.
+ Use this for customer demographics, behavior analysis, and segmentation.
+```
+
+
+
+### Dimension-level hints
+
+Explain individual columns:
+
+
+
+```yaml dbt 1.10+
+columns:
+ - name: last_name
+ config:
+ meta:
+ dimension:
+ ai_hint:
+ - Customer's last name
+ - Contains PII data - use for identification but be mindful of privacy
+```
+
+```yaml dbt <=1.9
+columns:
+ - name: last_name
+ meta:
+ dimension:
+ ai_hint:
+ - Customer's last name
+ - Contains PII data - use for identification but be mindful of privacy
+```
+
+
+
+### Metric-level hints
+
+Clarify what metrics measure:
+
+
+
+```yaml dbt 1.10+
+columns:
+ - name: customer_id
+ config:
+ meta:
+ metrics:
+ unique_customer_count:
+ type: count_distinct
+ ai_hint:
+ - Unique customer count for business reporting
+ - Use this for customer acquisition and retention analysis
+```
+
+```yaml dbt <=1.9
+columns:
+ - name: customer_id
+ meta:
+ metrics:
+ unique_customer_count:
+ type: count_distinct
+ ai_hint:
+ - Unique customer count for business reporting
+ - Use this for customer acquisition and retention analysis
+```
+
+
+
+## Writing effective instructions
+
+Think of your instructions as teaching your AI agent about your world. The better you explain your business context and preferences, the more useful and relevant your agent's responses will be.
+
+Focus on four key areas: what your agent should know about your industry, your team's goals and constraints, how you like data analyzed, and how results should be communicated.
+
+### What to include
+
+- **Industry terminology and key metrics** including acronyms your team uses regularly (e.g., "CPM means Cost Per Mille, not cost per mile" or "Our ARR calculations exclude one-time setup fees")
+- **Communication style** for how results should be presented to your team (e.g., "Keep explanations simple for non-technical stakeholders" or "Always include actionable next steps")
+- **Business constraints** like regulatory requirements or budget limitations that affect decision-making
+- **Analysis preferences** your team relies on (e.g., "Always compare month-over-month growth" or "Flag any churn rates above 5% as concerning")
+- **Context for interpreting your data** (e.g., "Our Q4 always shows higher sales due to holiday promotions" or "Weekend traffic is typically 40% lower")
+
+
+ **Good example - Sales Team Agent:**
+ You analyze sales performance for our SaaS company. Focus on MRR, churn, and pipeline
+ health. When MRR growth drops below 10% month-over-month, flag it as concerning.
+ Present insights in simple terms that our sales managers can act on immediately.
+ Always include trend explanations and next steps.
+
+
+### What to avoid
+
+- **Contradictory instructions** that create confusion about priorities
+- **Overly complex rules** that are hard to follow consistently
+- **Vague guidance** like "be helpful" without explaining what that means for your situation
+- **Too many different focus areas** in one agent, remember to keep each agent focused, there are no limits on the number of agents you can create!
+- **Restating basic features**, don't tell the AI to "create charts" since it already does that
+
+
+ **Poor example - Too vague:**
+ Be helpful and analyze data well. Create good charts and explain things clearly.
+
diff --git a/guides/ai-agents/data-access.mdx b/guides/ai-agents/data-access.mdx
new file mode 100644
index 00000000..59246791
--- /dev/null
+++ b/guides/ai-agents/data-access.mdx
@@ -0,0 +1,121 @@
+---
+title: Data access control
+description: Understand how AI agents access and use your data
+---
+
+AI agents offer flexible data access control to balance insights with privacy and security. By default, agents work with metadata only, but you can optionally enable data access for deeper analysis.
+
+## Data access modes
+
+**Metadata-only mode (default):**
+
+- Agents can see your data structure, field names, and model definitions
+- They can generate appropriate queries and visualizations
+- No actual data values (except for one-row query results) are shared with the agent
+- Perfect for exploring data structure and creating initial analyses
+
+**Data access enabled:**
+
+- Agents receive actual query results in addition to metadata
+- Can provide specific insights, identify trends, and analyze patterns in your data
+- Offers detailed summaries and data-driven recommendations
+- Can search for actual field values to ensure accurate filters when building visualizations
+- Only shares data when explicitly enabled per agent
+
+
+ Data access is optional and controlled per agent. When disabled, agents only
+ work with your data model structure and cannot see actual data values. This
+ ensures sensitive information is only shared when you explicitly choose to
+ enable this capability.
+
+
+
+ To enable data access, go to your agent settings and toggle the "Data Access"
+ option.
+
+
+
+
+
+## User attributes and permissions
+
+AI agents automatically respect all data access controls configured through [user attributes](/references/user-attributes). This ensures that agents only access data that the user is authorized to see, maintaining your existing security policies.
+
+### How user attributes flow through AI queries
+
+When an AI agent generates and executes queries on behalf of a user, it inherits that user's attribute values and applies them to all data access:
+
+**Row-level security:**
+- Agents automatically apply `sql_filter` rules defined in your models
+- Only rows matching the user's attribute values are included in query results
+- Example: If a user has `sales_region: 'EMEA'`, the agent will only query data for that region
+
+**Column-level security:**
+- Agents respect `required_attributes` on dimensions
+- Columns the user cannot access are invisible to the agent
+- Metrics derived from restricted columns are also unavailable
+- Example: If `salary` requires `is_admin: 'true'`, non-admin users' agents cannot query salary data
+
+**Table-level security:**
+- Agents respect `required_attributes` on models
+- Tables the user cannot access are completely hidden from the agent
+- The agent cannot reference or join restricted tables
+- Example: If `payments` requires `is_admin: 'true'`, non-admin users' agents cannot query the payments table
+
+### Default behavior
+
+
+**In the Lightdash app:** AI agents automatically use the logged-in user's attributes for all queries.
+
+**In Slack:** AI agents currently use the attributes of the user who created the agent. We plan to respect user attributes based on Slack user email in the future—reach out if you need this feature!
+
+
+### How this works behind the scenes
+
+When an agent generates a query:
+
+1. The agent receives the user's complete attribute profile (both direct user attributes and group attributes)
+2. All `sql_filter` rules are automatically applied to the generated SQL
+3. Dimensions and tables with `required_attributes` are filtered from the available schema
+4. The agent only sees and can query data within the user's permissions
+
+This happens transparently—the agent doesn't need special configuration. Your existing user attribute rules automatically protect AI-generated queries just like they protect manual queries.
+
+### Example: Regional sales access
+
+Consider this model configuration:
+
+```yaml
+models:
+ - name: sales
+ meta:
+ sql_filter: ${TABLE}.region IN (${lightdash.attributes.sales_region})
+ columns:
+ - name: revenue
+ - name: customer_name
+ meta:
+ dimension:
+ required_attributes:
+ can_view_pii: "true"
+```
+
+For a user with `sales_region: 'EMEA'` and no `can_view_pii` attribute:
+
+- The agent can query `revenue` data, but only for EMEA region
+- The agent cannot see or query `customer_name` (PII restriction)
+- If the agent tries to analyze customer names, it will fail with a permissions error
+- All generated queries automatically include `WHERE region IN ('EMEA')`
+
+### Security considerations
+
+- **Metadata mode:** Even in metadata-only mode, agents respect user attributes when showing available fields
+- **Data access mode:** When data access is enabled, query results are filtered by user attributes
+- **Query generation:** Agents cannot generate queries that bypass user attribute restrictions
+- **Error handling:** If an agent attempts to access restricted data, the query fails with a permissions error
+
+
+Custom SQL in table calculations or SQL Runner can potentially bypass user attribute filters. AI agents use the standard query interface and cannot bypass these restrictions.
+
diff --git a/guides/ai-agents/evaluations.mdx b/guides/ai-agents/evaluations.mdx
new file mode 100644
index 00000000..67ff98f4
--- /dev/null
+++ b/guides/ai-agents/evaluations.mdx
@@ -0,0 +1,42 @@
+---
+title: User-defined evaluations
+description: Test and validate your AI agent's performance with custom evaluation suites
+---
+
+Create custom evaluation suites to batch test your agent's performance and ensure consistent, high-quality responses across different scenarios.
+
+
+
+
+
+## How evaluations work
+
+1. **Define evaluation questions** - Build a set of test questions for each agent. You can either:
+ - Manually create questions that represent common use cases
+ - Select responses from existing agent conversations in the admin page to add to your evaluation set
+
+
+
+
+
+2. **Run batch tests** - Execute all prompts in your evaluation set against the agent to see how it responds
+
+3. **Review results** - Manually review the agent's responses to ensure they meet your quality standards and expectations
+
+## Using feedback to improve evaluations
+
+Encourage your team to actively use the thumbs-up/thumbs-down feature when interacting with AI agents. This feedback helps admins in two key ways:
+
+- **Identify improvement areas** - Thumbs-down responses highlight where the agent needs work
+- **Build better evaluation sets** - Filter and easily add thumbs-down responses to your evaluation suite to test fixes and prevent regressions
+
+This systematic testing approach helps you:
+
+- Verify agent performance before deploying changes
+- Ensure consistency across common queries
diff --git a/guides/ai-agents/getting-started.mdx b/guides/ai-agents/getting-started.mdx
new file mode 100644
index 00000000..01199594
--- /dev/null
+++ b/guides/ai-agents/getting-started.mdx
@@ -0,0 +1,154 @@
+---
+title: Getting started with AI agents
+sidebarTitle: Getting started
+description: 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.
+
+## Creating your first AI agent
+
+
+
+
+
+1. **Find the "Ask AI" button** in your project - this will be your entry point to AI agents
+2. **Create a new agent** (only admins and developers can create new AI agents)
+3. **Configure your agent:**
+
+ - **Name and image** - Give your agent a memorable name and visual identity
+ - **Instructions (optional)** - Provide context about your models, tables, or specific use cases to help the AI give more relevant responses. Some templates are provided to get you started.
+ - **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
+ - **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
+ - **User and Group Access (optional)** - Control which users and groups can access your agent through the agent settings
+ - **Tags (optional)** - Use dbt tags to control which metrics and dimensions the agent can access
+ - **Slack Integration (optional)** - Connect your agent to Slack channels so users can interact directly from Slack
+
+Once set up, you can start asking questions immediately! Try asking "What kind of data can you access?" to get started.
+
+
+
+
+
+## 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.
+
+
+
+
+
+## Limiting access to specific explores and fields
+
+For each AI agent, you can configure which fields are used to answer questions using the tags you've defined in your YAML files. You can add one or many tags - fields with **any** of the tags in the list will be considered by the AI agent.
+
+Use tags to control which metrics and dimensions each AI agent can access. This helps focus the AI on the most relevant data for analysis and ensures agents only work with appropriate datasets. You can add tags at the model level to give access to entire explores, or at the individual metric and dimension level for more granular control.
+
+### Adding tags at the model level
+
+Tag entire models to give your AI agent access to all metrics and dimensions within that explore:
+
+
+
+```yaml dbt 1.10+
+models:
+ - name: marketing_campaigns
+ config:
+ meta:
+ tags: ["marketing", "ai"] # <--------- tagging the entire model
+ columns:
+ - name: campaign_name
+ config:
+ meta:
+ dimension:
+ type: string
+ - name: impressions
+ config:
+ meta:
+ metrics:
+ total_impressions:
+ type: sum
+```
+
+```yaml dbt <=1.9
+models:
+ - name: marketing_campaigns
+ meta:
+ tags: ["marketing", "ai"] # <--------- tagging the entire model
+ columns:
+ - name: campaign_name
+ meta:
+ dimension:
+ type: string
+ - name: impressions
+ meta:
+ metrics:
+ total_impressions:
+ type: sum
+```
+
+
+
+### Adding tags to individual metrics & dimensions
+
+For more granular control, tag specific metrics and dimensions:
+
+
+
+```yaml dbt 1.10+
+models:
+ - name: orders
+ columns:
+ - name: status
+ config:
+ meta:
+ dimension:
+ tags: ["ai", "sales"] # <--------- tagging the dimension
+ - name: location
+ config:
+ meta:
+ dimension:
+ tags: ["ai", "operations"] # <--------- taggint 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
+- name: orders
+ columns:
+ - name: status
+ meta:
+ dimension:
+ tags: ['ai', 'sales'] # <--------- tagging the dimension
+ - name: location
+ meta:
+ dimension:
+ tags: ['ai', 'operations'] # <--------- taggint 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
+```
+
+
diff --git a/guides/ai-agents/self-improvement.mdx b/guides/ai-agents/self-improvement.mdx
new file mode 100644
index 00000000..ed293cd5
--- /dev/null
+++ b/guides/ai-agents/self-improvement.mdx
@@ -0,0 +1,105 @@
+---
+title: Self-improvement
+description: Enable AI agents to improve your semantic layer automatically
+---
+
+
+ This feature is currently in Beta. Enable it in your agent settings to start
+ testing with your team.
+
+
+AI agents can now improve your semantic layer by proposing changes to your data models. When enabled, agents can update field descriptions, create new metrics, and refine your data documentation based on conversations and user feedback. All changes are tracked in changesets and can be reviewed or reverted at any time.
+
+## How it works
+
+When self-improvement is enabled, your AI agent can:
+
+1. **Propose changes** to your semantic layer during conversations
+2. **Apply changes immediately** to a changeset (batch of changes)
+3. **Track all modifications** with full history and attribution
+4. **Allow review and rejection** of changes by authorized users
+
+Changes are visible in the chat interface and can be managed through the Project Settings > Changesets page.
+
+
+
+
+
+
+
+
+
+
+## What agents can improve
+
+**Update descriptions** for better documentation:
+
+- Explore descriptions to clarify data sources and use cases
+- Metric descriptions to explain calculations and business logic
+- Dimension descriptions to provide field context
+
+**Create new metrics** based on conversations:
+
+- Custom aggregations derived from existing dimensions
+
+## Enabling self-improvement
+
+To enable self-improvement for an agent:
+
+1. Go to your agent settings
+2. Toggle the "Enable Self-Improvement" switch
+3. Save your changes
+
+
+
+
+
+
+
+Only admins and developers can enable and use self-improvement
+
+## Managing changes
+
+All proposed changes are tracked in changesets, which you can access from Project Settings:
+
+**View all changes:**
+
+- Navigate to Project Settings > Changesets
+- See a complete list of proposed changes with details about what was modified
+- View who proposed each change and when
+
+
+
+
+
+
+
+**Review changes in chat:**
+
+- Each proposed change appears as a card in the conversation
+- Click "View Changeset" to see the full details
+- Use the "Reject" button to revert changes you don't want
+
+**Revert changes:**
+
+- Individual changes can be rejected directly from the chat interface
+- Use "Revert" in the changesets page to undo specific changes
+- Use "Revert All" to undo multiple changes at once
+- If a project is re-deployed, the changeset will be applied if possible
+
+
+ Once a change is reverted, the action cannot be undone. The semantic layer
+ will return to its previous state for that field or metric.
+
diff --git a/guides/ai-agents/using-ai-agents.mdx b/guides/ai-agents/using-ai-agents.mdx
new file mode 100644
index 00000000..8482461e
--- /dev/null
+++ b/guides/ai-agents/using-ai-agents.mdx
@@ -0,0 +1,93 @@
+---
+title: Using AI agents
+description: Learn how to interact with AI agents in Lightdash and Slack
+---
+
+## Core capabilities
+
+AI agents in Lightdash allow you to:
+
+- **Ask questions in natural language** - Simply type what you want to know about your data, like "What's our total revenue by region?" or "Show me user growth over the last 6 months"
+- **Get instant visualizations** - Receive bar charts, time series, and tables automatically generated based on your questions
+- **Explore interactively** - Follow up with additional questions, drill down into specific data points, or request different chart types
+- **Maintain conversation context** - AI agents remember your conversation history, so you can build on previous questions and refine your analysis
+- **Provide text-only responses** - Get answers in natural language when visualizations aren't needed
+- **Guide you to the right data** - Direct you to the most relevant explores or tables for your questions
+- **Discover existing content** - Find and share relevant charts and dashboards that have already been created in your project
+- **Generate complete dashboards** - Create multiple related visualizations at once that tell a cohesive story about your data, perfect for executive summaries or thematic analyses
+
+As mentioned earlier, Lightdash agents use the **semantic layer** defined in your dbt models to understand your data structure, relationships, and business logic.
+This ensures that the AI generates accurate queries and visualizations based on your specific data context.
+So, *when an Agent generates an answer, the output is a semantic query, **not SQL!*** This means that you can easily swap between the conversational AI interface and the standard Lightdash exploration experience.
+
+## Using AI agents in Slack
+
+Connect your AI agents to Slack for collaborative data analysis and team-wide insights sharing, here's how:
+
+1. Select or create an AI agent in your Lightdash instance
+2. Add the [Slack integration](https://docs.lightdash.com/guides/using-slack-integration#using-the-slack-integration) in your organization settings
+3. Under 'Integrations', add the channel you want to use
+ {" "}
+
+
+
+4. Tag your **Slack App** in the channel you want to use
+5. Start asking questions like "What kind of data can you access?" or "Show me total order amount over time"
+6. Get instant results directly in Slack
+
+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 enable this context sharing in your Lightdash Integrations settings.
+
+
+
+
+
+### Demo
+
+Watch this comprehensive demo to see AI agents in action:
+
+
+
+
+
+## FAQs
+
+1. Does Lightdash store the query data?
+
+Lightdash only stores simple one-line answers so you can look back at your conversation history. We also save the basic query info to recreate these when needed. The actual data and detailed results stays in your warehouse and gets pulled fresh when the results are revisited (unless data access is enabled).
+
+2. Why can't I set multiple Agents for the same Slack channel?
+
+Since you have to mention the Slack App for your organization, and to avoid unexpected results, we don't allow multiple agents for the same slack channel. To align with best practices, we recommend one slack channel per project, so you prompt with confidence.
+
+## Known limitations
+
+
+ These limitations reflect the current state of AI agents as we continue
+ developing and improving the feature. Many of these constraints will be
+ addressed in future releases, so stay tuned! Your feedback and feature
+ requests help us prioritize what to build next.
+
+
+### Data analysis and calculations
+
+As mentioned in the [FAQs](#faqs), AI Agents currently work with your dbt model metadata rather than actual data values. This means they can't perform forecasting, predictive analytics or custom statistical calculations. They also can't create [table calculations](https://docs.lightdash.com/guides/table-calculations) or [custom fields](https://docs.lightdash.com/references/custom-fields) on-the-fly.
+
+### Query and visualizations constraints
+
+Results are limited by configurable query limits set at server level to ensure good performance. These limits can only be adjusted through environment variables at the moment.
+
+Agents can create bar charts, time series charts and tables, but don't yet support Lighdash's [full range of chart types](https://docs.lightdash.com/references/chart-types) including [custom visualizations](https://docs.lightdash.com/references/custom-charts), heat maps or bubble plots.
+
+### Data access and context
+
+Agent access to your data is controlled thorugh tags in your dbt models. If certain fields aren't accessible, check that they have the appropiate tags assigned to your agent.
+
+Agents don't remember context between different conversation sessions. Each chat start fresh.