Skip to content

Commit 6c01b52

Browse files
authored
Clarify FallbackModel behavior on ValidationErrors (#3603)
1 parent 14d8cd8 commit 6c01b52

File tree

2 files changed

+8
-4
lines changed

2 files changed

+8
-4
lines changed

docs/agents.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -708,7 +708,7 @@ print(result_sync.output)
708708
The final request uses `temperature=0.0` (run-time), `max_tokens=500` (from model), demonstrating how settings merge with run-time taking precedence.
709709

710710
!!! note "Model Settings Support"
711-
Model-level settings are supported by all concrete model implementations (OpenAI, Anthropic, Google, etc.). Wrapper models like `FallbackModel`, `WrapperModel`, and `InstrumentedModel` don't have their own settings - they use the settings of their underlying models.
711+
Model-level settings are supported by all concrete model implementations (OpenAI, Anthropic, Google, etc.). Wrapper models like [`FallbackModel`](models/overview.md#fallback-model), [`WrapperModel`][pydantic_ai.models.wrapper.WrapperModel], and [`InstrumentedModel`][pydantic_ai.models.instrumented.InstrumentedModel] don't have their own settings - they use the settings of their underlying models.
712712

713713
### Model specific settings
714714

docs/models/overview.md

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -87,8 +87,7 @@ in sequence until one successfully returns a result. Under the hood, Pydantic AI
8787
from one model to the next if the current model returns a 4xx or 5xx status code.
8888

8989
!!! note
90-
91-
The provider SDKs on which Models are based (like OpenAI, Anthropic, etc.) often have built-in retry logic that can delay the `FallbackModel` from activating.
90+
The provider SDKs on which Models are based (like OpenAI, Anthropic, etc.) often have built-in retry logic that can delay the `FallbackModel` from activating.
9291

9392
When using `FallbackModel`, it's recommended to disable provider SDK retries to ensure immediate fallback, for example by setting `max_retries=0` on a [custom OpenAI client](openai.md#custom-openai-client).
9493

@@ -173,7 +172,9 @@ In the year 2157, Captain Maya Chen piloted her spacecraft through the vast expa
173172

174173
In this example, if the OpenAI model fails, the agent will automatically fall back to the Anthropic model with its own configured settings. The `FallbackModel` itself doesn't have settings - it uses the individual settings of whichever model successfully handles the request.
175174

176-
In this next example, we demonstrate the exception-handling capabilities of `FallbackModel`.
175+
### Exception Handling
176+
177+
The next example demonstrates the exception-handling capabilities of `FallbackModel`.
177178
If all models fail, a [`FallbackExceptionGroup`][pydantic_ai.exceptions.FallbackExceptionGroup] is raised, which
178179
contains all the exceptions encountered during the `run` execution.
179180

@@ -230,3 +231,6 @@ By default, the `FallbackModel` only moves on to the next model if the current m
230231
[`ModelAPIError`][pydantic_ai.exceptions.ModelAPIError], which includes
231232
[`ModelHTTPError`][pydantic_ai.exceptions.ModelHTTPError]. You can customize this behavior by
232233
passing a custom `fallback_on` argument to the `FallbackModel` constructor.
234+
235+
!!! note
236+
Validation errors (from [structured output](../output.md#structured-output) or [tool parameters](../tools.md)) do **not** trigger fallback. These errors use the [retry mechanism](../agents.md#reflection-and-self-correction) instead, which re-prompts the same model to try again. This is intentional: validation errors stem from the non-deterministic nature of LLMs and may succeed on retry, whereas API errors (4xx/5xx) generally indicate issues that won't resolve by retrying the same request.

0 commit comments

Comments
 (0)