Rename pending tools to deferred tools

pydantic · DouweM · Jul 16, 2025 · Jun 3, 2025 · Jun 3, 2025 · Jun 3, 2025
commit c1115aece71a36f9c51f24e7f8a086c75d5d7630
diff --git a/pydantic_ai_slim/pydantic_ai/_agent_graph.py b/pydantic_ai_slim/pydantic_ai/_agent_graph.py
@@ -22,7 +22,7 @@
 from pydantic_graph.nodes import End, NodeRunEndT
 
 from . import _output, _system_prompt, exceptions, messages as _messages, models, result, usage as _usage
-from .output import OutputDataT, OutputSpec, PendingToolCalls
+from .output import DeferredToolCalls, OutputDataT, OutputSpec
 from .settings import ModelSettings, merge_model_settings
 from .tools import RunContext, ToolDefinition, ToolKind
 
@@ -549,8 +549,8 @@ async def _handle_tool_calls(  # noqa: C901
             ):
                 yield event
 
-        pending_calls: list[_messages.ToolCallPart] = []
-        for call in tool_calls_by_kind['pending']:
+        deferred_calls: list[_messages.ToolCallPart] = []
+        for call in tool_calls_by_kind['deferred']:
             if final_result:
                 parts.append(
                     _messages.ToolReturnPart(
@@ -561,19 +561,19 @@ async def _handle_tool_calls(  # noqa: C901
                 )
             else:
                 yield _messages.FunctionToolCallEvent(call)
-                pending_calls.append(call)
+                deferred_calls.append(call)
 
-        if pending_calls:
-            if not ctx.deps.output_schema.pending_tool_calls:
+        if deferred_calls:
+            if not ctx.deps.output_schema.deferred_tool_calls:
                 raise exceptions.UserError(
-                    'There are pending tool calls but PendingToolCalls is not among output types.'
+                    'There are pending tool calls but DeferredToolCalls is not among output types.'
                 )
 
-            pending_tool_names = [call.tool_name for call in pending_calls]
-            pending_tool_defs = {
-                tool_def.name: tool_def for tool_def in toolset.tool_defs if tool_def.name in pending_tool_names
+            deferred_tool_names = [call.tool_name for call in deferred_calls]
+            deferred_tool_defs = {
+                tool_def.name: tool_def for tool_def in toolset.tool_defs if tool_def.name in deferred_tool_names
             }
-            output_data = cast(NodeRunEndT, PendingToolCalls(pending_calls, pending_tool_defs))
+            output_data = cast(NodeRunEndT, DeferredToolCalls(deferred_calls, deferred_tool_defs))
             final_result = result.FinalResult(output_data)
 
         if final_result:

diff --git a/pydantic_ai_slim/pydantic_ai/_output.py b/pydantic_ai_slim/pydantic_ai/_output.py
@@ -15,12 +15,12 @@
 from ._run_context import AgentDepsT, RunContext
 from .exceptions import ModelRetry, UserError
 from .output import (
+    DeferredToolCalls,
     ModelStructuredOutput,
     OutputDataT,
     OutputMode,
     OutputSpec,
     OutputTypeOrFunction,
-    PendingToolCalls,
     PromptedStructuredOutput,
     StructuredOutputMode,
     TextOutput,
@@ -129,7 +129,7 @@ async def validate(
 
 @dataclass
 class BaseOutputSchema(ABC, Generic[OutputDataT]):
-    pending_tool_calls: bool
+    deferred_tool_calls: bool
 
     @abstractmethod
     def with_default_mode(self, mode: StructuredOutputMode) -> OutputSchema[OutputDataT]:
@@ -182,8 +182,8 @@ def build(  # noqa: C901
         """Build an OutputSchema dataclass from an output type."""
         raw_outputs = _flatten_output_spec(output_spec)
 
-        outputs = [output for output in raw_outputs if output is not PendingToolCalls]
-        pending_tool_calls = len(outputs) < len(raw_outputs)
+        outputs = [output for output in raw_outputs if output is not DeferredToolCalls]
+        deferred_tool_calls = len(outputs) < len(raw_outputs)
         if output := next((output for output in outputs if isinstance(output, ModelStructuredOutput)), None):
             if len(outputs) > 1:
                 raise UserError('ModelStructuredOutput cannot be mixed with other output types.')
@@ -194,7 +194,7 @@ def build(  # noqa: C901
                     name=output.name,
                     description=output.description,
                 ),
-                pending_tool_calls=pending_tool_calls,
+                deferred_tool_calls=deferred_tool_calls,
             )
         elif output := next((output for output in outputs if isinstance(output, PromptedStructuredOutput)), None):
             if len(outputs) > 1:
@@ -207,7 +207,7 @@ def build(  # noqa: C901
                     description=output.description,
                 ),
                 template=output.template,
-                pending_tool_calls=pending_tool_calls,
+                deferred_tool_calls=deferred_tool_calls,
             )
 
         text_outputs: Sequence[type[str] | TextOutput[OutputDataT]] = []
@@ -240,20 +240,20 @@ def build(  # noqa: C901
                 text_output_schema = PlainTextOutputProcessor(text_output.output_function)
 
             if len(tools) == 0:
-                return PlainTextOutputSchema(processor=text_output_schema, pending_tool_calls=pending_tool_calls)
+                return PlainTextOutputSchema(processor=text_output_schema, deferred_tool_calls=deferred_tool_calls)
             else:
                 return ToolOrTextOutputSchema(
-                    processor=text_output_schema, tools=tools, pending_tool_calls=pending_tool_calls
+                    processor=text_output_schema, tools=tools, deferred_tool_calls=deferred_tool_calls
                 )
 
         if len(tool_outputs) > 0:
-            return ToolOutputSchema(tools=tools, pending_tool_calls=pending_tool_calls)
+            return ToolOutputSchema(tools=tools, deferred_tool_calls=deferred_tool_calls)
 
         if len(other_outputs) > 0:
             schema = OutputSchemaWithoutMode(
                 processor=cls._build_processor(other_outputs, name=name, description=description, strict=strict),
                 tools=tools,
-                pending_tool_calls=pending_tool_calls,
+                deferred_tool_calls=deferred_tool_calls,
             )
             if default_mode:
                 schema = schema.with_default_mode(default_mode)
@@ -343,19 +343,21 @@ def __init__(
         self,
         processor: ObjectOutputProcessor[OutputDataT] | UnionOutputProcessor[OutputDataT],
         tools: dict[str, OutputTool[OutputDataT]],
-        pending_tool_calls: bool,
+        deferred_tool_calls: bool,
     ):
-        super().__init__(pending_tool_calls)
+        super().__init__(deferred_tool_calls)
         self.processor = processor
         self._tools = tools
 
     def with_default_mode(self, mode: StructuredOutputMode) -> OutputSchema[OutputDataT]:
         if mode == 'model_structured':
-            return ModelStructuredOutputSchema(processor=self.processor, pending_tool_calls=self.pending_tool_calls)
+            return ModelStructuredOutputSchema(processor=self.processor, deferred_tool_calls=self.deferred_tool_calls)
         elif mode == 'prompted_structured':
-            return PromptedStructuredOutputSchema(processor=self.processor, pending_tool_calls=self.pending_tool_calls)
+            return PromptedStructuredOutputSchema(
+                processor=self.processor, deferred_tool_calls=self.deferred_tool_calls
+            )
         elif mode == 'tool':
-            return ToolOutputSchema(tools=self.tools, pending_tool_calls=self.pending_tool_calls)
+            return ToolOutputSchema(tools=self.tools, deferred_tool_calls=self.deferred_tool_calls)
         else:
             assert_never(mode)
 
@@ -517,8 +519,8 @@ async def process(
 class ToolOutputSchema(OutputSchema[OutputDataT]):
     _tools: dict[str, OutputTool[OutputDataT]] = field(default_factory=dict)
 
-    def __init__(self, tools: dict[str, OutputTool[OutputDataT]], pending_tool_calls: bool):
-        super().__init__(pending_tool_calls)
+    def __init__(self, tools: dict[str, OutputTool[OutputDataT]], deferred_tool_calls: bool):
+        super().__init__(deferred_tool_calls)
         self._tools = tools
 
     @property
@@ -561,9 +563,9 @@ def __init__(
         self,
         processor: PlainTextOutputProcessor[OutputDataT] | None,
         tools: dict[str, OutputTool[OutputDataT]],
-        pending_tool_calls: bool,
+        deferred_tool_calls: bool,
     ):
-        super().__init__(tools=tools, pending_tool_calls=pending_tool_calls)
+        super().__init__(tools=tools, deferred_tool_calls=deferred_tool_calls)
         self.processor = processor
 
     @property

diff --git a/pydantic_ai_slim/pydantic_ai/output.py b/pydantic_ai_slim/pydantic_ai/output.py
@@ -233,7 +233,7 @@ def split_into_words(text: str) -> list[str]:
 
 
 @dataclass
-class PendingToolCalls:
+class DeferredToolCalls:
     """Output type for calls to tools defined as pending."""

     tool_calls: list[ToolCallPart]

diff --git a/pydantic_ai_slim/pydantic_ai/tools.py b/pydantic_ai_slim/pydantic_ai/tools.py
@@ -324,7 +324,7 @@ async def prepare_tool_def(self, ctx: RunContext[AgentDepsT]) -> ToolDefinition
 With PEP-728 this should be a TypedDict with `type: Literal['object']`, and `extra_parts=Any`
 """
 
-ToolKind: TypeAlias = Literal['function', 'output', 'pending']
+ToolKind: TypeAlias = Literal['function', 'output', 'deferred']
 """Kind of tool."""
 
 

diff --git a/tests/test_tools.py b/tests/test_tools.py
@@ -16,7 +16,7 @@
 from pydantic_ai.messages import ModelMessage, ModelRequest, ModelResponse, TextPart, ToolCallPart, ToolReturnPart
 from pydantic_ai.models.function import AgentInfo, FunctionModel
 from pydantic_ai.models.test import TestModel
-from pydantic_ai.output import PendingToolCalls, ToolOutput
+from pydantic_ai.output import DeferredToolCalls, ToolOutput
 from pydantic_ai.tools import ToolDefinition
 
 from .conftest import IsStr
@@ -1180,19 +1180,19 @@ def infinite_retry_tool(ctx: RunContext[None]) -> int:
     assert call_retries == [0, 1, 2, 3, 4, 5]
 
 
-def test_pending_tool():
-    agent = Agent(TestModel(), output_type=[str, PendingToolCalls])
+def test_deferred_tool():
+    agent = Agent(TestModel(), output_type=[str, DeferredToolCalls])
 
     async def prepare_tool(ctx: RunContext[None], tool_def: ToolDefinition) -> ToolDefinition:
-        return replace(tool_def, kind='pending')
+        return replace(tool_def, kind='deferred')
 
     @agent.tool_plain(prepare=prepare_tool)
     def my_tool(x: int) -> int:
         return x + 1
 
     result = agent.run_sync('Hello')
     assert result.output == snapshot(
-        PendingToolCalls(
+        DeferredToolCalls(
             tool_calls=[ToolCallPart(tool_name='my_tool', args={'x': 0}, tool_call_id=IsStr())],
             tool_defs={
                 'my_tool': ToolDefinition(
@@ -1204,7 +1204,7 @@ def my_tool(x: int) -> int:
                         'required': ['x'],
                         'type': 'object',
                     },
-                    kind='pending',
+                    kind='deferred',
                 )
             },
         )