Interface: SouledAgentOptions

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

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

Extends

AgentOptions

Properties

agencies?

optional agencies: AgencyLaunchOptions

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

Temporary teams this agent launches from a turn, with runtime: 'gmi': launch: true registers the launch_agency tool, which runs an agency() team on one goal and returns its answer as the call's result, and the other fields bound every launch (depth, seats, launches in flight, budget share and pool, deadline, members a launch may seat by key, hitl). Every bound is checked, and the members record read, at construction: a member put in the record afterwards is never seated. Off unless launch is true; the legacy runtime throws when it is, and its construction warning names agencies when another field is set, since it applies none of them.

Inherited from

AgentOptions.agencies

apiKey?

optional apiKey: string

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

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:1592

Avatar visual presentation configuration.

Inherited from

AgentOptions.avatar

baseUrl?

optional baseUrl: string

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

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

AgentOptions.baseUrl

budget?

optional budget: SpendBudget | SpendBudgetOptions

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

One spend budget for every call this agent and its sessions make: each provider call is checked against what is left before it is made and recorded after it, and AgentSession.recordExternalCost charges costs made outside AgentOS to it. Settings make one SpendBudget for the agent; pass an instance to share it wider. With runtime: 'gmi' every completion call a GMI makes is checked against it before it is sent, metaprompts and self-reflection included; its cognitive memory's embeddings and the learning layer's own calls are not counted. A seat's turn (sessionSeat(), or a member a launched team seats) is checked against it and charged to it beside the budget its team's call carries, and so is a team the seat's turn launches; its refusal of a seat's call runs the carried budget's onLimitReached function, as a refusal by that budget's parent does.

Inherited from

AgentOptions.budget

cache?

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

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

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:145

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:1597

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

Inherited from

AgentOptions.channels

cognition?

optional cognition: CognitionProfile | CognitionConfig

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

GMI profile when runtime is 'gmi': 'light' (the default), 'full', or each switch set in a CognitionConfig.

Inherited from

AgentOptions.cognition

cognitiveMechanisms?

optional cognitiveMechanisms: CognitiveMechanismsConfig

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

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

AgentOptions.cognitiveMechanisms

controls?

optional controls: ResourceControls

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

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

AgentOptions.controls

customModelParams?

optional customModelParams: Record<string, unknown>

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

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:1632

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

AgentOptions.dependsOn

discovery?

optional discovery: DiscoveryConfig

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

Runtime capability discovery configuration.

Inherited from

AgentOptions.discovery

effort?

optional effort: string

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

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:1588

Emergent agent synthesis configuration.

Inherited from

AgentOptions.emergent

fallbackProviders?

optional fallbackProviders: FallbackProviderEntry[]

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

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:1580

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

AgentOptions.guardrails

history?

optional history: false | Partial<SessionHistoryConfig>

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

Session conversation-history policy. 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:1586

Human-in-the-loop approval configuration.

Inherited from

AgentOptions.hitl

hostPolicy?

optional hostPolicy: HostLLMPolicy

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

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:1442

Free-form system instructions prepended to the system prompt.

Inherited from

AgentOptions.instructions

learning?

optional learning: boolean | LearningConfig | null

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

The learning layer when runtime is 'gmi' (docs/GMI.md, "Learning"). Unset, false or null: off, and the agent runs as it did before the layer existed. true or a LearningConfig: the agent's GMIs send the personality section as a system prompt of its own on every turn, and each session opened with a user id is bound to a learner. The legacy runtime ignores it.

Inherited from

AgentOptions.learning

maxSteps?

optional maxSteps: number

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

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:1514

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:1568

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.

Inherited from

AgentOptions.memory

memoryProvider?

optional memoryProvider: AgentMemoryProvider

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

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 as fire-and-forget after each LLM call, except schema calls, which observe only the accepted exchange after validation.

Inherited from

AgentOptions.memoryProvider

memoryProviderOptions?

optional memoryProviderOptions: MemoryProviderHookOptions

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

Optional tunables for the automatic memoryProvider hooks. timeoutMs bounds each getContext call before the turn ships without memory (default MEMORY_TIMEOUT_MS, 5000); tokenBudget is forwarded to getContext as the recall ceiling (default DEFAULT_MEMORY_TOKEN_BUDGET, 2000). Both fall back to the historical module constants when omitted.

Inherited from

AgentOptions.memoryProviderOptions

model?

optional model: string

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

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:1444

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:1607

Observability and telemetry configuration.

Inherited from

AgentOptions.observability

on?

optional on: AgencyCallbacks

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

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

AgentOptions.on

onAfterGeneration()?

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

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

Post-generation hook, called after each LLM step.

Parameters

onBeforeGeneration()?

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

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

Pre-generation hook, called before each LLM step. On the GMI path with learning on, its system is the persona's base prompt, which holds no personality section; the system text in messages holds the section after the base prompt.

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:248

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:165

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:1603

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:1584

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

Inherited from

AgentOptions.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:1460

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

AgentOptions.personality

policyTier?

