Skip to main content

Interface: AgentOSConfig

Defined in: packages/agentos/src/api/AgentOS.ts:500

Properties​

agencies?​

optional agencies: RuntimeAgencyLaunchOptions

Defined in: packages/agentos/src/api/AgentOS.ts:840

Teams 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.

Default​

undefined (no tool)

authService?​

optional authService: IAuthService

Defined in: packages/agentos/src/api/AgentOS.ts:615

Optional authentication service implementing IAuthService. Provide via the auth extension or your own adapter.

conversationManagerConfig​

conversationManagerConfig: ConversationManagerConfig

Defined in: packages/agentos/src/api/AgentOS.ts:590

Configuration for the ConversationManager.

defaultPersonaId​

defaultPersonaId: string

Defined in: packages/agentos/src/api/AgentOS.ts:596

The default Persona ID to use if none is specified in an interaction.

emergent?​

optional emergent: boolean

Defined in: packages/agentos/src/api/AgentOS.ts:799

Enable emergent capability creation. When true, the agent gains access to the forge_tool meta-tool and can create new tools at runtime.

Default​

false

emergentConfig?​

optional emergentConfig: Partial<EmergentConfig>

Defined in: packages/agentos/src/api/AgentOS.ts:805

Configuration for the emergent capability engine. Only applies when emergent: true.

extensionManifest?​

optional extensionManifest: ExtensionManifest

Defined in: packages/agentos/src/api/AgentOS.ts:721

Optional extension manifest describing packs to load.

extensionOverrides?​

optional extensionOverrides: ExtensionOverrides

Defined in: packages/agentos/src/api/AgentOS.ts:723

Declarative overrides applied after packs are loaded.

extensionSecrets?​

optional extensionSecrets: Record<string, string>

Defined in: packages/agentos/src/api/AgentOS.ts:633

Optional map of secretId -> value for extension/tool credentials.

externalTools?​

optional externalTools: ExternalToolRegistry

Defined in: packages/agentos/src/api/AgentOS.ts:675

Optional 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.

gmiManagerConfig​

gmiManagerConfig: GMIManagerConfig

Defined in: packages/agentos/src/api/AgentOS.ts:502

Configuration for the GMIManager.

guardrailOutputMode?​

optional guardrailOutputMode: "stream" | "hold"

Defined in: packages/agentos/src/api/AgentOS.ts:631

hold: 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.

guardrailService?​

optional guardrailService: IGuardrailService

Defined in: packages/agentos/src/api/AgentOS.ts:619

Optional guardrail service implementation used for policy enforcement.

hitlManager?​

optional hitlManager: IHumanInteractionManager

Defined in: packages/agentos/src/api/AgentOS.ts:586

Optional human-in-the-loop manager for approvals/clarifications.

languageConfig?​

optional languageConfig: AgentOSLanguageConfig

Defined in: packages/agentos/src/api/AgentOS.ts:756

Optional multilingual configuration enabling detection, negotiation, translation.

learning?​

optional learning: boolean | LearningConfig | null

Defined in: packages/agentos/src/api/AgentOS.ts:827

The 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.

Default​

false

longTermMemoryRetriever?​

optional longTermMemoryRetriever: ILongTermMemoryRetriever

Defined in: packages/agentos/src/api/AgentOS.ts:514

Optional retriever for injecting durable long-term memory context into prompts (e.g. user/org/persona memories stored in a RAG/KG).

manageRetrievalAugmentorLifecycle?​

optional manageRetrievalAugmentorLifecycle: boolean

Defined in: packages/agentos/src/api/AgentOS.ts:543

If true, AgentOS will call retrievalAugmentor.shutdown() during AgentOS.shutdown(). Default: false (caller manages lifecycle).

memoryTools?​

optional memoryTools: AgentOSMemoryToolsConfig

Defined in: packages/agentos/src/api/AgentOS.ts:641

Optional 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.

modelProviderManagerConfig​

modelProviderManagerConfig: AIModelProviderManagerConfig

Defined in: packages/agentos/src/api/AgentOS.ts:594

Configuration for the AIModelProviderManager.

observability?​

optional observability: AgentOSObservabilityConfig

Defined in: packages/agentos/src/api/AgentOS.ts:811

Optional observability config for tracing, metrics, and log correlation. Default: disabled (opt-in).

orchestratorConfig​

orchestratorConfig: AgentOSOrchestratorConfig

