Gateway Tenant Profiles

Isolate tenants per route with RouteBinding.profile — one gateway multiplexes many tenants without sharing memory or secrets

A route’s profile: field names an isolated tenant scope so one gateway can safely serve many tenants without leaking memory or secrets between them.

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 isolation scope.

   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 wrapper knows which tenant scope 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. Leave a route unscoped

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

   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. An unmatched route yields RouteMatch(profile=None).

---

Fail-Closed Contract

Tenant isolation is fail-closed by design — a misconfigured route can never silently share another tenant’s memory or secrets.

• Blank or whitespace-only profile normalises to None (unscoped) — never an empty-named scope.
• An unmatched route yields RouteMatch(profile=None) and never inherits another tenant’s profile, even when the fallback agent is the same.
• Treat profile is None as “no tenant scope” and fail closed rather than entering an anonymous namespace.

This page documents the routing-protocol contract only: RouteBinding.profile and RouteMatch.profile are defined on the gateway protocol. The wrapper wiring that actually enters a profile’s memory namespace / secret scope is a follow-up — describe the contract to integrators, but don’t rely on the wrapper isolation subsystem until it ships.

---

Configuration Options

Field	Type	Default	Description
profile (on RouteBinding)	Optional[str]	None	Isolated tenant-profile name the route enters. Blank/whitespace coerces to None.
profile (on RouteMatch)	Optional[str]	None	Populated by resolve_route() from the winning binding; None when unmatched or unscoped.

---

Best Practices

Give every tenant its own profile name

Use one stable, tenant-specific value per route (acme, globex). Never reuse a profile name across tenants — that would merge their memory and secret scopes.

Treat None as fail-closed, not shared

When match.profile is None, do not fall back to a “default tenant” that another route also uses. Unscoped means isolated, not shared.

Bind tenants on stable identifiers

Route tenant profiles on channel_id or account — stable platform ids — rather than display names, which change.

Keep profile names out of user-controlled input

Profile names come from your config, not from message content. Never derive a profile from a field a user can set.

---

Related

Route Bindings

The full routing surface — match by peer, role, channel, account, and priority.

Scoped Approvals

Durable, agent-scoped approval grants that don’t leak across agents.