Embedding Multiple Agents - Mindset AI Documentation

Overview

Mindset AI SDK 3 lets you embed multiple AI agents on a single webpage. Each agent operates independently with complete state isolation—conversations, inputs, and errors in one agent don’t affect others. This enables you to provide specialized agents for different contexts: a sales assistant in your checkout flow, a support bot in your account section, and a product expert on your catalog pages—all on the same site.

SDK 3 Required: Multi-agent embedding is available in SDK 3.

Quick Start

Include the SDK once, define multiple agents, and initialize—all agents render automatically.

<!-- Include the SDK -->
<script src="MINDSET-SERVER-URL/mindset-sdk3.umd.js"></script>

<!-- Define multiple agents -->
<mindset-agent agentUid="sales-assistant-agent-uid"></mindset-agent>
<mindset-agent agentUid="support-bot-agent-uid"></mindset-agent>

<!-- Initialize once - all agents render automatically -->
<script>
  window.mindset.init({
    appUid: 'your-app-uid',
    fetchAuthentication: async () => {
      const token = await yourAuthService.getToken();
      return { token };
    }
  });
</script>

Call init() only once. The SDK automatically discovers and renders all <mindset-agent> tags on the page.

How It Works

Instance Isolation

Each agent receives a unique instance ID ({agentUid}::{uuid}), ensuring complete isolation:

Resource	Behavior
Conversation History	Each agent maintains separate message threads
User Input	Typing in one agent doesn’t affect others
Error State	Errors in one agent don’t cascade to others
Theme/Styling	Shared across all agents (configured once in `init()`)

Shadow DOM

Each agent renders inside its own Shadow DOM container, providing:

CSS Isolation — Your website styles don’t affect agents, and vice versa
DOM Isolation — Agent elements don’t interfere with your page’s JavaScript

Shadow DOM ensures agents can be safely embedded in any website without CSS conflicts or JavaScript interference.

Configuration

Agent Tag Attributes

<mindset-agent agentUid="your-agent-uid"></mindset-agent>

Attribute	Required	Description
`agentUid`	Yes	Unique identifier from Agent Management Studio (case-sensitive)

Initialization Options

window.mindset.init({
  // Required
  appUid: 'your-app-uid',
  fetchAuthentication: async () => ({ token: 'your-token' }),

  // Optional - Theme (applies to all agents)
  theme: {
    brightness: 'light',
    seedColor: '#5a8eff',
    dynamicSchemeVariant: 'content',
  },

  // Optional - Custom Font (applies to all agents)
  customFontTheme: {
    fontFamily: 'Inter',
  },

  // Optional
  enableVoice: false,
});

Theme and font customization apply to all agents on the page. Individual agents cannot have different themes.

Dynamic Agent Embedding

The SDK automatically detects agents added after initialization—useful for single-page applications and conditional loading.

// Initialize SDK first
await window.mindset.init({
  appUid: 'your-app-uid',
  fetchAuthentication: async () => ({ token: 'your-token' }),
});

// Later, add a new agent dynamically
const newAgent = document.createElement('mindset-agent');
newAgent.setAttribute('agentUid', 'contextual-helper-agent-uid');
document.getElementById('help-section').appendChild(newAgent);
// Agent renders automatically - no additional code needed

Use Cases

Single Page Applications — Add agents on route changes without re-initializing Conditional Display — Show agents based on user actions or state Lazy Loading — Add agents only when their section becomes visible

Flexible UI with Multiple Agents

When using Flexible UI (via <mindset-container>), only the first container on the page receives full flexible UI support. Subsequent containers render their agents as standard floating chat windows.

What is Flexible UI?

Flexible UI provides display modes like tray view, pill button, and smooth transitions between minimized/maximized states. It’s enabled by wrapping <mindset-agent> in a <mindset-container>.

The Limitation

<!-- ✅ First container - Gets full flexible UI -->
<mindset-container
  agent-view-mode="all"
  agent-title="Sales Assistant"
  agent-icon="https://example.com/icon.png">
  <mindset-agent agentUid="sales-agent-uid"></mindset-agent>
</mindset-container>

<!-- ⚠️ Second container - NO flexible UI, renders as standard chat -->
<mindset-container
  agent-view-mode="tray-only"
  agent-title="Support Bot">
  <mindset-agent agentUid="support-agent-uid"></mindset-agent>
</mindset-container>

Container	Flexible UI	Display Modes	Tray/Pill Button
First	✅ Yes	✅ all/chat-only/tray-only/no-tray/docked-left/docked-right	✅ Available
Second+	❌ No	❌ Fixed floating window	❌ Not available

Recommended Pattern

Use flexible UI for your primary agent only, and standard <mindset-agent> tags for others:

<!-- Primary agent with flexible UI -->
<mindset-container agent-view-mode="all">
  <mindset-agent agentUid="primary-agent-uid"></mindset-agent>
</mindset-container>

<!-- Additional agents without container -->
<mindset-agent agentUid="secondary-agent-uid"></mindset-agent>
<mindset-agent agentUid="tertiary-agent-uid"></mindset-agent>

Best Practices

Authentication with Token Refresh

Always return a fresh or refreshed token from fetchAuthentication:

fetchAuthentication: async () => {
  // Always return fresh/refreshed token
  const token = await yourAuthService.getOrRefreshToken();
  if (!token) throw new Error('Authentication failed');
  return { token };
}

