Document BuiltinOrLocalTool capability (#4828)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: DouweM

docs/capabilities.md

@@ -126,6 +126,15 @@ Constraint fields like `allowed_domains` or `blocked_domains` require the builti
 WebSearch(allowed_domains=['example.com'])
 ```
 
+All of these capabilities are subclasses of [`BuiltinOrLocalTool`][pydantic_ai.capabilities.BuiltinOrLocalTool], which you can use directly or subclass to build your own provider-adaptive tools. For example, to pair [`CodeExecutionTool`][pydantic_ai.builtin_tools.CodeExecutionTool] with a local fallback:
+
+```python {title="custom_builtin_or_local.py" test="skip" lint="skip"}
+from pydantic_ai.builtin_tools import CodeExecutionTool
+from pydantic_ai.capabilities import BuiltinOrLocalTool
+
+cap = BuiltinOrLocalTool(builtin=CodeExecutionTool(), local=my_local_executor)
+```
+
 ### PrepareTools
 
 [`PrepareTools`][pydantic_ai.capabilities.PrepareTools] wraps a [`ToolsPrepareFunc`][pydantic_ai.tools.ToolsPrepareFunc] as a capability, for filtering or modifying [tool definitions](tools.md) per step:

pydantic_ai_slim/pydantic_ai/agent/__init__.py

@@ -47,7 +47,7 @@
 from .._tool_manager import ParallelExecutionMode, ToolManager
 from ..builtin_tools import AbstractBuiltinTool
 from ..capabilities import AbstractCapability, CombinedCapability
-from ..capabilities.builtin_or_local import BuiltinTool as BuiltinToolCap
+from ..capabilities.builtin_tool import BuiltinTool as BuiltinToolCap
 from ..capabilities.history_processor import HistoryProcessor as HistoryProcessorCap
 from ..models.instrumented import InstrumentationSettings, InstrumentedModel, instrument_model
 from ..output import OutputDataT, OutputSpec, StructuredDict

pydantic_ai_slim/pydantic_ai/capabilities/__init__.py

@@ -12,7 +12,8 @@
     WrapToolExecuteHandler,
     WrapToolValidateHandler,
 )
-from .builtin_or_local import BuiltinOrLocalTool, BuiltinTool
+from .builtin_or_local import BuiltinOrLocalTool
+from .builtin_tool import BuiltinTool
 from .combined import CombinedCapability
 from .history_processor import HistoryProcessor
 from .hooks import Hooks, HookTimeoutError

pydantic_ai_slim/pydantic_ai/capabilities/abstract.py

@@ -197,17 +197,17 @@ async def wrap_run(
         *,
         handler: WrapRunHandler,
     ) -> AgentRunResult[Any]:
-        """Wraps the entire agent run. ``handler()`` executes the run.
+        """Wraps the entire agent run. `handler()` executes the run.
 
-        If ``handler()`` raises and this method catches the exception and
+        If `handler()` raises and this method catches the exception and
         returns a result instead, the error is suppressed and the recovery
         result is used.
 
-        If this method does not call ``handler()`` (short-circuit), the run
+        If this method does not call `handler()` (short-circuit), the run
         is skipped and the returned result is used directly.
 
         Note: if the caller cancels the run (e.g. by breaking out of an
-        ``iter()`` loop), this method receives an :class:`asyncio.CancelledError`.
+        `iter()` loop), this method receives an :class:`asyncio.CancelledError`.
         Implementations that hold resources should handle cleanup accordingly.
         """
         return await handler()
@@ -222,15 +222,15 @@ async def on_run_error(
 
         This is the error counterpart to
         [`after_run`][pydantic_ai.capabilities.AbstractCapability.after_run]:
-        while ``after_run`` is called on success, ``on_run_error`` is called on
+        while `after_run` is called on success, `on_run_error` is called on
         failure (after [`wrap_run`][pydantic_ai.capabilities.AbstractCapability.wrap_run]
         has had its chance to recover).
 
-        **Raise** the original ``error`` (or a different exception) to propagate it.
+        **Raise** the original `error` (or a different exception) to propagate it.
         **Return** an [`AgentRunResult`][pydantic_ai.run.AgentRunResult] to suppress
         the error and recover the run.
 
-        Not called for ``GeneratorExit`` or ``KeyboardInterrupt``.
+        Not called for `GeneratorExit` or `KeyboardInterrupt`.
         """
         raise error
 
@@ -252,7 +252,7 @@ async def after_node_run(
         node: AgentNode[AgentDepsT],
         result: NodeResult[AgentDepsT],
     ) -> NodeResult[AgentDepsT]:
-        """Called after each graph node succeeds. Can modify the result (next node or ``End``)."""
+        """Called after each graph node succeeds. Can modify the result (next node or `End`)."""
         return result
 
     async def wrap_node_run(
@@ -299,8 +299,8 @@ async def on_node_run_error(
         This is the error counterpart to
         [`after_node_run`][pydantic_ai.capabilities.AbstractCapability.after_node_run].
 
-        **Raise** the original ``error`` (or a different exception) to propagate it.
-        **Return** a next node or ``End`` to recover and continue the graph.
+        **Raise** the original `error` (or a different exception) to propagate it.
+        **Return** a next node or `End` to recover and continue the graph.
 
         Useful for recovering from
         [`UnexpectedModelBehavior`][pydantic_ai.exceptions.UnexpectedModelBehavior]
@@ -362,7 +362,7 @@ async def on_model_request_error(
         This is the error counterpart to
         [`after_model_request`][pydantic_ai.capabilities.AbstractCapability.after_model_request].
 
-        **Raise** the original ``error`` (or a different exception) to propagate it.
+        **Raise** the original `error` (or a different exception) to propagate it.
         **Return** a [`ModelResponse`][pydantic_ai.messages.ModelResponse] to suppress
         the error and use the response as if the model call succeeded.
 
@@ -422,7 +422,7 @@ async def on_tool_validate_error(
         Fires for [`ValidationError`][pydantic.ValidationError] (schema mismatch) and
         [`ModelRetry`][pydantic_ai.exceptions.ModelRetry] (custom validator rejection).
 
-        **Raise** the original ``error`` (or a different exception) to propagate it.
+        **Raise** the original `error` (or a different exception) to propagate it.
         **Return** validated args to suppress the error and continue as if validation passed.
 
         Not called for [`SkipToolValidation`][pydantic_ai.exceptions.SkipToolValidation].
@@ -480,7 +480,7 @@ async def on_tool_execute_error(
         This is the error counterpart to
         [`after_tool_execute`][pydantic_ai.capabilities.AbstractCapability.after_tool_execute].
 
-        **Raise** the original ``error`` (or a different exception) to propagate it.
+        **Raise** the original `error` (or a different exception) to propagate it.
         **Return** any value to suppress the error and use it as the tool result.
 
         Not called for control flow exceptions

pydantic_ai_slim/pydantic_ai/capabilities/builtin_or_local.py

@@ -4,55 +4,15 @@
 from dataclasses import dataclass, replace
 from typing import Any, Literal
 
-import pydantic
-
 from pydantic_ai.builtin_tools import AbstractBuiltinTool
 from pydantic_ai.exceptions import UserError
 from pydantic_ai.tools import AgentBuiltinTool, AgentDepsT, RunContext, Tool, ToolDefinition
 from pydantic_ai.toolsets import AbstractToolset
+from pydantic_ai.toolsets.function import FunctionToolset
+from pydantic_ai.toolsets.prepared import PreparedToolset
 
 from .abstract import AbstractCapability
 
-_BUILTIN_TOOL_ADAPTER = pydantic.TypeAdapter(AbstractBuiltinTool)
-
-
-@dataclass
-class BuiltinTool(AbstractCapability[AgentDepsT]):
-    """A capability that registers a builtin tool with the agent.
-
-    Wraps a single [`AgentBuiltinTool`][pydantic_ai.tools.AgentBuiltinTool] — either a static
-    [`AbstractBuiltinTool`][pydantic_ai.builtin_tools.AbstractBuiltinTool] instance or a callable
-    that dynamically produces one.
-
-    When `builtin_tools` is passed to [`Agent.__init__`][pydantic_ai.Agent.__init__], each item is
-    automatically wrapped in a `BuiltinTool` capability.
-    """
-
-    tool: AgentBuiltinTool[AgentDepsT]
-
-    def get_builtin_tools(self) -> Sequence[AgentBuiltinTool[AgentDepsT]]:
-        return [self.tool]
-
-    @classmethod
-    def from_spec(cls, tool: AbstractBuiltinTool | None = None, **kwargs: Any) -> BuiltinTool[Any]:
-        """Create from spec.
-
-        Supports two YAML forms:
-
-        - Flat: `{BuiltinTool: {kind: web_search, search_context_size: high}}`
-        - Explicit: `{BuiltinTool: {tool: {kind: web_search}}}`
-        """
-        if tool is not None:
-            validated = _BUILTIN_TOOL_ADAPTER.validate_python(tool)
-        elif kwargs:
-            validated = _BUILTIN_TOOL_ADAPTER.validate_python(kwargs)
-        else:
-            raise TypeError(
-                '`BuiltinTool.from_spec()` requires either a `tool` argument or keyword arguments'
-                ' specifying the builtin tool type (e.g. `kind="web_search"`)'
-            )
-        return cls(tool=validated)
-
 
 @dataclass
 class BuiltinOrLocalTool(AbstractCapability[AgentDepsT]):
@@ -61,8 +21,20 @@ class BuiltinOrLocalTool(AbstractCapability[AgentDepsT]):
     When the model supports the builtin natively, the local fallback is removed.
     When the model doesn't support the builtin, it is removed and the local tool stays.
 
-    Can be used directly by providing `builtin` and `local` arguments, or subclassed
-    to set defaults via `_default_builtin`, `_default_local`, and `_requires_builtin`.
+    Can be used directly:
+
+    ```python {test="skip" lint="skip"}
+    from pydantic_ai.capabilities import BuiltinOrLocalTool
+
+    cap = BuiltinOrLocalTool(builtin=WebSearchTool(), local=my_search_func)
+    ```
+
+    Or subclassed to set defaults by overriding `_default_builtin`, `_default_local`,
+    and `_requires_builtin`.
+    The built-in [`WebSearch`][pydantic_ai.capabilities.WebSearch],
+    [`WebFetch`][pydantic_ai.capabilities.WebFetch], and
+    [`ImageGeneration`][pydantic_ai.capabilities.ImageGeneration] capabilities
+    are all subclasses.
     """
 
     builtin: AgentBuiltinTool[AgentDepsT] | bool = True
@@ -159,9 +131,6 @@ def get_toolset(self) -> AbstractToolset[AgentDepsT] | None:
         if local is None or local is False or self._requires_builtin():
             return None
 
-        from pydantic_ai.toolsets.function import FunctionToolset
-        from pydantic_ai.toolsets.prepared import PreparedToolset
-
         # local is Tool | AbstractToolset after __post_init__ resolution
         toolset: AbstractToolset[AgentDepsT] = local if isinstance(local, AbstractToolset) else FunctionToolset([local])  # pyright: ignore[reportUnknownVariableType]
 

pydantic_ai_slim/pydantic_ai/capabilities/builtin_tool.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any
+
+import pydantic
+
+from pydantic_ai.builtin_tools import AbstractBuiltinTool
+from pydantic_ai.tools import AgentBuiltinTool, AgentDepsT
+
+from .abstract import AbstractCapability
+
+_BUILTIN_TOOL_ADAPTER = pydantic.TypeAdapter(AbstractBuiltinTool)
+
+
+@dataclass
+class BuiltinTool(AbstractCapability[AgentDepsT]):
+    """A capability that registers a builtin tool with the agent.
+
+    Wraps a single [`AgentBuiltinTool`][pydantic_ai.tools.AgentBuiltinTool] — either a static
+    [`AbstractBuiltinTool`][pydantic_ai.builtin_tools.AbstractBuiltinTool] instance or a callable
+    that dynamically produces one.
+
+    When `builtin_tools` is passed to [`Agent.__init__`][pydantic_ai.Agent.__init__], each item is
+    automatically wrapped in a `BuiltinTool` capability.
+    """
+
+    tool: AgentBuiltinTool[AgentDepsT]
+
+    def get_builtin_tools(self) -> Sequence[AgentBuiltinTool[AgentDepsT]]:
+        return [self.tool]
+
+    @classmethod
+    def from_spec(cls, tool: AbstractBuiltinTool | None = None, **kwargs: Any) -> BuiltinTool[Any]:
+        """Create from spec.
+
+        Supports two YAML forms:
+
+        - Flat: `{BuiltinTool: {kind: web_search, search_context_size: high}}`
+        - Explicit: `{BuiltinTool: {tool: {kind: web_search}}}`
+        """
+        if tool is not None:
+            validated = _BUILTIN_TOOL_ADAPTER.validate_python(tool)
+        elif kwargs:
+            validated = _BUILTIN_TOOL_ADAPTER.validate_python(kwargs)
+        else:
+            raise TypeError(
+                '`BuiltinTool.from_spec()` requires either a `tool` argument or keyword arguments'
+                ' specifying the builtin tool type (e.g. `kind="web_search"`)'
+            )
+        return cls(tool=validated)

pydantic_ai_slim/pydantic_ai/capabilities/hooks.py

@@ -267,7 +267,7 @@ def decorator(f: _FuncT) -> _FuncT:
 class _HookRegistration(Generic[AgentDepsT]):
     """Decorator namespace for registering hooks on a :class:`Hooks` instance.
 
-    Accessed via ``hooks.on``. Each method corresponds to a lifecycle hook and
+    Accessed via `hooks.on`. Each method corresponds to a lifecycle hook and
     can be used as a bare decorator or a parameterized decorator::
 
         @hooks.on.before_model_request
@@ -355,7 +355,7 @@ def node_run_error(self, func: OnNodeRunErrorHookFunc | None = None, *, timeout:
     # --- Event stream ---
 
     def run_event_stream(self, func: WrapRunEventStreamHookFunc, /) -> WrapRunEventStreamHookFunc:
-        """Register a ``wrap_run_event_stream`` hook. Timeout not supported for stream wrappers."""
+        """Register a `wrap_run_event_stream` hook. Timeout not supported for stream wrappers."""
         self._r.setdefault('wrap_run_event_stream', []).append(_HookEntry(func))
         return func
 
@@ -554,7 +554,7 @@ class Hooks(AbstractCapability[AgentDepsT]):
 
     For extension developers building reusable capabilities, subclass
     :class:`AbstractCapability` directly. For application code that needs
-    a few hooks without the ceremony of a subclass, use ``Hooks``.
+    a few hooks without the ceremony of a subclass, use `Hooks`.
 
     Example using decorators::
 

pydantic_ai_slim/pydantic_ai/capabilities/prefix_tools.py

@@ -5,6 +5,7 @@
 
 from pydantic_ai.tools import AgentDepsT
 from pydantic_ai.toolsets import AbstractToolset, AgentToolset
+from pydantic_ai.toolsets._dynamic import DynamicToolset
 from pydantic_ai.toolsets.prefixed import PrefixedToolset
 
 from .wrapper import WrapperCapability
@@ -46,8 +47,8 @@ def from_spec(cls, *, prefix: str, capability: dict[str, Any] | str) -> PrefixTo
         """Create from spec with a nested capability specification.
 
         Args:
-            prefix: The prefix to add to tool names (e.g. ``'mcp'`` turns ``'search'`` into ``'mcp_search'``).
-            capability: A capability spec (same format as entries in the ``capabilities`` list).
+            prefix: The prefix to add to tool names (e.g. `'mcp'` turns `'search'` into `'mcp_search'`).
+            capability: A capability spec (same format as entries in the `capabilities` list).
         """
         from pydantic_ai.agent.spec import load_capability_from_nested_spec
 
@@ -62,6 +63,4 @@ def get_toolset(self) -> AgentToolset[AgentDepsT] | None:
             # Pyright can't narrow Callable type aliases out of unions after isinstance check
             return PrefixedToolset(toolset, prefix=self.prefix)  # pyright: ignore[reportUnknownArgumentType]
         # ToolsetFunc callable — wrap in DynamicToolset so PrefixedToolset can delegate
-        from pydantic_ai.toolsets._dynamic import DynamicToolset
-
         return PrefixedToolset(DynamicToolset[AgentDepsT](toolset_func=toolset), prefix=self.prefix)

pydantic_ai_slim/pydantic_ai/capabilities/thinking.py

@@ -12,18 +12,18 @@
 class Thinking(AbstractCapability[AgentDepsT]):
     """Enables and configures model thinking/reasoning.
 
-    Uses the unified ``thinking`` setting in
+    Uses the unified `thinking` setting in
     [`ModelSettings`][pydantic_ai.settings.ModelSettings] to work portably across providers.
-    Provider-specific thinking settings (e.g., ``anthropic_thinking``,
-    ``openai_reasoning_effort``) take precedence when both are set.
+    Provider-specific thinking settings (e.g., `anthropic_thinking`,
+    `openai_reasoning_effort`) take precedence when both are set.
     """
 
     effort: ThinkingLevel = True
     """The thinking effort level.
 
-    - ``True``: Enable thinking with the provider's default effort.
-    - ``False``: Disable thinking (silently ignored on always-on models).
-    - ``'minimal'``/``'low'``/``'medium'``/``'high'``/``'xhigh'``: Enable thinking at a specific effort level.
+    - `True`: Enable thinking with the provider's default effort.
+    - `False`: Disable thinking (silently ignored on always-on models).
+    - `'minimal'`/`'low'`/`'medium'`/`'high'`/`'xhigh'`: Enable thinking at a specific effort level.
     """
 
     def get_model_settings(self) -> _ModelSettings | None:

pydantic_ai_slim/pydantic_ai/models/bedrock.py

@@ -49,7 +49,7 @@
 from pydantic_ai.profiles.openai import OPENAI_REASONING_EFFORT_MAP
 from pydantic_ai.providers import Provider, infer_provider
 from pydantic_ai.providers.bedrock import BedrockModelProfile, remove_bedrock_geo_prefix
-from pydantic_ai.settings import ModelSettings
+from pydantic_ai.settings import ModelSettings, ThinkingLevel
 from pydantic_ai.tools import ToolDefinition
 
 if TYPE_CHECKING:
@@ -590,8 +590,6 @@ def _get_thinking_fields(
         elif variant == 'qwen' and 'reasoning_config' not in existing:
             if thinking is not False:
                 # Qwen only supports low/high; map others to closest
-                from ..settings import ThinkingLevel
-
                 level_map: dict[ThinkingLevel, str] = {
                     True: 'high',
                     'minimal': 'low',