Skip to main content

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?​

optional providerUserId: 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?​

optional prompt: 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?​

optional abortSignal: 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?​

optional accountIdOf: 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?​

optional apiKey: string

Defined in: packages/agentos/src/api/generateText.ts:714

Override the API key instead of reading from environment variables.


baseUrl?​

optional baseUrl: string

Defined in: packages/agentos/src/api/generateText.ts:716

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


budget?​

optional budget: 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?​

optional cache: 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 NO cache_control at 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 (carrying ttl when 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: false would drop the prefix marker as well.
  • omitted / { ttl: '5m' } — default 5-minute auto markers.

cacheDiagnostics?​

optional cacheDiagnostics: 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?​

optional chainOfThought: 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?​

optional customModelParams: 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?​

optional effort: 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?​

optional fallbackProviders: 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?​

optional frequencyPenalty: 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?​

optional guards: 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?​

optional hookErrors: "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?​

optional hostPolicy: 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?​

optional maxAttempts: 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?​

optional maxSteps: 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?​

optional maxTokens: number

Defined in: packages/agentos/src/api/generateText.ts:564

Hard cap on output tokens. Provider-dependent default applies when omitted.


messages?​

optional messages: Message[]

Defined in: packages/agentos/src/api/generateText.ts:476

Full conversation history. Appended before prompt when both are supplied.


model?​

optional model: string

Defined in: packages/agentos/src/api/generateText.ts:470

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

Either provider or model (or an API key env var for auto-detection) is required.


onAfterGeneration()?​

optional onAfterGeneration: (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​

GenerationHookResult

Returns​

Promise<void | GenerationHookResult>


onAttempt()?​

optional onAttempt: (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​

AttemptOutcome

Returns​

void


onBeforeGeneration()?​

optional onBeforeGeneration: (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​

GenerationHookContext

Returns​

Promise<void | GenerationHookContext>


onBeforeToolExecution()?​

optional onBeforeToolExecution: (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​

ToolCallHookInfo

Returns​

Promise<ToolCallHookInfo | null>


onFallback()?​

optional onFallback: (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?​

optional planning: 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?​

optional policyTier: "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?​

optional presencePenalty: 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?​

optional prompt: 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?​

optional promptCacheKey: 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?​

optional promptCacheRetention: "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?​

optional provider: 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?​

optional requestTimeout: 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?​

optional router: 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?​

optional routerParams: 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?​

optional serviceTier: "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?​

optional sessionId: 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?​

optional source: 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?​

optional store: 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?​

optional system: 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?​

optional temperature: number

Defined in: packages/agentos/src/api/generateText.ts:548

Sampling temperature forwarded to the provider (0-2 for most providers).


thinking?​

optional thinking: 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?​

optional toolChoice: 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?​

optional toolMode: 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?​

optional tools: 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?​

optional topP: number

Defined in: packages/agentos/src/api/generateText.ts:550

Nucleus sampling top-p forwarded to the provider.


usageLedger?​

optional usageLedger: AgentOSUsageLedgerOptions

Defined in: packages/agentos/src/api/generateText.ts:718

Optional durable usage ledger configuration for helper-level accounting.