34 — Tenant Isolation

Concept overview

Tenant isolation spans the entire agent system: authentication, retrieval, caches, memory, queues, checkpoints, tools, logs, and model-serving resources. Adding a tenant column is useful only if every relevant operation enforces it. Derive tenant context from trusted identity and carry it through all asynchronous and delegated work.

Choose isolation strength from risk and operating requirements. Shared infrastructure with enforced partitions can be efficient; separate databases, keys, workers, or accounts provide stronger boundaries at greater cost. Data isolation and performance isolation are distinct: preventing cross-tenant reads does not prevent one tenant from exhausting shared capacity.

Why it matters in production

Proof of concept

A prototype with one tenant hides many isolation assumptions. Add two synthetic tenants with overlapping document and user identifiers before expanding access.

Production

Production uses mandatory tenant predicates, tenant-aware cache keys, scoped credentials, and isolated session state. Background jobs must reconstruct trusted tenant context rather than use a global default.

Enterprise scale

At scale, test migration, backup restoration, support tooling, and noisy-neighbor behavior. Isolation controls need to remain intact during administrative operations as well as ordinary requests.

Architecture components

Tenant identity resolver

Establishes trusted tenant context from authenticated sessions or service credentials.

Data partition layer

Enforces tenant boundaries in retrieval, records, object storage, and checkpoint access.

Execution scope

Carries tenant identity through queues, workers, delegation, and tool credentials.

Cache and memory boundary

Prevents shared keys, reused sessions, or summaries from mixing tenant content.

Resource governor

Applies tenant quotas and monitors performance interference separately from data access.

The architecture, mapped

flowchart LR
 I["Trusted tenant identity"] --> G["Request scope"]
 G --> Q["Tenant-scoped job"]
 Q --> W["Scoped worker"]
 W --> D["Partitioned document store"]
 W --> C["Tenant-keyed cache"]
 W --> S["Tenant checkpoint state"]
 W --> T["Scoped tool credentials"]
 W --> R["Resource quota"]

sequenceDiagram
 participant A as Authenticated API
 participant Q as Durable queue
 participant W as Worker
 participant S as Scoped data service
 A->>A: Resolve trusted tenant identity
 A->>Q: Persist job with verified tenant context
 Q->>W: Deliver job and context
 W->>W: Validate scope and claim ownership
 W->>S: Read using tenant-scoped credentials
 S-->>W: Authorized tenant records
 W->>S: Store artifact with tenant ownership

Runtime flow

1. 1

   Resolve tenant

   Bind a request to authenticated tenant context and reject conflicting user-supplied identifiers.

2. 2

   Scope resources

   Select permitted partitions, keys, credentials, and execution pools.

3. 3

   Propagate context

   Attach trusted tenant metadata to durable jobs and child tasks.

4. 4

   Enforce access

   Apply mandatory boundaries at every data and tool service, including cache lookup.

5. 5

   Publish scoped results

   Validate that artifacts and citations belong to the requesting tenant.

6. 6

   Audit isolation

   Test cross-tenant requests, administrative paths, and resource contention continuously.

Separating building-owner portfolios

Property management software · Illustrative enterprise scenario, not a reported customer outcome.

Business situation

A SaaS platform offers maintenance assistants to property owners with separate tenants and overlapping contractor names.

The problem

A cache keyed only by a natural-language question can return another owner's maintenance history.

Agent requirement

The assistant must isolate portfolio records, conversations, work orders, and generated reports while sharing infrastructure efficiently.

Architecture

Trusted tenant context scopes database rows, vector partitions, cache keys, worker jobs, and contractor-tool credentials.

Runtime

• A manager asks about recurring elevator failures; retrieval and cache lookup are restricted to that owner's portfolio.
• The generated report and its download route retain tenant ownership and recheck it on access.

Failure scenario

If a background job lacks tenant context, it fails before retrieving data instead of falling back to an application-wide credential.

Operational impact

Measure cross-tenant test failures, missing-scope rejections, cache isolation, and noisy-neighbor latency under concurrent load.

Architecture tradeoffs

Failure scenarios & recovery

Common architecture mistakes

Trusting tenant IDs in request text

Resolve identity from authenticated context.

Isolating the database but sharing cache keys

Include tenant and authorization scope across all derived stores.

Ignoring backups and migrations

Test isolation through administrative data movement.

When to choose this pattern

Choose it when

• One platform serves independent customer organizations.
• Data and operational boundaries differ by tenant.
• Shared resources need both access and fairness controls.

Avoid it when

• The application is intentionally single-tenant and isolated already.
• Tenant identity cannot be established reliably.
• Shared deployment cannot meet required boundary strength.

Architecture checklist

• Require trusted tenant context everywhere.
• Scope caches, memory, and artifacts.
• Propagate identity through asynchronous jobs.
• Test cross-tenant identifier collisions.
• Review backup and support-tool access.
• Load-test noisy-neighbor behavior.

Related concepts

• 21 — Authorization-Aware RAG
• 23 — Attribute-Based Access Control (ABAC)
• 25 — Data PII Masking
• 33 — Token Rate Limiting
• 95 — Distributed Memory Architectures

Primary references

• NIST SP 800-162: attribute based access control
• Open Policy Agent documentation