> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindset.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Builder SDK Playground: Step-by-Step Guide

> Agent Builder SDK Playground  

The Agent Builder SDK Playground lets you preview and configure embeddable UI components that your tenants can use to build agents and contexts. You can generate integration code, customize themes, and test components before embedding them in your platform.

<Info>
  The Agent Builder SDK is a premium feature that enables you to embed agent-building capabilities directly into your product.
</Info>

The Agent Builder SDK lets you embed components that enable your tenants to build and manage their own agents and knowledge contexts—directly inside your platform. This guide walks you through:

<Steps>
  <Step title="Preview and Configure Components">
    Use the playground to see how components look and work
  </Step>

  <Step title="Customize Appearance">
    Match your brand with theme settings
  </Step>

  <Step title="Generate Integration Code">
    Copy ready-to-use code for your platform
  </Step>

  <Step title="Understand Deployment">
    Learn how agents get deployed to end-users
  </Step>
</Steps>

<CardGroup cols={2}>
  <Card title="Part 1: Enable Agent Creation" icon="wrench" iconType="duotone">
    Enable tenants to create agents and contexts (covered in this guide)
  </Card>

  <Card title="Part 2: Deploy to End-Users" icon="rocket" iconType="duotone">
    Deploy those agents to end-users via Agent Sessions API
  </Card>
</CardGroup>

## Understanding the Components

Agent Builder SDK provides embeddable UI components for both agents and knowledge contexts. Each has two component types you can choose from.

<Tabs>
  <Tab title="Agent Components">
    **Agents** are autonomous units tailored to specific roles—think of them as subject matter experts that can perform tasks, make decisions, and use tools.

    <AccordionGroup>
      <Accordion title="Agent Builder" icon="list">
        `<mindset-agents-manager>`

        * Complete list view of all agents
        * Built-in create, edit, and delete functionality
        * Search and filtering capabilities
        * **Best for:** Complete out-of-box experience with minimal customization
      </Accordion>

      <Accordion title="Agent Configuration" icon="sliders">
        `<mindset-agent-configuration>`

        * Only the create/edit interface
        * No list view included
        * **Best for:** Building your own custom list view UI (tiles, cards, tables)
      </Accordion>
    </AccordionGroup>

    <Card title="Learn More About Agents" href="https://docs.mindset.ai/build-optimize/guides/agents/howto-create-agents">
      Read the complete guide to creating agents
    </Card>
  </Tab>

  <Tab title="Context Components">
    **Knowledge Contexts** are bundles of files, links, and data that agents can reference—essentially a dynamic library for your agents.

    <AccordionGroup>
      <Accordion title="Context Builder" icon="list">
        `<mindset-contexts-manager>`

        * Complete list view of all contexts
        * Built-in create, edit, and delete functionality
        * Search and filtering capabilities
        * **Best for:** Complete out-of-box experience with minimal customization
      </Accordion>

      <Accordion title="Context Configuration" icon="sliders">
        `<mindset-context-configuration>`

        * Only the create/edit interface
        * No list view included
        * **Best for:** Building your own custom list view UI
      </Accordion>
    </AccordionGroup>

    <Card title="Learn More About Contexts" icon="book" href="https://docs.mindset.ai/build-optimize/guides/knowledge/choosing-data-for-your-agents">
      Read the complete guide to knowledge contexts
    </Card>
  </Tab>
</Tabs>

## How to Use the Playground

### Step 1: Access the Playground

Navigate to the Agent Builder SDK Playground in your Mindset AI application:

<Steps>
  <Step title="Open Developer Tools">
    Go to **Developer Tools** in your left sidebar
  </Step>

  <Step title="Select Agent Builder SDK Playground">
    Click **Agent Builder SDK Playground**
  </Step>

  <Step title="Launch">
    Click **Launch Playground** to open the preview environment
  </Step>
</Steps>

<Info>
  The playground helps you preview components, customize styling, and generate integration code before embedding them in your platform.
</Info>

### Step 2: Initialize the SDK Components

The playground pre-populates your app credentials automatically:

<CardGroup cols={2}>
  <Card title="App ID" icon="fingerprint">
    Your current app identifier
  </Card>

  <Card title="External Tenant ID" icon="users">
    A unique test tenant for your app
  </Card>
</CardGroup>

This test tenant keeps all your playground experiments separate from real tenant data, making it easy to filter out test objects later.

**To initialize:**

1. Select the components and tabs you want to display
2. Click **Initialize SDK Components**

### Step 3: Choose Your Component

Select which component you want to preview and configure.

