Multi-provider routing: customProvider, gateway, and fallbacks

TL;DR: The SDK gives you three routing layers; use the cheapest one that fits. You will outgrow a single hardcoded model. Layer 1: AI Gateway string ids. model: 'openai/gpt-5' or 'anthropic/claude-opus-4-6'.

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).

When to use

You hit exactly this: Multi-provider routing: customProvider, gateway, and fallbacks in Multi-provider routing.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Multi-provider routing (versions mentioned here: v7).

Edge cases

• Best when you need provider options (custom baseURL, organization, providerOptions).
• For cost control, route by task: cheap model for classification and drafts, strong model for final answers.

Verified against the live AI SDK docs 2026-09-26. The introduction shows gateway string ids; the providers-and-models page covers provider packages; the v7 migration codemod table documents experimental_customProvider to customProvider. The message-metadata guide shows attaching model info per message.