Interface: GenerateTextOptions
Defined in: packages/agentos/src/api/generateText.ts:455
Properties
__approvalGate?
optional__approvalGate:ApprovalGateFn
Defined in: packages/agentos/src/api/generateText.ts:956
Internal
Internal — DO NOT set from application code. The tool-approval gate,
set by agency() when hitl.approvals.beforeTool is listed, or
forwarded from a parent agency. Every tool loop calls it after
onBeforeToolExecution, on the arguments that hook left; anything but
its exact approval skips the tool and tells the model.
__emptyPrompt?
optional__emptyPrompt:boolean
Defined in: packages/agentos/src/api/generateText.ts:946
Internal
Internal: set by the guards when a sanitizer removed the whole text of prompt. The empty prompt is then sent as
an empty user turn, where an empty prompt a caller passes adds none. Not part of the public API.
__fallbackDepth?
optional__fallbackDepth:number
Defined in: packages/agentos/src/api/generateText.ts:836
Internal
Internal — DO NOT set from application code. Fallback-hop depth,
threaded into the provider-fallback recursion so the leg's usage
observer event carries fallbackDepth and hosts can tell leg
traffic from primary traffic. Absent (0) on top-level calls.
__fallbackWalk?
optional__fallbackWalk:FallbackWalkContext
Defined in: packages/agentos/src/api/generateText.ts:855
Internal
Internal — DO NOT set from application code. The fallback walk's state
before this leg ran, and the leg's role, handed down the recursion. Its
presence marks fallbackProviders as already resolved, so a nested walk
never resolves it again.
__guardRun?
optional__guardRun:TextGuardRun
Defined in: packages/agentos/src/api/generateText.ts:939
Internal
Internal: the run of a call that carries guards, set by the wrapper and carried by every fallback leg so each
tool loop can ask it about a call. Not part of the public API.
__hopBase?
optional__hopBase:FallbackHopBase
Defined in: packages/agentos/src/api/generateText.ts:846
Internal
Internal — DO NOT set from application code. The outermost call's
maxTokens, effort and cache, threaded into the provider-fallback
recursion so a hop's per-entry overrides (see
fallbackHopOverrides) apply to that hop alone. Absent on a
top-level call, where the call's own values are the base.
__maskError()?
optional__maskError: (error) =>unknown
Defined in: packages/agentos/src/api/generateText.ts:982
Internal
Internal — set by an agency's seating on every seat and the chair: the
call's error mask. The tool loops pass a tool's error through it, as one
redacted string, before they write the call record, the tool turn and the
tool-result stream part.
Parameters
error
unknown
Returns
unknown
__onUsageReport()?
optional__onUsageReport: () =>void
Defined in: packages/agentos/src/api/generateText.ts:994
Internal
Internal — set by streamObject(). streamText() calls it each time it
counts usage a provider reported into the stream's usage: a provider
stream's final chunk, a prompt-shim round's response, the planning
call's response, and an error that carries its step's usage (a refused
turn); every fallback leg, which runs with the same options, calls it
too. usage counts what was never reported as zero, so this tells a
report of zero tokens from no report. generateText() does not read it.
Returns
void
__panelDeadline?
optional__panelDeadline:boolean
Defined in: packages/agentos/src/api/generateText.ts:973
Internal
Internal — set by a panel when its own deadline is the smallest bound it
passes as requestTimeout: a timeout error then does not count against
the provider's circuit breaker.
__rootStartedAt?
optional__rootStartedAt:number
Defined in: packages/agentos/src/api/generateText.ts:827
Internal
Internal — DO NOT set from application code. The outermost call's
Date.now() start, threaded into the provider-fallback recursion so
the winning hop's usage-observer durationMs reports true end-to-end
wall-clock (spanning failed primary attempts) rather than only its own
leg. Absent on a top-level call, where it defaults to that call's start.
__strictCredentials?
optional__strictCredentials:boolean
Defined in: packages/agentos/src/api/generateText.ts:965
Internal
Internal — set by an agency's seating on every seat and the chair. With it,
provider resolution ignores a setDefaultProvider() default that names no
provider, for the key and for the URL, and never reroutes Anthropic to
OpenRouter: a provider with no key of its own fails. Rides every failover hop.
_callerUser?
optional_callerUser:object
Defined in: packages/agentos/src/api/generateText.ts:1070
INTERNAL: the caller this call's tools run for, set by agent() from the
session's user, or from a one-shot call's own id. Each tool is told its
user and the subject its memory is keyed by in userContext, its session
in sessionData.sessionId, and the user id the caller named in
callerTurn.providerUserId. A direct call has none, and its tools are
told system. Not part of the public API.
providerUserId?
optionalproviderUserId:string
sessionId
sessionId:
string
subject
subject:
object
subject.id
id:
string
subject.kind
kind:
"user"|"session"
userId
userId:
string
_continuation?
optional_continuation:object
Defined in: packages/agentos/src/api/generateText.ts:1061
INTERNAL (failover): the call a fallback leg continues. The leg keeps
the call's tool run id, so tool execution contexts carry the same
session, numbers its steps from stepOffset in hooks, synthetic tool
call ids and tool contexts, and reports the call's original prompt to
hooks (a leg that continues after tool rounds receives it inside
messages instead). Not part of the public API.
helperToolRunId
helperToolRunId:
string
prompt?
optionalprompt:string
stepOffset
stepOffset:
number
_hardLimitsText?
optional_hardLimitsText:string
Defined in: packages/agentos/src/api/generateText.ts:1044
Internal
The exact text of the hard-limits block a string system ends with, set by agent() beside it: a call
that sends schema instructions sends them before that block, which stays the last system text.
_responseFormat?
optional_responseFormat:Record<string,unknown> | {type:string; }
Defined in: packages/agentos/src/api/generateText.ts:1012
Internal
Used by generateObject and AgentSession.send (with responseSchema) to forward a provider-specific response_format payload to the provider. Not part of the public API.
Shape varies by provider: OpenAI accepts json_object or
json_schema, Anthropic uses an internal _agentosUseToolForStructuredOutput
marker whose route AnthropicProvider sends as the JSON output format
(output_config.format, every model that has it, when the schema fits
its limits), as a non-strict forced tool call (a model without the format,
and a schema it cannot carry on a model that accepts a forced choice) or
as a schema block in the system prompt (such a schema on a model that
refuses a forced choice, or a forced-tool request that turns thinking on;
the format itself rides with thinking), Gemini uses a
_gemini.responseSchema extra.
The provider implementations consume whatever shape is here.
_responseFormatBuilder()?
optional_responseFormatBuilder: (providerId,modelId) =>Record<string,unknown> |undefined
Defined in: packages/agentos/src/api/generateText.ts:1027
Internal
Rebuilds the provider-native structured-output payload for a
FALLBACK leg's provider, and for the provider and model a call resolves
to when a router moved it off the call's own provider and model (the
pair _responseFormat is built for) or the resolver sends it to another
provider (an Anthropic call with no Anthropic key or base URL goes to
OpenRouter). When absent, legs and a routed call
receive _responseFormat verbatim (legacy behavior — provider-side
guards then drop foreign shapes, so the leg runs with zero provider
enforcement). generateObject and AgentSession.send supply this;
hand-rolled generateText callers are unaffected. modelId is '' when
the fallback entry omits model (the provider's default text model is
resolved later).
Parameters
providerId
string
modelId
string
Returns
Record<string, unknown> | undefined
_schemaInstruction?
optional_schemaInstruction:string
Defined in: packages/agentos/src/api/generateText.ts:1039
Internal
Schema instructions (buildSchemaInstructionText) that a call
whose _responseFormat carries no schema sends as a system message after
its system prompt: no payload for the provider or model, or a JSON mode
without one. Each fallback leg decides for its own payload. AgentSession.send
supplies this for a structured send; generateObject puts the schema in its
own system prompt and leaves it unset.
_transcriptIncludeTrailingCallerMessages?
optional_transcriptIncludeTrailingCallerMessages:number
Defined in: packages/agentos/src/api/generateText.ts:1052
INTERNAL (sessions): how many TRAILING entries of messages belong to
THIS call's transcript delta rather than prior history. Sessions that
carry a non-string user turn inside messages set 1 so the delta
includes it; prompt-based calls leave it unset (the prompt push is
captured positionally). Not part of the public API.
abortSignal?
optionalabortSignal:AbortSignal
Defined in: packages/agentos/src/api/generateText.ts:531
Ends the call when it aborts: the provider request in flight is cancelled, a provider's wait between retries
(a 429's Retry-After or a backoff) ends at once, no further step, retry or fallback hop starts, and the call
rejects with the signal's reason. An abort never walks the fallback chain. The signal
reaches the provider as ModelCompletionOptions.abortSignal; a request whose provider does not read it runs to
its end, and the call then rejects with the signal's reason.
accountIdOf?
optionalaccountIdOf:LlmUsageAccountResolver
Defined in: packages/agentos/src/api/generateText.ts:817
Names the account of a call whose GenerateTextOptions.budget names none, for the global LLM usage observer
(LlmUsageEvent.accountId). Asked for each usage event that is about to reach an observer, with the event's
provider, model, source and surface. A budget that names an account wins, and this is not asked.
apiKey?
optionalapiKey:string
Defined in: packages/agentos/src/api/generateText.ts:714
Override the API key instead of reading from environment variables.
baseUrl?
optionalbaseUrl:string
Defined in: packages/agentos/src/api/generateText.ts:716
Override the provider base URL (useful for local proxies or Ollama).
budget?
optionalbudget:SpendBudget|SpendBudgetOptions
Defined in: packages/agentos/src/api/generateText.ts:914
A spend budget for this call and, when the same SpendBudget instance is passed to several calls, for all of them: each provider call is checked against what is left before it is made and recorded after it, a failed request's billed usage included. A call the budget refuses is not tried on a fallback provider.
cache?
optionalcache:false| {tail?:boolean;ttl?:"5m"|"1h"; }
Defined in: packages/agentos/src/api/generateText.ts:654
Per-call prompt-cache control, forwarded to cache-capable providers
(Anthropic directly and on anthropic/* slugs through OpenRouter;
false also suppresses OpenAI's session-derived prompt_cache_key).
false— this request emits NOcache_controlat all: the provider's automatic markers (request-level marker, thinking-mode block markers, the moving message-tail) are suppressed AND any caller-placed system/message markers (e.g. SystemContentBlock.cacheBreakpoint) are stripped before the wire. Set this on TRUE one-shots — a single never-repeated call pays the cache-write premium (1.25x/2x input) on bytes nothing will ever read back.{ ttl: '1h' }— the automatic markers (including the moving message-tail pinned for multi-turn history) carry a 1-hour TTL instead of the 5-minute default. Set this on slow loops: codegen orchestrator/tool steps gap 2-14 minutes and human-paced conversation turns regularly exceed 5 minutes, so the default-TTL entry expires between steps and every turn re-writes. Caller-placed markers keep their own TTLs (SystemContentBlock.cacheTtl), except that shorter system markers are raised to 1 hour when a 1-hour tail follows them (Anthropic rejects a longer TTL after a shorter one).{ tail: false }— the provider places no breakpoint on the messages (no moving tail, no request-level marker), and the markers the caller set (SystemContentBlock.cacheBreakpoint) go out exactly as set. With no caller marker anywhere, the end of the first system message is marked instead (carryingttlwhen given). Set this on calls that re-send a long stable prefix and never the same tail twice (judges, classifiers): the prefix is still read back from the cache, and the unique tail is not written at the 1.25x/2x premium.cache: falsewould drop the prefix marker as well.- omitted /
{ ttl: '5m' }— default 5-minute auto markers.
cacheDiagnostics?
optionalcacheDiagnostics:boolean| {previousMessageId?:string|null; }
Defined in: packages/agentos/src/api/generateText.ts:684
Enable Anthropic prompt-cache diagnostics (beta cache-diagnosis-2026-04-07)
across the agentic loop. The loop auto-threads each step's response id into
the next step's diagnostics.previous_message_id, so every step after the
first carries a comparison verdict: cacheMissReason: null = prefix stable,
a populated reason (system_changed / tools_changed / messages_changed
/ ...) = where the cached prefix diverged. Per-step verdicts surface on the
GenerationHookResult.cacheDiagnostics hook field; the last step's
verdict lands on GenerateTextResult.cacheDiagnostics. Anthropic-only
(other providers ignore the option) and best-effort — diagnostics never
block or fail a request.
The object form seeds the FIRST step's previous_message_id so a caller
can thread across REQUESTS, not just across the steps of one call: pass
the prior turn's GenerateTextResult.providerMessageId and the
first step's verdict names any divergence from that turn's prompt.
true keeps the in-call-only behavior (first step compares nothing).
chainOfThought?
optionalchainOfThought:string|boolean
Defined in: packages/agentos/src/api/generateText.ts:728
Chain-of-thought instruction prepended to the system prompt when tools are available. Encourages the model to reason explicitly before choosing an action.
false(default): no CoT injection.true: inject the default CoT instruction.string: inject a custom CoT instruction.
customModelParams?
optionalcustomModelParams:Record<string,unknown>
Defined in: packages/agentos/src/api/generateText.ts:712
Provider-specific TOP-LEVEL request-payload parameters, forwarded
verbatim into ModelCompletionOptions.customModelParams. Provider
implementations spread these onto the outgoing request body (OpenRouter /
OpenAI / Anthropic / Ollama all honor it), so this is the escape hatch
for params the typed options don't model — e.g. OpenRouter
provider-routing preferences:
customModelParams: { provider: { sort: 'throughput' } }
Keys collide last-wins with the typed fields at the provider layer, so
only pass params the target provider understands. The Anthropic provider
reconciles three keys with the model: with thinking: false on a model
that turns thinking off only at effort high or below (Opus 5, Sonnet
5.5, Haiku 5.5), an output_config.effort of xhigh or max passed here
is sent as high; a temperature or top_p passed here for a model that
rejects them is dropped (and top_k on Claude Sonnet 5.5 and Claude
Haiku 5.5); and a model
passed here is the one the request is shaped for.
With planning on, the planning call takes OpenRouter's routing controls
(provider, models, route, transforms) and plugins from this
record, so the preferences that say where the caller's messages may go
hold for it too. Every other key goes to the turn's requests alone.
effort?
optionaleffort:string
Defined in: packages/agentos/src/api/generateText.ts:581
Reasoning depth / token-spend control forwarded to effort-capable models
(Opus 4.5+, Sonnet 4.6, Fable/Mythos 5) as output_config.effort
(low|medium|high|xhigh|max). Independent of thinking and tool_choice; the
provider drops it on unsupported models or invalid values.
fallbackProviders?
optionalfallbackProviders:FallbackProviderEntry[]
Defined in: packages/agentos/src/api/generateText.ts:788
Ordered list of fallback providers to try when the primary provider fails with a retryable error (HTTP 402/429/5xx, network errors, auth failures).
Default behavior (omit / undefined): auto-build the canonical
fallback chain for the primary provider via buildFallbackChain,
filtered to providers that have API keys present in the environment.
No import needed: fallback is on by default.
Strict mode ([]): explicitly opt out of fallback. The primary
provider's error is re-thrown after exhausting any provider-internal
retries. Use this when billing isolation, capability auditing, or
provider-pinned testing requires a single-provider guarantee.
Custom chain (array of entries): specify exactly which providers (and optional model overrides) to try, in order. Each entry's model defaults to the provider's text-generation default from PROVIDER_DEFAULTS when omitted. Providers are tried left-to-right; the first successful response wins.
Examples
const result = await generateText({
provider: 'anthropic',
prompt: 'Hello',
});
// On retryable Anthropic failure, walks anthropic -> openai -> gemini -> ...
const result = await generateText({
provider: 'anthropic',
prompt: 'Hello',
fallbackProviders: [],
});
const result = await generateText({
provider: 'anthropic',
prompt: 'Hello',
fallbackProviders: [
{ provider: 'openai', model: 'gpt-4o-mini' },
{ provider: 'openrouter' },
],
});
frequencyPenalty?
optionalfrequencyPenalty:number
Defined in: packages/agentos/src/api/generateText.ts:556
Frequency penalty forwarded to the provider (OpenAI / OpenRouter range -2..2). Reduces verbatim token repetition. Anthropic has no equivalent and the provider drops it, so it's a no-op on Claude models.
guards?
optionalguards:TextGuardrailOptions
Defined in: packages/agentos/src/api/generateText.ts:932
Guards enforced on this call: the call's own user turn before the first provider request, every tool call before
any hook, and the whole reply before it is returned. A guard runs closed unless its config says
failClosed: false. A stop rejects with GuardrailStopError; mode: 'dryRun' evaluates and reports and changes
nothing. Named guards because an agent's guardrails field is a list of ids that nothing enforces.
hookErrors?
optionalhookErrors:"throw"|"warn"
Defined in: packages/agentos/src/api/generateText.ts:920
What a generation or tool hook's error does: 'warn' (the default) logs it and goes on; 'throw' ends the call
with it, so a guard written as a hook can stop a call. A call a hook stops is not tried on a fallback provider and
does not count against the provider's health.
hostPolicy?
optionalhostPolicy:HostLLMPolicy
Defined in: packages/agentos/src/api/generateText.ts:872
Host-level routing hints that can be forwarded into the model router without requiring callers to construct raw router params directly.
maxAttempts?
optionalmaxAttempts:number
Defined in: packages/agentos/src/api/generateText.ts:517
The most attempts this call makes, a first and its retries together; the provider's configured count when left
out. Within one attempt, a key-scoped failure (a rejected, unpaid or throttled key) on a pool of several keys
re-sends the same request with the next usable key, at most once per key, and those sends are not counted.
The OpenAI, Anthropic, Gemini and OpenRouter providers read it, wait no backoff after the last attempt, and
refuse a count that is not a whole number of 1 or more with a RangeError before anything is sent, streamed
or not; the Anthropic and Gemini streams send one request and retry nothing but key hops. A request sent
again on another route after a 404 (a retired Gemini id on its alias, an OpenRouter request without its
schema) draws on the same count. Other providers keep their configured retries.
maxSteps?
optionalmaxSteps:number
Defined in: packages/agentos/src/api/generateText.ts:536
Maximum number of agentic steps (LLM calls) to execute before returning.
Each tool-call round trip counts as one step. Defaults to 1.
maxTokens?
optionalmaxTokens:number
Defined in: packages/agentos/src/api/generateText.ts:564
Hard cap on output tokens. Provider-dependent default applies when omitted.
messages?
optionalmessages:Message[]
Defined in: packages/agentos/src/api/generateText.ts:476
Full conversation history. Appended before prompt when both are supplied.
model?
optionalmodel:string
Defined in: packages/agentos/src/api/generateText.ts:470
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").
Either provider or model (or an API key env var for auto-detection) is required.
onAfterGeneration()?
optionalonAfterGeneration: (result) =>Promise<void|GenerationHookResult>
Defined in: packages/agentos/src/api/generateText.ts:908
Called after each LLM generation step. Can check output against guardrails, redact PII, or transform the response. Return a modified result to transform output, or void to pass through.
Parameters
result
Returns
Promise<void | GenerationHookResult>
onAttempt()?
optionalonAttempt: (outcome) =>void
Defined in: packages/agentos/src/api/generateText.ts:523
Called once per attempt, with the answer of the attempt's last send (a key hop's earlier answers are not reported), so a caller can settle the attempts it paid for. The OpenAI provider (and the providers that send through it) reports attempts; the others report nothing.
Parameters
outcome
Returns
void
onBeforeGeneration()?
optionalonBeforeGeneration: (context) =>Promise<void|GenerationHookContext>
Defined in: packages/agentos/src/api/generateText.ts:902
Called before each LLM generation step. Can inject memory context into messages, sanitize input via guardrails, or modify the prompt. Return a modified context to transform input, or void to pass through.
Parameters
context
Returns
Promise<void | GenerationHookContext>
onBeforeToolExecution()?
optionalonBeforeToolExecution: (info) =>Promise<ToolCallHookInfo|null>
Defined in: packages/agentos/src/api/generateText.ts:925
Called before each tool execution. Can modify arguments, apply
permission checks, or return null to skip the tool call entirely.
Parameters
info
Returns
Promise<ToolCallHookInfo | null>
onFallback()?
optionalonFallback: (error,fallbackProvider) =>void
Defined in: packages/agentos/src/api/generateText.ts:802
Callback invoked when a fallback provider is about to be tried after the primary (or a previous fallback) failed. Useful for logging or metrics.
Parameters
error
Error
The error that triggered the fallback.
fallbackProvider
string
The provider the next leg is sent to. An entry
whose model id carries another provider's prefix ({ provider: 'anthropic', model: 'openrouter:anthropic/claude-sonnet-4.5' }) is sent
to the provider the prefix names, so this is 'openrouter'. So is an
Anthropic entry with no Anthropic key or base URL (its own, the global
default's or ANTHROPIC_BASE_URL) while OPENROUTER_API_KEY is set:
the credential layer sends it to OpenRouter.
Returns
void
planning?
optionalplanning:boolean|PlanningConfig
Defined in: packages/agentos/src/api/generateText.ts:737
Enable plan-then-execute mode. When true (or a PlanningConfig),
an upfront LLM call decomposes the task into numbered steps before the
tool-calling loop begins. The plan is injected into the system prompt
so the model executes with full awareness of the strategy.
Set to false or omit to skip planning entirely (the default).
policyTier?
optionalpolicyTier:"safe"|"standard"|"mature"|"private-adult"
Defined in: packages/agentos/src/api/generateText.ts:896
Caller's intended content policy tier. On 'mature' or
'private-adult' with no explicit fallbackProviders, the auto-built
fallback chain is buildPolicyAwareFallbackChain: the tier's
ranked uncensored OpenRouter models, then the availability chain, so a
content-policy refusal from the primary (an OpenAI or Anthropic model)
re-routes to a model that can complete the request rather than
hard-failing.
Combined with the isContentPolicyRefusal branch in
isRetryableError, this also makes the fallback loop fire on
OpenAI's 400 + code: 'content_policy_violation', which the
network-only retryable matrix would otherwise treat as a hard error.
When omitted, the chain follows the tier the call resolves to
(resolvePolicyTier): routerParams.policyTier, then this field,
then hostPolicy (a host policy without a tier counts as standard),
then the router's default tier. safe and standard keep the
availability-only chain.
Mirrors the existing policyTier parameter on
GenerateImageOptions and EditImageOptions.
presencePenalty?
optionalpresencePenalty:number
Defined in: packages/agentos/src/api/generateText.ts:562
Presence penalty forwarded to the provider (OpenAI / OpenRouter range -2..2). Nudges the model toward new topics. Anthropic has no equivalent and the provider drops it, so it's a no-op on Claude models.
prompt?
optionalprompt:string
Defined in: packages/agentos/src/api/generateText.ts:472
Single user turn to append after any messages. Convenience alternative to building a messages array.
promptCacheKey?
optionalpromptCacheKey:string|false
Defined in: packages/agentos/src/api/generateText.ts:591
OpenAI prompt-cache shard key (spec batch-1 C2; other providers ignore
it). 'auto' derives a sha256-hashed key from sessionId
(omitted when no session id is set; raw ids never leave the process);
an explicit string is sent verbatim; false omits the field. Absent
defaults to 'auto' on the native OpenAI endpoint unless the call
carries cache: false; OpenAI-compatible gateways (custom baseURL)
keep the omit default.
promptCacheRetention?
optionalpromptCacheRetention:"in_memory"|"24h"|"30m"
Defined in: packages/agentos/src/api/generateText.ts:597
OpenAI prompt-cache retention request. Emitted only when the fail-closed
capability table allows the model/value combination; unsupported combos
are omitted with a debug log. See openai-cache-params.ts.
provider?
optionalprovider:string
Defined in: packages/agentos/src/api/generateText.ts:462
Provider name. When supplied without model, the default text model for
the provider is resolved automatically from the built-in defaults registry.
Example
`"openai"`, `"anthropic"`, `"ollama"`
requestTimeout?
optionalrequestTimeout:number
Defined in: packages/agentos/src/api/generateText.ts:506
Per-call request timeout in milliseconds, forwarded to the provider for
this call only. Large-output callers (e.g. structured-output generation
that emits long strings) can raise the abort window without slowing the
provider's default failover for chat or narration traffic. Native path
only; providers without a request timeout ignore it. streamText()
forwards it to the provider's stream: on Anthropic it bounds the stream's
connection (the request and its response headers), and the gap between
streamed events after that is the provider's streamIdleTimeoutMs.
router?
optionalrouter:IModelRouter
Defined in: packages/agentos/src/api/generateText.ts:862
Optional model router for intelligent provider/model selection.
When provided, the router's selectModel() is called before provider
resolution. The router result overrides model/provider.
If the router returns null, falls back to standard resolution.
routerParams?
optionalrouterParams:Partial<ModelRouteParams>
Defined in: packages/agentos/src/api/generateText.ts:867
Routing hints passed to the model router. Extracted automatically from system prompt and tool names when not provided.
serviceTier?
optionalserviceTier:"priority"|"default"|"auto"|"flex"
Defined in: packages/agentos/src/api/generateText.ts:603
OpenAI service tier (service_tier, verbatim). No default. 'flex'
bills at ~batch rates but can 429 under load; automatic tier fallback
is deliberately not implemented.
sessionId?
optionalsessionId:string
Defined in: packages/agentos/src/api/generateText.ts:665
Per-conversation affinity key, forwarded to providers that support
request affinity (OpenRouter sends it as session_id for provider
sticky routing — upstream prompt caches are host-scoped, so a
load-balanced conversation otherwise cold-misses the cache a prior
turn wrote on a different host). On the native OpenAI endpoint the
prompt_cache_key shard key derives from it automatically, so the
same id keeps cache routing warm there too. Pass a stable id per
conversation.
source?
optionalsource:string
Defined in: packages/agentos/src/api/generateText.ts:811
Optional source label forwarded to the global LLM usage observer registered via setGlobalLlmObserver. Hosts use this to tag the emitted telemetry row with a caller-defined meter key (e.g. 'narrator_turn', 'companion_reply', 'world_compile_job').
Has no effect when no observer is registered.
store?
optionalstore:boolean
Defined in: packages/agentos/src/api/generateText.ts:621
Sent to OpenAI as store on the request, on /v1/chat/completions and
/v1/responses alike. Left out, a chat completion sends no store key
and a Responses request sends store: false, as before. Other providers
ignore it, those built on the OpenAI provider (Groq, xAI, Together,
Mistral, LiteLLM, MiniMax) included, which leave it out of the request to
their own endpoint; customModelParams: { store } reaches such an
endpoint when it takes the field.
OpenAI keeps output unless a request says otherwise: "Responses are
stored by default. Chat completions are stored by default for new
accounts. To disable storage when using either API, set store: false."
(https://developers.openai.com/api/docs/guides/migrate-to-responses).
Every request the call makes carries it, on generateText() and
streamText() alike: each step of the tool loop, the planning request,
the prompt-tool loop's requests and a fallback leg.
system?
optionalsystem:string|SystemContentBlock[]
Defined in: packages/agentos/src/api/generateText.ts:474
System prompt injected as the first message. Accepts a plain string or structured blocks with cache breakpoints.
temperature?
optionaltemperature:number
Defined in: packages/agentos/src/api/generateText.ts:548
Sampling temperature forwarded to the provider (0-2 for most providers).
thinking?
optionalthinking:false| {budgetTokens:number; }
Defined in: packages/agentos/src/api/generateText.ts:574
Extended-thinking switch forwarded to Claude models. Any positive
budgetTokens turns adaptive thinking on (the number itself is not sent
and maxTokens passes through unchanged). 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.
toolChoice?
optionaltoolChoice:string|Record<string,unknown>
Defined in: packages/agentos/src/api/generateText.ts:495
Provider tool_choice passthrough. Forwarded verbatim to the provider so
callers can force a specific tool, force tool use, or set 'auto'. Provider
support varies; Anthropic + OpenAI honor it. Native path only (ignored on
the prompt-emulation shim).
toolMode?
optionaltoolMode:ToolMode
Defined in: packages/agentos/src/api/generateText.ts:546
Tool-calling strategy. 'auto' (default) uses native provider tool-calling,
and on a tool-unsupported provider error falls back to a prompt-based shim
(tool schemas rendered into the prompt, <tool_call> blocks parsed from the
model's text). 'native' forces native only. 'prompt' forces the shim.
The shim makes AgentOS tools work on models without native tool-use (e.g.
the uncensored OpenRouter catalog). Shim roundtrips are capped by maxSteps
(default 5 when unset on the shim path).
tools?
optionaltools:AdaptableToolInput
Defined in: packages/agentos/src/api/generateText.ts:488
Tools the model may invoke.
Accepted forms:
- named high-level tool maps
- external tool registries (
Record,Map, or iterable) - prompt-only
ToolDefinitionForLLM[]
Prompt-only definitions are visible to the model but return an explicit tool error if the model invokes them without an executor.
topP?
optionaltopP:number
Defined in: packages/agentos/src/api/generateText.ts:550
Nucleus sampling top-p forwarded to the provider.
usageLedger?
optionalusageLedger:AgentOSUsageLedgerOptions
Defined in: packages/agentos/src/api/generateText.ts:718
Optional durable usage ledger configuration for helper-level accounting.