Interface AgentOSConfig

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.

interface AgentOSConfig {
    gmiManagerConfig: GMIManagerConfig;
    orchestratorConfig: AgentOSOrchestratorConfig;
    rollingSummaryMemorySink?: IRollingSummaryMemorySink;
    longTermMemoryRetriever?: ILongTermMemoryRetriever;
    taskOutcomeTelemetryStore?: ITaskOutcomeTelemetryStore;
    retrievalAugmentor?: IRetrievalAugmentor;
    manageRetrievalAugmentorLifecycle?: boolean;
    ragConfig?: {
        enabled?: boolean;
        embeddingManagerConfig: EmbeddingManagerConfig;
        vectorStoreManagerConfig: VectorStoreManagerConfig;
        dataSourceConfigs: RagDataSourceConfig[];
        retrievalAugmentorConfig: RetrievalAugmentorServiceConfig;
        manageLifecycle?: boolean;
        bindToStorageAdapter?: boolean;
    };
    promptEngineConfig: PromptEngineConfig;
    toolOrchestratorConfig: ToolOrchestratorConfig;
    hitlManager?: IHumanInteractionManager;
    toolPermissionManagerConfig: ToolPermissionManagerConfig;
    conversationManagerConfig: ConversationManagerConfig;
    streamingManagerConfig: StreamingManagerConfig;
    modelProviderManagerConfig: AIModelProviderManagerConfig;
    defaultPersonaId: string;
    prisma: PrismaClient;
    authService?: IAuthService;
    subscriptionService?: ISubscriptionService;
    guardrailService?: IGuardrailService;
    extensionSecrets?: Record<string, string>;
    memoryTools?: AgentOSMemoryToolsConfig;
    standaloneMemory?: AgentOSStandaloneMemoryConfig;
    tools?: AdaptableToolInput;
    externalTools?: ExternalToolRegistry;
    schemaOnDemandTools?: {
        enabled?: boolean;
        allowPackages?: boolean;
        allowModules?: boolean;
        officialRegistryOnly?: boolean;
    };
    turnPlanning?: AgentOSTurnPlanningConfig;
    utilityAIService?: IUtilityAI & IPromptEngineUtilityAI;
    extensionManifest?: ExtensionManifest;
    extensionOverrides?: ExtensionOverrides;
    registryConfig?: MultiRegistryConfig;
    workflowEngineConfig?: WorkflowEngineConfig;
    workflowStore?: IWorkflowStore;
    languageConfig?: AgentOSLanguageConfig;
    personaLoader?: IPersonaLoader;
    storageAdapter?: StorageAdapter;
    emergent?: boolean;
    emergentConfig?: Partial<EmergentConfig>;
    observability?: AgentOSObservabilityConfig;
}

Properties

gmiManagerConfig orchestratorConfig rollingSummaryMemorySink? longTermMemoryRetriever? taskOutcomeTelemetryStore? retrievalAugmentor? manageRetrievalAugmentorLifecycle? ragConfig? promptEngineConfig toolOrchestratorConfig hitlManager? toolPermissionManagerConfig conversationManagerConfig streamingManagerConfig modelProviderManagerConfig defaultPersonaId prisma authService? subscriptionService? guardrailService? extensionSecrets? memoryTools? standaloneMemory? tools? externalTools? schemaOnDemandTools? turnPlanning? utilityAIService? extensionManifest? extensionOverrides? registryConfig? workflowEngineConfig? workflowStore? languageConfig? personaLoader? storageAdapter? emergent? emergentConfig? observability?

Properties

gmiManagerConfig

gmiManagerConfig: GMIManagerConfig

Configuration for the GMIManager.

orchestratorConfig

orchestratorConfig: AgentOSOrchestratorConfig

Configuration for the AgentOSOrchestrator.

Optional rollingSummaryMemorySink

rollingSummaryMemorySink?: IRollingSummaryMemorySink

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

Optional longTermMemoryRetriever

longTermMemoryRetriever?: ILongTermMemoryRetriever

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

Optional taskOutcomeTelemetryStore

taskOutcomeTelemetryStore?: ITaskOutcomeTelemetryStore

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

Optional retrievalAugmentor

retrievalAugmentor?: IRetrievalAugmentor

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.

Optional manageRetrievalAugmentorLifecycle

manageRetrievalAugmentorLifecycle?: boolean

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

Optional ragConfig

ragConfig?: {
    enabled?: boolean;
    embeddingManagerConfig: EmbeddingManagerConfig;
    vectorStoreManagerConfig: VectorStoreManagerConfig;
    dataSourceConfigs: RagDataSourceConfig[];
    retrievalAugmentorConfig: RetrievalAugmentorServiceConfig;
    manageLifecycle?: boolean;
    bindToStorageAdapter?: boolean;
}

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.

