Agent Builder SDK Complete Integration Guide

What is the Agent Builder SDK?

Agent Builder SDK lets your tenants create, build, and manage custom AI agents directly inside your application — without you building the UI or managing hundreds of custom agent requests. Embed pre-built components that give your customers the power to create, configure, and manage their own agents in minutes. The Agent Builder SDK is a premium feature that enables you to embed agent-building capabilities directly into your product.

Currently Available Components

Agent Management:

Agent Builder (<mindset-agents-manager>) — List and manage AI agents
Agent Configuration (<mindset-agent-configuration>) — Create and edit individual agents

Knowledge Context Management:

Context Builder (<mindset-contexts-manager>) — List and manage knowledge contexts
Context Configuration (<mindset-context-configuration>) — Create and edit individual contexts

How It Works

Load JavaScript

Load Mindset AI’s JavaScript via a <script> tag.

Place Custom Elements

Place custom HTML elements in your page — embed single components or combine multiple components on the same page.

Initialize the SDK

Call window.mindset.init() to configure and initialize.

Components Render

Components render automatically with full functionality.

Quick Start Example

Here’s a minimal working example that embeds multiple components on the same page:

<!DOCTYPE html>
<html>
<head>
    <title>Agent & Context Management</title>
</head>
<body>
    {/*  1. Place the custom elements in your page  */}
    <mindset-agents-manager></mindset-agents-manager>
    <mindset-contexts-manager></mindset-contexts-manager>

    {/*  2. Load the Agent Builder SDK JavaScript  */}
    <script src="https://[AMS-SDK-URL]/mindset-sdk2.js"></script>

    {/*  3. Initialize the SDK  */}
    <script>
        (async () => {
            const externalTenantId = getCurrentTenantId(); // Your logic

            await window.mindset.init({
                appUid: 'your-app-uid',
                externalTenantId: externalTenantId,
                theme: {}, // Customize the theme
                customFontTheme: {}, // Customize fonts
                fetchAuthentication: async () => fetchUserAuthToken() // Your logic
            });

            console.log('Agent Builder SDK initialized');
        })();
    </script>
</body>
</html>

Available Components

Tab Control Works for Both Component TypesThe displayTabs attribute works identically for both Builder and Configuration components:

Builder components (<mindset-agents-manager>, <mindset-contexts-manager>) — Controls tabs in the built-in create/edit dialogs
Configuration components (<mindset-agent-configuration>, <mindset-context-configuration>) — Controls tabs in the standalone interface

Use displayTabs to show only the tabs your tenants need, regardless of which component type you choose.

1. Agent Builder — `<mindset-agents-manager>`

Displays a list of all agents for the tenant with the ability to:

View all agents
Create new agents
Edit existing agents
Delete agents
Search and filter agents

Usage:

<mindset-agents-manager></mindset-agents-manager>

Optional Attributes:

Attribute	Type	Description
`displayTabs`	string (optional)	Comma-separated list of tabs to display when creating or editing agents. Available tabs: Policy, Options, LLM, Contexts, Bias, Preview. Works the same as in `<mindset-agent-configuration>`.

Examples:

{/*  Show all default tabs  */}
<mindset-agents-manager></mindset-agents-manager>

{/*  Show only specific tabs  */}
<mindset-agents-manager displayTabs="Policy,Bias,Preview"></mindset-agents-manager>

This component provides the complete agent management interface, including list view and built-in create/edit dialogs.

2. Agent Configuration — `<mindset-agent-configuration>`

Displays the agent creation or editing dialog for a single agent. This component is useful when you want to:

Embed agent creation/editing in a form
Control when and how the configuration interface appears
Build your own custom list view UI

Attributes:

Attribute	Type	Description
`agentUid`	string (optional)	UID of agent to edit. If omitted, creates new agent
`onClose`	string (optional)	JavaScript code to execute when configuration UI is dismissed
`displayTabs`	string (optional)	Comma-separated list of tabs to display. Available tabs: Policy, Options, LLM, Contexts, Bias, Preview
`hideBackButtonForAgentEditDialog`	string (optional)	Set to `"true"` to hide the Back button in the top-left of the configuration screen. Useful when embedding without the parent manager, where there is no previous screen to navigate back to. Omit or set to `"false"` to keep it visible (default).

Usage Examples:

{/*  Create new agent  */}
<mindset-agent-configuration></mindset-agent-configuration>

