m4Mindset docs
llms.txt

Mindset v3 / Build & Optimize / AMS SDK

View as Markdown

Agent Sessions

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

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

Rule 2: MCP Servers (Maximum 5 Total)

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

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

  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

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