Skip to main content
Embedding is available to all Lightdash Cloud users and Enterprise On-Prem customers. Get in touch to have this feature enabled in your account.

​
Overview

AI agent embedding lets you drop a Lightdash AI agent 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
  • Viewing agent-generated charts and tables in the response
  • Saving AI-generated charts into a fixed destination space (via write actions)
  • Row-level filtering via 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:

​
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. 
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. See Lightdash.AiAgent for the full prop list and styling options.

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

AI agents overview

Learn how to design and configure agents before embedding them

React SDK reference

Full prop reference for the Lightdash.AiAgent component

Embedding reference

Complete JWT structure for AI agent embed tokens

Write actions

Configure the actor and destination space for embedded writes