AI Gateway Introduces Virtual Models: Switch Models Without Changing Code

Vercel AI Gateway has recently introduced the Virtual Models feature. It abstracts "model string + configuration" into a reusable ID, moving model switching from the code layer to the gateway layer. For teams building Agent applications, this is an engineering practice worth paying attention to.

What Problem Do Virtual Models Solve

AI Gateway itself already makes model calls simple: pass in any model ID, and the gateway routes to a healthy provider, automatically falling back on failure. But that model string is still written in code, so every model change typically means a redeployment.

Virtual models change this. You create an ID for a task, such as vmc/coding-agent, then configure which model it uses behind the scenes and with what parameters in AI Gateway:

vercel ai-gateway virtual-models create coding-agent \
  --model anthropic/claude-opus-5.5 \
  --config '{"speed":"fast","zeroDataRetention":true}'

Then simply use this ID as the model string in your code:

import { streamText } from 'ai';

const result = streamText({
  model: 'vmc/coding-agent',
  prompt: 'Remove the deprecated API calls from this module.',
});

When you need to switch models, edit the virtual model to point to a new model. All applications and Agents calling that ID will automatically adopt the new configuration within minutes, with no code changes or redeployment required.

AI Gateway is a model routing middleware layer provided by Vercel, sitting between application code and model providers (Anthropic, OpenAI, Google, etc.). Applications only need to pass a model identifier string to the gateway; the gateway handles selecting healthy provider endpoints, automatically falling back to backup models on timeouts or errors, and uniformly managing billing, observability, and data retention policies. Because its interface is compatible with AI SDK as well as OpenAI- and Anthropic-compatible APIs, teams can switch underlying providers without rewriting calling code. Virtual models are built on top of this routing capability: the gateway could already resolve the "model string → real model" mapping, and virtual models simply turn that mapping into a configuration object that can be edited in the console and managed with versioning.

One Task, One Model

The original article presents a compelling scenario: customer support ticket triage, an Agent task that may run hundreds of times per hour and is cost-sensitive; versus legal contract review, which may run only a few times a day but requires strong reasoning capability.

Virtual models give each task its own dedicated model configuration that can evolve over time. You may not have noticed, but settings like fallback, Zero Data Retention, and tags switch along with the virtual model; however, provider-specific options take effect per provider — when a virtual model switches from an Anthropic model to an OpenAI model, Anthropic-specific settings no longer apply. The original article explicitly reminds readers to review provider options every time they switch providers.

For virtual models carrying production traffic, the original article recommends first creating a candidate virtual model (such as vmc/coding-agent-candidate) pointing to the new model, running evaluations, and then switching; if quality degrades, simply point the original virtual model back to the old model.

Zero Data Retention means the provider commits not to persistently store request and response content, discarding it once processing is complete, typically used in scenarios involving sensitive content such as contracts, medical records, or internal code. disallowPromptTraining prohibits providers from using request data for model training. Both are switches at the data governance level, and in AI Gateway they can be written into requests or fixed in virtual model configuration. In contrast, fallback is a failover mechanism: when the primary model returns an error, is rate-limited, or times out, the gateway automatically switches to the next model in the list. tags are labels attached to requests, used to aggregate spending and call volume to specific tasks or teams, forming the basis for cost allocation and billing analysis. The original article emphasizes that these settings switch along with the virtual model because they are cross-cutting configurations managed uniformly by the gateway, rather than provider-specific parameters.

Centralized Governance: Who Can Change It and What Changes Mean

A virtual model is also a governance unit. Team members can all call the virtual model, but role permissions control who can modify it. Platform and security teams can centrally govern and test models and settings while giving teams fast access to models once released.

A key design: settings on the virtual model take precedence over same-named settings in requests. Callers cannot override the provider order, fallback, or service tier you set. For example, once the fallback model for vmc/storefront-assistant is centrally configured, all applications using that ID will adopt the same failover configuration, even if a different fallback is specified in the request.

Security policies are also enforced: if a virtual model requires Zero Data Retention or disallows providers that train on request data, these configurations remain in effect even if a request explicitly sets zeroDataRetention or disallowPromptTraining to false. Tags on the virtual model also replace tags carried in requests, ensuring spending is accurately attributed to the task. The Virtual Models page displays request counts, spending, and success rates for each task.

provider options refer to request parameters specific to each model provider, such as Anthropic's extended thinking budget, OpenAI's reasoning effort, or specific cache control fields. They are passed in through a separate providerOptions field in AI SDK, and their semantics differ from gateway-level general configurations like fallback and tags, and they are not portable across providers. Therefore, when a virtual model switches from an Anthropic model to an OpenAI model, provider options originally written for Anthropic will be ignored or cause errors, and each must be reviewed and replaced with equivalent parameters supported by the new provider. This is also one of the engineering reasons the original article recommends creating a candidate virtual model for production traffic and running evaluations before switching: provider option incompatibilities often do not surface during type checking and only manifest in real calls.

Model Update Pace Forces Architectural Adjustments

The original article provides an intuitive data point: in the past 90 days, 125 new models from more than 10 labs went live on AI Gateway, averaging about 10 per week. At such an iteration pace, model selection itself is becoming an operational task that requires continuous adjustment.

Virtual models move the execution of this work from the code repository to gateway configuration, reducing the friction of "switching models = shipping a release." It is also compatible with all model types on AI Gateway, including image, video, speech, embedding, and real-time models, and supports AI SDK as well as OpenAI- and Anthropic-compatible APIs.

For teams using coding Agents such as Claude Code and Codex, they can connect via vercel ai-gateway setup, then select the virtual model in each harness's model selector or configuration.

Some Practical Recommendations

Virtual model naming should reflect task semantics rather than model names — for example, naming by purpose like coding-agent or support-triage, avoiding IDs like claude-opus-agent that are tied to a specific model.

Running evaluations before switching models and preserving a rollback path are key to incorporating model updates into regular engineering processes. The constraints brought by centralized governance also mean security teams can apply unified policies across all callers, which is especially valuable when multiple teams share a gateway.

One-line Summary

Vercel AI Gateway introduces virtual models, moving model selection and configuration from code to centralized governance at the gateway layer.

Paragraph Summary

Vercel AI Gateway introduces the Virtual Models feature, abstracting "model string + configuration" into a reusable ID, turning model switching from a code change and release into editing configuration on the gateway side, with all callers automatically taking effect within minutes. The article notes this design is especially valuable for Agent teams: each task can be bound to a dedicated model configuration, and settings like fallback, Zero Data Retention, and tags persist across virtual model switches, but provider-specific options need to be reviewed when changing providers. A virtual model is also a governance unit, with its settings taking precedence over same-named configurations in requests, so callers cannot override failover policies and data retention requirements set by platform and security teams. Facing an iteration pace of 125 new models going live in 90 days, virtual models turn model selection into centrally operable work, and the article recommends running evaluations through candidate virtual models and preserving a rollback path.