{/*  Edit existing agent  */}
<mindset-agent-configuration agentUid="agent-abc123"></mindset-agent-configuration>

{/*  With close handler  */}
<mindset-agent-configuration
    agentUid="agent-abc123"
    onClose="handleAgentClose();">
</mindset-agent-configuration>

{/*  Show only specific tabs  */}
<mindset-agent-configuration
    agentUid="agent-abc123"
    displayTabs="Policy,LLM,Contexts">
</mindset-agent-configuration>

{/*  Hide the Back button for standalone embeds  */}
<mindset-agent-configuration
    agentUid="agent-abc123"
    hideBackButtonForAgentEditDialog="true">
</mindset-agent-configuration>

Agent Configuration Tabs

The <mindset-agent-configuration> component displays multiple configuration tabs: Always Displayed:

Settings — Basic agent configuration (name, description, etc.)
Personality — Agent behavior and tone

Optional Tabs (controlled via displayTabs):

Policy — Agent policies and guidelines
Options — Additional agent options
LLM — Language model configuration
Contexts — Knowledge base associations
Bias — Bias detection configuration
Preview — Agent preview

Controlling Tab Display:

{/*  Display all tabs (default)  */}
<mindset-agent-configuration agentUid="agent-123"></mindset-agent-configuration>

{/*  Display only required tabs (Settings, Personality)  */}
<mindset-agent-configuration agentUid="agent-123" displayTabs=""></mindset-agent-configuration>

{/*  Display specific optional tabs  */}
<mindset-agent-configuration
    agentUid="agent-123"
    displayTabs="Policy,LLM">
</mindset-agent-configuration>

Settings and Personality tabs are always displayed regardless of the displayTabs value.

3. Context Builder — `<mindset-contexts-manager>`

Displays a list of all knowledge contexts for the tenant with the ability to:

View all contexts
Create new contexts
Edit existing contexts
Delete contexts
Search and filter contexts

Usage:

<mindset-contexts-manager></mindset-contexts-manager>

Optional Attributes:

Attribute	Type	Description
`displayTabs`	string (optional)	Comma-separated list of tabs to display when creating or editing contexts. Available tabs: Prompts, Bias. Works the same as in `<mindset-context-configuration>`.

Examples:

{/*  Show all default tabs  */}
<mindset-contexts-manager></mindset-contexts-manager>

{/*  Show only specific tabs  */}
<mindset-contexts-manager displayTabs="Prompts"></mindset-contexts-manager>

This component provides the complete context management interface including list view and built-in create/edit dialogs.

Note on Synced ContextsThe Context Builder SDK does not allow tenants to create synced contexts directly. However, if an application administrator creates a synced context for a specific tenant using the Contexts API, that synced context will be visible to the tenant in the builder.

What are Knowledge Contexts?

Knowledge Contexts are bundles of files, links, and data that agents can reference — essentially a dynamic library for your agents.

Contexts — Documents, articles, and structured knowledge
Custom Prompts — Instructions that guide the AI’s responses
Bias — Overview of bias within your Contexts

4. Context Configuration — `<mindset-context-configuration>`

Displays the context creation or editing dialog for a single knowledge context. This component is useful when you want to:

Embed context creation/editing in a form
Build your own custom list view UI

Attributes:

Attribute	Type	Description
`contextUid`	string (optional)	UID of context to edit. If omitted, creates new context
`onClose`	string (optional)	JavaScript code to execute when dialog closes
`displayTabs`	string (optional)	Comma-separated list of tabs to display. Available tabs: Prompts, Bias
`hideBackButtonForContextEditDialog`	string (optional)	Set to `"true"` to hide the Back button in the top-left of the configuration screen. Useful when embedding without the parent manager, where there is no previous screen to navigate back to. Omit or set to `"false"` to keep it visible (default).

Usage Examples:

{/*  Create new context  */}
<mindset-context-configuration></mindset-context-configuration>

{/*  Edit existing context  */}
<mindset-context-configuration contextUid="context-xyz789"></mindset-context-configuration>

{/*  With close handler  */}
<mindset-context-configuration
    contextUid="context-xyz789"
    onClose="handleContextClose();">
</mindset-context-configuration>

{/*  Show only specific tabs  */}
<mindset-context-configuration
    contextUid="context-xyz789"
    displayTabs="Prompts">
</mindset-context-configuration>

