Agent Builder SDK Use Case Flows

Available Components Overview

The Agent Builder SDK provides four main components for agent and context management:

Component Comparison Matrix

Use Case 1: Agent Management with Agent Builder

This flow shows how to embed a complete agent management interface where tenant administrators can view, create, edit, and delete agents in one unified interface.

Prerequisites

Step-by-Step Flow

1. Authenticate the Tenant Admin

   Call the SDKUsers Auth API to create an auth token for the tenant admin user:

   bashCopy

       POST https://{environment}.api.mindset.ai/api/v1/appuid/{appUid}/sdkusers/auth
       Content-Type: application/json
       x-api-key: {your-api-key}
       
       {
         "externalId": "admin-user-123",
         "externalTenantId": "tenant-abc-456"
       }

   Response:

   jsonCopy

       {
         "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
       }

2. Construct the Web Page with Agent Builder

   Create an HTML page containing the Agent Builder component:

   htmlCopy

       <!DOCTYPE html>
       <html>
       <head>
           <title>Agent Management</title>
           <style>
               mindset-agents-manager {
                   display: block;
                   width: 100%;
                   min-height: 600px;
               }
           </style>
       </head>
       <body>
           <h1>Manage AI Agents</h1>
       
           <!-- Agent Builder component - complete CRUD interface -->
           <mindset-agents-manager></mindset-agents-manager>
       
           <!-- Load Agent Builder SDK JavaScript -->
           <script src="https://[AMS-SDK-URL]/mindset-sdk2.js"></script>
       
           <!-- Initialize SDK -->
           <script>
               (async () => {
                   await window.mindset.init({
                       appUid: 'your-app-uid',
                       externalTenantId: 'tenant-abc-456',
                       fetchAuthentication: async () => {
                           // Call your backend to get auth token
                           const response = await fetch('/api/mindset/auth', {
                               credentials: 'include'
                           });
                           const data = await response.json();
                           return data.authToken;
                       }
                   });
               })();
           </script>
       </body>
       </html>

3. Optional - Control Displayed Tabs

   You can control which configuration tabs are shown in the agent dialogs:

   htmlCopy

       <!-- Show only specific tabs in agent configuration -->
       <mindset-agents-manager displayTabs="Policy,LLM,Contexts"></mindset-agents-manager>

   Available tabs: Policy, Options, LLM, Contexts, Bias, Preview

Use Case 2: Standalone Agent Creation/Editing

This flow shows how to embed a standalone agent creation or editing interface.

Prerequisites

Step-by-Step Flow

1. Authenticate

   Follow the authentication steps from Use Case 1.

2. Construct the Web Page with Agent Configuration

   Creating a New AgentEditing an Existing Agent

   htmlCopy

           <!DOCTYPE html>
           <html>
           <head>
               <title>Create New Agent</title>
               <style>
                   mindset-agent-configuration {
                       display: block;
                       width: 100%;
                       min-height: 400px;
                   }
               </style>
           </head>
           <body>
               <h1>Create New Agent</h1>
           
               <!-- Agent Configuration component - no agentUid = create mode -->
               <mindset-agent-configuration
                   displayTabs="Policy"
                   onClose="handleAgentSaved();">
               </mindset-agent-configuration>
           
               <script src="https://[AMS-SDK-URL]/mindset-sdk2.js"></script>
               <script>
                   (async () => {
                       await window.mindset.init({
                           appUid: 'your-app-uid',
                           externalTenantId: 'tenant-abc-456',
                           fetchAuthentication: async () => {
                               const response = await fetch('/api/mindset/auth', {
                                   credentials: 'include'
                               });
                               const data = await response.json();
                               return data.authToken;
                           }
                       });
                   })();
           
                   function handleAgentSaved() {
                       // User closed the dialog
                       window.location.href = '/admin/agents';
                   }
               </script>
           </body>
           </html>

   htmlCopy

           <!-- Agent Configuration component - with agentUid = edit mode -->
           <mindset-agent-configuration
               agentUid="agent-abc-123"
               displayTabs="Policy"
               onClose="handleAgentSaved();">
           </mindset-agent-configuration>

