Skip to main content

Interface: SouledAgentOptions

Defined in: packages/agentos/src/api/souledAgent.ts:33

Options for souledAgent. Identical to AgentOptions, but soul is required.

Extends​

Properties​

apiKey?​

optional apiKey: string

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

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

Inherited from​

AgentOptions.apiKey

avatar?​

optional avatar: AvatarConfig

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

Avatar visual presentation configuration.

Inherited from​

AgentOptions.avatar

baseUrl?​

optional baseUrl: string

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

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

Inherited from​

AgentOptions.baseUrl

cache?​

optional cache: false | { ttl?: "5m" | "1h"; }

Defined in: packages/agentos/src/api/agent.ts:227

Per-call prompt-cache control forwarded to every generate / stream / session call this agent makes (same contract as GenerateTextOptions.cache): false sends zero cache markers; { ttl: '1h' } re-times the auto markers — including the moving conversation-history tail — onto the 1-hour cache. Set '1h' for agent loops whose steps gap past the 5-minute default cache TTL (multi-minute tool executions between LLM steps), where the default-paced history marker expires between steps and every step re-writes the whole prefix. Unset -> the provider's default marker pacing.

Inherited from​

AgentOptions.cache

chainOfThought?​

optional chainOfThought: string | boolean

Defined in: packages/agentos/src/api/agent.ts:120

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.

Inherited from​

AgentOptions.chainOfThought

channels?​

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

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

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

Inherited from​

AgentOptions.channels

cognitiveMechanisms?​

optional cognitiveMechanisms: CognitiveMechanismsConfig

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

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

Inherited from​

AgentOptions.cognitiveMechanisms

controls?​

optional controls: ResourceControls

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

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

Inherited from​

AgentOptions.controls

customModelParams?​

optional customModelParams: Record<string, unknown>

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

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​

AgentOptions.customModelParams

dependsOn?​

optional dependsOn: string[]

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

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.

Inherited from​

AgentOptions.dependsOn

discovery?​

optional discovery: DiscoveryConfig

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

Runtime capability discovery configuration.

Inherited from​

AgentOptions.discovery

effort?​

optional effort: string

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

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​

AgentOptions.effort

emergent?​

optional emergent: EmergentConfig

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

Emergent agent synthesis configuration.

Inherited from​

AgentOptions.emergent

fallbackProviders?​

optional fallbackProviders: FallbackProviderEntry[]

Defined in: packages/agentos/src/api/agent.ts:133

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

Defaults to auto-built chain when omitted — fallback is on by default. Pass [] for strict single-provider mode, or supply a custom array to control the chain. Applied to every generate(), stream(), and session.send() / session.stream() call made through this agent.

See​

GenerateTextOptions.fallbackProviders

Inherited from​

AgentOptions.fallbackProviders

guardrails?​

optional guardrails: string[] | GuardrailsConfig

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

Guardrail policy identifiers or structured config.

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

Inherited from​

AgentOptions.guardrails

history?​

optional history: false | Partial<SessionHistoryConfig>

Defined in: packages/agentos/src/api/agent.ts:236

Session conversation-history policy (spec 2026-07-20 §1a/§1c). Sessions maintain a lossless transcript by default — independent of the memory subsystem — bounded past maxTokens (default 120K estimated) by chunk-amortized whole-block eviction. false restores stateless sessions (the pre-0.10 memory: false behavior). Partial objects override individual bounds.

Inherited from​

AgentOptions.history

hitl?​

optional hitl: HitlConfig

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

Human-in-the-loop approval configuration.

Inherited from​

AgentOptions.hitl

hostPolicy?​

optional hostPolicy: HostLLMPolicy

Defined in: packages/agentos/src/api/agent.ts:144

Host-level routing hints forwarded to the high-level generation helpers.

Inherited from​

AgentOptions.hostPolicy

instructions?​

optional instructions: string

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

Free-form system instructions prepended to the system prompt.

Inherited from​

AgentOptions.instructions

maxSteps?​

optional maxSteps: number

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

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