Defined in: packages/agentos/src/api/AgentOS.ts:504

Configuration for the AgentOSOrchestrator.

personaLoader?​

optional personaLoader: IPersonaLoader

Defined in: packages/agentos/src/api/AgentOS.ts:758

Optional custom persona loader (useful for browser/local runtimes).

personas?​

optional personas: IPersonaDefinition[]

Defined in: packages/agentos/src/api/AgentOS.ts:764

Persona 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.

prisma​

prisma: PrismaClient

Defined in: packages/agentos/src/api/AgentOS.ts:613

An instance of the Prisma client for database interactions.

Optional when storageAdapter is provided:

  • If storageAdapter is provided, Prisma is only used for server-side features (auth, subscriptions).
  • If 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)
  // ...
});

promptEngineConfig​

promptEngineConfig: PromptEngineConfig

Defined in: packages/agentos/src/api/AgentOS.ts:582

Configuration for the prompt engine.

ragConfig?​

optional ragConfig: object

Defined in: packages/agentos/src/api/AgentOS.ts:558

Optional configuration for AgentOS-managed RAG subsystem initialization.

When provided and enabled, AgentOS will:

  • Initialize an EmbeddingManager with EmbeddingManagerConfig
  • Initialize a VectorStoreManager with VectorStoreManagerConfig and RagDataSourceConfig
  • Initialize a RetrievalAugmentor with RetrievalAugmentorServiceConfig
  • Pass the resulting IRetrievalAugmentor into GMIs via the GMIManager

Notes:

  • If retrievalAugmentor is provided, it takes precedence and this config is ignored.
  • By default, when AgentOS creates the RAG subsystem it also manages lifecycle and will shut it down during AgentOS.shutdown.

bindToStorageAdapter?​

optional bindToStorageAdapter: boolean

When 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.

dataSourceConfigs​

dataSourceConfigs: RagDataSourceConfig[]

Logical data sources mapped onto vector store providers.

embeddingManagerConfig​

embeddingManagerConfig: EmbeddingManagerConfig

Embedding manager configuration (must include at least one embedding model).

enabled?​

optional enabled: boolean

Enable or disable AgentOS-managed RAG initialization. Default: true.

manageLifecycle?​

optional manageLifecycle: boolean

If true, AgentOS will shut down the augmentor and any owned vector store providers during AgentOS.shutdown. Default: true.

retrievalAugmentorConfig​

retrievalAugmentorConfig: RetrievalAugmentorServiceConfig

Retrieval augmentor configuration (category behaviors, defaults).

vectorStoreManagerConfig​

vectorStoreManagerConfig: VectorStoreManagerConfig

Vector store manager configuration (providers).

registryConfig?​

optional registryConfig: MultiRegistryConfig

Defined in: packages/agentos/src/api/AgentOS.ts:750

Optional registry configuration for loading extensions and personas from custom sources. Allows self-hosted registries and custom git repositories.

Example​

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',
  }
}

requiredGuardrails?​

optional requiredGuardrails: RequiredGuardrailSpec[]

Defined in: packages/agentos/src/api/AgentOS.ts:626

Guards 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.

retrievalAugmentor?​

optional retrievalAugmentor: IRetrievalAugmentor

Defined in: packages/agentos/src/api/AgentOS.ts:538

Optional retrieval augmentor enabling vector-based RAG and/or GraphRAG. When provided, it is passed into GMIs via the GMIManager.

Notes:

  • This is separate from longTermMemoryRetriever, which injects pre-formatted memory text into prompts.
  • The augmentor instance is typically shared across GMIs; do not shut it down from individual GMIs.

rollingSummaryMemorySink?​

optional rollingSummaryMemorySink: IRollingSummaryMemorySink

Defined in: packages/agentos/src/api/AgentOS.ts:509

Optional sink for persisting rolling-memory outputs (summary_markdown + memory_json) into an external long-term store (RAG / knowledge graph / database).

schemaOnDemandTools?​

optional schemaOnDemandTools: object

Defined in: packages/agentos/src/api/AgentOS.ts:687

Optional: enable schema-on-demand meta tools for lazy tool schema loading.

When enabled, AgentOS registers three meta tools:

  • extensions_list
  • extensions_enable (side effects)
  • extensions_status

These tools allow an agent to load additional extension packs at runtime, so newly-enabled tool schemas appear in the next listAvailableTools() call.

