Interface AgentOptions

Configuration options for the agent factory function.

Extends BaseAgentConfig with backward-compatible convenience fields. All BaseAgentConfig fields (rag, discovery, permissions, emergent, voice, etc.) are accepted and stored in config but are not actively wired in the lightweight agent — they will be consumed by agency() and the full runtime.

interface AgentOptions {
    usageLedger?: AgentOSUsageLedgerOptions;
    chainOfThought?: string | boolean;
    fallbackProviders?: FallbackProviderEntry[];
    onFallback?: ((error, fallbackProvider) => void);
    router?: IModelRouter;
    onBeforeGeneration?: ((context) => Promise<void | GenerationHookContext>);
    onAfterGeneration?: ((result) => Promise<void | GenerationHookResult>);
    onBeforeToolExecution?: ((info) => Promise<null | ToolCallHookInfo>);
    memoryProvider?: any;
    skills?: SkillEntry[];
    model?: string;
    provider?: string;
    instructions?: string;
    name?: string;
    apiKey?: string;
    baseUrl?: string;
    personality?: Partial<{
        honesty: number;
        emotionality: number;
        extraversion: number;
        agreeableness: number;
        conscientiousness: number;
        openness: number;
    }>;
    tools?: AdaptableToolInput;
    maxSteps?: number;
    memory?: boolean | MemoryConfig;
    rag?: RagConfig;
    discovery?: DiscoveryConfig;
    guardrails?: string[] | GuardrailsConfig;
    security?: {
        tier: SecurityTier;
    };
    permissions?: PermissionsConfig;
    hitl?: HitlConfig;
    emergent?: EmergentConfig;
    voice?: VoiceConfig;
    avatar?: AvatarConfig;
    channels?: Record<string, Record<string, unknown>>;
    output?: unknown;
    provenance?: ProvenanceConfig;
    observability?: ObservabilityConfig;
    on?: AgencyCallbacks;
    controls?: ResourceControls;
    dependsOn?: string[];
    cognitiveMechanisms?: CognitiveMechanismsConfig;
}

Hierarchy

  • BaseAgentConfig
    • AgentOptions

Properties

usageLedger? chainOfThought? fallbackProviders? onFallback? router? onBeforeGeneration? onAfterGeneration? onBeforeToolExecution? memoryProvider? skills? model? provider? instructions? name? apiKey? baseUrl? personality? tools? maxSteps? memory? rag? discovery? guardrails? security? permissions? hitl? emergent? voice? avatar? channels? output? provenance? observability? on? controls? dependsOn? cognitiveMechanisms?

Properties

Optional usageLedger

usageLedger?: AgentOSUsageLedgerOptions

Top-level usage ledger shorthand for backward compatibility. When present, forwarded to observability.usageLedger internally.

Optional chainOfThought

chainOfThought?: string | boolean

Chain-of-thought reasoning instruction.

  • false — disable CoT injection.
  • true (default for agents) — inject the default CoT instruction when tools are present.
  • string — inject a custom CoT instruction when tools are present.

Optional fallbackProviders

fallbackProviders?: FallbackProviderEntry[]

Ordered list of fallback providers to try when the primary provider fails with a retryable error (HTTP 402/429/5xx, network errors).

Applied to every generate(), stream(), and session.send() / session.stream() call made through this agent.

See

GenerateTextOptions.fallbackProviders

Optional onFallback

onFallback?: ((error, fallbackProvider) => void)

Callback invoked when a fallback provider is about to be tried.

Type declaration

    • (error, fallbackProvider): void

    • Parameters

      • error: Error

        The error that triggered the fallback.

      • fallbackProvider: string

        The provider identifier being tried next.

      Returns void

Optional router

router?: IModelRouter

Model router for intelligent provider selection per-call.

Optional onBeforeGeneration

onBeforeGeneration?: ((context) => Promise<void | GenerationHookContext>)

Pre-generation hook, called before each LLM step.

Type declaration

Optional onAfterGeneration

onAfterGeneration?: ((result) => Promise<void | GenerationHookResult>)

Post-generation hook, called after each LLM step.

Type declaration

Optional onBeforeToolExecution

onBeforeToolExecution?: ((info) => Promise<null | ToolCallHookInfo>)

Pre-tool-execution hook.

Type declaration

Optional memoryProvider

memoryProvider?: any

Optional memory provider. When provided:

  • session.send()/stream() calls memory.getContext() before each turn and prepends results to the system prompt.
  • session.send()/stream() calls memory.observe() after each turn to encode the exchange into long-term memory.

Optional skills

skills?: SkillEntry[]

Optional skill entries to inject into the system prompt. Skill content is appended to the system prompt as markdown sections.

Optional model