Inherited from​

AgentOptions.maxSteps

maxTokens?​

optional maxTokens: number

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

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​

AgentOptions.maxTokens

memory?​

optional memory: boolean | MemoryConfig

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

Memory configuration.

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

Inherited from​

AgentOptions.memory

memoryProvider?​

optional memoryProvider: AgentMemoryProvider

Defined in: packages/agentos/src/api/agent.ts:203

Optional memory provider. When provided, memory auto-wires on all four agent call paths (see AgentMemoryProvider for hook contract).

  • getContext runs before each LLM call; result prepended as a system message.
  • observe runs after each LLM call as fire-and-forget.

Inherited from​

AgentOptions.memoryProvider

model?​

optional model: string

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

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​

AgentOptions.model

name?​

optional name: string

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

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

Inherited from​

AgentOptions.name

observability?​

optional observability: ObservabilityConfig

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

Observability and telemetry configuration.

Inherited from​

AgentOptions.observability

on?​

optional on: AgencyCallbacks

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

Event callbacks fired at various lifecycle points during the run.

Inherited from​

AgentOptions.on

onAfterGeneration()?​

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

Defined in: packages/agentos/src/api/agent.ts:192

Post-generation hook, called after each LLM step.

Parameters​

result​

GenerationHookResult

Returns​

Promise<void | GenerationHookResult>

Inherited from​

AgentOptions.onAfterGeneration

onBeforeGeneration()?​

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

Defined in: packages/agentos/src/api/agent.ts:190

Pre-generation hook, called before each LLM step.

Parameters​

context​

GenerationHookContext

Returns​

Promise<void | GenerationHookContext>

Inherited from​

AgentOptions.onBeforeGeneration

onBeforeToolExecution()?​

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

Defined in: packages/agentos/src/api/agent.ts:194

Pre-tool-execution hook.

Parameters​

info​

ToolCallHookInfo

Returns​

Promise<ToolCallHookInfo | null>

Inherited from​

AgentOptions.onBeforeToolExecution

onFallback()?​

optional onFallback: (error, fallbackProvider) => void

Defined in: packages/agentos/src/api/agent.ts:140

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

Parameters​

error​

Error

The error that triggered the fallback.

fallbackProvider​

string

The provider identifier being tried next.

Returns​

void

Inherited from​

AgentOptions.onFallback

output?​

optional output: unknown

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

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​

AgentOptions.output

permissions?​

optional permissions: PermissionsConfig

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

Fine-grained tool and resource permission overrides.

Inherited from​

AgentOptions.permissions

personality?​

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

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

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

Inherited from​

AgentOptions.personality

provenance?​

optional provenance: AgencyProvenanceConfig

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

Provenance and audit-trail configuration.

Inherited from​

AgentOptions.provenance

provider?​

optional provider: string

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

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

Inherited from​

AgentOptions.provider

rag?​

optional rag: RagConfig

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

Retrieval-Augmented Generation configuration.

Inherited from​

AgentOptions.rag

responseSchema?​

optional responseSchema: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

Defined in: packages/agentos/src/api/agent.ts:188

Optional Zod schema for validating the LLM's structured output.

When provided, the agent's generate() result includes a parsed field with the Zod-validated and typed output. JSON extraction and validation happen automatically in the onAfterGeneration hook. On validation failure, the agent retries internally (up to controls.maxValidationRetries ?? 1).

When omitted, behavior is unchanged — result.parsed is undefined. This is a non-breaking additive change.

Example​

import { z } from 'zod';
const myAgent = agent({
  name: 'Extractor',
  instructions: 'Extract entities as JSON',
  responseSchema: z.object({ entities: z.array(z.string()) }),
});
const result = await myAgent.generate('Find entities in: ...');
console.log(result.parsed?.entities); // string[]

Inherited from​

AgentOptions.responseSchema

router?​

optional router: IModelRouter

Defined in: packages/agentos/src/api/agent.ts:142

Model router for intelligent provider selection per-call.

Inherited from​

AgentOptions.router

