# Agent Sessions

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

Deploy tenant-created agents to end-users with dynamic permission control

In order to deploy tenant-made agents to the tenant's end-users, you need to use Agent Sessions. This guide covers agent session composition rules and deployment best practices.

## What is an Agent Session?

An **Agent Session** is a programmatically provisioned runtime instance that couples:

- 1 tenant-level agent (created via [Agent Builder SDK](https://docs4.mindset.ai/v3/features/deploy/ams-sdk))
- Knowledge sources (contexts OR RAG MCP)
- Tool integrations (MCP servers)
- 1 specific end-user (identified by `externalUserId`)

> **Info:** **Key Concept:** Agent sessions enable dynamic, per-user permission control. The same agent can be provisioned with different knowledge sources and tools for different users based on your platform's permission system.

## Agent Session Composition Rules

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

Choose **ONE** option:

- **Option A: Contexts**: Up to 30 context UIDs
- **Option B: RAG MCP**: Exactly 1 RAG-type MCP

> **Warning:** Cannot combine contexts and RAG MCP in same session - API will reject

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

- **RAG-type MCP**: 0 or 1 maximum per session
- **Tools-type MCPs**: 0 to 5 per session

> **Check:** Valid example: 1 RAG MCP + 4 Tools MCPs = 5 total

### Rule 3: Tags (Maximum 10)

Used for reporting, grouping, and filtering agent activity.

## Valid Configuration Examples

#### Configuration 1: Contexts + Tools

- Agent: `tenant-agent-123`
- Contexts: `[context-1, context-2, context-3]` (3 contexts)
- MCP Servers: `[gmail-tool, slack-tool]` (2 Tools MCPs)

#### Configuration 2: RAG MCP + Tools

- Agent: `tenant-agent-456`
- MCP Servers: `[company-rag-mcp, salesforce-tool, zendesk-tool]` (1 RAG + 2 Tools)

#### Configuration 3: Contexts Only

- Agent: `tenant-agent-789`
- Contexts: `[context-1, context-2, ..., context-30]` (30 contexts max)
- MCP Servers: none

## Invalid Configurations

#### ❌ Contexts + RAG MCP

- Contexts: `[context-1, context-2]`
- MCP Servers: `[company-rag-mcp]`

**Error:** API will reject - cannot mix content source types

#### ❌ Multiple RAG MCPs

- MCP Servers: `[company-rag-mcp, another-rag-mcp]`

**Error:** Only 1 RAG-type MCP allowed per session

#### ❌ More than 5 MCPs

- MCP Servers: `[mcp-1, mcp-2, mcp-3, mcp-4, mcp-5, mcp-6]`

**Error:** Maximum 5 MCP servers per session

## Deployment Flow

### 1. Tenant Creates Agent via Agent Builder SDK

Tenant admin uses `<mindset-agents-manager>` to create and configure agent

[Learn more about Agent Builder SDK](https://docs4.mindset.ai/v3/features/deploy/ams-sdk)

### 2. Your Backend Determines Permissions

Based on your platform's permission system, determine which contexts/MCPs the end-user can access

### 3. Create Agent Session via API

POST to AgentSessions API with:

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

### 4. Receive agentSessionUid

API returns unique session identifier (e.g., `"agent-123::session-789"`)

### 5. Embed Agent in User's UI

Use `<mindset-agent>` tag with agentSessionUid:

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

## Critical Security Note: Tenant Isolation

> **Warning:** **Important:** Understanding tenant isolation responsibilities
>
> - **Agent Builder SDK provides UI-level tenant isolation:** Tenants only see their own agents/contexts in management interface
> - **AgentSessions API does NOT enforce tenant boundaries:** No validation checks `externalTenantId` matching
> - **Your responsibility:** Your backend must enforce proper tenant allocation when creating agent sessions
> - **Technical possibility:** Agent from Tenant A could be coupled with context from Tenant B if your backend allows it
>
> Always validate tenant boundaries in your backend before creating agent sessions.

## Agent Session Lifecycle

- **Created on-demand**: Generate new session each time user accesses agent
- **Auto-expires after 31 days of inactivity**: Sessions become inactive if not used
- **Can be manually deleted via API**: DELETE endpoint available for immediate deactivation
- **Multiple sessions per user allowed**: Same user can have multiple active sessions with different configurations

## Related Documentation

- [Agent Builder SDK](https://docs4.mindset.ai/v3/features/deploy/ams-sdk): Learn how tenants create agents using embeddable components
- [Agent Sessions API](https://docs4.mindset.ai/v3/deploy/api/agentsessions-api): Complete API reference for managing agent sessions
- [Knowledge Contexts](https://docs4.mindset.ai/v3/features/build/contexts): Understanding context management and RAG
- [MCP Servers](https://docs4.mindset.ai/v3/features/build/mcp-servers): Integrating tools and services via MCP