AI SDK xAI 5.0.33 Released: Unified Reasoning Option Mapping Logic

The AI SDK's xAI provider package has released patch version 5.0.33. The core change revolves around a seemingly minor issue with broad impact: different model providers interpret the reasoning (reasoning effort) parameter inconsistently. This update unifies cross-provider mapping rules into a single predictable logic, directly affecting integrations including OpenAI, Fireworks, Anthropic, Bedrock, DeepSeek, Gemini, and more.

Why Reasoning Parameters Need "Translation"

In the AI SDK's abstraction layer, callers typically only need to provide a top-level reasoning value such as 'high', 'medium', or 'none'. But the underlying APIs each have different tier divisions: some models support 'xhigh', others only go up to 'high'; some models don't allow disabling reasoning at all; and still others throw errors for certain tiers.

So the SDK needs a mapping layer. Previously this mapping was implemented and decided independently by each provider, resulting in the same call behaving differently across providers. The 5.0.33 patch commit (61a315e) consolidates this logic into a single unified rule.

AI SDK's layered abstraction: AI SDK (formerly Vercel AI SDK) is a unified model-calling layer for TypeScript/JavaScript, whose core value is letting developers call different vendors' models through the same interface. Its abstraction has several layers: at the top are general functions like generateText/streamText and cross-model general parameters like reasoning; in the middle are provider adapters (such as @ai-sdk/openai, @ai-sdk/anthropic); at the bottom are each vendor's native APIs. providerOptions is the official "escape hatch," allowing callers to pass native parameters directly by provider namespace, bypassing the normalization of the general layer. Understanding this layering is essential to understanding why "automatic mapping of top-level parameters" and "pass-through of providerOptions" coexist—the former pursues consistency, the latter preserves precise control.

Reasoning effort: This is a parameter concept that emerged after 2025 with the spread of reasoning models, used to control the budget for "chain-of-thought" computation before the model gives an answer. OpenAI's reasoning_effort values include minimal/low/medium/high; Anthropic expresses it via thinking.budget_tokens in token counts; Google Gemini uses thinkingBudget. Vendors differ not only in tier names but even in "whether it can be disabled"—some models force reasoning, others allow none. This is precisely the fundamental reason the mapping layer must exist and must be designed carefully.

New Rules: Stay as Close as Possible to the Caller's Intent

According to the release notes, the unified resolution logic handles several cases:

First, provider-specific settings in providerOptions are passed through unchanged. If the caller explicitly writes providerOptions.openai.reasoningEffort, this value is sent to OpenAI exactly as-is, and the SDK no longer discards it just because the value isn't in the model's tier list. The same applies to Fireworks, which no longer rewrites providerOptions.fireworks.reasoningEffort.

Second, the top-level reasoning is mapped to the closest supported tier, preferring to round down. It only rounds up when no lower tier is available. The release notes give two concrete examples: on Anthropic and Bedrock models lacking an xhigh tier, 'xhigh' now maps to 'high' instead of the previously possible 'max'; on models such as DeepSeek^Ad, Kimi K3, and Mistral GLM-5.3, 'medium' maps to 'low' instead of 'high'.

Third, for models that cannot disable reasoning, 'none' is downgraded to the lowest tier with a compatibility warning. Previously such requests were either silently dropped or sent out and rejected by the API. The new logic maps them to the model's lowest reasoning tier and emits a compatibility warning. Affected models include the GPT-6 series that doesn't support 'none', xAI grok-4.5 and later versions, GPT-OSS on Groq, Kimi K3, Perplexity, QuiverAI, OpenAI gpt-oss models on Bedrock, and Gemini 2.5 Pro (minimum thinking budget). Gemini 3 and the between_tools mappings for Anthropic and Bedrock now also emit the same warning.

Fourth, the Fireworks exception list. Fireworks now sends the top-level reasoning value directly instead of uniformly capping at 'high'—but keeps exceptions for model families known to reject specific values: GPT-OSS, GLM-5.3, and Muse Spark reject 'none', while Nemotron and Inkling reject 'minimal'.

