pydantic-ai-slim 0.8.1__py3-none-any.whl → 1.0.0b1__py3-none-any.whl

pydantic_ai/retries.py

@@ -24,17 +24,17 @@ from httpx import (
 )
 
 try:
-    from tenacity import AsyncRetrying, RetryCallState, RetryError, Retrying, retry, wait_exponential
+    from tenacity import RetryCallState, RetryError, retry, wait_exponential
 except ImportError as _import_error:
     raise ImportError(
         'Please install `tenacity` to use the retries utilities, '
         'you can use the `retries` optional group — `pip install "pydantic-ai-slim[retries]"`'
     ) from _import_error
 
-from collections.abc import Awaitable
+from collections.abc import Awaitable, Callable
 from datetime import datetime, timezone
 from email.utils import parsedate_to_datetime
-from typing import TYPE_CHECKING, Any, Callable, NoReturn, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from typing_extensions import TypedDict
 
@@ -134,8 +134,9 @@ class TenacityTransport(BaseTransport):
 
     Example:
         ```python
-        from httpx import Client, HTTPTransport, HTTPStatusError
-        from tenacity import stop_after_attempt, retry_if_exception_type
+        from httpx import Client, HTTPStatusError, HTTPTransport
+        from tenacity import retry_if_exception_type, stop_after_attempt
+
         from pydantic_ai.retries import RetryConfig, TenacityTransport, wait_retry_after
 
         transport = TenacityTransport(
@@ -157,18 +158,7 @@ class TenacityTransport(BaseTransport):
         config: RetryConfig,
         wrapped: BaseTransport | None = None,
         validate_response: Callable[[Response], Any] | None = None,
-        **kwargs: NoReturn,
     ):
-        # TODO: Remove the following checks (and **kwargs) during v1 release
-        if 'controller' in kwargs:  # pragma: no cover
-            raise TypeError('The `controller` argument has been renamed to `config`, and now requires a `RetryConfig`.')
-        if kwargs:  # pragma: no cover
-            raise TypeError(f'Unexpected keyword arguments: {", ".join(kwargs)}')
-        if isinstance(config, Retrying):  # pragma: no cover
-            raise ValueError(
-                'Passing a Retrying instance is no longer supported; the `config` argument must be a `pydantic_ai.retries.RetryConfig`.'
-            )
-
         self.config = config
         self.wrapped = wrapped or HTTPTransport()
         self.validate_response = validate_response
@@ -224,7 +214,8 @@ class AsyncTenacityTransport(AsyncBaseTransport):
     Example:
         ```python
         from httpx import AsyncClient, HTTPStatusError
-        from tenacity import stop_after_attempt, retry_if_exception_type
+        from tenacity import retry_if_exception_type, stop_after_attempt
+
         from pydantic_ai.retries import AsyncTenacityTransport, RetryConfig, wait_retry_after
 
         transport = AsyncTenacityTransport(
@@ -245,18 +236,7 @@ class AsyncTenacityTransport(AsyncBaseTransport):
         config: RetryConfig,
         wrapped: AsyncBaseTransport | None = None,
         validate_response: Callable[[Response], Any] | None = None,
-        **kwargs: NoReturn,
     ):
-        # TODO: Remove the following checks (and **kwargs) during v1 release
-        if 'controller' in kwargs:  # pragma: no cover
-            raise TypeError('The `controller` argument has been renamed to `config`, and now requires a `RetryConfig`.')
-        if kwargs:  # pragma: no cover
-            raise TypeError(f'Unexpected keyword arguments: {", ".join(kwargs)}')
-        if isinstance(config, AsyncRetrying):  # pragma: no cover
-            raise ValueError(
-                'Passing an AsyncRetrying instance is no longer supported; the `config` argument must be a `pydantic_ai.retries.RetryConfig`.'
-            )
-
         self.config = config
         self.wrapped = wrapped or AsyncHTTPTransport()
         self.validate_response = validate_response