3. Configuration Component Integration Pattern

   For dynamic Configuration Component, create fresh elements each time:

   htmlCopy

       <div id="agent-modal" style="display: none;">
           <div class="modal-content">
               <button onclick="closeModal()">Close</button>
               <div id="agent-config-container"></div>
           </div>
       </div>
       
       <script>
           function createAgent() {
               const container = document.getElementById('agent-config-container');
               container.innerHTML = '<mindset-agent-configuration displayTabs="Policy" onClose="closeModal();"></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="closeModal();"></mindset-agent-configuration>`;
               document.getElementById('agent-modal').style.display = 'block';
           }
       
           function closeModal() {
               document.getElementById('agent-modal').style.display = 'none';
               document.getElementById('agent-config-container').innerHTML = '';
           }
       </script>

Use Case 3: Knowledge Context Management with Context Builder

This flow shows how to embed a complete knowledge context management interface where tenant administrators can view, create, edit, and delete contexts.

Prerequisites

Same as Use Case 1 (authentication and tenant setup)

Step-by-Step Flow

1. Authenticate

   Follow the authentication steps from Use Case 1.

2. Construct the Web Page with Context Builder

   Create an HTML page containing the Context Builder component:

   htmlCopy

       <!DOCTYPE html>
       <html>
       <head>
           <title>Knowledge Context Management</title>
           <style>
               mindset-contexts-manager {
                   display: block;
                   width: 100%;
                   min-height: 600px;
               }
           </style>
       </head>
       <body>
           <h1>Manage Knowledge Contexts</h1>
       
           <!-- Context Builder component - complete CRUD interface -->
           <mindset-contexts-manager></mindset-contexts-manager>
       
           <!-- Load Agent Builder SDK JavaScript -->
           <script src="https://[AMS-SDK-URL]/mindset-sdk2.js"></script>
       
           <!-- Initialize SDK -->
           <script>
               (async () => {
                   await window.mindset.init({
                       appUid: 'your-app-uid',
                       externalTenantId: 'tenant-abc-456',
                       fetchAuthentication: async () => {
                           const response = await fetch('/api/mindset/auth', {
                               credentials: 'include'
                           });
                           const data = await response.json();
                           return data.authToken;
                       }
                   });
               })();
           </script>
       </body>
       </html>

3. Optional - Control Displayed Tabs

   You can control which configuration tabs are shown in the context dialogs:

   htmlCopy

       <!-- Show only specific tabs in context configuration -->
       <mindset-contexts-manager displayTabs="Prompts"></mindset-contexts-manager>

   Available tabs: Prompts, Bias

Use Case 4: Standalone Context Creation/Editing

This flow shows how to embed a standalone context creation or editing interface.

Prerequisites

Step-by-Step Flow

1. Authenticate

   Follow the authentication steps from Use Case 1.

2. Construct the Web Page with Context Configuration

   Creating a New ContextEditing an Existing Context

   htmlCopy

           <!DOCTYPE html>
           <html>
           <head>
               <title>Create New Knowledge Context</title>
               <style>
                   mindset-context-configuration {
                       display: block;
                       width: 100%;
                       min-height: 400px;
                   }
               </style>
           </head>
           <body>
               <h1>Create New Knowledge Context</h1>
           
               <!-- Context Configuration component - no contextUid = create mode -->
               <mindset-context-configuration
                   displayTabs="Prompts,Bias"
                   onClose="handleContextSaved();">
               </mindset-context-configuration>
           
               <script src="https://[AMS-SDK-URL]/mindset-sdk2.js"></script>
               <script>
                   (async () => {
                       await window.mindset.init({
                           appUid: 'your-app-uid',
                           externalTenantId: 'tenant-abc-456',
                           fetchAuthentication: async () => {
                               const response = await fetch('/api/mindset/auth', {
                                   credentials: 'include'
                               });
                               const data = await response.json();
                               return data.authToken;
                           }
                       });
                   })();
           
                   function handleContextSaved() {
                       // User closed the dialog
                       window.location.href = '/admin/contexts';
                   }
               </script>
           </body>
           </html>

   htmlCopy

           <!-- Context Configuration component - with contextUid = edit mode -->
           <mindset-context-configuration
               contextUid="context-xyz-789"
               displayTabs="Prompts,Bias"
               onClose="handleContextSaved();">
           </mindset-context-configuration>

