Pydantic AI 2.62.0: Adjustable reasoning effort, model error classification

1. Adjust reasoning effort during a conversation

Reasoning effort controls how much effort a model puts into reasoning when generating an answer. This change lets it vary during a conversation instead of remaining fixed. OpenAI receives changes through configuration_update, while Anthropic receives output_config with each message. Their request formats differ, but both serve the same goal of adjusting settings at runtime.

Changed settings are saved in conversation history as ModelSettingsDeltaPart. The timing and details of reasoning effort changes thus appear as separate history entries. Code handling existing conversation histories must account for the new entry. The release notes also list this change among compatibility considerations.

The path for using Claude through OpenAI-compatible providers was also revised. Reasoning information outside the provider's native format is now passed in user messages. This affects OpenAIChatModel and OpenAIResponsesModel. Alongside reasoning effort settings, the path for passing reasoning information itself was updated.

2. Distinguish model request errors by cause

New error categories include ModelRequestRejectedError for rejected requests and ModelAuthenticationError for authentication failures. Applications can use these categories to branch follow-up handling rather than grouping failures under one error.

ModelNotFoundError was added for cases where a model cannot be found. It can, for example, support distinct guidance for checking credentials versus checking a model name. In practice, the new categories offer more clues for designing application responses around failure causes.

3. Consider cache preservation alongside history changes

Adjustable reasoning effort removes the need to keep the same setting throughout each conversation. On OpenRouter, changes now use configuration_update system messages to preserve the prompt cache, which temporarily stores repeated inputs for reuse. The concrete benefit is preserving the cache while making settings more flexible.

Developers also have more to manage. Code that saves or reads conversation history must account for settings changes, while code that constructs requests directly must reflect provider-specific delivery methods. Flexible settings therefore come with adjustments to history and request handling.

The release notes describe the cache preservation fix and new error categories. They do not provide cost or response-time measurements, or an exception-handling matrix for each provider response.

4. Review error classification and retry flows together

On Azure, FallbackModel, which handles fallback models, now classifies too_many_requests errors that occur while streaming a response. The fix addresses fallback routing based on the path through which an error is returned. Developers using this feature on Azure should review this path alongside the new error categories.

ModelRetry raised after a background tool step finishes now also counts toward max_retries. Background tools run separately from the user conversation. This fixes a path where retries were omitted from the count depending on when they were requested.

When adopting the update, it helps to review settings-change history and error-category handling as separate flows. The release notes flag both reasoning effort changes and new error categories as compatibility considerations. Feature adoption should therefore go alongside a review of existing history and error handling.

2.62.0 introduces paths for changing provider-specific reasoning settings during conversations and adds a basis for handling model failures by cause.