{/*  Hide the Back button for standalone embeds  */}
<mindset-context-configuration
    contextUid="context-xyz789"
    hideBackButtonForContextEditDialog="true">
</mindset-context-configuration>

The Back button is always visible on the manager components (<mindset-agents-manager>, <mindset-contexts-manager>). The hideBackButton... attributes only apply to the standalone configuration components, since users need the Back button to return to the list view.

Context Configuration Tabs

The <mindset-context-configuration> component displays configuration tabs: Always Displayed:

General — Basic context information (name, description, type)

Optional Tabs (controlled via displayTabs):

Prompts — Custom system prompts and instructions
Bias — Allows you to analyze the bias within your content

Controlling Tab Display:

{/*  Display all tabs (default)  */}
<mindset-context-configuration contextUid="context-123"></mindset-context-configuration>

{/*  Display specific tabs  */}
<mindset-context-configuration
    contextUid="context-123"
    displayTabs="Prompts,Bias">
</mindset-context-configuration>

Integration Patterns

Pattern 1: Builder Components Only (Recommended)

Use builder components for a complete, zero-configuration experience:

<div class="tabs">
    <button onclick="showAgents()">Agents</button>
    <button onclick="showContexts()">Contexts</button>
</div>

<div id="agents-view">
    <mindset-agents-manager></mindset-agents-manager>
</div>

<div id="contexts-view" style="display: none;">
    <mindset-contexts-manager></mindset-contexts-manager>
</div>

<script>
    function showAgents() {
        document.getElementById('agents-view').style.display = 'block';
        document.getElementById('contexts-view').style.display = 'none';
    }

    function showContexts() {
        document.getElementById('agents-view').style.display = 'none';
        document.getElementById('contexts-view').style.display = 'block';
    }
</script>

Pattern 2: Configuration Component Integration

Use configuration components in forms if you want to create your own list view UI.

function createAgent() {
    const container = document.getElementById('agent-config-container');
    container.innerHTML = '<mindset-agent-configuration displayTabs="Policy" onClose="closeAgentModal();"></mindset-agent-configuration>';
    document.getElementById('agent-modal').style.display = 'block';
}

function editAgent(agentUid) {
    const container = document.getElementById('agent-config-container');
    container.innerHTML = `<mindset-agent-configuration agentUid="${agentUid}" displayTabs="Policy" onClose="closeAgentModal();"></mindset-agent-configuration>`;
    document.getElementById('agent-modal').style.display = 'block';
}

function closeAgentModal() {
    document.getElementById('agent-modal').style.display = 'none';
    document.getElementById('agent-config-container').innerHTML = '';
}

Shadow DOM Support

The Agent Builder SDK supports Shadow DOM encapsulation, allowing you to embed admin widgets with proper style isolation. This is useful when integrating into applications that use Shadow DOM for component encapsulation.

Basic Setup

Pass an optional shadowRoot parameter to window.mindset.init(). You can provide either a direct reference or a function getter:

// Option 1: Direct reference (simple cases where shadow root is stable)
const shadowRoot = document.getElementById('my-container').shadowRoot;

await window.mindset.init({
  fetchAuthentication: () => getAuthToken(),
  appUid: 'your-app-uid',
  externalTenantId: 'your-tenant-id',
  shadowRoot: shadowRoot
});

// Option 2: Function getter (recommended — always returns the latest reference)
await window.mindset.init({
  fetchAuthentication: () => getAuthToken(),
  appUid: 'your-app-uid',
  externalTenantId: 'your-tenant-id',
  shadowRoot: () => document.getElementById('my-container').shadowRoot
});

Approach	When to use
Direct reference	The shadow root is created once and never destroyed during the application lifecycle
Function getter (recommended)	The shadow root may be destroyed and recreated during navigation or dynamic UI updates (e.g., SPA route changes, conditional rendering)

When shadowRoot is a function, the SDK calls it each time it needs to access the shadow root, ensuring it always has the latest valid reference. This prevents stale reference errors that can occur when a shadow root is destroyed and recreated while the SDK holds an old reference.

How It Works

When you provide the shadowRoot parameter, the SDK:

Resolves function getters — Calls the function to obtain the current shadow root each time access is needed
Scopes element detection — Restricts its MutationObserver to detect widgets only within that boundary
Provides style isolation — Prevents conflicts between your host application and admin widgets

Backward Compatibility

