Configure providers and failover

Select providers in app configuration

The default provider is OpenAI. The current adapter supports OpenAI-compatible connections, with registered settings for OpenAI, OpenRouter, Groq, xAI and DeepSeek. Set the corresponding server environment variables for the providers you select.

Use ai.provider for an ordered failover chain. A record pins a model per provider; an array uses their configured defaults. Text and structured generation require a Responses-compatible provider. Agent runs can also use supported Chat Completions providers.

ai: {
	...config.ai,
	provider: {
		openai: process.env.OPENAI_MODEL!,
		openrouter: process.env.OPENROUTER_MODEL!,
	},
},
// Set OPENAI_API_KEY and OPENROUTER_API_KEY on the server.

Understand when failover runs

Text calls move to the next configured provider for transient network failures, timeouts, overload, rate limits, quota exhaustion and server errors. Authentication and invalid-request errors remain terminal. Unconfigured or disabled providers are skipped.

Agents fail over only before the SDK has emitted an event for the attempt. Once streaming has started, the framework does not replay the run on another provider because a tool may already have changed your app. Persisted attempts show which provider failed and which one completed the work.

Share provider capacity across workers

AIRateLimiter stores rate-limit buckets and reservations in your database. It learns capacity from provider headers and defers calls when capacity is unavailable. Register its two models in your migrations; the generated app includes them.

Queue retries and quota deferrals use the framework queue contracts. Run workers for the queue you dispatch to, and monitor failed jobs alongside AI requests. The default per-request timeout is 60 seconds and SDK automatic retries are disabled; failover and queue policy remain explicit.

• Queue workers and retries

Keep application code provider independent

Your app calls Ai and extends Agent. Provider configuration, transport and cost handling live below those APIs. An OpenAI-compatible endpoint can use the existing connection options; a protocol that differs from these adapters needs a framework driver implementation.

Images and embeddings currently use the OpenAI adapter without cross-provider failover. Studio and Cloud are separate product work; these APIs do not require a hosted db3 account.