Designing Multi‑Tenant Agent Isolation for Verifiable Tenant Boundaries

1. Expand isolation from data layer to execution layer

In a multi‑tenant SaaS, the tenant boundary traditionally lives in database query filters, row‑level permissions, and object‑storage paths. When an Agent is added, the boundary must also cover document reads, vector‑store queries, tool calls, draft generation, approval triggers, and intermediate reasoning stored in context or task state. Forgetting the tenant at any of these steps creates a high‑risk automation system.

Business Data: traditional focus = query filtering, row‑level permissions, storage paths; agent risk = tool calls may read or write out‑of‑scope data.

Knowledge Retrieval: traditional focus = document and index permissions; agent risk = vector recall can mix answers from other enterprises.

Model Context: traditional focus = rarely involved; agent risk = historical dialogue, memory, or tool results may be reused incorrectly.

Prompt Configuration: traditional focus = hard‑coded on the server; agent risk = tenant‑specific rules, banned words, approval policies, brand tone may be loaded incorrectly.

Execution Environment: traditional focus = application instances, queues, caches, schedulers; agent risk = code execution, plugin calls, and long‑task state can interfere across tenants.

After widening the isolation surface, a tenant control plane is required to avoid scattering isolation logic across modules.

2. Tenant control plane injects identity, configuration, and policy into every execution

The entry point parses tenant context from domain, organization ID, user session, API key, enterprise WeChat app, SAML/OIDC token, or internal gateway signature and converts it into a unified tenant_context recognized by downstream modules.

The control plane stores three categories of information:

Identity & Permissions: which tenant, which role, which tools the user may invoke.

Resources & Quotas: which models, concurrency limits, number of vector indexes, and task queues the tenant may use.

Runtime Policies: default Prompt, knowledge‑base scope, approval rules, audit requirements, and data‑retention periods.

Minimal fields of tenant_context:

tenant_id: unique identifier used for databases, vector stores, caches, logs, and task queues.

user_id & role: determines who the tool call represents.

policy_version: selects the version of approval, risk‑control, data‑retention, and masking policies.

prompt_profile: selects the set of system prompts, business rules, and tenant‑specific constraints.

resource_scope: defines which knowledge bases, tools, models, queues, and storage spaces are visible for the request.

With a unified control plane, the execution layer can achieve “shared engine, isolated runtime”: the engine is not deployed per tenant, but each execution carries the tenant boundary.

3. Compute isolation tiered by tenant risk level

Agent compute isolation includes model calls, tool execution, code sandbox, asynchronous tasks, and cache state. Isolation strength must be balanced against cost.

Pool (shared): suitable for SMBs and low‑risk read/write tasks; all workers, caches, logs, and vector retrieval must carry tenant_context.

Bridge (partitioned): suitable for large or industry‑specific customers; shared control plane with independent queues, independent vector namespace, independent tool credentials, and independent quotas.

Silo (dedicated): suitable for financial, government, or high‑compliance customers; dedicated execution clusters, dedicated knowledge bases, dedicated keys, dedicated audit pipelines, and independent release cadence.

Long‑running tasks (minutes‑long) need tenant‑partitioned state, checkpoints, and temporary files, with continuous tenant‑boundary verification on resume, retry, or replay. If code or plugin execution is allowed, the sandbox must add a tenant‑level layer: tenant‑scoped temporary directories, network‑access policies, allowed‑tool lists, and resource limits.

4. RAG isolation must filter by tenant before retrieval

Retrieval‑augmented generation (RAG) splits enterprise documents into chunks, vectorizes them, and recalls relevant pieces for a user query. Cross‑tenant recall is the main risk; filtering after generation is too late.

Three common isolation approaches:

One independent index or collection per tenant (clear boundary, higher cost).

Shared index with namespace/partition/tenant partitioning.

Shared index with mandatory tenant_id filter in metadata.

Engineering rules (5):

Store tenant_id, knowledge‑base ID, permission tags, and data version when ingesting documents.

Vector retrieval API must reject requests lacking a tenant condition.

Re‑validate tenant and permissions on results before returning.

High‑value tenants use dedicated namespace/collection/database or physical index.

Record source, version, and permissions of recalled fragments before feeding them to the model for auditability.

Vendor capabilities:

Pinecone – namespace isolation.

Weaviate – collection‑level multi‑tenant.

Qdrant – payload filtering and sharding.

Milvus – database/collection/partition or partition‑key splitting.

Selection depends on tenant count, per‑tenant data volume, query latency, deletion requirements, and cost.

5. Prompt dynamic loading requires a versioned configuration system

Prompt templates carry business rules, brand tone, approval thresholds, knowledge‑base scope, banned actions, and compliance requirements. A versioned template combined with tenant configuration enables stable maintenance, gradual rollout, and audit.

Prompt loading chain (4 layers):

Platform baseline: output format, safety boundaries, tool‑call conventions, generic refusal policies.

Industry template: domain rules for after‑sales, legal, procurement, finance, HR, etc.

Tenant configuration: internal processes, approval roles, brand voice, sensitive words, disabled tools.

Task context: current user goal, authorized resources, retrieved evidence, current step state.

Each Agent reply and tool call must log the Prompt version, tenant‑policy version, and retrieved evidence version to enable reproducible audits. Fallback strategies: use platform defaults when tenant config is missing; reject high‑risk actions on config validation failure; gray‑scale Prompt versions per tenant, department, or task type.

6. Comprehensive architecture

The architecture consists of:

Entry authentication and tenant parsing.

Tenant control plane (identity, quotas, policies, Prompt profile, resource scope).

Shared Agent engine (planning, tool selection, state machine, model calls).

Isolated execution layer (queues, sandbox, tool credentials, task state, temporary files).

Isolated knowledge layer (namespace/collection, tenant filter, document permissions).

Audit‑replay layer (trace ID, Prompt version, retrieval source, tool results).

Orchestration is shared; context, resources, permissions, and side‑effects are isolated per tenant.

7. Pre‑launch checklist: verify tenant boundaries before expanding intelligent capabilities

Eight verification items:

Entry layer rejects requests lacking tenant_context.

All tool calls re‑validate tenant, user, and action permissions on the server.

Vector retrieval API enforces tenant filter; the model cannot decide the retrieval scope.

Prompt loading records template version, tenant‑config version, and policy version.

Long‑task state, checkpoints, caches, and temporary files are partitioned by tenant.

High‑risk actions go through approval or human interruption; the model cannot submit them directly.

Logs can trace request, retrieval, Prompt, tool call, and final answer as a single chain.

Regular cross‑tenant attack tests: wrong tenant_id, over‑privileged namespace, Prompt poisoning, forged tool parameters.

Clear, verifiable tenant boundaries are essential for trustworthy multi‑tenant Agent SaaS. The engine can become stronger, but tenant boundaries must remain continuously enforceable.