Embedding Guide

Learn how to embed Agent5ive agents in your websites and applications.

Overview

Agent5ive provides multiple ways to embed your agents into your own websites and applications. This allows your users to interact with your agents directly from your digital properties without having to visit the Agent5ive platform.

There are three primary methods for embedding your agents:

JavaScript SDK - A lightweight script that adds a chat widget to your website
iFrame Embedding - Directly embed the agent chat interface into your webpage
React Component - Integrate the agent into your React applications
MCP Integration - Connect your agent to MCP-compatible clients like Claude Desktop

Important: Before you can embed an agent, it must be published publicly in your Agent5ive dashboard. Private agents cannot be embedded or accessed through the JavaScript SDK, iFrame embedding, or MCP integration.

Important: Agent Visibility Setting

Agents must be published publicly in your Agent5ive dashboard for embedding to work. Private agents cannot be accessed through the JavaScript SDK, iFrame embedding, or MCP integration.

To publish your agent publicly, go to your Agent5ive dashboard, select the agent, navigate to the "Deploy" tab, and click the "Publish Publicly" button.

JavaScript SDK

The JavaScript SDK is the easiest way to add your agent to any website. It creates a customizable chat widget that appears as a button in the corner of your site. When clicked, it opens a chat interface where users can interact with your agent.

Installation

To add the Agent5ive chat widget to your website, add the following script tag to the <body> section of your HTML:

<script src="https://agent5ive.com/agent5ive.js" defer></script>

Then, initialize the widget with your agent's deployment ID and configuration options:

<script>
  document.addEventListener('DOMContentLoaded', function() {
    if (window.AgentXChat && window.AgentXChat.init) {
      window.AgentXChat.init({
        deploymentId: "YOUR_DEPLOYMENT_ID",
        agentName: "Your Agent Name",
        baseUrl: "https://agent5ive.com",
        buttonText: "Chat with Agent",
        buttonColor: "#0ea5e9",
        buttonTextColor: "#ffffff",
        chatWindowColor: "#ffffff",
        chatWindowTextColor: "#000000",
        headerColor: "#0ea5e9",
        headerTextColor: "#ffffff",
        position: "right",
        bottomOffset: "20px",
        rightOffset: "20px",
        zIndex: 1000,
        initialMessage: "Hi there! How can I help you today?"
      });
    }
  });
</script>

What Users Will See

When you embed your agent using the JavaScript SDK, users will see:

Chat Button - A floating button in the corner of your website with your agent's name
Chat Interface - When clicked, a chat window opens with your agent's welcome message
Tool Indicators - If you've enabled tools like Web Browsing or Trend Search, users will see toggles for these tools
Voice Chat Option - If you've enabled voice features, users will see a microphone button
Image Upload - If you've enabled image vision, users will see an upload button

The chat interface is designed to be intuitive and user-friendly, with your agent's personality and capabilities fully preserved.

User Experience:

When a user interacts with your embedded agent, they'll experience the same high-quality conversations as on the Agent5ive platform. Your agent will maintain its personality, use its configured tools appropriately, and provide the specialized assistance you designed it for.

Voice-Enabled Agents Require Microphone Permissions

If your agent uses voice features, users will be prompted to grant microphone access when they interact with the voice functionality. Make sure to inform your users about this requirement. The JavaScript SDK automatically handles the permission requests when needed.

Configuration Options

Option	Type	Required	Description
deploymentId	string	Yes	The unique ID of your agent deployment (found in your Agent5ive dashboard)
agentName	string	Yes	The name of your agent (displayed in the chat header)
baseUrl	string	Yes	The base URL of the Agent5ive platform
buttonText	string	Yes	The text displayed on the chat button
buttonColor	string	No	The background color of the chat button (hex code)
buttonTextColor	string	No	The text color of the chat button (hex code)
chatWindowColor	string	No	The background color of the chat window (hex code)
chatWindowTextColor	string	No	The text color of the chat window (hex code)
headerColor	string	No	The background color of the chat header (hex code)
headerTextColor	string	No	The text color of the chat header (hex code)
mobileBreakpoint	number	No	The screen width (in pixels) at which to switch to mobile view
mobileFullScreen	boolean	No	Whether to display the chat in full screen on mobile devices
position	string	No	The position of the chat button ('left' or 'right')
bottomOffset	string	No	The distance from the bottom of the screen (CSS value)
rightOffset	string	No	The distance from the right of the screen (CSS value)
zIndex	number	No	The z-index of the chat widget (for layering with other elements)
initialMessage	string	No	The first message displayed from the agent when the chat is opened

JavaScript API

The Agent5ive JavaScript SDK provides additional methods for programmatically controlling the chat widget:

Method	Description
AgentXChat.open()	Opens the chat window
AgentXChat.close()	Closes the chat window
AgentXChat.toggle()	Toggles the chat window open/closed
AgentXChat.sendMessage(text)	Programmatically sends a message as the user
AgentXChat.clearConversation()	Clears the current conversation history

Example Usage

Here's an example of how to use the JavaScript API to control the chat widget:

<button onclick="window.AgentXChat.open()">Open Chat</button>
<button onclick="window.AgentXChat.close()">Close Chat</button>
<button onclick="window.AgentXChat.toggle()">Toggle Chat</button>
<button onclick="window.AgentXChat.sendMessage('Hello, agent!')">Send Message</button>
<button onclick="window.AgentXChat.clearConversation()">Clear Chat</button>

Custom Styling

You can further customize the appearance of the chat widget by adding CSS variables to your website:

