How to embed AI agents

​

Overview

​

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 their own spaces, so the agent only sees and writes content the customer is allowed to see
• Keep one shared conversation per customer dashboard, with the agent’s changes limited to that dashboard

​

Available features

• Creating and continuing threads with the agent, and stopping or steering an answer while it streams
• Resuming a previous conversation on load, and listing past threads to build your own thread history UI
• Binding a thread to a dashboard and giving it background context
• Viewing agent-generated charts and tables in the response
• Opening saved charts and dashboards the agent references, when they live in one of the token’s write spaces or sourceSpaceUuids: charts in a side panel next to the chat, dashboards as a read-only view inside the embed
• Saving AI-generated charts into the token’s write spaces (via write actions)
• Row-level filtering via user attributes

​

Prerequisites

• An AI agent configured in your Lightdash project. See Set up AI agents.
• An embed secret for the project. See Embedding quickstart.
• At least one 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.

​

Embed an AI agent with the React SDK

import Lightdash from '@lightdash/sdk';

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

​

Resuming a thread from an iframe embed

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

​

Bind a thread to a dashboard

• A Linked dashboard card at the top of the thread opens the dashboard.
• The agent treats “this dashboard” as the bound dashboard. If the agent can create content, its changes are limited to that dashboard and the charts saved in it; see Threads bound to a dashboard.
• The thread context, up to 10,000 characters, is given to the agent on every turn as background from the user. It is never shown as a chat message, and embedded viewers can’t read it back.
• Neither the binding nor the context can be changed after the thread is created.

​

From the React SDK

​

From your backend

curl -X POST "https://app.lightdash.cloud/api/v1/projects/$PROJECT_UUID/aiAgents/$AGENT_UUID/threads" \
  -H "lightdash-embed-token: $EMBED_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "binding": { "type": "dashboard", "dashboardUuid": "'"$DASHBOARD_UUID"'" },
    "threadContext": "Summary of the previous conversation..."
  }'

​

Generate an AI agent embed token

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',
    writeSpaceUuids: ['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' });

• 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.writeSpaceUuids — the spaces the agent can create and update charts and dashboards in, and read them from. The first space is the default save target and scopes the embed’s threads.
• One of writeActions.serviceAccountUserUuid or writeActions.userUuid — the actor whose permissions are used when the agent runs queries and saves charts, and whose name appears next to messages in the chat. See Write actions.

• content.projectUuid — pins the embed to a specific project.
• content.canViewDebugInfo — shows the Debug panel on agent answers. See Debug information.
• writeActions.sourceSpaceUuids — extra spaces the agent can read, search, and bind threads to dashboards in, without being able to create or update content in them. See Add charts from other spaces.
• userAttributes — applies row-level filters to the agent’s queries, identical to other embed types.
• user.externalId / user.email — identifies the embedded viewer. Agent queries run as the write actor, so neither value is sent as a warehouse query tag; see User metadata for per-viewer attribution.

​

Access control

• A token issued for agent A cannot access agent B, even within the same project.
• The agent can read dashboards and saved charts that live in the token’s write spaces or sourceSpaceUuids, and only the spaces the write actor can view and the agent itself has access to. Other content returns a not-found error.
• Embedded viewers can open those saved charts in the chat side panel and those dashboards as a read-only view. Both run with the write actor’s permissions and the token’s userAttributes; content outside that scope is rejected.
• Charts are saved into the first write space by default. When the actor can create charts in more than one write space, the save dialog lets embedded users choose among them.
• Threads belong to the write actor and the first write space. Changing which space comes first changes which past threads viewers see.
• In a bound thread, the agent can only change the bound dashboard and the charts saved in it.
• 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.