@@ -314,7 +294,8 @@ def wait_retry_after(
     Example:
         ```python
         from httpx import AsyncClient, HTTPStatusError
-        from tenacity import stop_after_attempt, retry_if_exception_type
+        from tenacity import retry_if_exception_type, stop_after_attempt
+
         from pydantic_ai.retries import AsyncTenacityTransport, RetryConfig, wait_retry_after
 
         transport = AsyncTenacityTransport(

pydantic_ai/run.py

@@ -3,9 +3,8 @@ from __future__ import annotations as _annotations
 import dataclasses
 from collections.abc import AsyncIterator
 from copy import deepcopy
-from typing import Any, Generic, overload
-
-from typing_extensions import Literal
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Generic, Literal, overload
 
 from pydantic_graph import End, GraphRun, GraphRunContext
 
@@ -16,9 +15,11 @@ from . import (
     usage as _usage,
 )
 from .output import OutputDataT
-from .result import FinalResult
 from .tools import AgentDepsT
 
+if TYPE_CHECKING:
+    from .result import FinalResult
+
 
 @dataclasses.dataclass(repr=False)
 class AgentRun(Generic[AgentDepsT, OutputDataT]):
@@ -100,7 +101,7 @@ class AgentRun(Generic[AgentDepsT, OutputDataT]):
     def ctx(self) -> GraphRunContext[_agent_graph.GraphAgentState, _agent_graph.GraphAgentDeps[AgentDepsT, Any]]:
         """The current context of the agent run."""
         return GraphRunContext[_agent_graph.GraphAgentState, _agent_graph.GraphAgentDeps[AgentDepsT, Any]](
-            self._graph_run.state, self._graph_run.deps
+            state=self._graph_run.state, deps=self._graph_run.deps
         )
 
     @property
@@ -348,3 +349,9 @@ class AgentRunResult(Generic[OutputDataT]):
     def usage(self) -> _usage.RunUsage:
         """Return the usage of the whole run."""
         return self._state.usage
+
+    def timestamp(self) -> datetime:
+        """Return the timestamp of last response."""
+        model_response = self.all_messages()[-1]
+        assert isinstance(model_response, _messages.ModelResponse)
+        return model_response.timestamp

pydantic_ai/tools.py

@@ -1,15 +1,18 @@
 from __future__ import annotations as _annotations
 
-from collections.abc import Awaitable, Sequence
-from dataclasses import dataclass, field
-from typing import Any, Callable, Generic, Literal, Union
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import KW_ONLY, dataclass, field, replace
+from typing import Annotated, Any, Concatenate, Generic, Literal, TypeAlias, cast
 
+from pydantic import Discriminator, Tag
 from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue
 from pydantic_core import SchemaValidator, core_schema
-from typing_extensions import Concatenate, ParamSpec, Self, TypeAlias, TypeVar
+from typing_extensions import ParamSpec, Self, TypeVar
 
 from . import _function_schema, _utils
 from ._run_context import AgentDepsT, RunContext
+from .exceptions import ModelRetry
+from .messages import RetryPromptPart, ToolCallPart, ToolReturn
 
 __all__ = (
     'AgentDepsT',
@@ -25,18 +28,22 @@ __all__ = (
     'Tool',
     'ObjectJsonSchema',
     'ToolDefinition',
+    'DeferredToolRequests',
+    'DeferredToolResults',
+    'ToolApproved',
+    'ToolDenied',
 )
 
 
 ToolParams = ParamSpec('ToolParams', default=...)
 """Retrieval function param spec."""
 
-SystemPromptFunc: TypeAlias = Union[
-    Callable[[RunContext[AgentDepsT]], str],
-    Callable[[RunContext[AgentDepsT]], Awaitable[str]],
-    Callable[[], str],
-    Callable[[], Awaitable[str]],
-]
+SystemPromptFunc: TypeAlias = (
+    Callable[[RunContext[AgentDepsT]], str]
+    | Callable[[RunContext[AgentDepsT]], Awaitable[str]]
+    | Callable[[], str]
+    | Callable[[], Awaitable[str]]
+)
 """A function that may or maybe not take `RunContext` as an argument, and may or may not be async.
 
 Usage `SystemPromptFunc[AgentDepsT]`.
@@ -52,7 +59,7 @@ ToolFuncPlain: TypeAlias = Callable[ToolParams, Any]
 
 Usage `ToolPlainFunc[ToolParams]`.
 """
-ToolFuncEither: TypeAlias = Union[ToolFuncContext[AgentDepsT, ToolParams], ToolFuncPlain[ToolParams]]
+ToolFuncEither: TypeAlias = ToolFuncContext[AgentDepsT, ToolParams] | ToolFuncPlain[ToolParams]
 """Either kind of tool function.
 
 This is just a union of [`ToolFuncContext`][pydantic_ai.tools.ToolFuncContext] and
@@ -68,14 +75,12 @@ See [tool docs](../tools.md#tool-prepare) for more information.
 Example — here `only_if_42` is valid as a `ToolPrepareFunc`:
 
 ```python {noqa="I001"}
-from typing import Union
-
 from pydantic_ai import RunContext, Tool
 from pydantic_ai.tools import ToolDefinition
 
 async def only_if_42(
     ctx: RunContext[int], tool_def: ToolDefinition
-) -> Union[ToolDefinition, None]:
+) -> ToolDefinition | None:
     if ctx.deps == 42:
         return tool_def
 
