Create scoped Agent instances

Use a factory when several callers need the same Agent configuration with separate storage namespaces. Authenticate the caller before creating an instance; a factory does not verify identity or authorize domain tools.

`ScopedStorage`

ScopedStorage prefixes namespaces with the supplied tenant and user IDs. It wraps a StorageDriver, so database credentials and physical storage remain with the underlying driver. Use host-controlled, normalized identifiers; do not accept arbitrary namespace strings from a request.

`AgentFactory`

This complete local example uses in-memory storage owned by one short-lived Agent. It requires core and your configured model provider. Replace the demo scope with verified host identity.

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

export async function runScopedExample(model: ModelProvider, input: string) {
  const factory = new AgentFactory({
    name: "support", model,
    instructions: "Answer support questions briefly.",
    memory: { storage: new InMemoryStorage() },
  });
  const agent = factory.create({ tenantId: "demo", userId: "alice" });
  try {
    return await agent.run(input, { tenantId: "demo", userId: "alice", sessionId: "conversation-42" });
  } finally { await agent.close(); }
}

The created Agent is unregistered. Storage namespaces include the scope. Runtime identity is still explicit on the run so tools can inspect the verified tenant/user. Reuse the same backing store and owner scope when conversation state must continue; this short-lived in-memory example disappears when its owner ends.

Method signature

new AgentFactory(baseConfig).create(scope?) returns an Agent. Omitting scope creates an unscoped instance. See factory declarations for exact types.

What gets scoped automatically

Configuration	Factory behavior
`memory.storage`	Wraps in `ScopedStorage`
`checkpointing.storage`	Wraps when checkpointing is an object with a store
`userId`	Copies a supplied scope user ID to Agent configuration
Registration	Sets `register: false`
Tool services, semantic cache, cost tracker, vector/graph stores	Not scoped by this factory

Authorize each domain tool against the host’s identity. Storage namespaces are not a substitute for API authorization.

`TeamFactory`

TeamFactory.create(scope) creates an unregistered Team and wraps a supplied Team-level memory.storage value. In v4, Team does not consume TeamConfig.memory or install it on member Agents. Therefore that accepted option does not establish member memory isolation or shared transcripts. Create and configure member Agents explicitly, using AgentFactory or correctly scoped member storage before passing them to the Team. Members are passed by reference; creating a new Team does not clone or rescope existing members. See memory sharing and Team patterns.

`WorkflowFactory`

WorkflowFactory.create(scope) disables global registration. In v4 the scope argument does not automatically transform workflow storage or its referenced step Agents. Configure any step Agent’s scope before creating the workflow. Persisting a workflow snapshot also does not make external effects replay-safe; see recovery.

Put factories behind the host boundary

Verify credentials and derive normalized tenant/user IDs.
Bind or check authoritative session ownership.
Create scoped Agents and explicitly scoped tools/stores.
Run with the same verified identity and owned session.
Close resources according to their actual lifetime.

ScopedStorage.initialize() and close() delegate to the underlying driver. If Agents share a driver, closing one wrapper can close a service another Agent still needs. Choose dedicated driver lifetimes or a host-owned lifecycle adapter; the wrapper is not reference-counted. The owned-session API demonstrates the HTTP identity and ownership boundary. The tenant guide explains the storage choices and tests to add for a durable host.

Ship

Identity and boundaries

Recovery and upgrades

Operating the service

Create scoped Agent instances

`ScopedStorage`

`AgentFactory`

Method signature

What gets scoped automatically

`TeamFactory`

`WorkflowFactory`

Put factories behind the host boundary

​ScopedStorage

​AgentFactory

​Method signature

​What gets scoped automatically

​TeamFactory

​WorkflowFactory

​Put factories behind the host boundary

`ScopedStorage`

`AgentFactory`

Method signature

What gets scoped automatically

`TeamFactory`

`WorkflowFactory`

Put factories behind the host boundary