routerParams?​

optional routerParams: Partial<ModelRouteParams>

Defined in: packages/agentos/src/api/agent.ts:164

Routing hints passed to the model router's selectModel() call.

Useful for declaring capability requirements up-front so the router can pick a model that actually supports what the agent needs:

agent({
  name: 'World Architect',
  router: policyAwareRouter,
  routerParams: { requiredCapabilities: ['json_mode'] },
  output: WorldIdentitySchema,
});

When omitted, the router receives a minimal default params object (taskHint only, plus function_calling in requiredCapabilities when tools are declared).

Inherited from​

AgentOptions.routerParams

security?​

optional security: object

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

Security tier controlling permitted tools and capabilities.

tier​

tier: SecurityTier

Inherited from​

AgentOptions.security

skills?​

optional skills: SkillEntry[]

Defined in: packages/agentos/src/api/agent.ts:208

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

Inherited from​

AgentOptions.skills

soul​

soul: NonNullable<string | { content: string; } | { path: string; } | undefined>

Defined in: packages/agentos/src/api/souledAgent.ts:34

Per-agent identity loaded from a SOUL.md workspace (the OpenClaw / aaronjmars-soul.md convention). Three forms are accepted:

  • Workspace path — points at a directory containing SOUL.md and optional companion files (STYLE.md, IDENTITY.md, AGENTS.md, MEMORY.md, examples/):

    agent({ provider: 'anthropic', soul: '~/.agentos/agents/aria' });

  • Direct file path — points at a single SOUL.md file:

    agent({ provider: 'anthropic', soul: './personas/aria.soul.md' });

  • Inline content — pass the soul markdown directly (useful for tests and ephemeral agents):

    agent({ provider: 'anthropic', soul: { content: SOUL_MARKDOWN_STRING } });

Loading semantics: at agent boot the runtime reads SOUL.md, parses YAML frontmatter into an IPersonaDefinition (HEXACO traits, voice, mood, hardLimits), and injects the markdown body as the FIRST system message — before instructions, chainOfThought, personality, or skills. STYLE.md is appended as a second system message when present.

See​

  • loadSoul in @framers/agentos/cognition/substrate/personas/SoulLoader for the loader implementation and full SOUL.md format spec.
  • https://github.com/aaronjmars/soul.md for the cross-framework convention.

Overrides​

AgentOptions.soul

systemBlocks?​

optional systemBlocks: SystemContentBlock[]

Defined in: packages/agentos/src/api/agent.ts:215

Structured system prompt blocks with cache breakpoints. When provided, takes precedence over the assembled string from instructions, name, personality, and skills. Use this for prompt caching support with Anthropic.

Inherited from​

AgentOptions.systemBlocks

thinking?​

optional thinking: object

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

Extended-thinking budget (in tokens) forwarded to thinking-capable models (Opus 4.7/4.8) on every generate() / stream() / session call this agent makes. When set, the provider emits reasoning blocks and floors maxTokens at budgetTokens + 8192. Omitted = thinking off. No effect on models that do not support extended thinking.

budgetTokens​

budgetTokens: number

Example​

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

Inherited from​

AgentOptions.thinking

tools?​

optional tools: AdaptableToolInput

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

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​

AgentOptions.tools

usageLedger?​

optional usageLedger: AgentOSUsageLedgerOptions

Defined in: packages/agentos/src/api/agent.ts:113

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

Inherited from​

AgentOptions.usageLedger

verifyCitations?​

optional verifyCitations: VerifyCitationsConfig

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

Auto-verify citations after every generation.

When set, the agent retrieves sources for each user input, runs generation, then scores each atomic claim in the response against the retrieved sources via CitationVerifier. The resulting VerifiedResponse is attached to the generation result's grounding field — no separate verifier.verify(text, sources) call needed.

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:  (texts) => embeddingManager.embedBatch(texts),
    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​

AgentOptions.verifyCitations

voice?​

optional voice: VoiceConfig

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

Voice interface configuration.

Inherited from​

AgentOptions.voice