Multi-Tenant Primitives

The problem

A single Agentium process serving a SaaS product needs to:

Isolate tenants. Customer A’s memory must never bleed into customer B’s session.
Isolate users within a tenant. Alice’s userMemory.preferences must not be visible to Bob.
Share infrastructure. One model client, one StorageDriver, one process — but logically partitioned data.

Agentium v2.0 ships two building blocks:

AgentFactory / TeamFactory / WorkflowFactory — construct scope-aware agents per request.
ScopedStorage — namespace every read/write on any StorageDriver by tenant + user.

`ScopedStorage`

The lowest-level primitive. Wraps any StorageDriver and rewrites every namespace by prefixing with tenant + user identifiers.

import { ScopedStorage, SqliteStorage } from "@agentium/core";

const raw = new SqliteStorage("./data.db");

const acmeUserA = new ScopedStorage(raw, { tenantId: "acme", userId: "u-alice" });
const acmeUserB = new ScopedStorage(raw, { tenantId: "acme", userId: "u-bob" });

await acmeUserA.set("notes", "favorite_color", "blue");
await acmeUserB.set("notes", "favorite_color", "green");

await acmeUserA.get("notes", "favorite_color"); // "blue"
await acmeUserB.get("notes", "favorite_color"); // "green"

Namespace transformation

inner.set("sessions", "session-123", value)
  with scope { tenantId: "acme", userId: "u-alice" }
  →  inner.set("tenant:acme:user:u-alice:sessions", "session-123", value)

Rules:

Scope	Resulting namespace
`{ tenantId: "acme", userId: "u-alice" }`	`tenant:acme:user:u-alice:<ns>`
`{ tenantId: "acme" }` (no user)	`tenant:acme:<ns>`
`{ userId: "alice" }` (no tenant)	`user:alice:<ns>`
`{}` (empty)	`<ns>` (no prefix; identical to raw driver)

Two tenants on the same underlying driver therefore see disjoint key spaces.

Methods

ScopedStorage implements the full StorageDriver interface — get, set, delete, list, initialize, close. Every call goes through the namespace rewrite. initialize() and close() delegate to the inner driver (so calling close() on the scoped wrapper closes the SHARED driver — be careful in production).

Use directly without a factory

If you don’t need AgentFactory’s sugar, just construct a fresh agent per request with a ScopedStorage:

const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  memory: {
    storage: new ScopedStorage(rawStorage, { tenantId, userId }),
  },
});

`AgentFactory`

Sugar over ScopedStorage. Define the agent template once, call factory.create(scope) per request to materialize a scoped Agent.

Construction

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

const factory = new AgentFactory({
  name: "assistant",
  model: openai("gpt-4o"),
  instructions: "You are a helpful assistant.",
  memory: {
    storage: new InMemoryStorage(), // shared underlying storage
  },
});

The AgentConfig you pass is the template. Don’t include userId or any per-user state in the template — that’s what the factory injects.

Per-request agent creation

import express from "express";

const app = express();
app.use(express.json());

app.post("/chat", async (req, res) => {
  const tenantId = req.user.tenant;
  const userId = req.user.id;

  const agent = factory.create({ tenantId, userId });
  const result = await agent.run(req.body.input, { sessionId: `${tenantId}:${userId}` });
  res.json({ text: result.text });
});

factory.create({ ... }) returns a new Agent(...) whose:

userId is set to the scoped user (used by userMemory and event tracing).
memory.storage is wrapped in ScopedStorage.
checkpointing.storage, culture.storage, versioning.storage are also wrapped if present.
register: false is forced so the agent doesn’t pollute the global registry.

The factory itself is cheap (no model client allocation); allocate one per agent template at boot, then create() per request.

Method signature

class AgentFactory {
  constructor(base: AgentConfig);
  create(scope?: FactoryContext): Agent;
}

interface FactoryContext {
  tenantId?: string;
  userId?: string;
}

create() with no args returns an unscoped Agent (useful for admin / cron jobs).

What gets scoped automatically

AgentConfig field	Wrapped in ScopedStorage?
`memory.storage`	✅
`checkpointing` (when set as `{ storage }`)	✅
`culture.storage`	✅
`versioning.storage`	✅
`costTracker`	❌ (you tag costs per scope yourself)
`semanticCache`	❌ (you decide whether to share or scope)
Custom `tools` that hold their own storage	❌ (your responsibility)

If you have custom tools that persist anything, wrap their storage in ScopedStorage manually before adding them to the template.

`TeamFactory`

Identical pattern for Team:

import { TeamFactory, openai, TeamMode } from "@agentium/core";

const teamFactory = new TeamFactory({
  name: "research-crew",
  mode: TeamMode.Coordinate,
  model: openai("gpt-4o"),
  members: [researchAgent, writerAgent, reviewerAgent],
  memory: { storage: sharedStorage },
});

app.post("/team", async (req, res) => {
  const team = teamFactory.create({ tenantId: req.user.tenant });
  const result = await team.run(req.body.input);
  res.json(result);
});

Scopes memory.storage the same way. The team’s members are passed by reference; if they have their own scoped storage, that’s preserved.

`WorkflowFactory`

import { WorkflowFactory } from "@agentium/core";

const wfFactory = new WorkflowFactory({
  name: "etl",
  initialState: { rows: [] },
  steps: [...],
});

const wf = wfFactory.create({ tenantId: "acme" });
await wf.run();

Workflows currently don’t directly hold storage in their top-level config, so WorkflowFactory mostly disables global registration. The per-step agents (referenced by the workflow) carry whatever scope they were constructed with.

Putting it together — full SaaS pattern

import {
  AgentFactory,
  InMemoryStorage,
  openai,
  SemanticToolSelector,
  OpenAIEmbedding,
} from "@agentium/core";
import express from "express";

// One-time setup
const storage = new InMemoryStorage();
const embedder = new OpenAIEmbedding();

const factory = new AgentFactory({
  name: "assistant",
  model: openai("gpt-4o"),
  memory: { storage },
});

const selector = new SemanticToolSelector({ embedder, topK: 5 });
await selector.indexTools(allRegisteredTools);

const app = express();
app.use(express.json());

app.post("/chat", async (req, res) => {
  const { tenant, id: userId } = req.user;
  const shortlist = await selector.select(req.body.input);

  const agent = factory.create({ tenantId: tenant, userId });
  agent.setTools([...alwaysOnTools, ...shortlist]);

  const result = await agent.run(req.body.input, {
    sessionId: `${tenant}:${userId}`,
  });

  res.json({ text: result.text, usage: result.usage });
});

app.listen(3000);

Operational notes

One storage driver per process. Multiple ScopedStorage instances share one underlying driver — keep the driver alive for the process lifetime.
Don’t close the inner driver via the scoped wrapper. Adding a check to prevent accidental close-via-wrap is on the roadmap; for now, just call rawStorage.close() directly at shutdown.
For metrics / cost tracking, set tenantId on RunContext.metadata so observability picks it up. The factory already does this when you use userId — extend to tenantId in your hooks.
Test isolation explicitly. A unit test that writes under tenant A and reads under tenant B (expecting null) catches regressions early.

​Multi-Tenant Primitives

​The problem

​ScopedStorage

​Namespace transformation

​Methods

​Use directly without a factory

​AgentFactory

​Construction

​Per-request agent creation

​Method signature

​What gets scoped automatically

​TeamFactory

​WorkflowFactory

​Putting it together — full SaaS pattern

​Operational notes

​See also