Type declaration

  • Optional enabled?: boolean

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

  • embeddingManagerConfig: EmbeddingManagerConfig

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

  • vectorStoreManagerConfig: VectorStoreManagerConfig

    Vector store manager configuration (providers).

  • dataSourceConfigs: RagDataSourceConfig[]

    Logical data sources mapped onto vector store providers.

  • retrievalAugmentorConfig: RetrievalAugmentorServiceConfig

    Retrieval augmentor configuration (category behaviors, defaults).

  • Optional manageLifecycle?: boolean

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

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

promptEngineConfig

promptEngineConfig: PromptEngineConfig

Configuration for the prompt engine.

toolOrchestratorConfig

toolOrchestratorConfig: ToolOrchestratorConfig

Configuration for the tool orchestrator.

Optional hitlManager

hitlManager?: IHumanInteractionManager

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

toolPermissionManagerConfig

toolPermissionManagerConfig: ToolPermissionManagerConfig

Configuration for the tool permission manager.

conversationManagerConfig

conversationManagerConfig: ConversationManagerConfig

Configuration for the ConversationManager.

streamingManagerConfig

streamingManagerConfig: StreamingManagerConfig

Configuration for the internal streaming manager.

modelProviderManagerConfig

modelProviderManagerConfig: AIModelProviderManagerConfig

Configuration for the AIModelProviderManager.

defaultPersonaId

defaultPersonaId: string

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

prisma

prisma: PrismaClient

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)
  // ...
});

Optional authService

authService?: IAuthService

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

Optional subscriptionService

subscriptionService?: ISubscriptionService

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

Optional guardrailService

guardrailService?: IGuardrailService

Optional guardrail service implementation used for policy enforcement.

Optional extensionSecrets

extensionSecrets?: Record<string, string>

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

Optional memoryTools

memoryTools?: AgentOSMemoryToolsConfig

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.

Optional standaloneMemory

standaloneMemory?: AgentOSStandaloneMemoryConfig

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

Optional tools

tools?: AdaptableToolInput

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[]

Optional externalTools

externalTools?: ExternalToolRegistry

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.

Optional schemaOnDemandTools

schemaOnDemandTools?: {
    enabled?: boolean;
    allowPackages?: boolean;
    allowModules?: boolean;
    officialRegistryOnly?: boolean;
}

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.

Type declaration

  • Optional enabled?: boolean
  • Optional allowPackages?: boolean

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

  • Optional allowModules?: boolean

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

  • Optional officialRegistryOnly?: boolean

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

    Default: true.

Optional turnPlanning

turnPlanning?: AgentOSTurnPlanningConfig

Optional per-turn planning configuration. Defaults:

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

Optional utilityAIService

utilityAIService?: IUtilityAI & IPromptEngineUtilityAI

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.

Optional extensionManifest

extensionManifest?: ExtensionManifest

Optional extension manifest describing packs to load.

Optional extensionOverrides

extensionOverrides?: ExtensionOverrides

Declarative overrides applied after packs are loaded.

Optional registryConfig

registryConfig?: MultiRegistryConfig

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

Optional workflowEngineConfig

workflowEngineConfig?: WorkflowEngineConfig

Optional workflow engine configuration.

Optional workflowStore

workflowStore?: IWorkflowStore

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

Optional languageConfig

languageConfig?: AgentOSLanguageConfig

Optional multilingual configuration enabling detection, negotiation, translation.

Optional personaLoader

personaLoader?: IPersonaLoader

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

Optional storageAdapter

storageAdapter?: StorageAdapter

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.

Optional emergent

emergent?: boolean

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

Optional emergentConfig

emergentConfig?: Partial<EmergentConfig>

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

Optional observability

observability?: AgentOSObservabilityConfig

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

Settings

Member Visibility

Theme

On This Page

gmiManagerConfigorchestratorConfigrollingSummaryMemorySinklongTermMemoryRetrievertaskOutcomeTelemetryStoreretrievalAugmentormanageRetrievalAugmentorLifecycleragConfigpromptEngineConfigtoolOrchestratorConfighitlManagertoolPermissionManagerConfigconversationManagerConfigstreamingManagerConfigmodelProviderManagerConfigdefaultPersonaIdprismaauthServicesubscriptionServiceguardrailServiceextensionSecretsmemoryToolsstandaloneMemorytoolsexternalToolsschemaOnDemandToolsturnPlanningutilityAIServiceextensionManifestextensionOverridesregistryConfigworkflowEngineConfigworkflowStorelanguageConfigpersonaLoaderstorageAdapteremergentemergentConfigobservability