> ## 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.

# End-to-end Agent Deployment Flow 

> From tenant creation to end-user access

## Overview: Two-Part Process

<CardGroup cols={2}>
  <Card title="Part 1: Enable Creation" icon="users-gear" color="#A855F7">
    Tenants create agents and contexts using Agent Builder SDK components
  </Card>

  <Card title="Part 2: Deploy to Users" icon="rocket" color="#3B82F6">
    You deploy agents to end-users via Agent Sessions API
  </Card>
</CardGroup>

## Part 1: Enable Tenant Creation

<Steps>
  <Step title="Configure in Agent Builder SDK Playground">
    * Access Developer Tools → Agent Builder SDK Playground
    * Preview components (Agent Builder, Context Builder)
    * Customize theme, colors, fonts
    * Select which configuration tabs to display
    * Generate integration code
  </Step>

  <Step title="Embed Components in Your Platform">
    **For complete UI with list view:**

    * `<mindset-agents-manager>`
    * `<mindset-contexts-manager>`

    **For custom list view:**

    * `<mindset-agent-configuration>`
    * `<mindset-context-configuration>`

    **Flexible embedding:**

    * Embed single components per page or combine multiple components on the same page
  </Step>

  <Step title="Generate Authentication Token for Tenant Admin">
    **Before the tenant admin can use Agent Builder SDK components:**

    * Generate an `authToken` for the tenant admin user
    * **CRITICAL:** When creating the authToken, explicitly designate the user as a tenant admin by passing the `externalTenantId`
    * Provide this authToken to the Mindset SDK that runs in the tenant admin's page

    <Info>
      The tenant admin must have an authToken with `externalTenantId` specified to access Agent Builder SDK components
    </Info>
  </Step>

  <Step title="Tenant Creates Agent">
    **Tenant Admin** (externalTenantId: "tenant-acme-123") → Creates Agent via Agent Builder or Agent Configuration
  </Step>

  <Step title="Tenant Creates Contexts & Uploads Files (Optional)">
    * Creates Contexts via Context Builder or Context Configuration
    * Uploads Files (PDFs, docs, training materials, etc.)

    <Info>
      This step is optional if you're providing app-level contexts or using RAG MCP
    </Info>
  </Step>
</Steps>

## Part 2: Deploy to End-Users

<Steps>
  <Step title="Your Backend Determines Permissions">
    Based on your platform's permission system, determine for each end-user:

    * Which agent(s) should they access?
    * Which contexts/knowledge should they see?
    * Which MCP tools should be available?
  </Step>

  <Step title="Create Agent Session via API">
    **Required:**

    * `agentUid` (tenant's agent)
    * `externalUserId`

    **Choose ONE:**

    * `contextUids` (up to 30)
    * OR 1 RAG MCP

    **Optional:**

    * `mcpserverUids` (tools, up to 5 total)

    **Recommended:**

    * `tags` (include externalTenantId)
  </Step>

  <Step title="Receive agentSessionUid">
    API returns unique session identifier Example: `agentSessionUid: "agent-123::session-789"`
  </Step>

  <Step title="Generate Authentication Token for End-User">
    **Before the end-user can access the agent:**

    * Generate an `authToken` for the end-user
    * **CRITICAL:** The user's `externalUserId` in the authToken **must be an exact match** to the `externalUserId` used when creating the agent session for them
    * Provide this authToken to the Agent SDK component

    <Warning>
      ExternalUserId mismatch between authToken and agent session will prevent the user from accessing the agent
    </Warning>
  </Step>

  <Step title="Embed Agent Chat SDK for End-User">
    In the end-user's UI, embed:

    ```html theme={null}
            <mindset-agent agentUid="agent-123::session-789"></mindset-agent>
    ```

    ✅ **Deployment Complete!**
  </Step>
</Steps>

## Key Concepts

<AccordionGroup>
  <Accordion title="Authentication Requirements">
    **For Tenant Admins (Agent Builder SDK):**

    * Generate authToken with `externalTenantId` specified
    * This designates them as tenant admin with access to Agent Builder SDK components

    **For End-Users (Agent SDK):**

    * Generate authToken with `externalUserId`
    * `externalUserId` must exactly match the one used in the agent session creation
  </Accordion>

  <Accordion title="Tenant Isolation">
    * `externalTenantId` filters what tenants see in Agent Builder SDK components
    * Your backend enforces isolation in agent sessions
    * The same `externalTenantId` in the Agent Builder SDK components means users see each other's agents/contexts in the list views
    * Different `externalTenantId` values mean complete isolation in the list views
  </Accordion>

  <Accordion title="Flexible Context Mixing">
    * Agent sessions can combine app-level and tenant-level contexts
    * You control what each user sees through the Agent Sessions API
    * Up to 30 contexts can be provisioned per agent session
  </Accordion>

  <Accordion title="Per-User Permissions">
    * Same agent can be deployed with different contexts and tools for different users
    * Based on your platform's permission system
    * Your backend determines what each end-user can access
  </Accordion>
</AccordionGroup>

## Agent Session Composition Rules

### Rule 1: Knowledge Sources (Mutually Exclusive)

<Warning>
  **Choose ONE:**

  * **Option A:** Up to 30 contexts (app-level and/or tenant-level)
  * **Option B:** Exactly 1 RAG-type MCP

  ❌ Cannot combine contexts and RAG MCP in same session
</Warning>

### Rule 2: MCP Servers (Maximum 5 Total)

RAG-type MCP: 0 or 1\
Tools-type MCPs: 0 to 5\
✅ Valid: 1 RAG MCP + 4 Tools MCPs = 5 total

### Rule 3: Tags (Maximum 10)

Used for reporting, grouping, and filtering\
Recommended: Include externalTenantId

## Valid Configuration Examples

<CodeGroup>
  ```json Configuration 1: Contexts + Tools theme={null}
  {
    "agentUid": "tenant-agent-123",
    "externalUserId": "user-456",
    "contextUids": ["context-1", "context-2", "context-3"],
    "mcpserverUids": ["gmail-tool", "slack-tool"],
    "tags": ["tenant-acme-123"]
  }
  ```

  ```json Configuration 2: RAG MCP + Tools theme={null}
  {
    "agentUid": "tenant-agent-456",
    "externalUserId": "user-789",
    "mcpserverUids": ["company-rag-mcp", "salesforce-tool", "zendesk-tool"],
    "tags": ["tenant-techcorp-456"]
  }
  ```

  ```json Configuration 3: Contexts Only theme={null}
  {
    "agentUid": "tenant-agent-789",
    "externalUserId": "user-012",
    "contextUids": ["context-1", "context-2", "...", "context-30"],
    "tags": ["tenant-widgets-789"]
  }
  ```
</CodeGroup>

## Invalid Configurations

<Warning>
  **❌ Contexts + RAG MCP**

  ```json theme={null}
      {
        "contextUids": ["context-1", "context-2"],
        "mcpserverUids": ["company-rag-mcp"]
      }
  ```

  **Error:** Cannot mix content source types
</Warning>

<Warning>
  **❌ Multiple RAG MCPs**

  ```json theme={null}
      {
        "mcpserverUids": ["company-rag-mcp", "another-rag-mcp"]
      }
  ```

  **Error:** Only 1 RAG-type MCP allowed per session
</Warning>

<Warning>
  **❌ More than 5 MCPs**

  ```json theme={null}
      {
        "mcpserverUids": ["mcp-1", "mcp-2", "mcp-3", "mcp-4", "mcp-5", "mcp-6"]
      }
  ```

  **Error:** Maximum 5 MCP servers per session
</Warning>