Support returning resolved tools on the ModelRequest

Author: mwildehahn

pydantic_ai_slim/pydantic_ai/_agent_graph.py

@@ -495,6 +495,10 @@ async def _prepare_request(
 
         model_request_parameters = await _prepare_request_parameters(ctx)
 
+        # Populate tool tracking on the ModelRequest (the last request in the original history)
+        self.request.function_tools = model_request_parameters.function_tools
+        self.request.builtin_tools = model_request_parameters.builtin_tools
+
         model_settings = ctx.deps.model_settings
         usage = ctx.state.usage
         if ctx.deps.usage_limits.count_tokens_before_request:

pydantic_ai_slim/pydantic_ai/_tool_types.py

@@ -0,0 +1,80 @@
+from __future__ import annotations as _annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, TypeAlias
+
+from . import _utils
+
+ObjectJsonSchema: TypeAlias = dict[str, Any]
+"""Type representing JSON schema of an object, e.g. where `'type': 'object'`.
+
+This type is used to define tool parameters (aka arguments) in [`ToolDefinition`][pydantic_ai.tools.ToolDefinition].
+"""
+
+ToolKind: TypeAlias = Literal['function', 'output', 'external', 'unapproved']
+"""Kind of tool."""
+
+
+@dataclass(repr=False, kw_only=True)
+class ToolDefinition:
+    """Definition of a tool passed to a model.
+
+    This is used for both function tools and output tools.
+    """
+
+    name: str
+    """The name of the tool."""
+
+    parameters_json_schema: ObjectJsonSchema = field(default_factory=lambda: {'type': 'object', 'properties': {}})
+    """The JSON schema for the tool's parameters."""
+
+    description: str | None = None
+    """The description of the tool."""
+
+    outer_typed_dict_key: str | None = None
+    """The key in the outer [TypedDict] that wraps an output tool.
+
+    This will only be set for output tools which don't have an `object` JSON schema.
+    """
+
+    strict: bool | None = None
+    """Whether to enforce (vendor-specific) strict JSON schema validation for tool calls.
+
+    Setting this to `True` while using a supported model generally imposes some restrictions on the tool's JSON schema
+    in exchange for guaranteeing the API responses strictly match that schema.
+
+    When `False`, the model may be free to generate other properties or types (depending on the vendor).
+    When `None` (the default), the value will be inferred based on the compatibility of the parameters_json_schema.
+
+    Note: this is currently only supported by OpenAI models.
+    """
+
+    sequential: bool = False
+    """Whether this tool requires a sequential/serial execution environment."""
+
+    kind: ToolKind = field(default='function')
+    """The kind of tool:
+
+    - `'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
+    - `'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](../deferred-tools.md#deferred-tools) for more info.
+    - `'unapproved'`: a tool that requires human-in-the-loop approval.
+        See the [tools documentation](../deferred-tools.md#human-in-the-loop-tool-approval) for more info.
+    """
+
+    metadata: dict[str, Any] | None = None
+    """Tool metadata that can be set by the toolset this tool came from. It is not sent to the model, but can be used for filtering and tool behavior customization.
+
+    For MCP tools, this contains the `meta`, `annotations`, and `output_schema` fields from the tool definition.
+    """
+
+    @property
+    def defer(self) -> bool:
+        """Whether calls to this tool will be deferred.
+
+        See the [tools documentation](../deferred-tools.md#deferred-tools) for more info.
+        """
+        return self.kind in ('external', 'unapproved')
+
+    __repr__ = _utils.dataclasses_no_defaults_repr

pydantic_ai_slim/pydantic_ai/_utils.py

@@ -36,7 +36,7 @@
     from pydantic_graph import GraphRun, GraphRunResult
 
     from . import messages as _messages
-    from .tools import ObjectJsonSchema
+    from ._tool_types import ObjectJsonSchema
 
 _P = ParamSpec('_P')
 _R = TypeVar('_R')

pydantic_ai_slim/pydantic_ai/messages.py

@@ -16,7 +16,9 @@
 from typing_extensions import deprecated
 
 from . import _otel_messages, _utils
+from ._tool_types import ToolDefinition
 from ._utils import generate_tool_call_id as _generate_tool_call_id, now_utc as _now_utc
+from .builtin_tools import AbstractBuiltinTool
 from .exceptions import UnexpectedModelBehavior
 from .usage import RequestUsage
 
@@ -945,6 +947,22 @@ class ModelRequest:
     instructions: str | None = None
     """The instructions for the model."""
 
+    function_tools: Annotated[list[ToolDefinition] | None, pydantic.Field(exclude=True, repr=False)] = field(
+        default=None, repr=False
+    )
+    """Function tools that were available for this request.
+
+    Available for introspection during a run. This field is excluded from serialization.
+    """
+
+    builtin_tools: Annotated[list[AbstractBuiltinTool] | None, pydantic.Field(exclude=True, repr=False)] = field(
+        default=None, repr=False
+    )
+    """Builtin tools that were available for this request.
+
+    Available for introspection during a run. This field is excluded from serialization.
+    """
+
     kind: Literal['request'] = 'request'
     """Message type identifier, this is available on all parts as a discriminator."""
 

pydantic_ai_slim/pydantic_ai/tools.py

@@ -11,6 +11,7 @@
 
 from . import _function_schema, _utils
 from ._run_context import AgentDepsT, RunContext
+from ._tool_types import ObjectJsonSchema, ToolDefinition, ToolKind as _ToolKind
 from .exceptions import ModelRetry
 from .messages import RetryPromptPart, ToolCallPart, ToolReturn
 
@@ -28,12 +29,15 @@
     'Tool',
     'ObjectJsonSchema',
     'ToolDefinition',
+    'ToolKind',
     'DeferredToolRequests',
     'DeferredToolResults',
     'ToolApproved',
     'ToolDenied',
 )
 
