Heuristic:Openai Openai agents python GPT 5 Reasoning Settings
| Knowledge Sources | |
|---|---|
| Domains | Models, Configuration |
| Last Updated | 2026-02-11 14:00 GMT |
Overview
GPT-5 models require explicit reasoning settings; the SDK auto-applies `effort="low"` to avoid incompatibility with built-in tools.
Description
GPT-5 models (any model name starting with `gpt-5`) require a `reasoning` parameter in their model settings. The SDK auto-detects GPT-5 models and applies default reasoning settings. The default effort level is `"low"` rather than `"minimal"` because some built-in hosted tools (file search, image generation) do not support `"minimal"` reasoning effort. Two specific models (`gpt-5.1`, `gpt-5.2`) use `effort="none"` instead.
Usage
Be aware of this when:
- Switching to GPT-5: The SDK handles reasoning settings automatically, but custom `ModelSettings` may override them
- Using hosted tools: Do not set `reasoning.effort="minimal"` if using FileSearchTool or ImageGenerationTool
- Using gpt-5-chat: This variant does not require reasoning settings (treated as a non-reasoning model)
The Insight (Rule of Thumb)
- Action: Let the SDK auto-configure reasoning settings. If customizing, use `effort="low"` (not `"minimal"`) when using hosted tools.
- Value: Default model is `"gpt-4.1"` (overridable via `OPENAI_DEFAULT_MODEL`). GPT-5 models get `reasoning=Reasoning(effort="low"), verbosity="low"`.
- Trade-off: `"low"` effort uses more tokens than `"minimal"` or `"none"` but ensures compatibility with all tool types. Use `"none"` only for gpt-5.1/5.2 where it is explicitly supported.
Reasoning
Built-in tools that execute server-side (file search, image generation, code interpreter) have their own compatibility constraints with reasoning modes. The SDK chose `"low"` as the safest default that works universally while still providing reduced reasoning overhead compared to the full default.
Code evidence from `models/default_models.py:13-18`:
_GPT_5_DEFAULT_MODEL_SETTINGS: ModelSettings = ModelSettings(
# We chose "low" instead of "minimal" because some of the built-in tools
# (e.g., file search, image generation, etc.) do not support "minimal"
# If you want to use "minimal" reasoning effort, you can pass your own model settings
reasoning=Reasoning(effort="low"),
verbosity="low",
)
Model detection logic from `models/default_models.py:32-40`:
def gpt_5_reasoning_settings_required(model_name: str) -> bool:
if model_name.startswith("gpt-5-chat"):
# gpt-5-chat-latest does not require reasoning settings
return False
return model_name.startswith("gpt-5")
Special cases from `models/default_models.py:25`:
_GPT_5_NONE_EFFORT_MODELS = {"gpt-5.1", "gpt-5.2"}