Interface AgencyOptions

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").

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

Free-form system instructions prepended to the system prompt.

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

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

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.

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.

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

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

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,
});
Copy

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 },
});
Copy

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.

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

Memory configuration. agent() reads it only with runtime: 'gmi', where true or a MemoryConfig turns on cognitive memory for the agent's sessions (its embedding and consolidation fields are read) and false keeps it off, also under cognition: 'full'. A session's message history is set by history, not by this field.

Retrieval-Augmented Generation configuration.

Runtime capability discovery configuration.

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.

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

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

Human-in-the-loop approval configuration.

Emergent agent synthesis configuration.

Voice interface configuration.

Avatar visual presentation configuration.

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

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.

Provenance and audit-trail configuration.

Observability and telemetry configuration.

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

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.

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

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

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);
}
Copy