> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lightdash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI agents

> Enable AI Analyst and AI agents on a self-hosted Lightdash instance

<Info>
  <Badge icon="building-plus" color="blue" size="sm" shape="pill">Enterprise</Badge> AI Analyst and AI agents need a valid `LIGHTDASH_LICENSE_KEY` set on your instance before any of the configuration below takes effect. See [enterprise features](/self-host/enterprise-features) for applying the key.
</Info>

[AI Analyst](/agents) powers natural-language querying, AI-generated charts, and [AI agents](/agents/set-up-agents) that answer questions in-app and in Slack. To enable it on a self-hosted instance you need a model provider and the AI Analyst feature flag. Every AI feature that runs on top — [Data apps](/self-host/enterprise-features/data-apps), [AI writeback](/self-host/enterprise-features/ai-writeback), the [managed agent](#managed-agent), [MCP](/self-host/enterprise-features/mcp), and [multi-agent Slack channels](/self-host/enterprise-features#multi-agent-slack-channels) — assumes AI Analyst is enabled first.

## Prerequisites

* **Enterprise license** — `LIGHTDASH_LICENSE_KEY` must be set on your instance.
* **A model provider** — OpenAI, Anthropic, Azure AI, OpenRouter, or AWS Bedrock. OpenAI and Anthropic are the most tested.
* **Enough context budget on the chosen model** — AI Analyst sends the project's dbt catalog with every request.

## Enable AI Analyst

Set the main switch and provide credentials for one provider — the minimal setup uses OpenAI, the default provider:

```bash theme={null}
AI_COPILOT_ENABLED=true
OPENAI_API_KEY=<your-openai-api-key>
```

AI Analyst starts using the provider as soon as the backend restarts. To use a different provider, set `AI_DEFAULT_PROVIDER` (`openai`, `anthropic`, `azure`, `openrouter`, or `bedrock`) and the matching credentials — see [model providers](#model-providers) below. Optionally, set `ASK_AI_BUTTON_ENABLED=true` to add an "Ask AI" entry point in the app UI; without it, users reach agents from `/ai-agents`.

## Model providers

Each provider's exhaustive variable list lives in the [environment variables reference](/self-host/customize-deployment/environment-variables#ai-analyst); the notes below cover the choices and gotchas per provider.

### OpenAI (default)

Leave `AI_DEFAULT_PROVIDER` unset or set it to `openai`, then set `OPENAI_API_KEY`. `gpt-5.2` is the default model; override it with `OPENAI_MODEL_NAME`. All options: [OpenAI configuration](/self-host/customize-deployment/environment-variables#openai-configuration).

Behind an OpenAI-compatible LLM gateway (LiteLLM, an internal proxy), also set `OPENAI_BASE_URL` to the gateway URL and `OPENAI_MODEL_NAME` to a model your gateway exposes. If the gateway doesn't support streaming (SSE), set `OPENAI_SUPPORTS_STREAMING=false`. If it enforces Zero Data Retention, set `OPENAI_ZERO_DATA_RETENTION=true`.

### Anthropic

Set `AI_DEFAULT_PROVIDER=anthropic` and provide `ANTHROPIC_API_KEY`. `claude-sonnet-4-5` is the default model; override it with `ANTHROPIC_MODEL_NAME`. All options: [Anthropic configuration](/self-host/customize-deployment/environment-variables#anthropic-configuration).

To send Anthropic traffic through a corporate gateway, add `ANTHROPIC_BASE_URL`. See [Corporate LLM gateways](#corporate-llm-gateways) for the required URL, authentication, and API paths.

### Azure AI

Set `AI_DEFAULT_PROVIDER=azure` and point Lightdash at your deployment with `AZURE_AI_API_KEY`, `AZURE_AI_ENDPOINT`, `AZURE_AI_API_VERSION`, and `AZURE_AI_DEPLOYMENT_NAME`. For reasoning-capable deployments (e.g. `o3`), also set `AZURE_AI_DEPLOYMENT_SUPPORTS_REASONING=true`. All options: [Azure AI configuration](/self-host/customize-deployment/environment-variables#azure-ai-configuration).

### OpenRouter

Set `AI_DEFAULT_PROVIDER=openrouter` and provide `OPENROUTER_API_KEY`; override the default model with `OPENROUTER_MODEL_NAME`. All options: [OpenRouter configuration](/self-host/customize-deployment/environment-variables#openrouter-configuration).

### AWS Bedrock

Set `AI_DEFAULT_PROVIDER=bedrock` and `BEDROCK_REGION` (required — the AWS region where the target model is available), then authenticate with either `BEDROCK_API_KEY` or a `BEDROCK_ACCESS_KEY_ID`/`BEDROCK_SECRET_ACCESS_KEY` IAM pair — not both. Enable the corresponding models in the selected region before restarting Lightdash. All options: [AWS Bedrock configuration](/self-host/customize-deployment/environment-variables#aws-bedrock-configuration).

To send Bedrock traffic through a corporate gateway, add `BEDROCK_BASE_URL`. The gateway must support the Bedrock APIs used by every enabled Lightdash consumer. See [Corporate LLM gateways](#corporate-llm-gateways).

<Warning>
  `AI_DEFAULT_PROVIDER` is instance-wide. Setting it to `bedrock` also routes the selected [Data apps](/self-host/enterprise-features/data-apps) coding agent through Bedrock. `APPS_CODING_AGENT` chooses Claude or Codex; it does not change the provider.
</Warning>

## Corporate LLM gateways

Lightdash can route AI Analyst and Data app model traffic through an HTTP(S) corporate gateway. Use the base URL for the protocol your gateway exposes:

* `OPENAI_BASE_URL` for an OpenAI-compatible gateway.
* `ANTHROPIC_BASE_URL` for an Anthropic Messages gateway.
* `BEDROCK_BASE_URL` for a Bedrock-compatible gateway.

The gateway URL must include a scheme and must not contain credentials, query parameters, or a fragment. The Lightdash backend and any Data app sandbox must be able to resolve and reach the gateway hostname.

### Anthropic-compatible gateway

Configure `ANTHROPIC_BASE_URL` before the API's `/v1` segment. Lightdash accepts a trailing `/v1` and removes it, but using the unversioned base avoids ambiguity:

```bash theme={null}
AI_COPILOT_ENABLED=true
AI_DEFAULT_PROVIDER=anthropic
ANTHROPIC_API_KEY=<gateway-bearer-token>
ANTHROPIC_BASE_URL=https://llm-gateway.example.com/anthropic
```

When `ANTHROPIC_BASE_URL` is set, Lightdash sends `ANTHROPIC_API_KEY` as an `Authorization: Bearer` token. Without a gateway, direct Anthropic requests continue to use the standard `x-api-key` header.

Lightdash queries `/v1/models` to determine which models the credential can access. If the gateway does not expose the Models API, set `ANTHROPIC_AVAILABLE_MODELS` to the exact comma-separated model names the gateway accepts.

An organization-level BYO Anthropic key cannot be combined with an instance-wide `ANTHROPIC_BASE_URL`. Remove the organization key to use the gateway, or remove the gateway URL to route that organization through its own Anthropic account.

### Bedrock-compatible gateway

Configure the gateway together with the existing Bedrock provider settings:

```bash theme={null}
AI_COPILOT_ENABLED=true
AI_DEFAULT_PROVIDER=bedrock
BEDROCK_REGION=us-east-1
BEDROCK_API_KEY=<gateway-bearer-token>
BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock
```

The backend Bedrock provider still requires one supported credential mode: `BEDROCK_API_KEY`, static AWS credentials, or `BEDROCK_USE_DEFAULT_CREDENTIALS=true`. A custom Bedrock gateway used by Codex requires `BEDROCK_API_KEY`; Codex cannot combine an overridden endpoint with IAM/SigV4 credentials.

For Claude Data apps, set `CLAUDE_CODE_SKIP_BEDROCK_AUTH=true` only when the gateway accepts Claude Code requests without AWS authentication. This setting suppresses credentials inside Claude Code; it does not remove the backend provider's credential requirement.

### Required gateway APIs

One base URL can serve multiple consumers only if the gateway implements every wire protocol those consumers use:

| Consumer                                  | Required path relative to the configured base                                         |
| ----------------------------------------- | ------------------------------------------------------------------------------------- |
| AI Analyst through Anthropic              | Anthropic Messages: `/v1/messages`                                                    |
| Anthropic model discovery                 | Anthropic Models: `/v1/models`                                                        |
| AI Analyst through Bedrock                | Bedrock Converse: `/model/{model-id}/converse` or `/model/{model-id}/converse-stream` |
| Bedrock verified-answer embeddings        | Bedrock Invoke: `/model/{model-id}/invoke`                                            |
| Claude Data apps through Anthropic        | Anthropic Messages: `/v1/messages`                                                    |
| Claude Data apps through Bedrock          | Bedrock Invoke: `/model/{model-id}/invoke-with-response-stream`                       |
| Codex Data apps through a Bedrock gateway | OpenAI Responses: `/responses`                                                        |

A gateway that supports only Bedrock Converse, for example, can serve AI Analyst chat but cannot serve Claude Data app generation. For the coding-agent configuration and model naming rules, see [Data apps](/self-host/enterprise-features/data-apps).

<Note>
  These gateway settings do not reroute AI writeback, the onboarding agent, or the managed agent. When the managed agent is enabled alongside `ANTHROPIC_BASE_URL`, configure `MANAGED_AGENT_ANTHROPIC_API_KEY` separately for its direct Anthropic connection.
</Note>

### Validate before rollout

1. Confirm the Lightdash backend can resolve and connect to the gateway hostname.
2. Open AI Analyst and send a short prompt with the configured model. If model discovery fails, verify `/v1/models` or set `ANTHROPIC_AVAILABLE_MODELS`.
3. If Data apps are enabled, generate a small app with each coding agent you plan to support. This verifies the sandbox's separate network path and API wire.
4. Check gateway access logs for the expected paths in the table above. Redact authorization headers and tokens from logs.
5. Restrict direct provider egress only after both backend and sandbox traffic succeed through the gateway.

## Verified answers

Verified answers use vector embeddings to match new questions to previously validated ones. Enable embeddings with `AI_EMBEDDING_ENABLED=true` and pick an embedding provider with `AI_DEFAULT_EMBEDDING_PROVIDER` (`openai`, `bedrock`, or `azure`). The embedding provider can differ from the chat provider — see [verified answers](/agents/verified-answers) for how they're used at query time.

## Managed agent

The managed agent runs scheduled AI agent tasks on a cron. Provide `MANAGED_AGENT_ANTHROPIC_API_KEY` and, optionally, a list of allowed `MANAGED_AGENT_SKILL_IDS` and a custom `MANAGED_AGENT_SCHEDULE`. Without `ANTHROPIC_BASE_URL`, the managed agent can fall back to `ANTHROPIC_API_KEY`. When a gateway is configured, the dedicated key is required because managed-agent beta APIs continue to use Anthropic directly. See [autopilot](/agents/autopilot) for how the managed agent is used in-product.

## Costs

Self-hosting AI Analyst means you pay the selected model provider directly. Every user question sends the project's dbt catalog plus conversation history to the provider, so long conversations against large projects use noticeably more tokens than one-shot prompts. Provider dashboards expose usage — set spend limits before rolling out.

## Permissions

AI Analyst follows the standard project role model: any user with query access to a project can use AI Analyst there. Restrict access at the project level via [roles and groups](/workspace-admin/roles). To limit AI Analyst to specific projects across the instance, set `AI_COPILOT_ALLOWED_PROJECT_UUID` to a comma-separated list of project UUIDs.

## Troubleshooting

**The "Ask AI" button doesn't appear.**
Confirm `AI_COPILOT_ENABLED=true`, `LIGHTDASH_LICENSE_KEY` is set, and `ASK_AI_BUTTON_ENABLED=true` if you want the top-bar entry point. Users without query access to any project also won't see it.

**AI Analyst returns provider authentication errors.**
Check the API key for the selected `AI_DEFAULT_PROVIDER`. For Azure, verify `AZURE_AI_ENDPOINT`, `AZURE_AI_API_VERSION`, and `AZURE_AI_DEPLOYMENT_NAME` all match a deployment your key can call. For Bedrock, confirm the region has the target model enabled for your account.

**Multi-step conversations fail against an OpenAI-compatible gateway.**
If the gateway enforces Zero Data Retention, set `OPENAI_ZERO_DATA_RETENTION=true`. If it doesn't support SSE, set `OPENAI_SUPPORTS_STREAMING=false`.

**Verified answers never match.**
Confirm `AI_EMBEDDING_ENABLED=true` and that the embedding provider credentials are set. Tune `AI_VERIFIED_ANSWER_SIMILARITY_THRESHOLD` if legitimate matches fall below the default 0.6 similarity cutoff.