The shadowRoot parameter is optional. If not provided, the SDK operates in standard DOM mode without any changes needed:

// Standard DOM mode (no Shadow DOM)
document.body.innerHTML += '<mindset-agents-manager></mindset-agents-manager>';

await window.mindset.init({
  fetchAuthentication: getAuthToken,
  appUid: 'your-app-uid',
  externalTenantId: 'your-tenant-id'
  // No shadowRoot parameter — works as before
});

Technical Details

Element Detection:

With Shadow DOM: shadowRoot.querySelectorAll(selector)
Without Shadow DOM: document.querySelectorAll(selector)

MutationObserver Scope:

With Shadow DOM: Observes shadowRoot with { childList: true, subtree: true }
Without Shadow DOM: Observes document.body with { childList: true, subtree: true }

Appendix: Complete Component Reference

Agent Components

<mindset-agents-manager>

Feature	Details
Purpose	Complete agent management interface
Includes	List view, create, edit, delete
Attributes	`displayTabs` (optional)
Min Height	600px

<mindset-agent-configuration>

Feature	Details
Purpose	Single agent create/edit interface
Includes	Configuration dialog only
Attributes	`agentUid` (optional), `onClose` (optional), `displayTabs` (optional), `hideBackButtonForAgentEditDialog` (optional)
Available Tabs	Policy, Options, LLM, Contexts, Bias, Preview
Always Shown Tabs	Settings, Personality
Min Height	400px

Context Components

<mindset-contexts-manager>

Feature	Details
Purpose	Complete context management interface
Includes	List view, create, edit, delete
Attributes	`displayTabs` (optional)
Min Height	600px

<mindset-context-configuration>

Feature	Details
Purpose	Single context create/edit interface
Includes	Configuration dialog only
Attributes	`contextUid` (optional), `onClose` (optional), `displayTabs` (optional), `hideBackButtonForContextEditDialog` (optional)
Available Tabs	Prompts, Bias
Always Shown Tabs	General
Min Height	400px

Overview

Integrate Agent Chat SDK 3

Agent Chat SDK 3: Client-side Integration APIs

Data channels

Integrate Agent Chat SDK 2

MCP Server Integration

Agent Builder SDK Integration

API Overview

API playground

Webhooks

Agent Builder SDK Complete Integration Guide

What is the Agent Builder SDK?

Currently Available Components

How It Works

Quick Start Example

Available Components

1. Agent Builder — `<mindset-agents-manager>`

2. Agent Configuration — `<mindset-agent-configuration>`

Agent Configuration Tabs

3. Context Builder — `<mindset-contexts-manager>`

What are Knowledge Contexts?

4. Context Configuration — `<mindset-context-configuration>`

Context Configuration Tabs

Integration Patterns

Pattern 1: Builder Components Only (Recommended)

Pattern 2: Configuration Component Integration

Shadow DOM Support

Basic Setup

How It Works

Backward Compatibility

Technical Details

Appendix: Complete Component Reference

Agent Components

Context Components

​What is the Agent Builder SDK?

​Currently Available Components

​How It Works

​Quick Start Example

​Available Components

​1. Agent Builder — <mindset-agents-manager>

​2. Agent Configuration — <mindset-agent-configuration>

​Agent Configuration Tabs

​3. Context Builder — <mindset-contexts-manager>

​What are Knowledge Contexts?

​4. Context Configuration — <mindset-context-configuration>

​Context Configuration Tabs

​Integration Patterns

​Pattern 1: Builder Components Only (Recommended)

​Pattern 2: Configuration Component Integration

​Shadow DOM Support

​Basic Setup

​How It Works

​Backward Compatibility

​Technical Details

​Appendix: Complete Component Reference

​Agent Components

​Context Components

What is the Agent Builder SDK?

Currently Available Components

How It Works

Quick Start Example

Available Components

1. Agent Builder — `<mindset-agents-manager>`

2. Agent Configuration — `<mindset-agent-configuration>`

Agent Configuration Tabs

3. Context Builder — `<mindset-contexts-manager>`

What are Knowledge Contexts?

4. Context Configuration — `<mindset-context-configuration>`

Context Configuration Tabs

Integration Patterns

Pattern 1: Builder Components Only (Recommended)

Pattern 2: Configuration Component Integration

Shadow DOM Support

Basic Setup

How It Works

Backward Compatibility

Technical Details

Appendix: Complete Component Reference

Agent Components

Context Components