Skip to main content

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 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.
Embedded agents
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.
Embedded agent in drawer mode

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

​
Widget Types

When embedding, choose how the agent appears in your application:
WidgetDescription
FullRenders the agent inline, filling the container you provide. Best for dedicated agent pages.
BotA floating chat bubble in the corner that expands into a chat window. Best for support-style assistants.
DrawerA slide-in panel from the right edge of the screen. Best for contextual, on-demand chat.
Embedded agent widget types

​
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. 
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;
You can use user_id instead of email in the payload for user identification based on your application’s needs.

​
2. Add the Script to Your Page

Then insert this snippet into your HTML template or single page app: 
<!-- 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.
The container <div> is only needed for the full widget. The bot and drawer widgets render their own floating UI and ignore the container.

​
Embedding Parameters

The JWT token payload can include the following parameters:
ParameterTypeDescription
agent_idstringRequired. The ID of your agent.
emailstringEmail of the user interacting with the agent (for access control and analytics).
user_idstringOptional, instead of email — a unique identifier for the user.
embedding_configobjectConfiguration for how the widget renders. See below.

​
embedding_config Options

OptionTypeDescription
widgetstringThe widget type: "full", "bot", or "drawer".

​
Example: Full Server-Side Implementation

Here’s a more complete example using Node.js / Express: 
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