Skip to main content
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)
  • Knowledge sources (contexts OR RAG MCP)
  • Tool integrations (MCP servers)
  • 1 specific end-user (identified by externalUserId)
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
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
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

  • Agent: tenant-agent-123
  • Contexts: [context-1, context-2, context-3] (3 contexts)
  • MCP Servers: [gmail-tool, slack-tool] (2 Tools MCPs)
  • Agent: tenant-agent-456
  • MCP Servers: [company-rag-mcp, salesforce-tool, zendesk-tool] (1 RAG + 2 Tools)
  • Agent: tenant-agent-789
  • Contexts: [context-1, context-2, ..., context-30] (30 contexts max)
  • MCP Servers: none

​
Invalid Configurations

  • Contexts: [context-1, context-2]
  • MCP Servers: [company-rag-mcp]
Error: API will reject - cannot mix content source types
  • MCP Servers: [company-rag-mcp, another-rag-mcp]
Error: Only 1 RAG-type MCP allowed per session
  • 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 agentLearn more about Agent Builder 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:
        {
          "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:
        <mindset-agent agentUid="agent-123::session-789"></mindset-agent>

​
Critical Security Note: Tenant Isolation

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

Agent Builder SDK

Learn how tenants create agents using embeddable components

Agent Sessions API

Complete API reference for managing agent sessions

Knowledge Contexts

Understanding context management and RAG

MCP Servers

Integrating tools and services via MCP