Configuration for the AgentOSOrchestrator.
Optional rollingOptional sink for persisting rolling-memory outputs (summary_markdown + memory_json)
into an external long-term store (RAG / knowledge graph / database).
Optional longOptional retriever for injecting durable long-term memory context into prompts (e.g. user/org/persona memories stored in a RAG/KG).
Optional taskOptional persistence store for task outcome KPI windows. When provided, rolling task-outcome telemetry survives orchestrator restarts.
Optional spendA persisted per-account allowance. With one set, every processRequest needs an operationId and reserves its
units before any provider is called: a refusal or a meter that cannot answer ends the request with an error chunk
and no model call. The turn settles the reservation when it ends; a reply an output guardrail blocks is refunded.
Optional structuredThe schemas a request's structuredReply.schemaRef is looked up in. A Map<string, ZodType | JsonSchemaObject> is one.
Optional retrievalOptional retrieval augmentor enabling vector-based RAG and/or GraphRAG. When provided, it is passed into GMIs via the GMIManager.
Notes:
longTermMemoryRetriever, which injects pre-formatted
memory text into prompts.Optional manageIf true, AgentOS will call retrievalAugmentor.shutdown() during AgentOS.shutdown().
Default: false (caller manages lifecycle).
Optional ragOptional configuration for AgentOS-managed RAG subsystem initialization.
When provided and enabled, AgentOS will:
EmbeddingManager with EmbeddingManagerConfigVectorStoreManager with VectorStoreManagerConfig and RagDataSourceConfigRetrievalAugmentor with RetrievalAugmentorServiceConfigNotes:
retrievalAugmentor is provided, it takes precedence and this config is ignored.Optional enabled?: booleanEnable or disable AgentOS-managed RAG initialization. Default: true.
Embedding manager configuration (must include at least one embedding model).
Vector store manager configuration (providers).
Logical data sources mapped onto vector store providers.
Retrieval augmentor configuration (category behaviors, defaults).
Optional manageIf true, AgentOS will shut down the augmentor and any owned vector store providers during AgentOS.shutdown. Default: true.
Optional bindWhen true (default), AgentOS injects its storageAdapter into SQL vector-store providers
that did not specify adapter or storage. This keeps vector persistence colocated with
the host database by default.
Configuration for the prompt engine.
Configuration for the tool orchestrator.
Optional hitlOptional human-in-the-loop manager for approvals/clarifications.
Configuration for the tool permission manager.
Configuration for the ConversationManager.
Configuration for the internal streaming manager.
Configuration for the AIModelProviderManager.
The default Persona ID to use if none is specified in an interaction.
An instance of the Prisma client for database interactions.
Optional when storageAdapter is provided:
storageAdapter is provided, Prisma is only used for server-side features (auth, subscriptions).storageAdapter is omitted, Prisma is required for all database operations.Client-side usage:
const storage = await createAgentOSStorage({ platform: 'web' });
await agentos.initialize({
storageAdapter: storage.getAdapter(),
prisma: mockPrisma, // Stub for compatibility (can be minimal mock)
// ...
});
Optional authOptional authentication service implementing IAuthService. Provide via the auth extension or your own adapter.
Optional subscriptionOptional subscription service implementing ISubscriptionService. Provide via the auth extension or your own adapter.
Optional guardrailOptional guardrail service implementation used for policy enforcement.
Optional requiredGuards the deployment cannot run without, by id and stage. initialize() refuses to finish when one is missing
or does not implement a named stage; processRequest() refuses a request (SYS_GUARDRAIL_REQUIRED_MISSING) when
one has gone missing since. Each runs fail-closed with its deadline, and a guard required on output puts the
output in hold mode.
Optional guardrailhold: no TEXT_DELTA reaches the caller before the output guards have judged the whole reply. Default stream;
forced to hold when a required guard covers the output stage.
Optional extensionOptional map of secretId -> value for extension/tool credentials.
Optional memoryOptional standalone-memory tool registration.
When provided, AgentOS will load the standalone memory editor tools as an
extension pack during initialization, making them immediately available to
the shared ToolExecutor/ToolOrchestrator.
Optional standaloneOptional unified standalone-memory bridge.
This derives one or more AgentOS integrations from a single standalone
Memory instance:
Optional toolsOptional runtime-level registered tools.
These tools are normalized during initialization and registered into the
shared ToolOrchestrator, making them directly available to processRequest()
and other full-runtime flows without helper wrappers.
Accepts:
ExternalToolRegistry (Record, Map, or iterable)ToolDefinitionForLLM[]Optional externalOptional stable registry of host-managed external tools.
This is the runtime-level default for helper APIs such as
processRequestWithRegisteredTools(...) and
resumeExternalToolRequestWithRegisteredTools(...).
Per-call externalTools passed into those helpers override entries from
this configured registry by tool name.
Optional schemaOptional: enable schema-on-demand meta tools for lazy tool schema loading.
When enabled, AgentOS registers three meta tools:
extensions_listextensions_enable (side effects)extensions_statusThese tools allow an agent to load additional extension packs at runtime,
so newly-enabled tool schemas appear in the next listAvailableTools() call.
Optional enabled?: booleanOptional allowAllow enabling packs by explicit npm package name (source='package'). Default: true in non-production, false in production.
Optional allowAllow enabling packs by local module specifier/path (source='module'). Default: false.
Optional officialWhen true, only allow extension packs present in the official
@framers/agentos-extensions-registry catalog (if installed).
Default: true.
Optional turnOptional per-turn planning configuration. Defaults:
defaultToolFailureMode = fail_openOptional utilityAIServiceOptional. An instance of a utility AI service.
This service should conform to IUtilityAI for general utility tasks.
If the prompt engine is used and requires specific utility functions (like advanced
summarization for prompt construction), this service must also fulfill the contract
of IPromptEngineUtilityAI.
It's recommended that the concrete class for this service implements both interfaces if needed.
Optional extensionOptional extension manifest describing packs to load.
Optional extensionDeclarative overrides applied after packs are loaded.
Optional registryOptional registry configuration for loading extensions and personas from custom sources. Allows self-hosted registries and custom git repositories.
registryConfig: {
registries: {
'extensions': {
type: 'github',
location: 'your-org/your-extensions',
branch: 'main',
},
'personas': {
type: 'github',
location: 'your-org/your-personas',
branch: 'main',
}
},
defaultRegistries: {
tool: 'extensions',
persona: 'personas',
}
}
Optional workflowOptional workflow engine configuration.
Optional workflowOptional workflow store implementation. Defaults to the in-memory store if omitted.
Optional languageOptional multilingual configuration enabling detection, negotiation, translation.
Optional personaOptional custom persona loader (useful for browser/local runtimes).
Optional personasPersona definitions given inline, as parsed JSON objects or code-built objects. They are
served by an in-memory loader and validated like file personas. Exclusive with
personaLoader; when set, the file-system persona directory is not read.
Optional storageOptional cross-platform storage adapter for client-side persistence. Enables fully offline AgentOS in browsers (IndexedDB), desktop (SQLite), mobile (Capacitor).
Platform Support:
Usage:
import { createAgentOSStorage } from '@framers/sql-storage-adapter/agentos';
const storage = await createAgentOSStorage({ platform: 'auto' });
await agentos.initialize({
storageAdapter: storage.getAdapter(),
// ... other config
});
Graceful Degradation:
Optional emergentEnable emergent capability creation. When true, the agent gains access
to the forge_tool meta-tool and can create new tools at runtime.
false
Optional emergentConfiguration for the emergent capability engine.
Only applies when emergent: true.
Optional observabilityOptional observability config for tracing, metrics, and log correlation. Default: disabled (opt-in).
Optional learningThe learning layer (docs/GMI.md, "Learning"). Unset, false or null: off, and the runtime's GMIs run as they
did before the layer existed. true or a LearningConfig: every GMI sends its persona's personality section
as a system prompt of its own on every turn, and each session is bound to a learner: its persona with the user
and the resolved organization of its first turn. namespace is refused here, because the runtime takes the
organization from each turn. The layer the runtime builds keeps its learning store on storageAdapter (SQL when the
adapter has transactions; else in the process), reaches the memory tools' facade and the standalone memory's (its
retriever's and its sink's) for forgetUser and revert, after any learning.memoryTools the host sets, and the
memory tools pack leaves memory_reflect out. A host that built a layer itself passes it in
gmiManagerConfig.learningLayer instead, with its own store and facades: a layer passed there turns learning on
whatever this option says, and true or a config beside one is refused. AgentOS.getLearningLayer returns
the layer.
false
Optional agenciesTeams a persona's GMI may launch from a turn (launch_agency). With launch: true the runtime registers the
tool, which requires the agency:launch capability, so only a persona whose allowedCapabilities names it lists
and calls it (with toolPermissionManagerConfig.strictCapabilityChecking, on by default). Each call builds a
temporary agency() team whose seats are GMIs of this runtime (a registered persona by personaId, or one made
from the caller's for the seat's instructions), runs the goal once and returns one tool result, bounded by depth,
seats, launches in flight, one wall deadline and the caller's tools; the output guardrails that judge the caller's
tool calls judge the seats' calls too. The bounds are checked at initialization
whenever this is set; with launch: true, a config tool named launch_agency fails initialization too.
undefined (no tool)
Configuration for the GMIManager.