+ToolKind = _ToolKind
+
 
 ToolParams = ParamSpec('ToolParams', default=...)
 """Retrieval function param spec."""
@@ -433,80 +437,3 @@ async def prepare_tool_def(self, ctx: RunContext[ToolAgentDepsT]) -> ToolDefinit
             return await self.prepare(ctx, base_tool_def)
         else:
             return base_tool_def
-
-
-ObjectJsonSchema: TypeAlias = dict[str, Any]
-"""Type representing JSON schema of an object, e.g. where `"type": "object"`.
-
-This type is used to define tools parameters (aka arguments) in [ToolDefinition][pydantic_ai.tools.ToolDefinition].
-
-With PEP-728 this should be a TypedDict with `type: Literal['object']`, and `extra_parts=Any`
-"""
-
-ToolKind: TypeAlias = Literal['function', 'output', 'external', 'unapproved']
-"""Kind of tool."""
-
-
-@dataclass(repr=False, kw_only=True)
-class ToolDefinition:
-    """Definition of a tool passed to a model.
-
-    This is used for both function tools and output tools.
-    """
-
-    name: str
-    """The name of the tool."""
-
-    parameters_json_schema: ObjectJsonSchema = field(default_factory=lambda: {'type': 'object', 'properties': {}})
-    """The JSON schema for the tool's parameters."""
-
-    description: str | None = None
-    """The description of the tool."""
-
-    outer_typed_dict_key: str | None = None
-    """The key in the outer [TypedDict] that wraps an output tool.
-
-    This will only be set for output tools which don't have an `object` JSON schema.
-    """
-
-    strict: bool | None = None
-    """Whether to enforce (vendor-specific) strict JSON schema validation for tool calls.
-
-    Setting this to `True` while using a supported model generally imposes some restrictions on the tool's JSON schema
-    in exchange for guaranteeing the API responses strictly match that schema.
-
-    When `False`, the model may be free to generate other properties or types (depending on the vendor).
-    When `None` (the default), the value will be inferred based on the compatibility of the parameters_json_schema.
-
-    Note: this is currently only supported by OpenAI models.
-    """
-
-    sequential: bool = False
-    """Whether this tool requires a sequential/serial execution environment."""
-
-    kind: ToolKind = field(default='function')
-    """The kind of tool:
-
-    - `'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
-    - `'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](../deferred-tools.md#deferred-tools) for more info.
-    - `'unapproved'`: a tool that requires human-in-the-loop approval.
-        See the [tools documentation](../deferred-tools.md#human-in-the-loop-tool-approval) for more info.
-    """
-
-    metadata: dict[str, Any] | None = None
-    """Tool metadata that can be set by the toolset this tool came from. It is not sent to the model, but can be used for filtering and tool behavior customization.
-
-    For MCP tools, this contains the `meta`, `annotations`, and `output_schema` fields from the tool definition.
-    """
-
-    @property
-    def defer(self) -> bool:
-        """Whether calls to this tool will be deferred.
-
-        See the [tools documentation](../deferred-tools.md#deferred-tools) for more info.
-        """
-        return self.kind in ('external', 'unapproved')
-
-    __repr__ = _utils.dataclasses_no_defaults_repr

tests/test_messages.py

@@ -1,6 +1,7 @@
 import sys
 from datetime import datetime, timezone
 
+from pydantic_ai.builtin_tools import ImageGenerationTool
 import pytest
 from inline_snapshot import snapshot
 from pydantic import TypeAdapter
@@ -26,6 +27,7 @@
     UserPromptPart,
     VideoUrl,
 )
+from pydantic_ai.models import ToolDefinition
 
 from .conftest import IsDatetime, IsNow, IsStr
 
@@ -404,7 +406,9 @@ def test_pre_usage_refactor_messages_deserializable():
                         content='What is the capital of Mexico?',
                         timestamp=IsNow(tz=timezone.utc),
                     )
-                ]
+                ],
+                function_tools=None,
+                builtin_tools=None,
             ),
             ModelResponse(
                 parts=[TextPart(content='Mexico City.')],
@@ -605,3 +609,28 @@ def test_binary_content_validation_with_optional_identifier():
             'identifier': 'foo',
         }
     )
+
+
+def test_model_request_tool_tracking_excluded_from_serialization():
+    """Test that function_tools and builtin_tools are not serialized in the request."""
+    tool_def = ToolDefinition(
+        name='test_tool',
+        description='A test tool',
+        parameters_json_schema={'type': 'object', 'properties': {}},
+    )
+
+    request = ModelRequest(
+        parts=[UserPromptPart('test prompt')],
+        instructions='test instructions',
+        function_tools=[tool_def],
+        builtin_tools=[ImageGenerationTool()],
+    )
+
+    # Verify the fields are accessible
+    assert request.function_tools == [tool_def]
+    assert request.builtin_tools == [ImageGenerationTool()]
+
+    # Serialize - fields ARE excluded
+    serialized = ModelMessagesTypeAdapter.dump_python([request], mode='json')
+    assert 'function_tools' not in serialized[0]
+    assert 'builtin_tools' not in serialized[0]