Skip to main content

Interface: AgentOSConfig

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

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

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

Configuration for the ConversationManager.

defaultPersonaId​

defaultPersonaId: string

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

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

extensionManifest?​

optional extensionManifest: ExtensionManifest

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

Optional extension manifest describing packs to load.

extensionOverrides?​

optional extensionOverrides: ExtensionOverrides

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

Declarative overrides applied after packs are loaded.

extensionSecrets?​

optional extensionSecrets: Record<string, string>

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

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

gmiManagerConfig​

gmiManagerConfig: GMIManagerConfig

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

Configuration for the GMIManager.

guardrailService?​

optional guardrailService: IGuardrailService

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

Optional guardrail service implementation used for policy enforcement.

hitlManager?​

optional hitlManager: IHumanInteractionManager

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

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

languageConfig?​

optional languageConfig: AgentOSLanguageConfig

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

Optional multilingual configuration enabling detection, negotiation, translation.

longTermMemoryRetriever?​

optional longTermMemoryRetriever: ILongTermMemoryRetriever

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

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

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

modelProviderManagerConfig​

modelProviderManagerConfig: AIModelProviderManagerConfig

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

Configuration for the AIModelProviderManager.

observability?​

optional observability: AgentOSObservabilityConfig

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

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

orchestratorConfig​

orchestratorConfig: AgentOSOrchestratorConfig

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

Configuration for the AgentOSOrchestrator.

personaLoader?​

optional personaLoader: IPersonaLoader

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

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

prisma​

prisma: PrismaClient

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

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

Configuration for the prompt engine.

ragConfig?​

optional ragConfig: object

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

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

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

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

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

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.

storageAdapter?​

optional storageAdapter: any

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

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

Configuration for the StreamingManager.

subscriptionService?​

optional subscriptionService: ISubscriptionService

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

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

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

Configuration for the tool orchestrator.

toolPermissionManagerConfig​

toolPermissionManagerConfig: ToolPermissionManagerConfig

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

Configuration for the tool permission manager.

turnPlanning?​

optional turnPlanning: AgentOSTurnPlanningConfig

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

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

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

Optional workflow engine configuration.

workflowStore?​

optional workflowStore: IWorkflowStore

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

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