<Tabs>
  <Tab title="For Agents">
    <CardGroup cols={2}>
      <Card title="Agent Builder" icon="list">
        Complete list view + create/edit functionality
      </Card>

      <Card title="Agent Configuration" icon="sliders">
        Create/edit only (for custom list UI)
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="For Knowledge Contexts">
    <CardGroup cols={2}>
      <Card title="Context Builder" icon="list">
        Complete list view + create/edit functionality
      </Card>

      <Card title="Context Configuration" icon="sliders">
        Create/edit only (for custom list UI)
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

### Step 4: Configure What Your Tenants See

Once you've chosen your component, customize which tabs and options appear to your tenants.

<Tabs>
  <Tab title="Agent Configuration">
    <AccordionGroup>
      <Accordion title="Default Tabs (Always Visible)" defaultOpen icon="check">
        * **Settings:** Name, description, and purpose
        * **Personality:** Tone of voice and brand attributes
      </Accordion>

      <Accordion title="Optional Tabs (Toggle On/Off)" icon="toggle-on">
        * **Policy Rules:** Rules the agent must never break
        * **Options:** Additional agent configuration options
        * **LLM:** Language model settings and parameters
        * **Contexts:** Which contexts this agent can access
        * **Bias:** Guidance on how the agent should weigh information
        * **Preview:** Test the agent before deploying

        <Tip>
          Check the boxes for tabs you want tenants to access. Uncheck any tabs you want to hide.
        </Tip>
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Context Configuration">
    <AccordionGroup>
      <Accordion title="Default Tabs (Always Visible)" defaultOpen icon="check">
        * **Settings:** Name, description, and content management
        * **Content:** Upload files, add links, manage knowledge
      </Accordion>

      <Accordion title="Optional Tabs (Toggle On/Off)" icon="toggle-on">
        * **Prompt:** Custom instructions for how agents use this context
        * **Bias:** Guidance on information weighting or prioritization

        <Tip>
          Check the boxes for tabs you want tenants to access. Uncheck any tabs you want to hide.
        </Tip>
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

### Step 5: Customize Theme and Styling

Make the component match your brand by adjusting theme settings.

<CardGroup cols={3}>
  <Card title="Theme Mode" icon="moon">
    Light or dark
  </Card>

  <Card title="Seed Color" icon="palette">
    Preset colors or custom hex value
  </Card>

  <Card title="Font" icon="font">
    Available fonts (defaults to Manrope)
  </Card>
</CardGroup>

<Note>
  The preview updates in real-time as you adjust settings.
</Note>

### Step 6: Preview the Component

Test how the component works before generating integration code.

<Steps>
  <Step title="Click the Preview Tab">
    Switch to the preview interface
  </Step>

  <Step title="Interact as Your Tenants Would">
    * Create a test agent or context
    * Navigate between tabs
    * Test form inputs and actions
  </Step>
</Steps>

### Step 7: Generate Integration Code

Once you're satisfied with the configuration, grab the code to embed in your platform.

<Steps>
  <Step title="Open Integration Code">
    Click **Integration Code** at the top of the playground
  </Step>

  <Step title="Review the Code">
    Check the generated code snippet
  </Step>

  <Step title="Copy to Clipboard">
    Click **Copy Code**
  </Step>

  <Step title="Embed in Your Platform">
    Paste the code where you want the component to appear
  </Step>
</Steps>

## Understanding Tenant Isolation

### How externalTenantId Works

The `externalTenantId` parameter determines what tenants see in the embedded components:

<CardGroup cols={2}>
  <Card title="Same externalTenantId" icon="users" color="#10b981">
    Users see each other's agents and contexts in component list views
  </Card>

  <Card title="Different externalTenantId" icon="user-lock" color="#3b82f6">
    Users don't see each other's agents and contexts in component list views
  </Card>
</CardGroup>

**Example:**

```javascript theme={null}
// Tenant A
externalTenantId: "company-acme-123"

// Tenant B  
externalTenantId: "company-techcorp-456"
```

In the Agent Builder SDK components, Tenant A and B will not see each other's agents or contexts.

<Warning>
  **Important Security Note**

  The `externalTenantId` filters what appears in the Builder and Configuration components. However, when creating agent sessions (deploying agents to end-users), you have flexibility to pair agents and contexts from different tenants.

  **This means your backend is responsible for enforcing proper tenant isolation** when creating agent sessions through the Agent Sessions API.
</Warning>

## What Happens Next: Deploying Agents to End-Users

After tenants create agents using these embedded components, you'll need to deploy those agents to end-users. This happens through the Agent Sessions API.

### What is an Agent Session?

An Agent Session couples:

<CardGroup cols={2}>
  <Card title="Agent" icon="robot">
    1 tenant-created agent
  </Card>

  <Card title="Knowledge" icon="book">
    Contexts OR RAG MCP
  </Card>

  <Card title="Tools" icon="wrench">
    MCP server integrations
  </Card>

  <Card title="User" icon="user">
    1 specific end-user (externalUserId)
  </Card>
</CardGroup>

### Knowledge Source Options

