Skip to main content

Interface: AgentOSConfig

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

Interface​

AgentOSConfig

Description​

Defines the comprehensive configuration structure required to initialize and operate the AgentOS service. This configuration object aggregates settings for all major sub-components and dependencies of the AgentOS platform.

Properties​

authService?​

optional authService: IAuthService

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

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

Configuration for the ConversationManager.

defaultPersonaId​

defaultPersonaId: string

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

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

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

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

extensionManifest?​

optional extensionManifest: ExtensionManifest

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

Optional extension manifest describing packs to load.

extensionOverrides?​

optional extensionOverrides: ExtensionOverrides

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

Declarative overrides applied after packs are loaded.

extensionSecrets?​

optional extensionSecrets: Record<string, string>

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

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

externalTools?​

optional externalTools: ExternalToolRegistry

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

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

Configuration for the GMIManager.

guardrailService?​

optional guardrailService: IGuardrailService

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

Optional guardrail service implementation used for policy enforcement.

hitlManager?​

optional hitlManager: IHumanInteractionManager

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

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

languageConfig?​

optional languageConfig: AgentOSLanguageConfig

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

Optional multilingual configuration enabling detection, negotiation, translation.

longTermMemoryRetriever?​

optional longTermMemoryRetriever: ILongTermMemoryRetriever

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

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

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

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

Configuration for the AIModelProviderManager.

observability?​

optional observability: AgentOSObservabilityConfig

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

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

orchestratorConfig​

orchestratorConfig: AgentOSOrchestratorConfig

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

Configuration for the AgentOSOrchestrator.

personaLoader?​

optional personaLoader: IPersonaLoader

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

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

prisma​

prisma: PrismaClient

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

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

Configuration for the prompt engine.

ragConfig?​

optional ragConfig: object

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

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

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

retrievalAugmentor?​

optional retrievalAugmentor: IRetrievalAugmentor

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

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

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

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.

standaloneMemory?​

optional standaloneMemory: AgentOSStandaloneMemoryConfig

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

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

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

Configuration for the internal streaming manager.

subscriptionService?​

optional subscriptionService: ISubscriptionService

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

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

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

Configuration for the tool orchestrator.

toolPermissionManagerConfig​

toolPermissionManagerConfig: ToolPermissionManagerConfig

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

Configuration for the tool permission manager.

tools?​

optional tools: AdaptableToolInput

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

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

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

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

Optional workflow engine configuration.

workflowStore?​

optional workflowStore: IWorkflowStore

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

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