Add tool_choice setting

docs/api/settings.md

@@ -5,4 +5,4 @@
       inherited_members: true
       members:
         - ModelSettings
-        - UsageLimits
+        - ToolOrOutput

docs/tools-advanced.md

@@ -351,6 +351,72 @@ You can use `prepare_tools` to:
 
 If both per-tool `prepare` and agent-wide `prepare_tools` are used, the per-tool `prepare` is applied first to each tool, and then `prepare_tools` is called with the resulting list of tool definitions.
 
+## Tool Choice {#tool-choice}
+
+The `tool_choice` setting in [`ModelSettings`][pydantic_ai.settings.ModelSettings] controls which tools the model can use during a request. This is useful for disabling tools, forcing tool use, or restricting which tools are available.
+
+!!! warning "Per-Run Setting"
+    This feature is a stepping-stone to expanded functionality, like forcing an agent to call tools at specific steps.
+    Used directly, the `tool_choice` setting applies to **every model request** in an agent run:
+
+    - `'required'` forces a tool call at every step, not just the first
+    - `['tool_a']` restricts to that tool for the entire run, preventing completion if the agent needs output tools
+
+    If you want to use it for per-request control, use [direct model requests](direct.md) or the `prepare_tools` function above.
+
+Pydantic AI distinguishes between **[function tools](tools.md)** (tools you register via `@agent.tool`, [toolsets](toolsets.md), or [MCP](mcp/client.md)), and **output tools** (internal tools used for [structured output](output.md#tool-output)).
+
+### Options
+
+| Value | Description |
+|-------|-------------|
+| `'auto'` (default) | Model decides whether to use tools. All tools available. |
+| `'none'` | Disable function tools. Model can respond with text or use output tools. |
+| `'required'` | Force the model to use a tool. All tools remain available. |
+| `['tool_a', ...]` | Restrict to specific tools by name (can include output tool names). |
+| [`ToolOrOutput`][pydantic_ai.settings.ToolOrOutput]`(function_tools=['...'])` | Restrict function tools while auto-including all output tools. |
+
+### Example
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.test import TestModel
+from pydantic_ai.settings import ToolOrOutput
+
+agent = Agent(TestModel())
+
+
+@agent.tool_plain
+def get_weather(city: str) -> str:
+    return f'Sunny in {city}'
+
+
+@agent.tool_plain
+def get_time(city: str) -> str:
+    return f'12:00 in {city}'
+
+
+# Pass tool_choice via model_settings
+result = agent.run_sync('Hello', model_settings={'tool_choice': 'none'})
+
+# Use ToolOrOutput to restrict to specific function tools while allowing output
+result = agent.run_sync(
+    'Hello', model_settings={'tool_choice': ToolOrOutput(function_tools=['get_weather'])}
+)
+```
+
+### Provider Support
+
+All providers support `'auto'` and `'none'`. Key differences for other options:
+
+| Provider | `'required'` | Specific tools | Notes |
+|----------|:------------:|:--------------:|-------|
+| OpenAI | ✓ | ✓ | Full support |
+| Anthropic | ⚠️ | ⚠️ | Not supported with thinking enabled |
+| Google | ✓ | ✓ | |
+| Bedrock | ✓ | Single only | Multiple tools fall back to 'any' mode |
+| Groq/HuggingFace | ✓ | Single only | Multiple tools fall back to 'required' mode |
+
 ## Tool Execution and Retries {#tool-retries}
 
 When a tool is executed, its arguments (provided by the LLM) are first validated against the function's signature using Pydantic (with optional [validation context](output.md#validation-context)). If validation fails (e.g., due to incorrect types or missing required arguments), a `ValidationError` is raised, and the framework automatically generates a [`RetryPromptPart`][pydantic_ai.messages.RetryPromptPart] containing the validation details. This prompt is sent back to the LLM, informing it of the error and allowing it to correct the parameters and retry the tool call.

pydantic_ai_slim/pydantic_ai/agent/__init__.py

@@ -596,6 +596,21 @@ async def main():
         if infer_name and self.name is None:
             self._infer_name(inspect.currentframe())
 
+        # Validate tool_choice - 'required' and list[str] would prevent the agent from ever completing
+        # because they exclude output tools. These settings are only valid for direct model requests.
+        # TODO(prepare_model_settings): This validation remains correct for static model_settings.
+        # The hook CAN return 'required' or list[str] for per-step control (e.g., force tool on
+        # step 1, then allow completion on step 2+). The hook bypasses this validation because
+        # it applies dynamically per-request, not statically for the entire run.
+        if model_settings:
+            tool_choice = model_settings.get('tool_choice')
+            if tool_choice == 'required' or isinstance(tool_choice, list):
+                raise exceptions.UserError(
+                    f'tool_choice={tool_choice!r} is not supported in agent.run() because it prevents '
+                    f'the agent from producing a final response. Use ToolOrOutput to combine specific '
+                    f'tools with output capability, or use model.request() for direct model calls.'
+                )
+
         model_used = self._get_model(model)
         del model
 

pydantic_ai_slim/pydantic_ai/models/_tool_choice.py

@@ -0,0 +1,139 @@
+from typing import Literal
+
+from typing_extensions import assert_never
+
+from pydantic_ai.exceptions import UserError
+from pydantic_ai.models import ModelRequestParameters
+from pydantic_ai.settings import ModelSettings, ToolOrOutput
+
+_AutoOrRequired = Literal['auto', 'required']
+ResolvedToolChoice = Literal['none', 'auto', 'required'] | tuple[_AutoOrRequired, list[str]]
+
+
+def resolve_tool_choice(  # noqa: C901
+    model_settings: ModelSettings | None,
+    model_request_parameters: ModelRequestParameters,
+) -> ResolvedToolChoice:
+    """Resolve user-facing tool_choice into a canonical form for providers.
+
+    Pydantic AI distinguishes between function tools (e.g. user-registered via @agent.tool)
+    and output tools (framework-internal for structured output). The user-facing
+    `tool_choice` setting controls function tools only - this function resolves that
+    into a canonical form that providers can use, incorporating output tools as needed.
+
+    Args:
+        model_settings: Optional settings containing the tool_choice value.
+        model_request_parameters: Parameters describing available tools and output configuration.
+
+    Returns:
+        A canonical tool_choice value for providers:
+
+        - `'none'`: No tools should be called. Only valid when direct output (text/image) is allowed.
+        - `'auto'`: Model chooses whether to use tools. Direct output is allowed.
+        - `'required'`: Model must use a tool. Direct output is not allowed.
+        - `(tool_names, 'auto')`: Only these tools are available, direct output is allowed.
+        - `(tool_names, 'required')`: Only these tools are available, must use one.
+
+    Raises:
+        UserError: If tool_choice is incompatible with the available tools or output configuration.
+
+    Input behavior:
+
+        - `None` / `'auto'`: Returns `'auto'` if direct output allowed, else `'required'`.
+        - `'none'` / `[]`: Disables function tools. If output tools exist, returns them with
+          appropriate mode. Otherwise returns `'none'`.
+        - `'required'`: Requires function tool use. Raises if no function tools are defined.
+        - `list[str]`: Restricts to specified tools with `'required'` mode. Validates tool names.
+        - `ToolOrOutput`: Combines specified function tools with all output tools.
+          Returns `'auto'` mode if direct output is allowed, otherwise `'required'`.
+    """
+    function_tool_choice = (model_settings or {}).get('tool_choice')
+
+    allow_direct_output = model_request_parameters.allow_text_output or model_request_parameters.allow_image_output
+
+    available_tools = set(model_request_parameters.tool_defs.keys())
+
+    def _invalid_tools(chosen_tool_names: set[str], available_tools: set[str], *, available_label: str) -> None:
+        invalid = chosen_tool_names - available_tools
+        if invalid:
+            raise UserError(
+                f'Invalid tool names in `tool_choice`: {invalid}. {available_label}: {available_tools or "none"}'
+            )
+
+    # Default / auto
+    if function_tool_choice in (None, 'auto'):
+        return 'auto' if allow_direct_output else 'required'
+
+    # none / []: disable function tools, but output tools may still exist
+    elif function_tool_choice in ('none', []):
+        output_tool_names = [t.name for t in model_request_parameters.output_tools]
+
+        if output_tool_names:
+            if allow_direct_output:
+                mode: _AutoOrRequired = 'auto'
+            elif model_request_parameters.function_tools:
+                mode = 'required'
+            else:
+                return 'required'  # only output tools exist and direct output isn't allowed
+
+            return (mode, output_tool_names)
+
+        if allow_direct_output:
+            return 'none'
+
+        # pragma: no cover
+        assert False, 'Either output_tools or allow_text_output/allow_image_output must be set'
+
+    # required (only function tools allowed)
+    elif function_tool_choice == 'required':
+        if not model_request_parameters.function_tools:
+            raise UserError(
+                '`tool_choice` was set to "required", but no function tools are defined. '
+                'Please define function tools or change `tool_choice` to "auto" or "none".'
+            )
+        return 'required'
+
+    # list[str]: required, restricted to these tools
+    elif isinstance(function_tool_choice, list):
+        # unique names; doesn't retain order, but that's ok https://github.com/pydantic/pydantic-ai/pull/3611#discussion_r2677595474
+        chosen_set = set(function_tool_choice)
+        # we'll only raise here if none of the chosen tools are valid https://github.com/pydantic/pydantic-ai/pull/3611#discussion_r2677602549
+        if chosen_set - available_tools == chosen_set:
+            _invalid_tools(chosen_set, available_tools, available_label='Available tools')
+
+        if chosen_set == available_tools:
+            return 'required'
+
+        # tests require a deterministic order
+        return ('required', sorted(chosen_set))
+
+    # ToolOrOutput: specific function tools + all output tools or direct text/image output
+    elif isinstance(function_tool_choice, ToolOrOutput):
+        output_tool_names = [t.name for t in model_request_parameters.output_tools]
+
+        # stable order, unique
+        if not function_tool_choice.function_tools:
+            if output_tool_names:
+                return 'auto' if allow_direct_output else 'required'
+            return 'none'
+
+        chosen_function_set = set(function_tool_choice.function_tools)
+        all_function_tool_names = {t.name for t in model_request_parameters.function_tools}
+        # same as above - only raise if none are valid
+        if not chosen_function_set - all_function_tool_names == chosen_function_set:
+            _invalid_tools(
+                chosen_function_set,
+                all_function_tool_names,
+                available_label='Available function tools',
+            )
+
+        # tests require a deterministic order
+        allowed_tools = sorted([*chosen_function_set, *output_tool_names])
+        if set(allowed_tools) == available_tools:
+            return 'required'
+
+        # If direct output is allowed, use 'auto' mode to permit text/image responses
+        mode: _AutoOrRequired = 'auto' if allow_direct_output else 'required'
+        return (mode, allowed_tools)
+    else:
+        assert_never(function_tool_choice)