Multi-provider routing: customProvider, gateway, and fallbacks

You will outgrow a single hardcoded model. The SDK gives you three routing layers; use the cheapest one that fits.

Layer 1: AI Gateway string ids. model: 'openai/gpt-5' or 'anthropic/claude-opus-4-6'. One key (AIGATEWAYAPI_KEY), hundreds of models, zero factories. Best for trying models and simple switching.

Layer 2: provider factories. import { openai } from '@ai-sdk/openai'; model: openai('gpt-5'). Best when you need provider options (custom baseURL, organization, providerOptions).

Layer 3: customProvider for named routing with fallbacks.

import { customProvider } from 'ai'; import { openai } from '@ai-sdk/openai'; import { anthropic } from '@ai-sdk/anthropic';

const registry = customProvider({ languageModels: { 'fast': openai('gpt-5-mini'), 'smart': anthropic('claude-opus-4-6'), }, fallbackProvider: openai, // used when a name does not resolve });

const result = await generateText({ model: registry.languageModel('fast'), prompt: 'Hi' });

Rules:

1. Keep routing names stable ('fast', 'smart', 'cheap') and change the backing models in one place. Prompts and evals reference names, not model ids.
2. Fallbacks need compatible capabilities. Falling back from a tool-using model to one without tool support breaks the turn. Gate fallbacks by feature, not just availability.
3. The v7 codemod renamed experimental_customProvider to customProvider. Old snippets with the prefix still work only if you never upgraded.
4. Log which backing model served each request (messageMetadata or telemetry functionId plus model id). Debugging "the model got worse" requires knowing which model answered.
5. For cost control, route by task: cheap model for classification and drafts, strong model for final answers. The registry makes this a config change.
6. Validate model ids at startup in production. A retired id should fail deploy-time checks, not the first user request (NoSuchModelError at 2am).