Reasoning
Many language models support an internal "reasoning" phase (sometimes also called "thinking") before producing a response. The AI SDK provides a top-level reasoning parameter on generateText and streamText that controls this behavior across providers with a single, portable setting.
Basic Usage
The reasoning parameter accepts the following values:
| Value | Behavior |
|---|---|
'provider-default' | Use the provider's default reasoning behavior (default when omitted) |
'none' | Disable reasoning (lowest reasoning level if it cannot be disabled) |
'minimal' | Bare-minimum reasoning |
'low' | Fast, concise reasoning |
'medium' | Balanced reasoning |
'high' | Thorough reasoning |
'xhigh' | Extra-high reasoning |
'max' | Maximum reasoning |
Streaming
The reasoning parameter works the same way with streamText:
Precedence Rules
Provider-specific settings take precedence over the corresponding fields derived from reasoning. Partial configurations may still use portable reasoning to fill missing fields; summary and display settings can be used alongside it.
This design lets you use the portable reasoning parameter by default and fall back to providerOptions only when you need provider-specific features like exact token budgets.
Provider Support
The reasoning parameter is supported by providers including OpenAI, Anthropic, Google, xAI, Groq, DeepSeek, Moonshot AI, Fireworks, Amazon Bedrock, Mistral, Cohere, Alibaba, Open Responses, OpenAI Compatible, and Perplexity. Each provider translates the value to its native reasoning API.
How values are mapped
When a model does not support the requested value, the provider uses the closest supported value, rounding down. The values are ordered none < minimal < low < medium < high < xhigh < max, so 'xhigh' becomes 'high' on a model without an xhigh level. If there is no lower value, the next higher one is used.
Rounding never turns reasoning off: other values never map to 'none', and 'none' on a model that cannot disable reasoning maps to the model's lowest level. Providers emit a compatibility warning whenever the value they send differs from the requested value. Values set in providerOptions are sent unchanged (see Precedence Rules).
Providers only round values for models and model families they recognize by model ID, so newer versions of a known family use that family's levels. Unrecognized model IDs, such as fine-tuned or custom models, and OpenAI-compatible and Open Responses endpoints receive the value directly and the API decides whether it is supported.
For providers that use a token budget, the value maps to a percentage of the model's maximum output tokens ('max' maps to 95% by default), within the provider's budget limits.
Maximum reasoning can substantially increase token usage, latency, cost, and the chance of reaching request or output limits. Use it when the model's additional reasoning depth is worth those tradeoffs.
Providers and models that do not support reasoning configuration emit an unsupported warning and ignore the parameter.
Migrating from providerOptions
If you currently control reasoning via providerOptions, you can migrate to the top-level reasoning parameter for portability across providers.
Before (Anthropic)
After (Anthropic)
Before (Anthropic with older model)
After (Anthropic with older model)
If you need to enforce an exact token budget (e.g. exactly 12000 tokens), keep using providerOptions instead of the top-level reasoning parameter.
Before (Google with includeThoughts)
After (Google with includeThoughts)
Before (OpenAI with reasoningSummary)
After (OpenAI with reasoningSummary)
You can combine providerOptions with reasoning for provider-specific features such as reasoning summaries or display settings. Explicit effort or budget values override the corresponding mapped fields; partial configurations may still use portable reasoning to fill missing fields. See Precedence Rules for details.