@@ -99,7 +104,6 @@ Example — here `turn_on_strict_if_openai` is valid as a `ToolsPrepareFunc`:
 
 ```python {noqa="I001"}
 from dataclasses import replace
-from typing import Union
 
 from pydantic_ai import Agent, RunContext
 from pydantic_ai.tools import ToolDefinition
@@ -107,7 +111,7 @@ from pydantic_ai.tools import ToolDefinition
 
 async def turn_on_strict_if_openai(
     ctx: RunContext[None], tool_defs: list[ToolDefinition]
-) -> Union[list[ToolDefinition], None]:
+) -> list[ToolDefinition] | None:
     if ctx.model.system == 'openai':
         return [replace(tool_def, strict=True) for tool_def in tool_defs]
     return tool_defs
@@ -127,6 +131,88 @@ DocstringFormat: TypeAlias = Literal['google', 'numpy', 'sphinx', 'auto']
 * `'auto'` — Automatically infer the format based on the structure of the docstring.
 """
 
+
+@dataclass(kw_only=True)
+class DeferredToolRequests:
+    """Tool calls that require approval or external execution.
+
+    This can be used as an agent's `output_type` and will be used as the output of the agent run if the model called any deferred tools.
+
+    Results can be passed to the next agent run using a [`DeferredToolResults`][pydantic_ai.tools.DeferredToolResults] object with the same tool call IDs.
+
+    See [deferred tools docs](../tools.md#deferred-tools) for more information.
+    """
+
+    calls: list[ToolCallPart] = field(default_factory=list)
+    """Tool calls that require external execution."""
+    approvals: list[ToolCallPart] = field(default_factory=list)
+    """Tool calls that require human-in-the-loop approval."""
+
+
+@dataclass(kw_only=True)
+class ToolApproved:
+    """Indicates that a tool call has been approved and that the tool function should be executed."""
+
+    override_args: dict[str, Any] | None = None
+    """Optional tool call arguments to use instead of the original arguments."""
+
+    kind: Literal['tool-approved'] = 'tool-approved'
+
+
+@dataclass
+class ToolDenied:
+    """Indicates that a tool call has been denied and that a denial message should be returned to the model."""
+
+    message: str = 'The tool call was denied.'
+    """The message to return to the model."""
+
+    _: KW_ONLY
+
+    kind: Literal['tool-denied'] = 'tool-denied'
+
+
+def _deferred_tool_call_result_discriminator(x: Any) -> str | None:
+    if isinstance(x, dict):
+        if 'kind' in x:
+            return cast(str, x['kind'])
+        elif 'part_kind' in x:
+            return cast(str, x['part_kind'])
+    else:
+        if hasattr(x, 'kind'):
+            return cast(str, x.kind)
+        elif hasattr(x, 'part_kind'):
+            return cast(str, x.part_kind)
+    return None
+
+
+DeferredToolApprovalResult: TypeAlias = Annotated[ToolApproved | ToolDenied, Discriminator('kind')]
+"""Result for a tool call that required human-in-the-loop approval."""
+DeferredToolCallResult: TypeAlias = Annotated[
+    Annotated[ToolReturn, Tag('tool-return')]
+    | Annotated[ModelRetry, Tag('model-retry')]
+    | Annotated[RetryPromptPart, Tag('retry-prompt')],
+    Discriminator(_deferred_tool_call_result_discriminator),
+]
+"""Result for a tool call that required external execution."""
+DeferredToolResult = DeferredToolApprovalResult | DeferredToolCallResult
+"""Result for a tool call that required approval or external execution."""
+
+
+@dataclass(kw_only=True)
+class DeferredToolResults:
+    """Results for deferred tool calls from a previous run that required approval or external execution.
+
+    The tool call IDs need to match those from the [`DeferredToolRequests`][pydantic_ai.output.DeferredToolRequests] output object from the previous run.
+
+    See [deferred tools docs](../tools.md#deferred-tools) for more information.
+    """
+
+    calls: dict[str, DeferredToolCallResult | Any] = field(default_factory=dict)
+    """Map of tool call IDs to results for tool calls that required external execution."""
+    approvals: dict[str, bool | DeferredToolApprovalResult] = field(default_factory=dict)
+    """Map of tool call IDs to results for tool calls that required human-in-the-loop approval."""
+
+
 A = TypeVar('A')
 
 
@@ -167,6 +253,7 @@ class Tool(Generic[AgentDepsT]):
     docstring_format: DocstringFormat
     require_parameter_descriptions: bool
     strict: bool | None
+    requires_approval: bool
     function_schema: _function_schema.FunctionSchema
     """
     The base JSON schema for the tool's parameters.
@@ -187,6 +274,7 @@ class Tool(Generic[AgentDepsT]):
         require_parameter_descriptions: bool = False,
         schema_generator: type[GenerateJsonSchema] = GenerateToolJsonSchema,
         strict: bool | None = None,
+        requires_approval: bool = False,
         function_schema: _function_schema.FunctionSchema | None = None,
     ):
         """Create a new tool instance.
@@ -205,7 +293,6 @@ class Tool(Generic[AgentDepsT]):
         or with a custom prepare method:
 
         ```python {noqa="I001"}
