Make end_strategy also work for output tools, not just tools

docs/output.md

@@ -304,6 +304,14 @@ print(repr(result.output))
 
 1. If we were passing just `Fruit` and `Vehicle` without custom tool names, we could have used a union: `output_type=Fruit | Vehicle`. However, as `ToolOutput` is an object rather than a type, we have to use a list.
 
+!!! note "Handling Multiple Output Tool Calls"
+ When a model calls multiple output tools in the same response, the agent's `end_strategy` parameter controls whether all output tool functions are executed or only the first one:
+
+ - `'early'` (default): Only the first output tool is executed, and additional output tool calls are skipped once a final result is found. This is the default behavior.
+ - `'exhaustive'`: All output tool functions are executed, even after a final result is found. The first valid output tool's result is used as the final output.
+
+ This parameter also applies to [function tools](tools.md), not just output tools.
+
 _(This example is complete, it can be run "as is")_
 
 #### Native Output

docs/tools-advanced.md

@@ -378,6 +378,17 @@ If a tool requires sequential/serial execution, you can pass the [`sequential`][
 
 Async functions are run on the event loop, while sync functions are offloaded to threads. To get the best performance, _always_ use an async function _unless_ you're doing blocking I/O (and there's no way to use a non-blocking library instead) or CPU-bound work (like `numpy` or `scikit-learn` operations), so that simple functions are not offloaded to threads unnecessarily.
 
+### End Strategy
+
+When a model returns multiple tool calls (either function tools or [output tools](output.md)), the agent's `end_strategy` parameter controls whether all tools are executed once a final result is found:
+
+- **`'early'`** (default): Once a final result is found (from an output tool), all remaining tool calls (both function tools and output tools) are skipped.
+- **`'exhaustive'`**: All tool calls are executed, even after a final result is found. The first valid output tool's result is used as the final output.
+
+The `'exhaustive'` strategy is useful when tools have side effects (like logging, sending notifications, or updating metrics) that should always execute, regardless of whether a final result has been found.
+
+For more details on how `end_strategy` applies to output tools, see [Handling Multiple Output Tool Calls](output.md#handling-multiple-output-tool-calls).
+
 !!! note "Limiting tool executions"
  You can cap tool executions within a run using [`UsageLimits(tool_calls_limit=...)`](agents.md#usage-limits). The counter increments only after a successful tool invocation. Output tools (used for [structured output](output.md)) are not counted in the `tool_calls` metric.
 

pydantic_ai_slim/pydantic_ai/_agent_graph.py

@@ -61,8 +61,10 @@
 EndStrategy = Literal['early', 'exhaustive']
 """The strategy for handling multiple tool calls when a final result is found.
 
-- `'early'`: Stop processing other tool calls once a final result is found
-- `'exhaustive'`: Process all tool calls even after finding a final result
+- `'early'`: Stop processing other tool calls (both function tools and output tools) once a final result is found
+- `'exhaustive'`: Process all tool calls (both function tools and output tools) even after finding a final result
+
+This applies to both function tools and output tools.
 """
 DepsT = TypeVar('DepsT')
 OutputT = TypeVar('OutputT')
@@ -833,35 +835,56 @@ async def process_tool_calls( # noqa: C901
 
  # First, we handle output tool calls
  for call in tool_calls_by_kind['output']:
- if final_result:
- if final_result.tool_call_id == call.tool_call_id:
- part = _messages.ToolReturnPart(
- tool_name=call.tool_name,
- content='Final result processed.',
- tool_call_id=call.tool_call_id,
- )
- else:
- yield _messages.FunctionToolCallEvent(call)
- part = _messages.ToolReturnPart(
- tool_name=call.tool_name,
- content='Output tool not used - a final result was already processed.',
- tool_call_id=call.tool_call_id,
- )
- yield _messages.FunctionToolResultEvent(part)
-
+ # `final_result` can be passed into `process_tool_calls` from `Agent.run_stream`
+ # when streaming and there's already a final result
+ if final_result and final_result.tool_call_id == call.tool_call_id:
+ part = _messages.ToolReturnPart(
+ tool_name=call.tool_name,
+ content='Final result processed.',
+ tool_call_id=call.tool_call_id,
+ )
+ output_parts.append(part)
+ # Early strategy is chosen and final result is already set
+ elif ctx.deps.end_strategy == 'early' and final_result:
+ yield _messages.FunctionToolCallEvent(call)
+ part = _messages.ToolReturnPart(
+ tool_name=call.tool_name,
+ content='Output tool not used - a final result was already processed.',
+ tool_call_id=call.tool_call_id,
+ )
+ yield _messages.FunctionToolResultEvent(part)
  output_parts.append(part)
+ # Early strategy is chosen and final result is not yet set
+ # Or exhaustive strategy is chosen
  else:
  try:
  result_data = await tool_manager.handle_call(call)
  except exceptions.UnexpectedModelBehavior as e:
- ctx.state.increment_retries(
- ctx.deps.max_result_retries, error=e, model_settings=ctx.deps.model_settings
- )
- raise e # pragma: lax no cover
+ # If we already have a valid final result, don't fail the entire run
+ # This allows exhaustive strategy to complete successfully when at least one output tool is valid
+ if final_result:
+ # Just add a retry prompt part for the failed output tool
+ yield _messages.FunctionToolCallEvent(call)
+ retry_part = _messages.RetryPromptPart(
+ content=str(e.__cause__ or e),
+ tool_name=call.tool_name,
+ tool_call_id=call.tool_call_id,
+ )
+ output_parts.append(retry_part)
+ yield _messages.FunctionToolResultEvent(retry_part)
+ else:
+ # No valid result yet, so this is a real failure
+ ctx.state.increment_retries(
+ ctx.deps.max_result_retries, error=e, model_settings=ctx.deps.model_settings
+ )
+ raise e
  except ToolRetryError as e:
- ctx.state.increment_retries(
- ctx.deps.max_result_retries, error=e, model_settings=ctx.deps.model_settings
- )
+ # If we already have a valid final result, don't increment retries for invalid output tools
+ # This allows the run to succeed if at least one output tool returned a valid result
+ if not final_result:
+ ctx.state.increment_retries(
+ ctx.deps.max_result_retries, error=e, model_settings=ctx.deps.model_settings
+ )
  yield _messages.FunctionToolCallEvent(call)
  output_parts.append(e.tool_retry)
  yield _messages.FunctionToolResultEvent(e.tool_retry)
@@ -872,7 +895,10 @@ async def process_tool_calls( # noqa: C901
  tool_call_id=call.tool_call_id,
  )
  output_parts.append(part)
- final_result = result.FinalResult(result_data, call.tool_name, call.tool_call_id)
+
+ # In both `early` and `exhaustive` modes, use the first output tool's result as the final result
+ if not final_result:
+ final_result = result.FinalResult(result_data, call.tool_name, call.tool_call_id)
 
  # Then, we handle function tool calls
  calls_to_run: list[_messages.ToolCallPart] = []

pydantic_ai_slim/pydantic_ai/agent/__init__.py

@@ -115,7 +115,13 @@ class Agent(AbstractAgent[AgentDepsT, OutputDataT]):
 
  _name: str | None
  end_strategy: EndStrategy
- """Strategy for handling tool calls when a final result is found."""
+ """Strategy for handling tool calls when a final result is found.
+
+ - `'early'`: Stop processing other tool calls once a final result is found (default)
+ - `'exhaustive'`: Process all tool calls even after finding a final result
+
+ This applies to both function tools and output tools.
+ """
 
  model_settings: ModelSettings | None
  """Optional model request settings to use for this agents's runs, by default.