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

# How to embed AI agents

> Embed a Lightdash AI agent in your application so your users can chat with their data without leaving your product.

<Info>
  Embedding is available to all Lightdash Cloud users and Enterprise On-Prem customers. [Get in touch](https://lightdash.typeform.com/to/BujU5wg5) to have this feature enabled in your account.
</Info>

## Overview

AI agent embedding lets you drop a Lightdash [AI agent](/guides/ai-agents) into your own application. Embedded users can start new threads, ask questions in natural language, and view the charts the agent generates — all scoped to a single agent and space that you control with the embed JWT.

AI agent embeds use the same JWT-based security model as dashboard and chart embeds, but with a dedicated `content.type: "aiAgent"` token. Dashboard and chart tokens cannot access AI agent routes, and an AI agent token only grants access to the agent named in the token.

### When to use AI agent embedding

* Add a "Chat with your data" experience to your customer-facing app
* Let customers ask ad-hoc questions about their own data without giving them a Lightdash login
* Scope each customer's AI session to a specific space, so the agent only sees and writes content the customer is allowed to see

### Available features

Embedded AI agents support:

* Creating and continuing threads with the agent
* Resuming a previous conversation on load, and listing an embed user's past threads to build your own thread history UI
* Viewing agent-generated charts and tables in the response
* Saving AI-generated charts into a fixed destination space (via [write actions](/references/embedding#write-actions))
* Row-level filtering via [user attributes](/references/workspace/user-attributes)

Embedded AI sessions hide non-embed UI surfaces by default — including thread history sidebars, dashboard navigation, SQL mode, MCP server tools, and user preference screens. Actions that try to open full saved-chart or dashboard pages from generated artifacts are not supported inside an embed.

## Prerequisites

Before you embed an AI agent, you need:

* An AI agent configured in your Lightdash project. See [Getting started with AI agents](/guides/ai-agents/getting-started).
* An embed secret for the project. See [Embedding quickstart](/guides/embedding/how-to-embed-content).
* A destination space where AI-generated charts will be saved.
* A service account user (or regular Lightdash user) to act as the writer for AI actions. See [Write actions](/references/embedding#write-actions).

## Embed an AI agent with the React SDK

The React SDK ships a `Lightdash.AiAgent` component that renders the agent inside an iframe. Use it when you want the agent to live inside a React or Next.js app.

```tsx theme={null}
import Lightdash from '@lightdash/sdk';

function MyAiAgent() {
  return (
    <Lightdash.AiAgent
      instanceUrl="https://app.lightdash.cloud"
      agentUuid="your-agent-uuid"
      token={generateAiAgentToken()} // Server-side function
    />
  );
}
```

You can pass a `threadUuid` to deep-link the embed straight into an existing thread, or omit it to land on the new-thread screen. Pair it with the `onThreadChange` callback to persist the active thread in your app (for example in `localStorage`) so users pick up where they left off next time they visit.

To render a list of the embed user's previous conversations, use the [`Lightdash.useLightdashAiAgentThreads`](/references/react-sdk#lightdashuselightdashaiagentthreads) hook — it calls the AI agent threads endpoint with the same embed JWT and returns only threads scoped to the JWT user and their embed space.

See [`Lightdash.AiAgent`](/references/react-sdk#lightdashaiagent) for the full prop list and styling options.

### Resuming a thread from an iframe embed

If you construct the embed URL yourself (Node, Python, Go, or any other backend), append the thread UUID as an extra path segment before the JWT fragment to resume a specific conversation:

```
{siteUrl}/embed/{projectUuid}/ai-agents/{agentUuid}/threads/{threadUuid}#{embedJwt}
```

Omit the `/{threadUuid}` segment to land on the new-thread screen. The `threadUuid` must belong to the embed user identified by the JWT — thread access is enforced server-side.

## Generate an AI agent embed token

AI agent embeds require a JWT with `content.type: "aiAgent"` and a `writeActions` claim. Generate it server-side using your embed secret.

```javascript theme={null}
import jwt from 'jsonwebtoken';

const token = jwt.sign({
  content: {
    type: 'aiAgent',
    projectUuid: 'your-project-uuid',
    agentUuid: 'your-agent-uuid',
  },
  writeActions: {
    serviceAccountUserUuid: 'service-account-user-uuid',
    spaceUuid: 'destination-space-uuid',
  },
  userAttributes: {
    tenant_id: 'tenant-abc', // Row-level filtering for the embedded viewer
  },
  user: {
    email: 'customer@example.com',
  },
}, process.env.LIGHTDASH_EMBED_SECRET, { expiresIn: '1h' });
```

**Required fields:**

* `content.type` — must be `"aiAgent"`.
* `content.agentUuid` — the agent the embed is allowed to use. Tokens cannot switch to a different agent at runtime.
* `writeActions.spaceUuid` — the space AI-generated charts are saved into, and the only space the agent can read charts or dashboards from.
* One of `writeActions.serviceAccountUserUuid` or `writeActions.userUuid` — the actor whose permissions are used when the agent runs queries and saves charts. See [Write actions](/references/embedding#write-actions).

**Optional fields:**

* `content.projectUuid` — pins the embed to a specific project.
* `userAttributes` — applies row-level filters to the agent's queries, identical to other embed types.
* `user.email` / `user.externalId` — surfaced in audit and analytics for the embedded viewer.

## Access control

AI agent embeds enforce a tight scope:

* A token issued for agent A cannot access agent B, even within the same project.
* The agent can only read dashboards and saved charts that live in `writeActions.spaceUuid`. Other content returns a not-found error.
* The agent saves new charts into `writeActions.spaceUuid`. Embedded users cannot pick a different destination.
* Query results respect the write actor's permissions and any `userAttributes` claims on the JWT, so embedded viewers only see the rows they're entitled to.
* Dashboard and chart embed tokens are rejected by AI agent routes, and AI agent tokens are rejected by dashboard or chart routes.

## Next steps

<CardGroup cols={2}>
  <Card title="AI agents overview" icon="robot" href="/guides/ai-agents">
    Learn how to design and configure agents before embedding them
  </Card>

  <Card title="React SDK reference" icon="react" href="/references/react-sdk#lightdashaiagent">
    Full prop reference for the Lightdash.AiAgent component
  </Card>

  <Card title="Embedding reference" icon="book" href="/references/embedding#ai-agent-token">
    Complete JWT structure for AI agent embed tokens
  </Card>

  <Card title="Write actions" icon="pen-to-square" href="/references/embedding#write-actions">
    Configure the actor and destination space for embedded writes
  </Card>
</CardGroup>