# End-to-end Agent Deployment Flow

> You're reading the Mindset v3 documentation. v3 is no longer sold; this is reference for existing customers. Mindset 4 docs are at /docs.

From tenant creation to end-user access

## Overview: Two-Part Process

- **Part 1: Enable Creation**: Tenants create agents and contexts using Agent Builder SDK components
- **Part 2: Deploy to Users**: You deploy agents to end-users via Agent Sessions API

## Part 1: Enable Tenant Creation

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

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

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

### 4. Tenant Creates Agent

**Tenant Admin** (externalTenantId: "tenant-acme-123") → Creates Agent via Agent Builder or Agent Configuration

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

## Part 2: Deploy to End-Users

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

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

### 3. Receive agentSessionUid

API returns unique session identifier Example: `agentSessionUid: "agent-123::session-789"`

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

### 5. Embed Agent Chat SDK for End-User

In the end-user's UI, embed:

```html
        <mindset-agent agentUid="agent-123::session-789"></mindset-agent>
```

✅ **Deployment Complete!**

## Key Concepts

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

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

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

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

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

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

**Configuration 1: Contexts + Tools**

```json
{
  "agentUid": "tenant-agent-123",
  "externalUserId": "user-456",
  "contextUids": ["context-1", "context-2", "context-3"],
  "mcpserverUids": ["gmail-tool", "slack-tool"],
  "tags": ["tenant-acme-123"]
}
```

**Configuration 2: RAG MCP + Tools**

```json
{
  "agentUid": "tenant-agent-456",
  "externalUserId": "user-789",
  "mcpserverUids": ["company-rag-mcp", "salesforce-tool", "zendesk-tool"],
  "tags": ["tenant-techcorp-456"]
}
```

**Configuration 3: Contexts Only**

```json
{
  "agentUid": "tenant-agent-789",
  "externalUserId": "user-012",
  "contextUids": ["context-1", "context-2", "...", "context-30"],
  "tags": ["tenant-widgets-789"]
}
```

## Invalid Configurations

> **Warning:** **❌ Contexts + RAG MCP**
>
> ```json
>     {
>       "contextUids": ["context-1", "context-2"],
>       "mcpserverUids": ["company-rag-mcp"]
>     }
> ```
>
> **Error:** Cannot mix content source types

> **Warning:** **❌ Multiple RAG MCPs**
>
> ```json
>     {
>       "mcpserverUids": ["company-rag-mcp", "another-rag-mcp"]
>     }
> ```
>
> **Error:** Only 1 RAG-type MCP allowed per session

> **Warning:** **❌ More than 5 MCPs**
>
> ```json
>     {
>       "mcpserverUids": ["mcp-1", "mcp-2", "mcp-3", "mcp-4", "mcp-5", "mcp-6"]
>     }
> ```
>
> **Error:** Maximum 5 MCP servers per session