Keep your AI agent running when its primary model fails

A customer finishes a form, and the model behind your support assistant returns an error. A backup model can rescue the request, but it can also change the answer's quality, format, latency, and cost. Vercel AI Gateway lets you specify fallback models in order. The product decision is which differences your users can tolerate.

Vercel's official Model Fallbacks documentation, last updated October 2, 2026, describes providerOptions.gateway.models as the ordered backup list. The gateway tries the primary model first; if its providers fail, it moves to the next model. This guide was reviewed October 25. SoyJB has not simulated a real production outage in an account.

Start with a support-ticket contract

Imagine an agent that drafts replies to English-language support tickets. Its output needs a short summary, suggested response, and a flag for human escalation. If a fallback takes over, those fields still need to exist. Define the contract first: never send automatically when the escalation flag is missing, show a pending state if every model fails, and record which model served the answer.

Do not choose a backup on brand alone. Check that it accepts the modality your workflow uses—plain text, tools, images, or files—that your account has access, and that its worst-case cost fits your budget. A more expensive backup may make sense for urgent tickets but not for thousands of low-priority summaries.

Configure an ordered backup list

Vercel documents this pattern for AI SDK 7. Replace the model IDs with ones available in your catalog and test with your own AI_GATEWAY_API_KEY. This is a documentation-based example, not a benchmark run by SoyJB:

import { generateText } from 'ai';

const result = await generateText({
  model: 'anthropic/claude-fable-5',
  prompt: 'Summarize this support ticket in two sentences: login email never arrived.',
  providerOptions: {
    gateway: {
      models: [
        'anthropic/claude-opus-5',
        'google/gemini-3.1-pro-preview',
      ],
    },
  },
});

console.log(result.text);

The models array is an ordered fallback chain, not a vote or a quality comparison. Vercel says the gateway tries providers for the primary model, then advances when they all fail. The first successful model/provider combination returns the answer. If you also use order, that field sets provider preference for each model; it is different from the order of models.

Test the risk that matters

Create three sample tickets: a routine request, one that must be escalated, and one without enough information. Run each sample explicitly on the primary and on every candidate backup before relying on failover. Check that all required fields remain present, the requested language stays consistent, and the assistant does not invent a resolution. A backup that violates this contract should be removed even if it is fast.

Next, test a controlled failure in development. Passing a nonexistent model ID alone is not proof of resilience: it may represent bad configuration rather than a provider outage. Log the error code, chosen model, response time, and returned content. Vercel documents modelAttempts in provider metadata and gateway logs so you can see the attempted chain. That gives you evidence of backup usage instead of assuming it never activated.

Set a product boundary

Fallback may increase latency while earlier attempts fail. It can also change writing style, accuracy, context limits, and price. For an agent that takes action, add human confirmation before sending messages, charging customers, or editing records. If every model fails, return an explicit pending status and keep the job for an idempotent retry. Do not replay an operation without an idempotency key.

The practical choice: use fallback where a delayed, reviewable answer is better than an immediate error. Use one model or a retry queue when format, data handling, or cost cannot be made equivalent across providers. Review logs after the first week and tune the chain using actual failures rather than promising perfect uptime.

Source: Vercel AI Gateway Model Fallbacks, reviewed October 25, 2026. Confirm model IDs, availability, and prices in your account before deployment.