model?: string

Model identifier. Accepted in two formats:

  • "provider:model" — e.g. "openai:gpt-4o".
  • Plain model name when provider is also set.

Optional provider

provider?: string

Provider name (e.g. "openai", "anthropic", "ollama"). Auto-detected from environment API keys when omitted.

Optional instructions

instructions?: string

Free-form system instructions prepended to the system prompt.

Optional name

name?: string

Display name for the agent, injected into the system prompt.

Optional apiKey

apiKey?: string

Override the provider API key instead of reading from environment variables.

Optional baseUrl

baseUrl?: string

Override the provider base URL (useful for local proxies or Ollama).

Optional personality

personality?: Partial<{
    honesty: number;
    emotionality: number;
    extraversion: number;
    agreeableness: number;
    conscientiousness: number;
    openness: number;
}>

HEXACO-inspired personality trait overrides (0–1 scale). Encoded as a human-readable trait string appended to the system prompt.

Type declaration

  • honesty: number
  • emotionality: number
  • extraversion: number
  • agreeableness: number
  • conscientiousness: number
  • openness: number

Optional tools

tools?: AdaptableToolInput

Tools available to the agent on every call.

Accepts:

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

Optional maxSteps

maxSteps?: number

Maximum number of agentic steps (LLM calls) per invocation. Defaults to 5.

Optional memory

memory?: boolean | MemoryConfig

Memory configuration.

  • true — enable in-memory conversation history with default settings.
  • false — disable memory; every call is stateless.
  • MemoryConfig — full control over memory subsystems.

Optional rag

rag?: RagConfig

Retrieval-Augmented Generation configuration.

Optional discovery

discovery?: DiscoveryConfig

Runtime capability discovery configuration.

Optional guardrails

guardrails?: string[] | GuardrailsConfig

Guardrail policy identifiers or structured config.

  • string[] — shorthand; applies to both input and output.
  • GuardrailsConfig — full control with separate input/output lists.

Optional security

security?: {
    tier: SecurityTier;
}

Security tier controlling permitted tools and capabilities.

Type declaration

  • tier: SecurityTier

Optional permissions

permissions?: PermissionsConfig

Fine-grained tool and resource permission overrides.

Optional hitl

hitl?: HitlConfig

Human-in-the-loop approval configuration.

Optional emergent

emergent?: EmergentConfig

Emergent agent synthesis configuration.

Optional voice

voice?: VoiceConfig

Voice interface configuration.

Optional avatar

avatar?: AvatarConfig

Avatar visual presentation configuration.

Optional channels

channels?: Record<string, Record<string, unknown>>

Channel adapter configurations keyed by channel name. Values are channel-specific option objects passed through opaquely.

Optional output

output?: unknown

Output schema for structured generation. Accepts a Zod schema at runtime; typed as unknown here to avoid a hard dependency on the zod package in the types layer.

Optional provenance

provenance?: ProvenanceConfig

Provenance and audit-trail configuration.

Optional observability

observability?: ObservabilityConfig

Observability and telemetry configuration.

Optional on

on?: AgencyCallbacks

Event callbacks fired at various lifecycle points during the run.

Optional controls

controls?: ResourceControls

Resource limits (tokens, cost, time) applied to the entire run.

Optional dependsOn

dependsOn?: string[]

Names of other agents in the agency that must complete before this agent runs. Used with strategy: 'graph' to build an explicit dependency DAG. Agents with no dependsOn are roots and run first.

Example

`dependsOn: ['researcher']` — this agent waits for `researcher` to finish.

Optional cognitiveMechanisms

cognitiveMechanisms?: CognitiveMechanismsConfig

Cognitive mechanisms config — 8 neuroscience-backed memory mechanisms. All HEXACO-modulated (emotionality, conscientiousness, openness, etc.).

  • Pass {} for sensible defaults (all 8 mechanisms enabled).
  • Omit entirely to disable (zero overhead — no code paths execute).
  • Provide per-mechanism overrides to tune individual parameters.

Requires memory to be enabled (true or a MemoryConfig object). If cognitiveMechanisms is set but memory is disabled, a warning is logged and the mechanisms config is ignored.

See

Cognitive Mechanisms Docs

Settings

Member Visibility

Theme

On This Page

usageLedgerchainOfThoughtfallbackProvidersonFallbackrouteronBeforeGenerationonAfterGenerationonBeforeToolExecutionmemoryProviderskillsmodelproviderinstructionsnameapiKeybaseUrlpersonalitytoolsmaxStepsmemoryragdiscoveryguardrailssecuritypermissionshitlemergentvoiceavatarchannelsoutputprovenanceobservabilityoncontrolsdependsOncognitiveMechanisms