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

# 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](/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.
</Info>

## Agent Session Composition Rules

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

Choose **ONE** option:

<CardGroup cols={2}>
  <Card title="Option A: Contexts" icon="database">
    Up to 30 context UIDs
  </Card>

  <Card title="Option B: RAG MCP" icon="brain">
    Exactly 1 RAG-type MCP
  </Card>
</CardGroup>

<Warning>
  Cannot combine contexts and RAG MCP in same session - API will reject
</Warning>

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

### Rule 3: Tags (Maximum 10)

Used for reporting, grouping, and filtering agent activity.

## Valid Configuration Examples

<AccordionGroup>
  <Accordion title="Configuration 1: Contexts + Tools" icon="check">
    * Agent: `tenant-agent-123`
    * Contexts: `[context-1, context-2, context-3]` (3 contexts)
    * MCP Servers: `[gmail-tool, slack-tool]` (2 Tools MCPs)
  </Accordion>

  <Accordion title="Configuration 2: RAG MCP + Tools" icon="check">
    * Agent: `tenant-agent-456`
    * MCP Servers: `[company-rag-mcp, salesforce-tool, zendesk-tool]` (1 RAG + 2 Tools)
  </Accordion>

  <Accordion title="Configuration 3: Contexts Only" icon="check">
    * Agent: `tenant-agent-789`
    * Contexts: `[context-1, context-2, ..., context-30]` (30 contexts max)
    * MCP Servers: none
  </Accordion>
</AccordionGroup>

## Invalid Configurations

<AccordionGroup>
  <Accordion title="❌ Contexts + RAG MCP" icon="xmark">
    * Contexts: `[context-1, context-2]`
    * MCP Servers: `[company-rag-mcp]`

    **Error:** API will reject - cannot mix content source types
  </Accordion>

  <Accordion title="❌ Multiple RAG MCPs" icon="xmark">
    * MCP Servers: `[company-rag-mcp, another-rag-mcp]`

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

  <Accordion title="❌ More than 5 MCPs" icon="xmark">
    * MCP Servers: `[mcp-1, mcp-2, mcp-3, mcp-4, mcp-5, mcp-6]`

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

## Deployment Flow

<Steps>
  <Step title="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://docs.mindset.ai/features/deploy/ams-sdk)
  </Step>

  <Step title="Your Backend Determines Permissions">
    Based on your platform's permission system, determine which contexts/MCPs the end-user can access
  </Step>

  <Step title="Create Agent Session via API">
    POST to AgentSessions API with:

    ```json theme={null}
            {
              "agentUid": "tenant-agent-123",
              "externalUserId": "user-456",
              "contextUids": ["context-1", "context-2"],
              "mcpserverUids": ["gmail-tool", "slack-tool"]
            }
    ```
  </Step>

  <Step title="Receive agentSessionUid">
    API returns unique session identifier (e.g., `"agent-123::session-789"`)
  </Step>

  <Step title="Embed Agent in User's UI">
    Use `<mindset-agent>` tag with agentSessionUid:

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

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

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

<CardGroup cols={2}>
  <Card title="Agent Builder SDK" icon="toolbox" href="https://docs.mindset.ai/features/deploy/ams-sdk">
    Learn how tenants create agents using embeddable components
  </Card>

  <Card title="Agent Sessions API" icon="code" href="https://docs.mindset.ai/deploy/api/agentsessions-api">
    Complete API reference for managing agent sessions
  </Card>

  <Card title="Knowledge Contexts" icon="book" href="https://docs.mindset.ai/features/build/contexts">
    Understanding context management and RAG
  </Card>

  <Card title="MCP Servers" icon="plug" href="https://docs.mindset.ai/features/build/mcp-servers">
    Integrating tools and services via MCP
  </Card>
</CardGroup>