Compatibility warning mechanism: When the AI SDK encounters a situation where "the caller's intent cannot be fully satisfied by the target model," it returns a compatibility warning via the warnings array rather than throwing an exception that interrupts the request. These warnings can be read from the result object of generateText/streamText and typically carry an identifier like type: 'unsupported-setting'. For production environments, this design means the request still completes successfully, but the caller can use it for instrumentation, reporting, or degradation notices. Compared with silently dropping parameters (the problem is masked) and API errors (the request fails outright), the warning mechanism strikes a compromise between "availability" and "observability," and is a signal worth actively consuming in multi-model routing scenarios.

Signature Changes in Two Mapping Functions

This patch also adjusts the interfaces of two internal utilities, affecting developers who use them directly:

• mapReasoningToProviderEffort now accepts any reasoning value, returns an optional providerOptionsEffort (keeping the original value unchanged), and rounds tiers missing from the effort map to the closest supported tier.
• mapReasoningToProviderBudget maps 'none' to the minimum reasoning budget and always returns a budget value; for tiers missing from budgetPercentages, it uses a default percentage.

Additionally, OpenAICompatibleChatConfig adds an optional mapReasoning function, allowing providers compatible with the OpenAI protocol to customize how the top-level reasoning is mapped.

Budget-style vs. tier-style reasoning control: The mapping functions are split into mapReasoningToProviderEffort and mapReasoningToProviderBudget because vendors fundamentally differ in how they control reasoning depth. Tier-style (effort) is expressed with discrete labels, such as OpenAI's low/medium/high; budget-style (budget) is expressed in token counts, such as Anthropic's thinking.budget_tokens and Gemini's thinkingBudget. Budget-style usually requires conversion as a percentage based on the model's context window or maximum output tokens, hence the budgetPercentages configuration in the function signature and the fallback to a default percentage when a tier is missing. This also explains why the latter "always returns a budget value"—the budget-style interface has no intermediate "unset" state; a concrete value must be provided to send a valid request.

Practical Significance for Developers

This change is ostensibly a patch-level dependency update (it also upgrades @ai-sdk/provider-utils@5.0.71), but it addresses a long-standing pitfall for multi-model applications: the same reasoning effort configuration produces radically different behavior across providers.

For teams that need to switch between models, run A/B comparisons, or build model routing layers, unified mapping means less "mystical" tuning. In particular, 'none' handling changing from "silently drop or error" to "downgrade with warning" makes the behavior of models that can't disable reasoning predictable, and makes it easier to capture warnings at a higher layer for monitoring.

It's worth noting that the default round-down strategy means actual reasoning effort may be lower than the caller expects in some scenarios. If your application relies on the precise semantics of higher tiers like 'xhigh' or 'medium', it's recommended to specify them explicitly via providerOptions rather than relying on automatic mapping of top-level parameters.

Upgrade as usual via a dependency version update; this version is built from 2 commits on the main branch.

One-line Summary

AI SDK xAI 5.0.33 unifies cross-provider reasoning parameter mapping rules, eliminating behavioral inconsistencies.

Paragraph Summary

The AI SDK's xAI provider package released patch 5.0.33, whose core is unifying cross-provider reasoning effort mapping logic. Previously each provider implemented mapping independently, causing the same call to behave differently across models. The new rules include: provider-specific settings in providerOptions are passed through unchanged; top-level reasoning preferentially maps to the closest lower tier, rounding up only when no lower tier exists; on models that can't disable reasoning, 'none' is downgraded to the lowest tier with a compatibility warning, rather than silently dropped or causing an API error. The patch also adjusts the signatures of mapReasoningToProviderEffort and mapReasoningToProviderBudget, the latter now always returning a budget value, and adds an optional mapReasoning hook for OpenAI-compatible configurations. The article notes that applications relying on precise tier semantics should explicitly use providerOptions.