Strategic Placement

Place agents where they provide contextual help:

<section class="checkout">
  <mindset-agent agentUid="checkout-helper"></mindset-agent>
</section>

<section class="account">
  <mindset-agent agentUid="account-support"></mindset-agent>
</section>

This ensures users get relevant assistance in each section of your application.

Mobile Considerations

Consider limiting the number of agents on smaller screens:

if (window.innerWidth > 768) {
  // Show multiple agents on desktop
} else {
  // Show only primary agent on mobile
}

Multiple floating chat windows can overwhelm mobile users—prioritize the most important agent.

Use Cases

Contextual Support

Deploy different agents in different sections: checkout assistant, account support, product expert

Role-Based Agents

Show specialized agents based on user role: customer agent, admin agent, partner agent

Single Page Apps

Dynamically add/remove agents as users navigate between routes

Progressive Enhancement

Start with one agent, add more based on user behavior or session length

Troubleshooting

Agent not rendering

Possible causes:

Invalid agentUid
Agent UID doesn’t match Agent Management Studio exactly (case-sensitive)
SDK not loaded before agent tags

Solution: Verify the UID matches Agent Management Studio exactly. Ensure SDK script loads before <mindset-agent> tags appear in the DOM.

Authentication error

Possible causes:

fetchAuthentication not returning correct format
Token is invalid or expired
Network request failed

Solution: Ensure fetchAuthentication returns { token: string }. Check token validity. Verify network connectivity.

Agent shows error screen

Possible causes:

SDK initialization failed
Invalid configuration parameters
Network connectivity issues

Solution: Check browser console for error codes. Verify all required parameters (appUid, fetchAuthentication) are provided.

Styles look broken

Possible causes:

CSS conflicts with website styles
Outdated SDK version
Browser compatibility issues

Solution: Ensure you’re using the latest SDK version. Check that Shadow DOM is supported in your browser. Update SDK to latest version. Possible causes:

SDK bug (rare)
Multiple init() calls
Incorrect agent UID configuration

Solution: Verify you’re calling init() only once. Ensure each agent has a unique agentUid. Update SDK to latest version. If issue persists, contact support@mindset.ai.

Browser Support

Supported browsers: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+

Older browsers may not support Shadow DOM or other modern features required by the SDK.

Examples

Example 1: E-commerce Site

<!-- Product pages - Product expert -->
<div class="product-detail">
  <mindset-agent agentUid="product-expert-uid"></mindset-agent>
</div>

<!-- Checkout - Sales assistant -->
<div class="checkout-flow">
  <mindset-agent agentUid="checkout-assistant-uid"></mindset-agent>
</div>

<!-- Account - Support bot -->
<div class="account-settings">
  <mindset-agent agentUid="account-support-uid"></mindset-agent>
</div>

Example 2: SaaS Dashboard

<!-- Main dashboard - General assistant with flexible UI -->
<mindset-container agent-view-mode="all">
  <mindset-agent agentUid="general-assistant-uid"></mindset-agent>
</mindset-container>

<!-- Analytics page - Data expert -->
<div class="analytics-section">
  <mindset-agent agentUid="analytics-expert-uid"></mindset-agent>
</div>

<!-- Settings - Configuration helper -->
<div class="settings-section">
  <mindset-agent agentUid="settings-helper-uid"></mindset-agent>
</div>

Example 3: Dynamic Loading (SPA)

// Router logic for single-page app
router.on('/products', () => {
  const productAgent = document.createElement('mindset-agent');
  productAgent.setAttribute('agentUid', 'product-expert-uid');
  document.getElementById('agent-container').appendChild(productAgent);
});

router.on('/support', () => {
  const supportAgent = document.createElement('mindset-agent');
  supportAgent.setAttribute('agentUid', 'support-bot-uid');
  document.getElementById('agent-container').appendChild(supportAgent);
});

​Overview

​Quick Start

​How It Works

​Instance Isolation

​Shadow DOM

​Configuration

​Agent Tag Attributes

​Initialization Options

​Dynamic Agent Embedding

​Use Cases

​Flexible UI with Multiple Agents

​What is Flexible UI?

​The Limitation

​Recommended Pattern

​Best Practices

​Authentication with Token Refresh

​Strategic Placement

​Mobile Considerations

​Use Cases

Contextual Support

Role-Based Agents

Single Page Apps

Progressive Enhancement

​Troubleshooting

​Agent not rendering

​Authentication error

​Agent shows error screen

​Styles look broken

​Multiple agents sharing state

​Browser Support

​Examples

​Example 1: E-commerce Site

​Example 2: SaaS Dashboard

​Example 3: Dynamic Loading (SPA)

Overview

Quick Start

How It Works

Instance Isolation

Shadow DOM

Configuration

Agent Tag Attributes

Initialization Options

Dynamic Agent Embedding

Use Cases

Flexible UI with Multiple Agents

What is Flexible UI?

The Limitation

Recommended Pattern

Best Practices

Authentication with Token Refresh

Strategic Placement

Mobile Considerations

Use Cases

Troubleshooting

Agent not rendering

Authentication error

Agent shows error screen

Styles look broken

Multiple agents sharing state

Browser Support

Examples

Example 1: E-commerce Site

Example 2: SaaS Dashboard

Example 3: Dynamic Loading (SPA)