optional policyTier: "safe" | "standard" | "mature" | "private-adult"

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

Caller's intended content policy tier, forwarded to every generate() / stream() / session call this agent makes (same contract as GenerateTextOptions.policyTier): on 'mature' / 'private-adult' with no explicit fallbackProviders, the auto-built fallback chain leads with the tier's uncensored legs so a content-policy refusal from the primary re-routes to a model that can complete the request, and the model router receives the tier as a routing hint. Unset, the chain follows the tier the call otherwise resolves to (a host policy's tier or the router's default tier); with no tier anywhere it is the availability-only chain. A per-call policyTier in extra overrides this value.

Inherited from

AgentOptions.policyTier

provenance?

optional provenance: AgencyProvenanceConfig

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

Provenance and audit-trail configuration.

Inherited from

AgentOptions.provenance

provider?

optional provider: string

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

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:1570

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:238

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 after generation. 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:167

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:214

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'] },
  responseSchema: 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

runtime?

optional runtime: "gmi" | "legacy"

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

Which engine serves this agent. 'legacy' (the default) calls the model through generateText and streamText; 'gmi' serves every session with a Generalized Mind Instance (docs/GMI.md, "GMIs from agent()").

Inherited from

AgentOptions.runtime

security?

optional security: object

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

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

tier

tier: SecurityTier

Inherited from

AgentOptions.security

skills?

optional skills: SkillEntry[]

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

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:278

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: false | { budgetTokens: number; }

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

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

AgentOptions.thinking

tools?

optional tools: AdaptableToolInput

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

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:138

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:1689

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

AgentOptions.verifyCitations

voice?

optional voice: VoiceConfig & object

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

Explicit runtime binding. No provider is discovered from the process environment for this path.

Type Declaration

session?

optional session: object

session.agent

agent: object

session.agent.agentId

agentId: string = id

session.agent.allowedToolRefs

allowedToolRefs: string[]

session.agent.createdAt

createdAt: number = count

session.agent.endpoint

endpoint: object = EndpointSelectionSchema

session.agent.endpoint.modelId

modelId: string = id

session.agent.endpoint.modelRevision

modelRevision: string = revisionRef

session.agent.endpoint.optionsRef?

optional optionsRef: string

session.agent.endpoint.providerId

providerId: string = id

session.agent.language

language: string

session.agent.limits

limits: object = VoiceCallLimitsSchema

session.agent.limits.cleanupTimeoutMs

cleanupTimeoutMs: number = positive

session.agent.limits.maxDurationSeconds

maxDurationSeconds: number = positive

session.agent.limits.maxTurns

maxTurns: number = positive

session.agent.limits.reconnectGraceMs

reconnectGraceMs: number = count

session.agent.limits.setupTimeoutMs

setupTimeoutMs: number = positive

session.agent.limits.silenceTimeoutMs

silenceTimeoutMs: number = positive

session.agent.name

name: string

session.agent.prompt

prompt: string

session.agent.providerPolicy

providerPolicy: object = VoiceProviderPolicySchema

session.agent.providerPolicy.fallback

fallback: "none" | "allowlisted"

session.agent.providerPolicy.mode

mode: "provider" | "local" | "hosted"

session.agent.providerPolicy.providerIds

providerIds: string[]

session.agent.providerPolicy.purposes

purposes: ("stt" | "tts" | "vad" | "endpoint" | "reasoning")[]

session.agent.reasoning

reasoning: { attemptLimits: { maxAttempts: number; perAttempt: { cached_input_token: number; input_token: number; output_token: number; reasoning_token: number; request: number; }; }; cancellation: "native_abort" | "process_exit" | "unsupported"; fallbacks: ({ attemptLimits: ...; cancellation: ...; manifestDigest: ...; modelId: ...; modelRevision: ...; protocol: ...; provider: ...; usageUnits: ...; } | { attemptLimits: ...; cancellation: ...; credentialRef?: ...; endpointRef: ...; endpointRevision: ...; modelId: ...; modelRevision: ...; protocol: ...; provider: ...; usageUnits: ...; })[]; manifestDigest: string; modelId: string; modelRevision: string; protocol: { id: "openai-chat-completions"; version: 1; }; provider: "local"; usageUnits: { cached_input_token: "token"; input_token: "token"; output_token: "token"; reasoning_token: "token"; reasoningInOutput: boolean; }; } | { attemptLimits: { maxAttempts: number; perAttempt: { cached_input_token: number; input_token: number; output_token: number; reasoning_token: number; request: number; }; }; cancellation: "native_abort" | "process_exit" | "unsupported"; credentialRef?: string; endpointRef: string; endpointRevision: number; fallbacks: ({ attemptLimits: ...; cancellation: ...; manifestDigest: ...; modelId: ...; modelRevision: ...; protocol: ...; provider: ...; usageUnits: ...; } | { attemptLimits: ...; cancellation: ...; credentialRef?: ...; endpointRef: ...; endpointRevision: ...; modelId: ...; modelRevision: ...; protocol: ...; provider: ...; usageUnits: ...; })[]; modelId: string; modelRevision: string; protocol: { id: "openai-chat-completions"; version: 1; }; provider: "registered_endpoint"; usageUnits: { cached_input_token: "token"; input_token: "token"; output_token: "token"; reasoning_token: "token"; reasoningInOutput: boolean; }; } = ReasoningConfigSchema

