Skip to main content

Interface: AgencyOptions

Defined in: packages/agentos/src/api/types.ts:1899

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({
provider: 'openai',
model: '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.

Extends​

  • BaseAgentConfig

Properties​

adaptive?​

optional adaptive: boolean

Defined in: packages/agentos/src/api/types.ts:1937

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


agents​

agents: Record<string, AgencySeatConfig | Agent>

Defined in: packages/agentos/src/api/types.ts:1905

Named roster of sub-agents. Each value is either a seat config (the agency builds it with agent(); see AgencySeatConfig) or a pre-built Agent instance.


apiKey?​

optional apiKey: string

Defined in: packages/agentos/src/api/types.ts:1474

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

Inherited from​

BaseAgentConfig.apiKey


avatar?​

optional avatar: AvatarConfig

Defined in: packages/agentos/src/api/types.ts:1621

Avatar visual presentation configuration.

Inherited from​

BaseAgentConfig.avatar


baseUrl?​

optional baseUrl: string

Defined in: packages/agentos/src/api/types.ts:1480

Override the provider base URL (useful for local proxies or Ollama). An empty or whitespace-only value is unset: a same-provider setDefaultProvider() URL, then the provider's URL variable, apply as with none. A seat of an agency with a blank value takes the agency-level baseUrl as a seat with none does.

Inherited from​

BaseAgentConfig.baseUrl


chair?​

optional chair: false | AgencySeatConfig

Defined in: packages/agentos/src/api/types.ts:1915

panel only: the agent that synthesizes the seats' outputs (from picks its model from the pool), or false for no synthesis.


channels?​

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

Defined in: packages/agentos/src/api/types.ts:1626

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

Inherited from​

BaseAgentConfig.channels


cognitiveMechanisms?​

optional cognitiveMechanisms: CognitiveMechanismsConfig

Defined in: packages/agentos/src/api/types.ts:1679

Cognitive mechanisms config: the eight memory mechanisms of CognitiveMemoryManager (reconsolidation, retrieval-induced forgetting, involuntary recall, feeling of knowing, temporal gist, schema encoding, source-confidence decay and emotion regulation). Pass {} for the defaults, or override fields per mechanism.

The mechanisms run inside a CognitiveMemoryManager initialized with this config (CognitiveMemoryConfig.cognitiveMechanisms). agent() without runtime: 'gmi' and agency() construct no memory manager, so they log a warning and leave this field unused; agent({ runtime: 'gmi' }) with memory on passes it to the agent's memory manager. On the full runtime, a gmiManagerConfig.cognitiveMemoryFactory builds the manager for each GMI.

See​

Cognitive Memory

Inherited from​

BaseAgentConfig.cognitiveMechanisms


controls?​

optional controls: ResourceControls

Defined in: packages/agentos/src/api/types.ts:1653

Resource limits (tokens, cost, time). agency() and the full runtime enforce every field against the entire run. The lightweight agent() helper forwards two of them per call: maxTotalTokens caps each LLM call's completion output (mapped to maxTokens when no explicit maxTokens is set, NOT the prompt+completion run total) and maxDurationMs bounds each LLM request (mapped to requestTimeout). The remaining fields stay agency()-only.

Inherited from​

BaseAgentConfig.controls


customModelParams?​

optional customModelParams: Record<string, unknown>

Defined in: packages/agentos/src/api/types.ts:1588

Provider-specific TOP-LEVEL request-payload parameters forwarded verbatim on every generate/stream/session call via ModelCompletionOptions.customModelParams. Providers spread these onto the outgoing request body — the escape hatch for params the typed options don't model, e.g. OpenRouter provider-routing preferences:

customModelParams: { provider: { sort: 'throughput' } }

Inherited from​

BaseAgentConfig.customModelParams


dependsOn?​

optional dependsOn: string[]

Defined in: packages/agentos/src/api/types.ts:1661

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, or an empty one, are roots and run first. agency() throws AgencyConfigError, naming the agent, for a value that is not an array of names.

Example​

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

Inherited from​

BaseAgentConfig.dependsOn


discovery?​

optional discovery: DiscoveryConfig

Defined in: packages/agentos/src/api/types.ts:1601

Runtime capability discovery configuration.

Inherited from​

BaseAgentConfig.discovery


effort?​

optional effort: string

Defined in: packages/agentos/src/api/types.ts:1576

Reasoning-effort control forwarded to every generate/stream/session call. On effort-capable Claude models (Opus 4.5+, Sonnet 4.6, Fable/Mythos 5) the provider sends output_config.effort (low|medium|high|xhigh|max). On OpenAI reasoning models (o-series, GPT-5.x) the provider sends reasoning_effort (chat) / reasoning.effort (Responses), with max clamping to xhigh — OpenAI's ceiling — and a model-aware guard capping xhigh → high on ids not probe-verified for xhigh (gpt-5.5/5.6 families are verified). Independent of thinking; ignored on unsupported models/values. Works per-agent in agency() rosters — each sub-agent may pin its own depth.

Inherited from​

BaseAgentConfig.effort


emergent?​

optional emergent: EmergentConfig

Defined in: packages/agentos/src/api/types.ts:1617

Emergent agent synthesis configuration.

Inherited from​

BaseAgentConfig.emergent


guardrails?​

optional guardrails: string[] | GuardrailsConfig

Defined in: packages/agentos/src/api/types.ts:1609

Guardrail policy identifiers or structured config. agency() evaluates none of them (see GuardrailsConfig), and agent() does not apply them.

  • string[] — shorthand; agency() reads it as the output list.
  • GuardrailsConfig — separate input and output lists.

Inherited from​

BaseAgentConfig.guardrails


hitl?​

optional hitl: HitlConfig

Defined in: packages/agentos/src/api/types.ts:1615

Human-in-the-loop approval configuration.

Inherited from​

BaseAgentConfig.hitl


instructions?​

optional instructions: string

Defined in: packages/agentos/src/api/types.ts:1470

Free-form system instructions prepended to the system prompt.

Inherited from​

BaseAgentConfig.instructions


maxRounds?​

optional maxRounds: number

Defined in: packages/agentos/src/api/types.ts:1942

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


maxSteps?​

optional maxSteps: number

Defined in: packages/agentos/src/api/types.ts:1509

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

Inherited from​

BaseAgentConfig.maxSteps


maxTokens?​

optional maxTokens: number

Defined in: packages/agentos/src/api/types.ts:1542

Upper bound on completion tokens for each LLM call the agent makes. Forwarded to the underlying generateText / streamText call on every generate(), stream(), and session.send() invocation.

Caps tail spend when a model misbehaves and yaps past the intended output size. Omit to use the provider default — AnthropicProvider defaults to 16000 (set 2026-05-17; was 4096), OpenAIProvider defaults to 4096, GeminiProvider defaults to 8192. Set to ~2× the agent's typical response size so normal calls finish naturally and only runaway generations hit the cap.

Example​

// Cap a roleplay agent at 1024 — short turns, fast feedback.
const companion = agent({
provider: 'anthropic',
model: 'claude-sonnet-4-6',
instructions: 'Reply in character. 2-3 sentences.',
maxTokens: 1024,
});

// Tool-use agent emitting verbose JSON — go big so structured
// output doesn't truncate mid-token. Opus 4.7 supports 32000.
const codegen = agent({
provider: 'anthropic',
model: 'claude-opus-4-7',
tools: { GenerateCode, RunTests, JudgeOutput },
maxTokens: 16000,
});

Inherited from​

BaseAgentConfig.maxTokens


memory?​

optional memory: boolean | MemoryConfig

Defined in: packages/agentos/src/api/types.ts:1597

Memory configuration. With runtime: 'gmi', true or a MemoryConfig turns on cognitive memory for the agent's sessions (its embedding, consolidation, persistAccessState, store and recall fields are read) and false keeps it off, also under cognition: 'full'. Without it, agent() reads the working callback and recall.budget.totalTokens (see MemoryConfig.recall). A session's message history is set by history, not by this field.

Inherited from​

BaseAgentConfig.memory


model?​

optional model: string

Defined in: packages/agentos/src/api/types.ts:1463

Model identifier. Accepted in two formats:

  • Plain model name (e.g. "gpt-4o") when provider is also set. Preferred.
  • "provider:model" combined string (e.g. "openai:gpt-4o").

Inherited from​

BaseAgentConfig.model


modelPool?​

optional modelPool: Record<string, ModelPoolEntry>

Defined in: packages/agentos/src/api/types.ts:1911

Every model a seat may sit on, named. A config seat that names neither provider nor model is then filled from the pool per call (see SeatingConfig). Declaration order is the preference order.


name?​

optional name: string

Defined in: packages/agentos/src/api/types.ts:1472

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

Inherited from​

BaseAgentConfig.name


observability?​

optional observability: ObservabilityConfig

Defined in: packages/agentos/src/api/types.ts:1636

Observability and telemetry configuration.

Inherited from​

BaseAgentConfig.observability


on?​

optional on: AgencyCallbacks

Defined in: packages/agentos/src/api/types.ts:1643

Event callbacks fired at various lifecycle points during the run. agency() fires them for its run. A gmi() agent fires them only for the teams it launches with launch_agency (agencies.launch), each named launch:<agencyId>, and for those launches' failures; its own turns fire none, and neither does agent() without runtime: 'gmi'.

Inherited from​

BaseAgentConfig.on


output?​

optional output: unknown

Defined in: packages/agentos/src/api/types.ts:1632

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.

Inherited from​

BaseAgentConfig.output


panel?​

optional panel: PanelOptions

Defined in: packages/agentos/src/api/types.ts:1917

panel only: deadlines, a concurrency cap and the minimum text that counts as an answer.


permissions?​

optional permissions: PermissionsConfig

Defined in: packages/agentos/src/api/types.ts:1613

Tool and resource permission fields. Accepted and not enforced (see PermissionsConfig).

Inherited from​

BaseAgentConfig.permissions


personality?​

optional personality: Partial<{ agreeableness: number; conscientiousness: number; emotionality: number; extraversion: number; honesty: number; honesty_humility: number; honestyHumility: number; openness: number; opennessToExperience: number; }>

Defined in: packages/agentos/src/api/types.ts:1488

HEXACO-inspired personality trait overrides (0–1 scale). Encoded as a human-readable trait string appended to the system prompt. The SOUL.md spellings honestyHumility / honesty_humility and opennessToExperience are accepted for honesty and openness; when both spellings are given, the canonical key wins.

Inherited from​

BaseAgentConfig.personality


provenance?​

optional provenance: AgencyProvenanceConfig

Defined in: packages/agentos/src/api/types.ts:1634

Provenance and audit-trail configuration.

Inherited from​

BaseAgentConfig.provenance


provider?​

optional provider: string

Defined in: packages/agentos/src/api/types.ts:1468

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

Inherited from​

BaseAgentConfig.provider


quorum?​

optional quorum: AgencyQuorumConfig

Defined in: packages/agentos/src/api/types.ts:1927

The floor the fan-out must reach. Under parallel: successful seats and distinct provider ids, checked after the fan-out (a seat with empty text counts, minAgents defaults to 0, 'proceed' is honoured with zero survivors). Under panel: healthy seats (those that returned text), distinct providers and distinct known vendors; minAgents defaults to 2 for a roster of two or more, and zero healthy seats always throws. Ignored by the other strategies.


rag?​

optional rag: RagConfig

Defined in: packages/agentos/src/api/types.ts:1599

Retrieval-Augmented Generation configuration.

Inherited from​

BaseAgentConfig.rag


runtime?​

optional runtime: "gmi" | "legacy"

Defined in: packages/agentos/src/api/types.ts:1953

The engine of every config seat that names none (a roster config, the panel's chair, a specialist the hierarchical manager spawns): 'legacy' (the default) calls the model through generateText and streamText, 'gmi' serves each of the seat's calls with a Generalized Mind Instance (docs/GMI.md, "GMIs from agent()"). A seat's own runtime wins. Pre-built seats keep the engine they were built with, and the hierarchical manager and the parallel and debate synthesizers stay on the legacy engine. Any other value throws AgencyConfigError, here and on a seat; null is unset at both levels. The agency itself takes no cognition: a strategy runs a config seat through its generate() or stream(), which run the 'light' profile; seat a persistent GMI with sessionSeat() to run its own profile.


seating?​

optional seating: SeatingConfig

Defined in: packages/agentos/src/api/types.ts:1913

How pooled seats are filled. Requires modelPool.


security?​

optional security: object

Defined in: packages/agentos/src/api/types.ts:1611

Security tier. Accepted and not enforced (see SecurityTier).

tier​

tier: SecurityTier

Inherited from​

BaseAgentConfig.security


strategy?​

optional strategy: AgencyStrategy

Defined in: packages/agentos/src/api/types.ts:1932

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


thinking?​

optional thinking: false | { budgetTokens: number; }

Defined in: packages/agentos/src/api/types.ts:1563

Extended-thinking switch forwarded to Claude models on every generate() / stream() / session call this agent makes. Any positive budgetTokens turns adaptive thinking on (the number itself is not sent). false turns thinking off with the model's own off shape; Opus 5.5, Fable and Mythos always think. Omitted keeps the model's default: thinking on for Opus 5 and later, Sonnet 5 and later, Fable and Mythos, off for older models. Other providers ignore it.

Example​

const codegen = agent({
provider: 'anthropic',
model: 'claude-opus-5',
tools: { GenerateCode, RunTests, JudgeOutput },
maxTokens: 24000,
thinking: { budgetTokens: 8000 },
});

Inherited from​

BaseAgentConfig.thinking


tools?​

optional tools: AdaptableToolInput

Defined in: packages/agentos/src/api/types.ts:1507

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

Inherited from​

BaseAgentConfig.tools


verifyCitations?​

optional verifyCitations: VerifyCitationsConfig

Defined in: packages/agentos/src/api/types.ts:1718

Verify citations after generate() and default-runtime session calls.

When set, generate() produces the answer, then fetches sources for the user's input with the configured retriever and scores each atomic claim of the answer against them via CitationVerifier. The resulting VerifiedResponse is attached to the result's grounding field — no separate verifier.verify(text, sources) call needed. On the default runtime, session.send() also checks its reply and session.stream() exposes a grounding promise that runs after its text completes. Direct stream() and GMI session calls do not verify. When the retriever returns no sources, or retrieval or the verifier fails, grounding stays unset and the answer is returned as generated.

Pass a config object with the embedding function and the source retriever the verifier should use:

Example​

const docsAgent = agent({
provider: 'openai',
model: 'gpt-4o',
verifyCitations: {
embedFn: async (texts) => (await embeddingManager.generateEmbeddings({ texts })).embeddings,
retrieve: (query) => retriever.search(query),
},
});

const result = await docsAgent.generate('How do I configure a guardrail?');
console.log(result.text);
console.log(result.grounding?.overallGrounded);
for (const claim of result.grounding?.claims ?? []) {
if (claim.verdict !== 'supported') console.warn(claim.text);
}

Inherited from​

BaseAgentConfig.verifyCitations


voice?​

optional voice: VoiceConfig

Defined in: packages/agentos/src/api/types.ts:1619

Voice interface configuration.

Inherited from​

BaseAgentConfig.voice