-        from typing import Union
 
         from pydantic_ai import Agent, RunContext, Tool
         from pydantic_ai.tools import ToolDefinition
@@ -215,7 +302,7 @@ class Tool(Generic[AgentDepsT]):
 
         async def prep_my_tool(
             ctx: RunContext[int], tool_def: ToolDefinition
-        ) -> Union[ToolDefinition, None]:
+        ) -> ToolDefinition | None:
             # only register the tool if `deps == 42`
             if ctx.deps == 42:
                 return tool_def
@@ -240,6 +327,8 @@ class Tool(Generic[AgentDepsT]):
             schema_generator: The JSON schema generator class to use. Defaults to `GenerateToolJsonSchema`.
             strict: Whether to enforce JSON schema compliance (only affects OpenAI).
                 See [`ToolDefinition`][pydantic_ai.tools.ToolDefinition] for more info.
+            requires_approval: Whether this tool requires human-in-the-loop approval. Defaults to False.
+                See the [tools documentation](../tools.md#human-in-the-loop-tool-approval) for more info.
             function_schema: The function schema to use for the tool. If not provided, it will be generated.
         """
         self.function = function
@@ -258,6 +347,7 @@ class Tool(Generic[AgentDepsT]):
         self.docstring_format = docstring_format
         self.require_parameter_descriptions = require_parameter_descriptions
         self.strict = strict
+        self.requires_approval = requires_approval
 
     @classmethod
     def from_schema(
@@ -320,6 +410,10 @@ class Tool(Generic[AgentDepsT]):
             return a `ToolDefinition` or `None` if the tools should not be registered for this run.
         """
         base_tool_def = self.tool_def
+
+        if self.requires_approval and not ctx.tool_call_approved:
+            base_tool_def = replace(base_tool_def, kind='unapproved')
+
         if self.prepare is not None:
             return await self.prepare(ctx, base_tool_def)
         else:
@@ -334,11 +428,11 @@ This type is used to define tools parameters (aka arguments) in [ToolDefinition]
 With PEP-728 this should be a TypedDict with `type: Literal['object']`, and `extra_parts=Any`
 """
 
-ToolKind: TypeAlias = Literal['function', 'output', 'deferred']
+ToolKind: TypeAlias = Literal['function', 'output', 'external', 'unapproved']
 """Kind of tool."""
 
 
-@dataclass(repr=False)
+@dataclass(repr=False, kw_only=True)
 class ToolDefinition:
     """Definition of a tool passed to a model.
 
@@ -377,8 +471,18 @@ class ToolDefinition:
 
     - `'function'`: a tool that will be executed by Pydantic AI during an agent run and has its result returned to the model
     - `'output'`: a tool that passes through an output value that ends the run
-    - `'deferred'`: a tool whose result will be produced outside of the Pydantic AI agent run in which it was called, because it depends on an upstream service (or user) or could take longer to generate than it's reasonable to keep the agent process running.
-        When the model calls a deferred tool, the agent run ends with a `DeferredToolCalls` object and a new run is expected to be started at a later point with the message history and new `ToolReturnPart`s corresponding to each deferred call.
+    - `'external'`: a tool whose result will be produced outside of the Pydantic AI agent run in which it was called, because it depends on an upstream service (or user) or could take longer to generate than it's reasonable to keep the agent process running.
+        See the [tools documentation](../tools.md#deferred-tools) for more info.
+    - `'unapproved'`: a tool that requires human-in-the-loop approval.
+        See the [tools documentation](../tools.md#human-in-the-loop-tool-approval) for more info.
     """
 
+    @property
+    def defer(self) -> bool:
+        """Whether calls to this tool will be deferred.
+
+        See the [tools documentation](../tools.md#deferred-tools) for more info.
+        """
+        return self.kind in ('external', 'unapproved')
+
     __repr__ = _utils.dataclasses_no_defaults_repr

pydantic_ai/toolsets/__init__.py

@@ -1,7 +1,8 @@
 from ._dynamic import ToolsetFunc
 from .abstract import AbstractToolset, ToolsetTool
+from .approval_required import ApprovalRequiredToolset
 from .combined import CombinedToolset
-from .deferred import DeferredToolset
+from .external import DeferredToolset, ExternalToolset  # pyright: ignore[reportDeprecated]
 from .filtered import FilteredToolset
 from .function import FunctionToolset
 from .prefixed import PrefixedToolset
@@ -14,6 +15,7 @@ __all__ = (
     'ToolsetFunc',
     'ToolsetTool',
     'CombinedToolset',
+    'ExternalToolset',
     'DeferredToolset',
     'FilteredToolset',
     'FunctionToolset',
@@ -21,4 +23,5 @@ __all__ = (
     'RenamedToolset',
     'PreparedToolset',
     'WrapperToolset',
+    'ApprovalRequiredToolset',
 )

pydantic_ai/toolsets/_dynamic.py

@@ -1,18 +1,18 @@
 from __future__ import annotations
 
 import inspect
-from collections.abc import Awaitable
+from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, replace
-from typing import Any, Callable, Union
+from typing import Any, TypeAlias
 
-from typing_extensions import Self, TypeAlias
+from typing_extensions import Self
 
 from .._run_context import AgentDepsT, RunContext
 from .abstract import AbstractToolset, ToolsetTool
 
 ToolsetFunc: TypeAlias = Callable[
     [RunContext[AgentDepsT]],
-    Union[AbstractToolset[AgentDepsT], None, Awaitable[Union[AbstractToolset[AgentDepsT], None]]],
+    AbstractToolset[AgentDepsT] | None | Awaitable[AbstractToolset[AgentDepsT] | None],
 ]
 """A sync/async function which takes a run context and returns a toolset."""
 

pydantic_ai/toolsets/abstract.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
+from collections.abc import Callable
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Callable, Generic, Literal, Protocol
+from typing import TYPE_CHECKING, Any, Generic, Literal, Protocol
 
 from pydantic_core import SchemaValidator
 from typing_extensions import Self
@@ -11,6 +12,7 @@ from .._run_context import AgentDepsT, RunContext
 from ..tools import ToolDefinition, ToolsPrepareFunc
 
 if TYPE_CHECKING:
+    from .approval_required import ApprovalRequiredToolset
     from .filtered import FilteredToolset
     from .prefixed import PrefixedToolset
     from .prepared import PreparedToolset
@@ -33,7 +35,7 @@ class SchemaValidatorProt(Protocol):
     ) -> Any: ...
 
 
-@dataclass
+@dataclass(kw_only=True)
 class ToolsetTool(Generic[AgentDepsT]):
     """Definition of a tool available on a toolset.
 
@@ -173,3 +175,17 @@ class AbstractToolset(ABC, Generic[AgentDepsT]):
         from .renamed import RenamedToolset
 
         return RenamedToolset(self, name_map)
+
+    def approval_required(
+        self,
+        approval_required_func: Callable[[RunContext[AgentDepsT], ToolDefinition, dict[str, Any]], bool] = (
+            lambda ctx, tool_def, tool_args: True
+        ),
+    ) -> ApprovalRequiredToolset[AgentDepsT]:
+        """Returns a new toolset that requires (some) calls to tools it contains to be approved.
+
+        See [toolset docs](../toolsets.md#requiring-tool-approval) for more information.
+        """
+        from .approval_required import ApprovalRequiredToolset
+
+        return ApprovalRequiredToolset(self, approval_required_func)

pydantic_ai/toolsets/approval_required.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic_ai.exceptions import ApprovalRequired
+
+from .._run_context import AgentDepsT, RunContext
+from ..tools import ToolDefinition
+from .abstract import ToolsetTool
+from .wrapper import WrapperToolset
+
+
+@dataclass
+class ApprovalRequiredToolset(WrapperToolset[AgentDepsT]):
+    """A toolset that requires (some) calls to tools it contains to be approved.
+
+    See [toolset docs](../toolsets.md#requiring-tool-approval) for more information.
+    """
+
+    approval_required_func: Callable[[RunContext[AgentDepsT], ToolDefinition, dict[str, Any]], bool] = (
+        lambda ctx, tool_def, tool_args: True
+    )
+
+    async def call_tool(
+        self, name: str, tool_args: dict[str, Any], ctx: RunContext[AgentDepsT], tool: ToolsetTool[AgentDepsT]
+    ) -> Any:
+        if not ctx.tool_call_approved and self.approval_required_func(ctx, tool.tool_def, tool_args):
+            raise ApprovalRequired
+
+        return await super().call_tool(name, tool_args, ctx, tool)

pydantic_ai/toolsets/combined.py

@@ -1,20 +1,20 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Sequence
+from collections.abc import Callable, Sequence
 from contextlib import AsyncExitStack
 from dataclasses import dataclass, field, replace
-from typing import Any, Callable
+from typing import Any
 
+import anyio
 from typing_extensions import Self
 
 from .._run_context import AgentDepsT, RunContext
-from .._utils import get_async_lock
 from ..exceptions import UserError
 from .abstract import AbstractToolset, ToolsetTool
 
 
-@dataclass
+@dataclass(kw_only=True)
 class _CombinedToolsetTool(ToolsetTool[AgentDepsT]):
     """A tool definition for a combined toolset tools that keeps track of the source toolset and tool."""
 
@@ -31,14 +31,9 @@ class CombinedToolset(AbstractToolset[AgentDepsT]):
 
     toolsets: Sequence[AbstractToolset[AgentDepsT]]
 
-    _enter_lock: asyncio.Lock = field(compare=False, init=False)
-    _entered_count: int = field(init=False)
-    _exit_stack: AsyncExitStack | None = field(init=False)
-
-    def __post_init__(self):
-        self._enter_lock = get_async_lock()
-        self._entered_count = 0
-        self._exit_stack = None
+    _enter_lock: anyio.Lock = field(compare=False, init=False, default_factory=anyio.Lock)
+    _entered_count: int = field(init=False, default=0)
+    _exit_stack: AsyncExitStack | None = field(init=False, default=None)
 
     @property
     def id(self) -> str | None:

pydantic_ai/toolsets/{deferred.py → external.py}

@@ -4,6 +4,7 @@ from dataclasses import replace
 from typing import Any
 
 from pydantic_core import SchemaValidator, core_schema
+from typing_extensions import deprecated
 
 from .._run_context import AgentDepsT, RunContext
 from ..tools import ToolDefinition
@@ -12,10 +13,10 @@ from .abstract import AbstractToolset, ToolsetTool
 TOOL_SCHEMA_VALIDATOR = SchemaValidator(schema=core_schema.any_schema())
 
 
-class DeferredToolset(AbstractToolset[AgentDepsT]):
-    """A toolset that holds deferred tools whose results will be produced outside of the Pydantic AI agent run in which they were called.
+class ExternalToolset(AbstractToolset[AgentDepsT]):
+    """A toolset that holds tools whose results will be produced outside of the Pydantic AI agent run in which they were called.
 
-    See [toolset docs](../toolsets.md#deferred-toolset), [`ToolDefinition.kind`][pydantic_ai.tools.ToolDefinition.kind], and [`DeferredToolCalls`][pydantic_ai.output.DeferredToolCalls] for more information.
+    See [toolset docs](../toolsets.md#external-toolset) for more information.
     """
 
     tool_defs: list[ToolDefinition]
@@ -33,7 +34,7 @@ class DeferredToolset(AbstractToolset[AgentDepsT]):
         return {
             tool_def.name: ToolsetTool(
                 toolset=self,
-                tool_def=replace(tool_def, kind='deferred'),
+                tool_def=replace(tool_def, kind='external'),
                 max_retries=0,
                 args_validator=TOOL_SCHEMA_VALIDATOR,
             )
@@ -43,4 +44,9 @@ class DeferredToolset(AbstractToolset[AgentDepsT]):
     async def call_tool(
         self, name: str, tool_args: dict[str, Any], ctx: RunContext[AgentDepsT], tool: ToolsetTool[AgentDepsT]
     ) -> Any:
-        raise NotImplementedError('Deferred tools cannot be called')
+        raise NotImplementedError('External tools cannot be called directly')
+
+
+@deprecated('`DeferredToolset` is deprecated, use `ExternalToolset` instead')
+class DeferredToolset(ExternalToolset):
+    """Deprecated alias for `ExternalToolset`."""

pydantic_ai/toolsets/filtered.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
+from collections.abc import Callable
 from dataclasses import dataclass
-from typing import Callable
 
 from .._run_context import AgentDepsT, RunContext
 from ..tools import ToolDefinition