Gateway Tenant Profiles

Isolate tenant memory per route — the same agent serves many tenants without sharing conversation history

A route’s profile: field keys memory and session state per tenant on every turn, so one gateway multiplexes many tenants and their conversation histories never cross.

from praisonaiagents import Agent

# Same agent, two tenants — memory never crosses between them.
support = Agent(name="support", instructions="Help the customer.")
support.launch(gateway_config="gateway.yaml")

agents:
  support:
    instructions: "Help the customer."
    model: gpt-4o-mini

channels:
  discord-acme:
    platform: discord
    token: ${ACME_DISCORD}
    routes:
      default: { agent: support, profile: acme }
  slack-globex:
    platform: slack
    token: ${GLOBEX_SLACK}
    routes:
      default: { agent: support, profile: globex }

Two channels, two tenants, one agent — acme’s chat history and globex’s chat history are stored under separate keys and never leak into each other.

Quick Start

1. Bind two tenants to the same agent

   Give each route a different profile: value. The same support agent serves both tenants, but each route names its own memory namespace.

   agents:
     support:
       instructions: "You are the support assistant."
       model: gpt-4o-mini
   
   routing:
     bindings:
       - agent: support
         channel_id: discord-acme
         profile: acme
       - agent: support
         channel_id: slack-globex
         profile: globex

2. Read the resolved profile in code

   resolve_route() copies the winning binding’s profile onto the RouteMatch, so the gateway knows which tenant namespace to enter for the turn.

   from praisonaiagents.gateway import RouteBinding, RouteFacts, resolve_route
   
   bindings = [
       RouteBinding(agent="support", channel_id="discord-acme", profile="acme"),
       RouteBinding(agent="support", channel_id="slack-globex", profile="globex"),
   ]
   
   match = resolve_route(bindings, RouteFacts(channel_id="discord-acme"), default_agent="support")
   
   print(match.agent)    # "support"
   print(match.profile)  # "acme"

3. Isolate a whole tenant server in one line

   Bind profile: on a guild_id rule to isolate a whole tenant server — every current and future channel in the guild inherits the namespace.

   channels:
     discord-fleet:
       platform: discord
       token: ${DISCORD_BOT_TOKEN}
       routes:
         default: general
       bindings:
         - { guild_id: "9001", agent: support, profile: acme   }  # entire acme server → acme namespace
         - { guild_id: "9002", agent: support, profile: globex }  # entire globex server → globex namespace

   A channel-level route also covers the threads beneath it — see Parent-chain matching.

4. Leave a route unscoped

   Omit profile: (or leave it blank) and the route stays unscoped — match.profile is None and its memory is never namespaced.

   match = resolve_route(bindings, RouteFacts(channel_id="unknown"), default_agent="support")
   
   print(match.agent)    # "support"  (fallback)
   print(match.profile)  # None       (never inherits acme or globex)

How It Works

resolve_route() picks the most-specific matching binding and copies its profile onto the returned RouteMatch; the gateway then enters that namespace before the agent runs, and every storage key for the turn is prefixed with profile:<name>:. An unmatched route yields RouteMatch(profile=None) and stays unscoped.

What the Profile Isolates Today

Only memory/session state is namespaced by the profile today; the other dimensions named on the routing protocol are separable follow-ups.

Storage-key example

The tenant name appears as profile:<name>: at the head of the key, so you can reason about exactly what is isolated.

# Unscoped route (no profile)
storage_key = "u1"

# Route with profile: acme
storage_key = "profile:acme:u1"

# Route with profile: acme + per_chat scope
storage_key = "profile:acme:telegram:acct:default:chat:-100123:"

When To Use a Profile

Fail-Closed Contract

Configuration Options

At runtime the resolved profile flows into BotSessionManager‘s storage-key derivation on every routed turn — Discord and Slack via _routed_message_handler, Telegram via handle_message — so the memory namespace is applied before the agent runs.

Best Practices

Related