Interface: AgentOptions
Defined in: packages/agentos/src/api/agent.ts:174
Configuration options for the agent factory function.
Extends BaseAgentConfig with backward-compatible convenience fields.
All BaseAgentConfig fields are accepted. Without runtime: 'gmi', the
lightweight agent does not apply the ones the agent column of the
capability contract defers (rag, discovery, guardrails, security,
permissions, emergent, voice, etc.), and one warning at construction names
those that are set. No surface applies security or permissions.
Extends
BaseAgentConfig
Extended by
Properties
accountIdOf?
optionalaccountIdOf:LlmUsageAccountResolver
Defined in: packages/agentos/src/api/agent.ts:184
Names the account of a call whose budget names none, on every generate, stream and session call this agent makes
(GenerateTextOptions.accountIdOf): the global LLM usage observer's events carry it as accountId.
agencies?
optionalagencies:AgencyLaunchOptions
Defined in: packages/agentos/src/api/agent.ts:427
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.
apiKey?
optionalapiKey: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?
optionalavatar:AvatarConfig
Defined in: packages/agentos/src/api/types.ts:1621
Avatar visual presentation configuration.
Inherited from
BaseAgentConfig.avatar
baseUrl?
optionalbaseUrl: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
budget?
optionalbudget:SpendBudget|SpendBudgetOptions
Defined in: packages/agentos/src/api/agent.ts:227
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.
cache?
optionalcache:false| {tail?:boolean;ttl?:"5m"|"1h"; }
Defined in: packages/agentos/src/api/agent.ts:349
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.
{ tail: false } keeps the system-prefix markers and places no
breakpoint on the messages, for a one-call-per-input agent (a judge, a
classifier) whose prefix repeats and whose tail never does; a multi-turn
session wants the tail, which is what reads its history back.
Unset -> the provider's default marker pacing.
chainOfThought?
optionalchainOfThought:string|boolean
Defined in: packages/agentos/src/api/agent.ts:191
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.
channels?
optionalchannels: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
cognition?
optionalcognition:CognitionProfile|CognitionConfig
Defined in: packages/agentos/src/api/agent.ts:410
GMI profile when runtime is 'gmi': 'light' (the default), 'full', or each
switch set in a CognitionConfig.
cognitiveMechanisms?
optionalcognitiveMechanisms: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
Inherited from
BaseAgentConfig.cognitiveMechanisms
controls?
optionalcontrols: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?
optionalcustomModelParams: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?
optionaldependsOn: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?
optionaldiscovery:DiscoveryConfig
Defined in: packages/agentos/src/api/types.ts:1601
Runtime capability discovery configuration.
Inherited from
BaseAgentConfig.discovery
effort?
optionaleffort: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?
optionalemergent:EmergentConfig
Defined in: packages/agentos/src/api/types.ts:1617
Emergent agent synthesis configuration.
Inherited from
BaseAgentConfig.emergent
fallbackProviders?
optionalfallbackProviders:FallbackProviderEntry[]
Defined in: packages/agentos/src/api/agent.ts:204
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
guardrails?
optionalguardrails: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
history?
optionalhistory:false|Partial<SessionHistoryConfig>
Defined in: packages/agentos/src/api/agent.ts:358
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.
hitl?
optionalhitl:HitlConfig
Defined in: packages/agentos/src/api/types.ts:1615
Human-in-the-loop approval configuration.
Inherited from
BaseAgentConfig.hitl
hostPolicy?
optionalhostPolicy:HostLLMPolicy
Defined in: packages/agentos/src/api/agent.ts:216
Host-level routing hints forwarded to the high-level generation helpers.
instructions?
optionalinstructions:string
Defined in: packages/agentos/src/api/types.ts:1470
Free-form system instructions prepended to the system prompt.
Inherited from
BaseAgentConfig.instructions
learning?
optionallearning:boolean|LearningConfig|null
Defined in: packages/agentos/src/api/agent.ts:417
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.
maxSteps?
optionalmaxSteps: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?
optionalmaxTokens: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?
optionalmemory: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
memoryProvider?
optionalmemoryProvider:AgentMemoryProvider
Defined in: packages/agentos/src/api/agent.ts:307
Optional memory provider. When provided, memory auto-wires on all four agent call paths (see AgentMemoryProvider for hook contract).
getContextruns once per turn; its recall goes into every model call of the turn as a data block in a user-role message before the turn's own, with one static line of the system prompt that explains it.observeruns as fire-and-forget once per side of an answered turn, after the result the caller receives: a schema call observes only the accepted exchange, and a stream that ends in an error is not observed.
memoryProviderOptions?
optionalmemoryProviderOptions:MemoryProviderHookOptions
Defined in: packages/agentos/src/api/agent.ts:317
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 ceiling of the recalled text (default
DEFAULT_MEMORY_TOKEN_BUDGET, 2000). The block the recall is sent in adds
its tags, a note, each record's keys and the escapes of <, > and &
beyond that ceiling. Both fall back to the module constants when omitted.
model?
optionalmodel:string
Defined in: packages/agentos/src/api/types.ts:1463
Model identifier. Accepted in two formats:
- Plain model name (e.g.
"gpt-4o") whenprovideris also set. Preferred. "provider:model"combined string (e.g."openai:gpt-4o").
Inherited from
BaseAgentConfig.model
name?
optionalname: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?
optionalobservability:ObservabilityConfig
Defined in: packages/agentos/src/api/types.ts:1636
Observability and telemetry configuration.
Inherited from
BaseAgentConfig.observability
on?
optionalon: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
onAfterGeneration()?
optionalonAfterGeneration: (result) =>Promise<void|GenerationHookResult>
Defined in: packages/agentos/src/api/agent.ts:293
Post-generation hook, called after each LLM step.
Parameters
result
Returns
Promise<void | GenerationHookResult>
onBeforeGeneration()?
optionalonBeforeGeneration: (context) =>Promise<void|GenerationHookContext>
Defined in: packages/agentos/src/api/agent.ts:291
Pre-generation hook, called before each LLM step. On the GMI path with learning on, or with traits (the
personality option or a soul's hexaco), 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
Returns
Promise<void | GenerationHookContext>
onBeforeToolExecution()?
optionalonBeforeToolExecution: (info) =>Promise<ToolCallHookInfo|null>
Defined in: packages/agentos/src/api/agent.ts:295
Pre-tool-execution hook.
Parameters
info
Returns
Promise<ToolCallHookInfo | null>
onFallback()?
optionalonFallback: (error,fallbackProvider) =>void
Defined in: packages/agentos/src/api/agent.ts:212
Callback invoked when a fallback provider is about to be tried.
Parameters
error
Error
The error that triggered the fallback.
fallbackProvider
string
The provider the next leg is sent to, as GenerateTextOptions.onFallback names it.
Returns
void
output?
optionaloutput: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
permissions?
optionalpermissions: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?
optionalpersonality: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
policyTier?
optionalpolicyTier:"safe"|"standard"|"mature"|"private-adult"
Defined in: packages/agentos/src/api/agent.ts:241
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.
provenance?
optionalprovenance:AgencyProvenanceConfig
Defined in: packages/agentos/src/api/types.ts:1634
Provenance and audit-trail configuration.
Inherited from
BaseAgentConfig.provenance
provider?
optionalprovider: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
rag?
optionalrag:RagConfig
Defined in: packages/agentos/src/api/types.ts:1599
Retrieval-Augmented Generation configuration.
Inherited from
BaseAgentConfig.rag
responseSchema?
optionalresponseSchema:ZodType<unknown,unknown,$ZodTypeInternals<unknown,unknown>>
Defined in: packages/agentos/src/api/agent.ts:285
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[]
router?
optionalrouter:IModelRouter
Defined in: packages/agentos/src/api/agent.ts:214
Model router for intelligent provider selection per-call.
routerParams?
optionalrouterParams:Partial<ModelRouteParams>
Defined in: packages/agentos/src/api/agent.ts:261
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).
runtime?
optionalruntime:"gmi"|"legacy"
Defined in: packages/agentos/src/api/agent.ts:405
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()").
security?
optionalsecurity: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
skills?
optionalskills:SkillEntry[]
Defined in: packages/agentos/src/api/agent.ts:322
Optional skill entries to inject into the system prompt. Skill content is appended to the system prompt as markdown sections.
soul?
optionalsoul:string| {content:string;optional?:boolean; } | {optional?:boolean;path:string; }
Defined in: packages/agentos/src/api/agent.ts:399
Per-agent identity loaded from a SOUL.md workspace (the OpenClaw / 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: when the agent is built without systemBlocks (which
replace the assembled prompt, the soul's prose with it), agent() reads
the soul and joins its prose into one system prompt, first the SOUL.md body, then a
## Style section from STYLE.md, then the memory/index.md catalog, before
instructions, name, personality and skills. The front matter applies
too: the hard limits close the system prompt as a block of their own, after
systemBlocks as well; the hexaco scores render as the trait paragraph when
personality is unset; and the soul's name is the name line when name is
unset. Mood, voice, avatar and reasoning-trace limits have no renderer on this
runtime; runtime: 'gmi' applies mood and the trace limits through its
persona. A soul that fails to load, or whose
front matter has a field of the wrong type, throws SoulLoadError when the
agent is built. optional: true on the object forms runs the agent without
it and writes one soul.load_failed log line.
See
loadSoulin@framers/agentos/cognition/substrate/personas/SoulLoaderfor the loader implementation and full SOUL.md format spec.- https://github.com/aeonfun/soul.md for the cross-framework convention.
systemBlocks?
optionalsystemBlocks:SystemContentBlock[]
Defined in: packages/agentos/src/api/agent.ts:333
Structured system prompt blocks with cache breakpoints.
When provided, they replace the assembled prompt whole: the soul's SOUL.md
prose, STYLE.md and memory index are not added, and neither are
instructions, name, personality and skills. The soul is still
loaded at build: its hard limits close the prompt as one more block after
yours, and a soul that fails to load throws SoulLoadError unless it is
given as { path, optional: true }.
Use this for prompt caching support with Anthropic.
thinking?
optionalthinking: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?
optionaltools: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
usageLedger?
optionalusageLedger:AgentOSUsageLedgerOptions
Defined in: packages/agentos/src/api/agent.ts:179
Top-level usage ledger shorthand. When present, forwarded to
observability.usageLedger internally.
verifyCitations?
optionalverifyCitations: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?
optionalvoice:VoiceConfig&object
Defined in: packages/agentos/src/api/agent.ts:429
Explicit runtime binding. No provider is discovered from the process environment for this path.
Type Declaration
session?
optionalsession: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?
optionaloptionsRef: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?
optionalcredentialRef: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?
optionaloptionsRef: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?
optionalcredentialRef: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?
optionaloptionsRef: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?
optionaloptionsRef: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
Overrides
BaseAgentConfig.voice