<Tabs>
  <Tab title="Option A: Contexts">
    <Card title="Contexts" icon="books">
      * Provision up to 30 contexts per agent session
      * Can be app-level, tenant-level, or mixed
      * Contexts are created via Contexts API or embedded Context components
    </Card>
  </Tab>

  <Tab title="Option B: RAG MCP">
    <Card title="RAG MCP" icon="database">
      * Provision exactly 1 RAG-type MCP per agent session
      * Cannot combine with contexts (mutually exclusive)
    </Card>
  </Tab>
</Tabs>

<Warning>
  You must choose **one** of these options for each agent session. You cannot combine contexts and RAG MCP.
</Warning>

### How Tenants Get Knowledge

<AccordionGroup>
  <Accordion title="Method 1: Tenant Uploads Their Own Files" icon="upload">
    * Tenant uses Context Builder or Context Configuration component
    * Tenant creates contexts and manually uploads files
    * You provision these tenant-level contexts in agent sessions
  </Accordion>

  <Accordion title="Method 2: You Provide App-Level Contexts" icon="building">
    * You create app-level contexts via Contexts API
    * You provision these to tenants through agent sessions
    * Tenants don't need to upload anything
  </Accordion>

  <Accordion title="Method 3: You Create Tenant-Level Contexts on Their Behalf" icon="code">
    * Use Contexts API with `externalTenantId` parameter
    * Create contexts programmatically for specific tenants
    * Option to set up synced ingestion (e.g., from Google Drive)
  </Accordion>

  <Accordion title="Method 4: RAG MCP" icon="database">
    * Provision a RAG MCP instead of contexts
    * Cannot be combined with contexts in the same session
  </Accordion>
</AccordionGroup>

### Adding Tool Integrations

Beyond knowledge sources, you can add tool integrations:

<Card title="MCP Server Limits" icon="wrench">
  * Up to **5 MCP servers total** per agent session (including RAG if used)
  * Add tools like Salesforce MCP, custom MCPs, etc.
  * **Example:** 1 RAG MCP + 4 Tools MCPs = 5 total
</Card>

### Tagging Agent Sessions

<Tip>
  Add tags to agent sessions for reporting and filtering:

  * **Recommended:** Include `externalTenantId` as a tag
  * Helps identify which sessions belong to which tenants in your data
</Tip>

## Decision Framework

### Question 1: Do you want to use Mindset's list view UI or build your own?

<CardGroup cols={2}>
  <Card title="Use Mindset's List View" icon="list" color="#10b981">
    Embed Builder Components

    `<mindset-agents-manager>`

    `<mindset-contexts-manager>`
  </Card>

  <Card title="Build Your Own List View" icon="code" color="#3b82f6">
    Embed Configuration Components

    `<mindset-agent-configuration>`

    `<mindset-context-configuration>`
  </Card>
</CardGroup>

### Question 2: Who provides the knowledge/context for agents?

<AccordionGroup>
  <Accordion title="Tenants Upload Their Own Files" icon="upload">
    Embed Context Builder or Context Configuration
  </Accordion>

  <Accordion title="You Provide Centrally" icon="building">
    Create app-level contexts and upload files, don't embed context components
  </Accordion>

  <Accordion title="Mix of Both" icon="shuffle">
    Embed context components AND create app-level contexts
  </Accordion>

  <Accordion title="Use RAG MCP Instead" icon="database">
    No contexts needed, provision RAG MCP in agent sessions
  </Accordion>
</AccordionGroup>

### Question 3: Do agents need tool integrations?

<CardGroup cols={2}>
  <Card title="Yes" icon="check" color="#10b981">
    Add tool MCPs when creating agent sessions (up to 5 total)
  </Card>

  <Card title="No" icon="xmark" color="#6b7280">
    Create agent sessions with only knowledge sources
  </Card>
</CardGroup>

## The Complete Flow

<Steps>
  <Step title="Part 1: Enable Agent Creation (This Guide)">
    * Configure components in the playground
    * Embed components on your platform
    * Tenants create and configure agents
    * Optionally: Tenants create contexts and upload files
  </Step>

  <Step title="Part 2: Deploy to End-Users (Next Step)">
    * Use Agent Sessions API to couple agents with knowledge and tools
    * Provision appropriate contexts or RAG MCP based on user permissions
    * Embed agent chat SDK for end-users
    * Tag sessions with externalTenantId for tracking
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Integration Guide" icon="book" href="https://docs.mindset.ai/deploy/ams-sdk/ams-sdk-integration-guide">
    Review Agent Builder SDK Complete Integration Guide for technical implementation details
  </Card>

  <Card title="Agent Sessions API" icon="code" href="https://docs.mindset.ai/deploy/api/agentsessions-api">
    Review Agent Sessions API documentation for deployment specifics
  </Card>
</CardGroup>