Vercel AI SDK, Multiple Providers: One App Contract, Multiple PathsVercel AI SDK + Multiple Providers
Use multiple providers with the Vercel AI SDK by centralizing configuration and contract-testing capabilities, streams, tools, errors, and usage.
TL;DR
Gateway simplifies access; dedicated adapters expose native controls.
Keep keys, base URLs, aliases and ownership outside UI code.
Tools, object output, streaming and provider options vary.
Assign routing and retry policy to one layer.
Vercel AI SDK with multiple providers: gateway or direct access
The AI SDK supports three useful integration shapes. A plain creator/model string uses Vercel AI Gateway as the default provider; dedicated provider packages connect directly and expose provider-specific options; and createProviderRegistry() gives an application a central registry with identifiers in the providerId:modelId form. Custom providers can add aliases or preconfigured model settings on top of those adapters.
Choose by control boundary rather than code brevity. Gateway access is useful when one credential, centralized usage and provider routing are desired. Direct packages fit workloads that depend on native parameters or separate commercial relationships. A registry is valuable when both approaches must coexist without scattering imports and model strings across request handlers.
Whichever shape you choose, pin the registry and routing configuration, keep credentials on the server and preserve the resolved provider, model and adapter version in telemetry. A friendly alias must not hide a change in data path, policy or feature support.
Provider setup options
| Option | Best fit | Verify before choosing |
|---|---|---|
| AI Gateway | One integration and shared routing across supported models. | Verify gateway options, data path, capabilities and native evidence. |
| Dedicated provider | Native package and provider-specific controls. | More dependencies, keys and operational paths to manage. |
| OpenAI-compatible | Reuse a compatible client shape. | Test tools, object output, streams, errors and usage semantics. |
| Custom provider | Implement a controlled application abstraction. | You own conformance, maintenance and failure behavior. |
Provider registry checklist
Load server-side keys by environment and provider scope.
Map workload names to versioned model and capability sets.
Handle text, tool, finish, error and usage events consistently.
Record provider, model, route, native ID and usage.
Test every provider path
A provider switch is safe only when the application-level contract still holds. Build fixtures around the AI SDK functions your product actually uses—text generation, streaming, structured output, embeddings and tools—and assert both normalized events and any provider-specific metadata the application depends on.
- Run the same text, object, tool and streaming fixtures across direct, registry and gateway paths.
- Inject timeout, rate limit, partial stream, invalid structured output and malformed tool arguments.
- Verify one retry owner, a shared deadline and bounded provider or model fallback ordering.
- Compare time to first token, total latency, token accounting, cost attribution and finish reasons.
- Canary aliases and routing options, then keep the previous registry version ready for an immediate rollback.
Put a provider registry behind the application
Application code should call stable AI SDK functions with a workload alias such as support-fast or analysis-structured. A server-side registry resolves that alias to a gateway model string, dedicated provider model or compatible adapter plus its required middleware and options. The resolution should also return a policy snapshot and configuration version, not just a model object.
Keep gateway routing options such as provider ordering or restrictions in versioned configuration. On each response, preserve normalized AI SDK events alongside the requested alias, resolved model, actual provider endpoint, fallback history and provider-native evidence. This makes it possible to distinguish an application regression from a routing or provider change.
Production rule: never let a model string or alias silently change the provider, policy, feature contract or data path.
Add QVeris beside the AI SDK model interface
The AI SDK and gateway handle model inference, while QVeris supplies external APIs, tools, services and live data through Discover → Inspect → Call. Keep those responsibilities explicit. Selecting a different language model should not automatically grant a new tool, change an API credential or bypass the approval required for an external action.
Share the parent trace, tenant, deadline and policy snapshot so a single workflow can be reconstructed, but keep model and capability credentials, quotas and retry budgets separate. Before exposing a QVeris capability as an AI SDK tool, inspect its schema and permissions, validate the returned evidence and decide whether the action is safe to repeat after a model fallback.
Create an explicit AI SDK provider registry
The AI SDK's OpenAI-compatible package creates named provider instances with independent base URLs and keys. Keep those instances in a server-only registry, map product workloads to stable aliases, and never allow a browser request to supply an arbitrary provider URL.
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';
const gateway = createOpenAICompatible({
name: 'qveris-gateway',
apiKey: process.env.LLM_GATEWAY_API_KEY!,
baseURL: process.env.LLM_GATEWAY_BASE_URL!,
includeUsage: true,
});
const models = {
fast: gateway(process.env.LLM_FAST_MODEL!),
quality: gateway(process.env.LLM_QUALITY_MODEL!),
} as const;
const result = await generateText({ model: models.fast, prompt: 'Reply AI_SDK_OK' });
console.log(result.text, result.usage);- Resolve the alias on the server and reject unknown aliases.
- Contract-test tools, structured output, streaming, abort signals, and usage for each exact model.
- Log the registry version and chosen model with every request.
Verified implementation reference: AI SDK OpenAI-compatible provider.
FAQ
No. The AI SDK also supports dedicated, compatible and custom providers.
No. Verify the current model and provider capability matrix.
In one selected gateway or application layer, not both.