session.agent.revision

revision: number = positive

session.agent.scopeId

scopeId: string = id

session.agent.state

state: "active" | "archived"

session.agent.stt

stt: object = SpeechSelectionSchema

session.agent.stt.codec

codec: "mp3" | "opus" | "wav" | "pcm_s16le" | "pcm_f32le"

session.agent.stt.credentialRef?

optional credentialRef: string

session.agent.stt.mode

mode: "streaming" | "batch"

session.agent.stt.modelId

modelId: string = id

session.agent.stt.modelRevision

modelRevision: string = revisionRef

session.agent.stt.optionsRef?

optional optionsRef: string

session.agent.stt.providerId

providerId: string = id

session.agent.stt.sampleRate

sampleRate: number

session.agent.transcriptPolicy

transcriptPolicy: { mode: "none"; } | { deliveryTtlSeconds: number; mode: "delivery"; } | { mode: "retained"; retentionSeconds: number; } = TranscriptPolicySchema

session.agent.tts

tts: object = SpeechSelectionSchema

session.agent.tts.codec

codec: "mp3" | "opus" | "wav" | "pcm_s16le" | "pcm_f32le"

session.agent.tts.credentialRef?

optional credentialRef: string

session.agent.tts.mode

mode: "streaming" | "batch"

session.agent.tts.modelId

modelId: string = id

session.agent.tts.modelRevision

modelRevision: string = revisionRef

session.agent.tts.optionsRef?

optional optionsRef: string

session.agent.tts.providerId

providerId: string = id

session.agent.tts.sampleRate

sampleRate: number

session.agent.updatedAt

updatedAt: number = count

session.agent.vad

vad: object = VadSelectionSchema

session.agent.vad.modelId

modelId: string = id

session.agent.vad.modelRevision

modelRevision: string = revisionRef

session.agent.vad.optionsRef?

optional optionsRef: string

session.agent.vad.providerId

providerId: string = id

session.agent.vad.threshold

threshold: number

session.agent.version

version: 1

session.agent.voice

voice: object = VoiceSelectionSchema

session.agent.voice.id

id: string

session.agent.voice.revision

revision: string = revisionRef

session.agent.webhookRef

webhookRef: string | null

session.factory

factory: VoiceSessionFactory

Inherited from

AgentOptions.voice

Extends​

Properties​

agencies?​

Inherited from​

apiKey?​

Inherited from​

avatar?​

Inherited from​

baseUrl?​

Inherited from​

budget?​

Inherited from​

cache?​

Inherited from​

chainOfThought?​

Inherited from​

channels?​

Inherited from​

cognition?​

Inherited from​

cognitiveMechanisms?​

See​

Inherited from​

controls?​

Inherited from​

customModelParams?​

Inherited from​

dependsOn?​

Example​

Inherited from​

discovery?​

Inherited from​

effort?​

Inherited from​

emergent?​

Inherited from​

fallbackProviders?​

See​

Inherited from​

guardrails?​

Inherited from​

history?​

Inherited from​

hitl?​

Inherited from​

hostPolicy?​

Inherited from​

instructions?​

Inherited from​

learning?​

Inherited from​

maxSteps?​

Inherited from​

maxTokens?​

Example​

Inherited from​

memory?​

Inherited from​

memoryProvider?​

Inherited from​

memoryProviderOptions?​

Inherited from​

model?​

Inherited from​

name?​

Inherited from​

observability?​

Inherited from​

on?​

Inherited from​

onAfterGeneration()?​

Parameters​

result​

Returns​

Inherited from​

onBeforeGeneration()?​

Parameters​

context​

Returns​

Inherited from​

Extends

Properties

agencies?

Inherited from

apiKey?

Inherited from

avatar?

Inherited from

baseUrl?

Inherited from

budget?

Inherited from

cache?

Inherited from

chainOfThought?

Inherited from

channels?

Inherited from

cognition?

Inherited from

cognitiveMechanisms?

See

Inherited from

controls?

Inherited from

customModelParams?

Inherited from

dependsOn?

Example

Inherited from

discovery?

Inherited from

effort?

Inherited from

emergent?

Inherited from

fallbackProviders?

See

Inherited from

guardrails?

Inherited from

history?

Inherited from

hitl?

Inherited from

hostPolicy?

Inherited from

instructions?

Inherited from

learning?

Inherited from

maxSteps?

Inherited from

maxTokens?

Example

Inherited from

memory?

Inherited from

memoryProvider?

Inherited from

memoryProviderOptions?

Inherited from

model?

Inherited from

name?

Inherited from

observability?

Inherited from

on?

Inherited from

onAfterGeneration()?

Parameters

result

Returns

Inherited from

onBeforeGeneration()?

Parameters

context

Returns

Inherited from