allowModules?​

optional allowModules: boolean

Allow enabling packs by local module specifier/path (source='module'). Default: false.

allowPackages?​

optional allowPackages: boolean

Allow enabling packs by explicit npm package name (source='package'). Default: true in non-production, false in production.

enabled?​

optional enabled: boolean

officialRegistryOnly?​

optional officialRegistryOnly: boolean

When true, only allow extension packs present in the official @framers/agentos-extensions-registry catalog (if installed).

Default: true.

spendMeter?​

optional spendMeter: AgentOSSpendMeterConfig

Defined in: packages/agentos/src/api/AgentOS.ts:525

A 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.

standaloneMemory?​

optional standaloneMemory: AgentOSStandaloneMemoryConfig

Defined in: packages/agentos/src/api/AgentOS.ts:651

Optional unified standalone-memory bridge.

This derives one or more AgentOS integrations from a single standalone Memory instance:

  • memory tools
  • long-term memory retriever
  • rolling-summary sink

storageAdapter?​

optional storageAdapter: StorageAdapter

Defined in: packages/agentos/src/api/AgentOS.ts:792

Optional cross-platform storage adapter for client-side persistence. Enables fully offline AgentOS in browsers (IndexedDB), desktop (SQLite), mobile (Capacitor).

Platform Support:

  • Web: IndexedDB (recommended) or sql.js
  • Electron: better-sqlite3 (native) or sql.js (fallback)
  • Capacitor: @capacitor-community/sqlite (native) or IndexedDB
  • Node: better-sqlite3 or PostgreSQL

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:

  • If omitted, AgentOS falls back to Prisma (server-side only).
  • If provided, AgentOS uses storageAdapter for conversations, Prisma only for auth/subscriptions.
  • Recommended: Always provide storageAdapter for cross-platform compatibility.

streamingManagerConfig​

streamingManagerConfig: StreamingManagerConfig

Defined in: packages/agentos/src/api/AgentOS.ts:592

Configuration for the internal streaming manager.

structuredSchemas?​

optional structuredSchemas: IStructuredSchemaRegistry

Defined in: packages/agentos/src/api/AgentOS.ts:527

The schemas a request's structuredReply.schemaRef is looked up in. A Map<string, ZodType | JsonSchemaObject> is one.

subscriptionService?​

optional subscriptionService: ISubscriptionService

Defined in: packages/agentos/src/api/AgentOS.ts:617

Optional subscription service implementing ISubscriptionService. Provide via the auth extension or your own adapter.

taskOutcomeTelemetryStore?​

optional taskOutcomeTelemetryStore: ITaskOutcomeTelemetryStore

Defined in: packages/agentos/src/api/AgentOS.ts:519

Optional persistence store for task outcome KPI windows. When provided, rolling task-outcome telemetry survives orchestrator restarts.

toolOrchestratorConfig​

toolOrchestratorConfig: ToolOrchestratorConfig

Defined in: packages/agentos/src/api/AgentOS.ts:584

Configuration for the tool orchestrator.

toolPermissionManagerConfig​

toolPermissionManagerConfig: ToolPermissionManagerConfig

Defined in: packages/agentos/src/api/AgentOS.ts:588

Configuration for the tool permission manager.

tools?​

optional tools: AdaptableToolInput

Defined in: packages/agentos/src/api/AgentOS.ts:664

Optional 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:

  • a named high-level tool map
  • an ExternalToolRegistry (Record, Map, or iterable)
  • a prompt-only ToolDefinitionForLLM[]

turnPlanning?​

optional turnPlanning: AgentOSTurnPlanningConfig

Defined in: packages/agentos/src/api/AgentOS.ts:710

Optional per-turn planning configuration. Defaults:

  • defaultToolFailureMode = fail_open
  • discovery-driven tool selection enabled when discovery is available.

utilityAIService?​

optional utilityAIService: IUtilityAI & IPromptEngineUtilityAI

Defined in: packages/agentos/src/api/AgentOS.ts:719

Optional. 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.

workflowEngineConfig?​

optional workflowEngineConfig: WorkflowEngineConfig

Defined in: packages/agentos/src/api/AgentOS.ts:752

Optional workflow engine configuration.

workflowStore?​

optional workflowStore: IWorkflowStore

Defined in: packages/agentos/src/api/AgentOS.ts:754

Optional workflow store implementation. Defaults to the in-memory store if omitted.