Multi-tenant isolation

A tenant ID identifies a scope; it does not authenticate a caller or automatically isolate every resource. In v4, configure storage scoping explicitly and authorize access to sessions, tools, and external records in the host. There is no AgentConfig.tenant option.

Quick Start

This host function receives an already authenticated identity, a host-owned storage driver, and a model. AgentFactory scopes memory and checkpoint storage; the run options carry the same identity to hooks and tools.

import { AgentFactory, type ModelProvider, type StorageDriver } from "@agentium/core";

export async function answerForTenant(
  model: ModelProvider,
  storage: StorageDriver,
  identity: { tenantId: string; userId: string },
  sessionId: string,
  input: string,
) {
  if (!identity.tenantId || !identity.userId) throw new Error("Verified identity required");
  const factory = new AgentFactory({
    name: "support", model,
    memory: { storage, summaries: false },
  });
  const agent = factory.create(identity);
  try {
    return await agent.run(input, { ...identity, sessionId });
  } finally {
    await agent.close({ closeStorage: false });
  }
}

The host initializes shared storage before accepting requests and closes it after all Agents have drained. Passing closeStorage: false prevents one request from closing a shared connection. Authenticate and authorize sessionId before invoking this function; the function does not validate session ownership itself.

Tenant-Scoped Storage

For a custom data namespace, wrap a storage driver explicitly:

import { InMemoryStorage, TenantScopedStorage } from "@agentium/core";

const base = new InMemoryStorage();
const acme = new TenantScopedStorage(base, "acme");
const other = new TenantScopedStorage(base, "other");
try {
  await acme.set("notes", "order-42", { status: "open" });
  console.log(await acme.get("notes", "order-42")); // { status: "open" }
  console.log(await other.get("notes", "order-42")); // null
} finally {
  await base.close();
}

TenantScopedStorage prefixes namespaces with t:<tenantId>:. ScopedStorage, used by the factories, supports tenant and user scope. Both wrappers delegate close() to their underlying driver; the host should close a shared driver once. Use separate database accounts or storage instances when the application requires physical isolation.

Extracting Tenant ID

extractTenantFromHeaders() and extractTenantFromJwt() extract values; neither verifies signatures, authenticates a user, nor confirms organization membership. Read tenant claims only after your authentication middleware has verified them. Never accept an arbitrary X-Tenant-Id header as authorization.

Context Propagation

Pass tenantId and userId in agent.run(input, options) when hooks and tools need them. Factory storage scope and run context are separate responsibilities. Application tools must still scope their own SQL, file, HTTP, and vector queries. Use the owned-session API recipe to verify missing credentials, cross-user denial, and session reuse. For memory visibility rules, read memory isolation.

Verify isolation

Test two verified tenants with the same session label and document ID. Check memory, checkpoints, tool results, and external data independently. Include a request with a conflicting body identity and assert denial before model or tool execution. A successful namespace test alone does not establish end-to-end authorization.

Ship

Identity and boundaries

Recovery and upgrades

Operating the service

Multi-tenant isolation

Quick Start

Tenant-Scoped Storage

Extracting Tenant ID

Context Propagation

Verify isolation

​Quick Start

​Tenant-Scoped Storage

​Extracting Tenant ID

​Context Propagation

​Verify isolation

Quick Start

Tenant-Scoped Storage

Extracting Tenant ID

Context Propagation

Verify isolation