3. Configuration Component Integration Pattern

   For dynamic configuration component, create fresh elements each time:

   htmlCopy

       <div id="context-modal" style="display: none;">
           <div class="modal-content">
               <button onclick="closeContextModal()">Close</button>
               <div id="context-config-container"></div>
           </div>
       </div>
       
       <script>
           function createContext() {
               const container = document.getElementById('context-config-container');
               container.innerHTML = '<mindset-context-configuration displayTabs="Prompts,Bias" onClose="closeContextModal();"></mindset-context-configuration>';
               document.getElementById('context-modal').style.display = 'block';
           }
       
           function editContext(contextUid) {
               const container = document.getElementById('context-config-container');
               container.innerHTML = `<mindset-context-configuration contextUid="${contextUid}" displayTabs="Prompts,Bias" onClose="closeContextModal();"></mindset-context-configuration>`;
               document.getElementById('context-modal').style.display = 'block';
           }
       
           function closeContextModal() {
               document.getElementById('context-modal').style.display = 'none';
               document.getElementById('context-config-container').innerHTML = '';
           }
       </script>

Understanding fetchAuthentication

The fetchAuthentication parameter is a function that returns a Promise resolving to an auth token. This enables a deferred authentication pattern:

1. Page Loads

   Your page loads and displays the Agent Builder SDK UI immediately

2. SDK Requests Auth

   The SDK calls fetchAuthentication() only when it actually needs authentication

3. Client Calls Backend

   Your client-side code makes a request to your backend API

4. Backend Generates Token

   Your backend calls the Mindset SDKUsers Auth API to generate the token

5. Token Returned

   Your backend returns the token to your frontend

6. SDK Authenticated

   The SDK uses the token for authenticated operations

Example Implementation

    await window.mindset.init({
        appUid: 'your-app-uid',
        externalTenantId: 'tenant-abc-456',
        fetchAuthentication: async () => {
            // Call YOUR backend API
            const response = await fetch('/api/mindset/auth', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                credentials: 'include' // Send session cookies
            });
            const data = await response.json();
            return data.authToken;
        }
    });

    app.post('/api/mindset/auth', async (req, res) => {
        // Get current user from your session
        const user = req.session.user;
    
        // Call Mindset SDKUsers Auth API
        const response = await fetch(
            `https://b.api.mindset.ai/api/v1/appuid/${MINDSET_APP_UID}/sdkusers/auth`,
            {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                    'x-api-key': MINDSET_API_KEY
                },
                body: JSON.stringify({
                    externalId: user.id,
                    externalTenantId: user.tenantId
                })
            }
        );
    
        const data = await response.json();
        res.json({ authToken: data.authToken });
    });

Component Attributes Reference

Agent Builder

Agent Configuration

Context Builder

Context Configuration

Security Best Practices

    const container = document.getElementById('config-container');
    container.innerHTML = `<mindset-agent-configuration agentUid="${uid}"></mindset-agent-configuration>`;

    const element = document.getElementById('agent-config');
    element.setAttribute('agentUid', uid); // May not trigger re-initialization

Receiving Notifications (Optional)

When users save agents or contexts, you have two options to get the resource details:

    {
      "event": "agent.created",
      "timestamp": "2025-10-06T14:30:00Z",
      "data": {
        "uid": "agent-new-123",
        "name": "Customer Support Agent",
        "externalTenantId": "tenant-abc-456",
        "createdBy": "admin-user-123"
      }
    }

    GET https://{environment}.api.mindset.ai/api/v1/appuid/{appUid}/agents?externalTenantId=tenant-abc-456
    x-api-key: {your-api-key}

    GET https://{environment}.api.mindset.ai/api/v1/appuid/{appUid}/contexts?externalTenantId=tenant-abc-456
    x-api-key: {your-api-key}

Next Steps