fix: unknown tool calls no longer exhaust global retry counter (#4940)

Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>

Author: dsfaccini

pydantic_ai_slim/pydantic_ai/_agent_graph.py

@@ -1436,9 +1436,8 @@ async def process_tool_calls(  # noqa: C901
     else:
         calls_to_run.extend(tool_calls_by_kind['function'])
 
-    # Then, we handle unknown tool calls
+    # Unknown tools use per-tool retry handling via ModelRetry in ToolManager
     if tool_calls_by_kind['unknown']:
-        ctx.state.increment_retries(ctx.deps.max_result_retries)
         calls_to_run.extend(tool_calls_by_kind['unknown'])
 
     calls_to_run_results: dict[str, DeferredToolResult] = {}
@@ -1489,6 +1488,7 @@ async def process_tool_calls(  # noqa: C901
                 else:
                     validated = await tool_manager.validate_tool_call(call)
             except exceptions.UnexpectedModelBehavior:
+                ctx.state.check_incomplete_tool_call()
                 yield _messages.FunctionToolCallEvent(call, args_valid=False)
                 raise
             validated_calls[call.tool_call_id] = validated

tests/test_agent.py

@@ -3511,7 +3511,7 @@ def empty(_: list[ModelMessage], _info: AgentInfo) -> ModelResponse:
     agent = Agent(FunctionModel(empty))
 
     with capture_run_messages() as messages:
-        with pytest.raises(UnexpectedModelBehavior, match=r'Exceeded maximum retries \(1\) for output validation'):
+        with pytest.raises(UnexpectedModelBehavior, match=r"Tool 'foobar' exceeded max retries count of 1"):
             agent.run_sync('Hello')
     assert messages == snapshot(
         [
@@ -3607,7 +3607,7 @@ def empty(_: list[ModelMessage], _info: AgentInfo) -> ModelResponse:
     agent = Agent(FunctionModel(empty), retries=num_retries)
 
     with capture_run_messages() as messages:
-        with pytest.raises(UnexpectedModelBehavior, match=r'Exceeded maximum retries \(2\) for output validation'):
+        with pytest.raises(UnexpectedModelBehavior, match=r"Tool 'foobar' exceeded max retries count of 2"):
             agent.run_sync('Hello')
     assert messages == snapshot(
         [
@@ -9149,6 +9149,44 @@ def test_override_resets_after_context(self):
         assert result.output == 'max_tokens=100 temperature=None'
 
 
+def test_unknown_tool_with_valid_tool_does_not_exhaust_retries():
+    """Unknown tool calls should not increment the global retry counter.
+
+    When the model returns both an unknown tool and a valid tool in the same
+    response, the unknown tool is handled via per-tool retries (ModelRetry)
+    downstream. The global retry counter should only reflect output validation
+    retries, not unknown-tool retries, so valid tools keep working.
+
+    We set retries=2 (per-tool max for unknown tools) and output_retries=1
+    (global max for output validation) to isolate the bug: per-tool retries
+    allow 2 rounds of the unknown tool, but the old code's global increment
+    would exhaust output_retries after just 2 rounds.
+    """
+    call_count = 0
+
+    def model_function(messages: list[ModelMessage], info: AgentInfo) -> ModelResponse:
+        nonlocal call_count
+        call_count += 1
+        if call_count <= 2:
+            return ModelResponse(
+                parts=[
+                    ToolCallPart('nonexistent_tool', '{}'),
+                    ToolCallPart('valid_tool', '{"x": 1}'),
+                ]
+            )
+        return ModelResponse(parts=[TextPart('done')])
+
+    agent = Agent(FunctionModel(model_function), retries=2, output_retries=1)
+
+    @agent.tool_plain
+    def valid_tool(x: int) -> str:
+        return f'result={x}'
+
+    result = agent.run_sync('Hello')
+    assert result.output == 'done'
+    assert call_count == 3
+
+
 # endregion
 
 

tests/test_streaming.py

@@ -770,7 +770,7 @@ async def ret_a(x: str) -> str:  # pragma: no cover
         return x
 
     with capture_run_messages() as messages:
-        with pytest.raises(UnexpectedModelBehavior, match=r'Exceeded maximum retries \(0\) for output validation'):
+        with pytest.raises(UnexpectedModelBehavior, match=r"Tool 'foobar' exceeded max retries count of 0"):
             async with agent.run_stream('hello'):
                 pass
 
@@ -2629,6 +2629,22 @@ def known_tool(x: int) -> int:
                     timestamp=IsNow(tz=timezone.utc),
                 ),
             ),
+            FunctionToolCallEvent(
+                part=ToolCallPart(
+                    tool_name='known_tool',
+                    args={'x': 5},
+                    tool_call_id=IsStr(),
+                ),
+                args_valid=True,
+            ),
+            FunctionToolCallEvent(
+                part=ToolCallPart(
+                    tool_name='unknown_tool',
+                    args={'arg': 'value'},
+                    tool_call_id=IsStr(),
+                ),
+                args_valid=False,
+            ),
         ]
     )
 

tests/test_ui.py

@@ -531,8 +531,11 @@ async def stream_function(
             '<response>',
             "<tool-call name='unknown_tool'>None",
             "</tool-call name='unknown_tool'>",
-            "<error type='UnexpectedModelBehavior'>Exceeded maximum retries (1) for output validation</error>",
             '</response>',
+            '<request>',
+            "<function-tool-call name='unknown_tool'>None</function-tool-call>",
+            "<error type='UnexpectedModelBehavior'>Tool 'unknown_tool' exceeded max retries count of 1</error>",
+            '</request>',
             '</stream>',
         ]
     )

tests/test_vercel_ai.py

@@ -2261,7 +2261,7 @@ async def stream_function(
                 'toolName': 'unknown_tool',
             },
             {'type': 'tool-input-available', 'toolCallId': IsStr(), 'toolName': 'unknown_tool', 'input': {}},
-            {'type': 'error', 'errorText': 'Exceeded maximum retries (1) for output validation'},
+            {'type': 'error', 'errorText': "Tool 'unknown_tool' exceeded max retries count of 1"},
             {'type': 'finish-step'},
             {'type': 'finish', 'finishReason': 'error'},
             '[DONE]',