Interface AgencyOptions

Configuration for the agency() factory function. Extends BaseAgentConfig with a required agents roster and optional multi-agent orchestration settings.

Example

import { agency, hitl } from '@framers/agentos';

const myAgency = agency({
  model: 'openai:gpt-4o',
  strategy: 'sequential',
  agents: {
    researcher: { instructions: 'Find relevant papers.' },
    writer:     { instructions: 'Write a clear summary.' },
  },
  controls: { maxTotalTokens: 50_000, onLimitReached: 'warn' },
  hitl: {
    approvals: { beforeTool: ['delete-file'], beforeReturn: true },
    handler: hitl.autoApprove(),
    timeoutMs: 30_000,
    onTimeout: 'reject',
  },
  on: {
    agentStart: (e) => console.log(`[${e.agent}] started`),
    agentEnd: (e) => console.log(`[${e.agent}] done in ${e.durationMs}ms`),
  },
});

See

agency -- the factory function that consumes this configuration. See BaseAgentConfig for the shared config surface inherited by this interface.

interface AgencyOptions {
    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;
    agents: Record<string, BaseAgentConfig | Agent>;
    strategy?: AgencyStrategy;
    adaptive?: boolean;
    maxRounds?: number;
}

Hierarchy

  • BaseAgentConfig
    • AgencyOptions

Properties

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? agents strategy? adaptive? maxRounds?

Properties

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

agents

agents: Record<string, BaseAgentConfig | Agent>

Named roster of sub-agents. Each value is either a BaseAgentConfig object (the agency will instantiate it) or a pre-built Agent instance.

Optional strategy

strategy?: AgencyStrategy

Orchestration strategy for coordinating sub-agents. Defaults to "sequential" when omitted.

Optional adaptive

adaptive?: boolean

Whether the orchestrator may override strategy at runtime based on task complexity signals.

Optional maxRounds

maxRounds?: number

Maximum number of orchestration rounds before the run is terminated. Applies to iterative strategies like "debate" and "review-loop".

Settings

Member Visibility

Theme

On This Page

modelproviderinstructionsnameapiKeybaseUrlpersonalitytoolsmaxStepsmemoryragdiscoveryguardrailssecuritypermissionshitlemergentvoiceavatarchannelsoutputprovenanceobservabilityoncontrolsdependsOncognitiveMechanismsagentsstrategyadaptivemaxRounds