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

# Embedding

> Embed your agents into any website, app, or third-party tool with a single line of code

# Embedding Agents

You already have the ability to **create agents on top of your lakehouse**. With **embedding**, you can take those same agents and drop them into **your own apps, websites, or any third-party tool** — with **just one line of code**.

<Frame>
  <img src="https://mintcdn.com/datazone/2Q0MAXg0d_-tzwOS/images/covers/embedded-agents.png?fit=max&auto=format&n=2Q0MAXg0d_-tzwOS&q=85&s=fbaa645070f96f560992aff7cdbdba2c" alt="Embedded agents" width="1920" height="741" data-path="images/covers/embedded-agents.png" />
</Frame>

The embedded agent connects to the **same data sources, tools, and model configuration** you set up in Datazone, so your users get the full conversational experience without ever leaving your product.

<Frame>
  <img src="https://mintcdn.com/datazone/2Q0MAXg0d_-tzwOS/images/illustrations/agent-embed-illustration.png?fit=max&auto=format&n=2Q0MAXg0d_-tzwOS&q=85&s=8ea55e0c1613aa778559599b438192f5" alt="Embedded agent in drawer mode" width="1938" height="983" data-path="images/illustrations/agent-embed-illustration.png" />
</Frame>

## Overview

Embedding works through a secure, token-based mechanism:

1. Your server generates a **signed JWT token** containing the agent ID and embedding configuration.
2. The token is used to build a **signed script URL**.
3. You drop a single `<script>` tag into your HTML, and the agent renders inside your application.

The token is signed with your **secret key** on the server, so credentials are never exposed to the browser.

<Frame>
  <video controls className="w-full aspect-video rounded-xl" autoPlay loop playsInline muted src="https://co-datazone-public.s3.amazonaws.com/datazone-docs-media-contents/EmbeddedAgentAnswer.mp4" />
</Frame>

## Widget Types

When embedding, choose how the agent appears in your application:

| Widget     | Description                                                                                              |
| ---------- | -------------------------------------------------------------------------------------------------------- |
| **Full**   | Renders the agent inline, filling the container you provide. Best for dedicated agent pages.             |
| **Bot**    | A floating chat bubble in the corner that expands into a chat window. Best for support-style assistants. |
| **Drawer** | A slide-in panel from the right edge of the screen. Best for contextual, on-demand chat.                 |

<Frame>
  <img src="https://mintcdn.com/datazone/2Q0MAXg0d_-tzwOS/images/illustrations/embedding-agent-widget-types.png?fit=max&auto=format&n=2Q0MAXg0d_-tzwOS&q=85&s=18c2f922c1a3393567d796ba38402fb9" alt="Embedded agent widget types" width="1559" height="458" data-path="images/illustrations/embedding-agent-widget-types.png" />
</Frame>

## Integration Steps

### 1. Generate the Signed Script URL

Insert this snippet into **your server code** to generate the signed script URL. The secret key must stay on the server — never expose it in client-side code.

```javascript theme={null}
const jwt = require("jsonwebtoken");

const DATAZONE_SITE_URL = "https://dev.datazone.co";
const DATAZONE_SECRET_KEY = "your_secret_key"; // Replace with your actual secret key

const payload = {
  agent_id: "your_agent_id", // Replace with your agent's ID
  email: "user@example.com", // User's email
  embedding_config: {
    widget: "drawer", // "full" | "bot" | "drawer"
  },
};

const token = jwt.sign(payload, DATAZONE_SECRET_KEY);

// Use this URL as the <script> source in your HTML
const scriptUrl = DATAZONE_SITE_URL + "/app/api/widget/agent?token=" + token;
```

<Info>
  You can use `user_id` instead of `email` in the payload for user identification based on your application's needs.
</Info>

### 2. Add the Script to Your Page

Then insert this snippet into your **HTML template or single page app**:

```html theme={null}
<!-- Required only for the "full" widget; bot/drawer ignore it -->
<div id="datazone-agent-embed-container" style="width:100%;height:100vh;"></div>

<script src="{scriptUrl}" async></script>
```

Replace `{scriptUrl}` with the signed URL generated on your server.

<Note>
  The container `<div>` is only needed for the **full** widget. The **bot** and **drawer** widgets render their own floating UI and ignore the container.
</Note>

## Embedding Parameters

The JWT token payload can include the following parameters:

| Parameter          | Type   | Description                                                                      |
| ------------------ | ------ | -------------------------------------------------------------------------------- |
| `agent_id`         | string | **Required.** The ID of your agent.                                              |
| `email`            | string | Email of the user interacting with the agent (for access control and analytics). |
| `user_id`          | string | Optional, instead of email — a unique identifier for the user.                   |
| `embedding_config` | object | Configuration for how the widget renders. See below.                             |

### `embedding_config` Options

| Option   | Type   | Description                                        |
| -------- | ------ | -------------------------------------------------- |
| `widget` | string | The widget type: `"full"`, `"bot"`, or `"drawer"`. |

## Example: Full Server-Side Implementation

Here's a more complete example using Node.js / Express:

```javascript theme={null}
const express = require("express");
const jwt = require("jsonwebtoken");
const app = express();

// Configuration
const DATAZONE_SITE_URL = "https://dev.datazone.co";
const DATAZONE_SECRET_KEY = process.env.DATAZONE_SECRET_KEY; // Store in environment variables

app.get("/agent", (req, res) => {
  // Get user information from your auth system
  const currentUser = req.user;

  // Create the token
  const payload = {
    agent_id: "6a0e502103bdcc40271925f1",
    email: currentUser.email,
    embedding_config: {
      widget: "drawer",
    },
  };

  const token = jwt.sign(payload, DATAZONE_SECRET_KEY);
  const scriptUrl = DATAZONE_SITE_URL + "/app/api/widget/agent?token=" + token;

  // Render your page with the script URL
  res.render("agent", { scriptUrl });
});

app.listen(3000, () => console.log("Server running on port 3000"));
```

## Security Considerations

* Keep your Datazone secret key secure and **never expose it in client-side code**.
* Generate tokens **server-side** and pass the complete script URL to your frontend.
* Use the `email` or `user_id` field to scope access and track usage per user.
* Set appropriate content security policies for embedding.

## Troubleshooting

If your embedded agent isn't loading correctly:

1. Check that your token is signed correctly with the right secret key.
2. Verify that the agent ID is correct.
3. For the **full** widget, ensure the `datazone-agent-embed-container` div exists on the page.
4. Look for CORS or CSP issues in your browser's developer tools.

## Next Steps

* [Agents Overview](/reference/agents/overview) - Learn how to create and configure agents
* [Chat Interface](/reference/agents/chat) - Explore the conversational experience
* [Contact Support](mailto:support@datazone.co) - Get help with embedding setup