Skip to main content

Interface: FallbackProviderEntry

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

A fallback provider entry specifying an alternative provider (and optionally model) to try when the primary provider fails with a retryable error.

See​

GenerateTextOptions.fallbackProviders

Properties​

apiKey?​

optional apiKey: string

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

Key for this hop. Written by an agency's seating; omitted, the hop reads the provider's environment variable.


baseUrl?​

optional baseUrl: string

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

Base URL for this hop, written by seating; omitted, the provider's URL variable.


cache?​

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

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

Per-hop prompt-cache disposition applied ONLY when THIS entry serves the call (same override shape as FallbackProviderEntry.effort). false sends zero cache_control on the hop; { ttl } re-times the hop's markers. Omitted -> the hop inherits the call-level GenerateTextOptions.cache.

The canonical chains (buildFallbackChain / buildPolicyAwareFallbackChain) pin cache: false on every leg: rescue traffic is sporadic and one-shot-shaped, so cache writes on a fallback hop rarely earn their reads back (the claude-sonnet-5 leg measured 0.45x write amortization in wilds prod, 2026-07-13..20 — the writes cost ~2x what the reads saved). A caller-supplied entry keeps full control: omit to inherit, or set a ttl to cache a hop deliberately.


effort?​

optional effort: string

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

Per-hop reasoning depth applied ONLY when THIS entry serves the call, forwarded as output_config.effort (Anthropic) / reasoning_effort (OpenAI). Lets a chain run a fallback at a different depth than the primary — e.g. a gpt-5.6-sol frontier fallback at 'max' while the primary keeps its own (or no) effort, so arming the chain is dormant for the primary call. Omitted -> the hop inherits the call-level effort.


group?​

optional group: "uncensored"

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

The entry's group in a policy chain. 'uncensored' marks the catalog ladder legs; a walk runs the first two as standing legs and the rest only to replace a standing leg that failed on availability or did not fit the request.


maxTokensHeadroom?​

optional maxTokensHeadroom: number

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

Extra output tokens granted ONLY when THIS entry serves the call: the hop runs with maxTokens = <the original call's maxTokens> + headroom. For models whose hidden reasoning shares the output cap. Every current Gemini 3.x model thinks, and its thinking tokens count against maxOutputTokens; a rescue hop inherits a budget sized for the primary, and without room for the thinking the visible reply comes back cut short or empty (measured 2026-09-30: gemini-3.1-pro-preview at 400 tokens spent 382 thinking and returned 60 characters).

Ignored when the call set no maxTokens. Never compounds: every hop is granted its own headroom over the ORIGINAL budget, and an entry without headroom runs at the original.


model?​

optional model: string

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

Model identifier override. When omitted, the provider's default text model is used.


origin?​

optional origin: "policy-default"

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

Who wrote this entry. 'policy-default' marks an entry the policy chain built for a mature or private-adult tier; a walk may pass over only such entries (one that names the failed first model, and Claude legs after a refusal). Absent on caller-written entries, which keep their order and contents.


provider​

provider: string

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

Provider identifier (e.g. "openai", "anthropic", "openrouter").


vendor?​

optional vendor: string

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

Who trained this hop's model, when its id and endpoint cannot say; an agency seat's record reads it when this hop answered. Seating writes a pool entry's vendor here; a fixed seat's own chain may declare it.