Skip to main content
Getting started with AI agents is simple - you can begin using them right away on any project in your Lightdash instance.
1

Enable AI features (Admin)

Organization admins must first enable AI features for users, follow the guide
2

Create your first agent

Set up a new AI agent in your Lightdash project, follow the guide
3

Configure your agent

Use tags to control which data the agent can access, follow the guide.
4

Connect to Slack

Enable team collaboration through Slack, follow the guide

​
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. Go to Settings → Ask AI → General
  2. Find the toggle labeled Enable AI features for users
  3. Turn on the toggle to make AI features visible across your organization
When enabled:
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.

​
Set an organization default AI model

Admins can choose the default model (and reasoning behavior) used for new AI agent chats across the organization.
  1. Go to Organization settings → Ask AI → General.
  2. Under Default AI model, pick a model from the dropdown. Leave it empty to fall back to the system default.
  3. If the selected model supports reasoning, toggle High reasoning by default to start new chats with high reasoning enabled.
The org default applies to every new chat unless an agent overrides it or the user changes the model in the chat. Existing threads keep the model they were started with.

​
Bring your own AI providers and models

Instead of using the instance-wide Anthropic and OpenAI keys configured by your Lightdash administrator, org admins can store their organization’s own provider API keys and control which models are exposed to users. When a key is set, Ask AI routes that provider’s model calls through your org’s account — including agent chats, thread-title generation, the Slack agent path, agent readiness checks, doc summarization, the AI router, ambient AI, and data-app clarification prompts. Both the API keys and the per-provider model availability controls live in one card: AI providers & models on the Ask AI → General settings page.
This card is only visible when the org-ai-provider-api-keys feature flag is enabled for your organization. If you don’t see it under Ask AI → Settings → General, contact Lightdash support to have it turned on.

​
How to set a provider key

  1. Go to Organization settings → Ask AI → General.
  2. In the AI providers & models card, find the block for Anthropic or OpenAI.
  3. Paste your provider API key into the input and click Set key. The key is sent once and encrypted at rest — it is never returned by the API again.
  4. Once saved, the block shows a Key set badge and the input placeholder switches to a partially-redacted hint (e.g. sk-ant-api03-R2D...igAA for Anthropic, sk-...j3kl for OpenAI), similar to Anthropic’s and OpenAI’s own dashboards.
  5. To rotate a key, paste a new value and click Update. To remove a key, click Remove — the provider falls back to the instance-wide key (if configured).

​
Behavior

  • Setting a key routes that provider’s model calls through the org key. Removing the key falls back to the instance-wide configuration.
  • Providers that are not keyed at the org level continue to use the instance configuration, so you can BYO one provider without touching the other.
  • The Default AI model dropdown includes models for any provider your org has keyed, even when the instance itself has no key configured for that provider. For example, an org that stores its own OpenAI key sees OpenAI models in the dropdown even on an Anthropic-only instance.
  • Provider availability at the org level is validated against each provider’s public models API on save (with a short timeout). If the check fails, the provider fails closed — models that require the check remain hidden until it succeeds.

​
Control which models users can pick

Once at least one BYO provider key is set, each provider block gains two controls:
  • Available to users — toggle a provider off to hide all of its models from the model picker across your org. Existing agents that already reference a hidden model keep working; new selections are blocked.
  • Allowed models — a multi-select that restricts which of the provider’s models users can pick when creating or editing an agent. Leaving it empty allows every model the provider exposes.
At least one model must remain available across your org, so the settings API rejects updates that would leave zero selectable models.
When an org stores only an Anthropic key (no OpenAI key), OpenAI is automatically hidden — Lightdash will not silently fall back to the instance’s OpenAI key. Store an OpenAI key too if you want OpenAI models available.

​
Key-gated models

Some models are hidden by default and only become selectable once your BYO key can access them. Currently this applies to Claude Opus 4.8 — after you save an Anthropic key, Lightdash verifies access against Anthropic’s models API and unlocks the preset automatically.

​
Security

  • Keys are encrypted at rest using the instance’s LIGHTDASH_SECRET.
  • The settings API never returns the raw key after it’s been set. Reads only expose a providerApiKeysSet boolean per provider and the partially-redacted providerApiKeyHint.
  • Sending null for a provider removes its key.
  • Provider keys and model visibility must be updated in separate requests — the “at least one model available” check would otherwise read a stale key.

​
Scope (v1)

The org key is used for chat and agent utility calls only. The following continue to use the instance-wide keys: Agent reviews are automatically paused while an org has any BYO provider key set, so review turns never route agent data through the instance provider. Remove all BYO keys to re-enable reviews.

​
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.

​
Default model (optional)

Choose the default model and reasoning setting used for new chats with this agent. Leave the model empty to inherit the organization default. Lightdash resolves the model for a new chat in this order:
  1. The user’s per-chat selection
  2. The agent’s default model
  3. The organization default model
  4. The system default
Users can still change the model in each chat, and existing threads continue with the model they were started with.

​
Knowledge documents (optional)

Upload reference material — glossaries, metric definitions, business context, internal SOPs — that your agent can consult while answering questions. Use this for the kind of context that doesn’t fit neatly into a dbt ai_hint or your instructions. See knowledge documents best practices for guidance on what to upload.

​
Data Access

By default, agents have data access enabled so they can analyze actual query results and provide insights based on the data. You can turn it off per agent if you want metadata-only behavior. This section also holds the Pass user information toggle, which lets the agent tailor answers to who is asking. Learn more in data access control.

​
User and Group Access (optional)

By default, your agent is available to everyone in the project. While you’re still setting it up, you can keep it to admins and developers only, then open it up — to everyone, or to specific users and groups — once it’s ready. You’ll find these options under the agent’s access settings. This controls who can use the agent, which is separate from data access control (what data the agent can query).

​
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.
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

- 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
  1. Add the corresponding tags to your agent settings under the Tags field. This tells the agent which tagged dimensions and metrics it should access.
  1. 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.

​
Enable AI writeback (optional, Beta)

Allow your agent to edit your dbt project from chat — renaming metrics, adding dimensions, or updating descriptions — and open a pull request with the changes for review. Read more on the AI writeback (beta) 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
  1. Add Slack to your organization in organization settings. An admin needs to complete this step. See the how-to guide.
  2. Add the desired slack channel to your agent integration settings.
  1. Add the Lightdash for analytics app to your desired slack channel by going to #channel —> Edit settings —> Integrations:
  1. 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”.
  1. 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 pick which agent to talk to — you interact with the single Lightdash Slack app and the AI Router automatically picks the best-fit agent for each question. How you interact with the app depends on where you’re posting:
  • New message in the multi-agent channel — no @mention needed. Lightdash picks up the message automatically and routes it to the best-fit agent.
  • Reply in an existing thread — @mention the Lightdash Slack app. Without the mention, Lightdash will not respond in-thread.

​
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.