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.

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.

Overview

Embedding works through a secure, token-based mechanism:

Your server generates a signed JWT token containing the agent ID and embedding configuration.
The token is used to build a signed script URL.
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.

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.

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:

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:

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:

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

Next Steps

Agents Overview - Learn how to create and configure agents
Chat Interface - Explore the conversational experience
Contact Support - Get help with embedding setup

Get Started

Reference

Deployment

Tutorial

Embedding

Embedding Agents

Overview

Widget Types

Integration Steps

1. Generate the Signed Script URL

2. Add the Script to Your Page

Embedding Parameters

`embedding_config` Options

Example: Full Server-Side Implementation

Security Considerations

Troubleshooting

Next Steps

​Embedding Agents

​Overview

​Widget Types

​Integration Steps

​1. Generate the Signed Script URL

​2. Add the Script to Your Page

​Embedding Parameters

​embedding_config Options

​Example: Full Server-Side Implementation

​Security Considerations

​Troubleshooting

​Next Steps

Embedding Agents

Overview

Widget Types

Integration Steps

1. Generate the Signed Script URL

2. Add the Script to Your Page

Embedding Parameters

`embedding_config` Options

Example: Full Server-Side Implementation

Security Considerations

Troubleshooting

Next Steps