Skip to main content

Function: buildFallbackChain()

buildFallbackChain(excludeProvider?, call?): FallbackProviderEntry[]

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

Auto-discovers available LLM providers from well-known environment variables and builds an ordered fallback chain.

Each entry in the returned array contains a provider identifier and an optional model suitable for fallback use. Providers are ordered by general availability; the OpenAI legs pin a Sol model, the platform's quality floor for failover traffic. A primary-provider outage must not silently downgrade user-facing output to a mini-tier model:

  1. OpenAI (gpt-6.2-sol)
  2. Anthropic (claude-sonnet-5-5 at effort low, with 1024 tokens of output headroom for thinking; claude-sonnet-5 for a call whose toolChoice forces a tool, since Sonnet 5.5 refuses a forced choice and would be sent auto)
  3. OpenRouter (openai/gpt-5.6-sol)
  4. Gemini (gemini-3.1-pro-preview)

Parameters​

excludeProvider?​

string

Provider to omit from the chain (typically the primary provider that already failed).

call?​

The call the chain rescues: its toolChoice picks the Anthropic leg's model, so a required tool stays required on that hop. Every leg pins cache: false: failover hops are sporadic one-shots, so prompt-cache writes on a rescue leg almost never earn their reads back (see FallbackProviderEntry.cache). Callers wanting a cached hop supply their own chain with a per-entry ttl.

toolChoice?​

string | Record<string, unknown>

Returns​

FallbackProviderEntry[]

An array of { provider, model?, cache } entries ready for use as GenerateTextOptions.fallbackProviders.

Example​

// Primary is anthropic: build fallback chain from remaining providers
const chain = buildFallbackChain('anthropic');
// => [{ provider: 'openai', model: 'gpt-6.2-sol' }, { provider: 'openrouter', model: 'openai/gpt-5.6-sol' }, ...]