:root {
  --agent5ive-primary-color: #0ea5e9;
  --agent5ive-text-color: #ffffff;
  --agent5ive-bg-color: #ffffff;
  --agent5ive-input-bg-color: #f1f5f9;
  --agent5ive-border-radius: 8px;
  --agent5ive-font-family: 'Inter', sans-serif;
}

Finding Your Deployment ID

To find your agent's deployment ID, go to your Agent5ive dashboard, select the agent you want to embed, click on the "Deploy" tab, and copy the deployment ID from the "Embed" section.

AI-Powered Theme Customization

Agent5ive offers an innovative AI-powered theme customization feature that automatically generates custom CSS styles for your embedded chat widget based on your brand identity. This ensures perfect brand alignment between your website and the agent widget without manual CSS coding.

✨ AI-Generated Brand-Aligned Themes

Simply upload your brand image (logo, website screenshot, or brand colors) and/or provide a brand description, and our AI will automatically generate matching CSS styles for your chat widget. The generated styles are hosted on Vercel Blob Storage and can be easily integrated into your embed code.

How It Works

The AI theme customization process is simple and intuitive:

Navigate to the Theme Tab - In your Agent5ive dashboard, go to the Deploy section and click on the "Embed this agent" button. Select the "Theme" tab.
Provide Brand Assets - You have two options:
- Upload a Brand Image (Optional) - Upload your logo, a website screenshot, or an image showing your brand colors (max 5MB)
- Add a Brand Description (Optional) - Describe your brand style in text (e.g., "Modern tech startup with blue and white colors, clean and minimal design")
Note: If you don't provide an image, a minimum of 5 words is required for the description.
Generate Theme - Click the generate button and let AI analyze your brand assets and create custom CSS styles
Download CSS Files - Two CSS files will be automatically generated and hosted:
- agent5ive-widget-theme.css - Styles for the widget button/popup
- agent5ive-chat-theme.css - Styles for the chat interface
Use in Your Embed Code - Reference the hosted CSS URLs in your AgentXChat initialization

Visual Example

Here's what the AI theme customization interface looks like:

What the Interface Shows:

Brand Image Upload - Area to upload your logo, website screenshot, or brand colors
Brand Description - Text field to describe your brand style and aesthetic
Theme Generated Status - Confirmation that your custom theme has been created and hosted
CSS Files Downloaded - Display of the two generated CSS files with their hosted URLs on Vercel Blob Storage
Integration Code - Example code snippet showing how to use the CSS files in your embed

Using AI-Generated Themes in Your Code

Once your theme is generated, you'll receive hosted CSS URLs that you can reference in your embed code:

<script>
  AgentXChat.init({
    deploymentId: "68e2a0a2f7c2897882a8621a",
    widgetThemeUrl: "https://pgysmrif8xfchszs.public.blob.vercel-storage.com/css/deployments/68e2a0a2f7c2897882a8621a/agent5ive-widget-theme-68e2a0a2f7c2897882a8621a.css",
    chatThemeUrl: "https://pgysmrif8xfchszs.public.blob.vercel-storage.com/css/deployments/68e2a0a2f7c2897882a8621a/agent5ive-chat-theme-68e2a0a2f7c2897882a8621a.css"
  });
</script>

Benefits of AI Theme Customization

✓Perfect Brand Alignment

AI analyzes your brand assets to create styles that perfectly match your website's look and feel

✓No CSS Knowledge Required

Skip manual CSS coding - let AI handle the styling complexity for you

✓Hosted and Ready to Use

CSS files are automatically hosted on Vercel Blob Storage - just reference the URLs

✓Flexible Input Options

Use images, text descriptions, or both to guide the AI theme generation

Regenerating Themes

If you're not satisfied with the generated theme, you can regenerate it by providing different brand assets or descriptions. Each generation creates new CSS files with updated styles. You can also override the generated CSS with your own custom versions if needed.

Advanced: Custom CSS Override

While the AI-generated themes work great out of the box, you can also download the CSS files and modify them to fine-tune specific aspects. Host your modified versions and reference them in your embed code:

<script>
  AgentXChat.init({
    deploymentId: "YOUR_DEPLOYMENT_ID",
    widgetThemeUrl: "https://your-domain.com/custom-widget-theme.css",
    chatThemeUrl: "https://your-domain.com/custom-chat-theme.css"
  });
</script>

Best Practices

Performance Considerations

Load the JavaScript SDK asynchronously to prevent blocking page rendering
Consider lazy-loading the chat widget only when needed
For iFrames, use a reasonable height to avoid excessive scrolling
Test your embedded agent on various devices and screen sizes

User Experience Tips

Set a clear initial message to guide users on how to interact with the agent
Match the chat widget's colors to your website's branding
Consider using the JavaScript SDK for a less intrusive experience
Use iFrames when you want the chat to be a central part of your page

Security Considerations

When embedding agents in your website, keep these security considerations in mind:

Content Security Policy (CSP) - If your website uses a strict CSP, you may need to addhttps://agent5ive.com to your allowed sources for scripts, frames, and connect-src
User Authentication - Consider using the userId parameter to maintain conversation context for authenticated users
Sensitive Information - Be mindful of what information your agent has access to and what it might share in conversations
Rate Limiting - The Agent5ive platform includes rate limiting to prevent abuse, but you may want to implement additional measures on your side

Getting Help

If you encounter any issues with embedding your agents, or have questions about customization options, please contact our support team at sales@agent5ive.com.

Explore Tool Integration

Documentation

Guides

Tutorials

Help