Function: buildFallbackChain()

buildFallbackChain(excludeProvider?): FallbackProviderEntry[]

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

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 gpt-5.5 — 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-5.5)
2. Anthropic (claude-sonnet-5)
3. OpenRouter (openai/gpt-5.5)
4. Gemini (gemini-2.5-flash)

Parameters

excludeProvider?

string

Provider to omit from the chain (typically the primary provider that already failed). 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.

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-5.5' }, { provider: 'openrouter', model: 'openai/gpt-5.5' }, ...]