pydantic-ai-slim 1.0.7__py3-none-any.whl → 1.0.9__py3-none-any.whl

pydantic_ai/_agent_graph.py

@@ -8,6 +8,7 @@ from collections import defaultdict, deque
 from collections.abc import AsyncIterator, Awaitable, Callable, Iterator, Sequence
 from contextlib import asynccontextmanager, contextmanager
 from contextvars import ContextVar
+from copy import deepcopy
 from dataclasses import field, replace
 from typing import TYPE_CHECKING, Any, Generic, Literal, TypeGuard, cast
 
@@ -186,9 +187,8 @@ class UserPromptNode(AgentNode[DepsT, NodeRunEndT]):
                 messages = ctx_messages.messages
                 ctx_messages.used = True
 
-        message_history = _clean_message_history(ctx.state.message_history)
-        # Add message history to the `capture_run_messages` list, which will be empty at this point
-        messages.extend(message_history)
+        # Replace the `capture_run_messages` list with the message history
+        messages[:] = _clean_message_history(ctx.state.message_history)
         # Use the `capture_run_messages` list as the message history so that new messages are added to it
         ctx.state.message_history = messages
         ctx.deps.new_message_index = len(messages)
@@ -455,7 +455,18 @@ class ModelRequestNode(AgentNode[DepsT, NodeRunEndT]):
         # This will raise errors for any tool name conflicts
         ctx.deps.tool_manager = await ctx.deps.tool_manager.for_run_step(run_context)
 
-        message_history = await _process_message_history(ctx.state, ctx.deps.history_processors, run_context)
+        original_history = ctx.state.message_history[:]
+        message_history = await _process_message_history(original_history, ctx.deps.history_processors, run_context)
+        # Never merge the new `ModelRequest` with the one preceding it, to keep `new_messages()` from accidentally including part of the existing message history
+        message_history = [*_clean_message_history(message_history[:-1]), message_history[-1]]
+        # `ctx.state.message_history` is the same list used by `capture_run_messages`, so we should replace its contents, not the reference
+        ctx.state.message_history[:] = message_history
+        # Update the new message index to ensure `result.new_messages()` returns the correct messages
+        ctx.deps.new_message_index -= len(original_history) - len(message_history)
+
+        # Do one more cleaning pass to merge possible consecutive trailing `ModelRequest`s into one, with tool call parts before user parts,
+        # but don't store it in the message history on state.
+        # See `tests/test_tools.py::test_parallel_tool_return_with_deferred` for an example where this is necessary
         message_history = _clean_message_history(message_history)
 
         model_request_parameters = await _prepare_request_parameters(ctx)
@@ -465,7 +476,7 @@ class ModelRequestNode(AgentNode[DepsT, NodeRunEndT]):
         usage = ctx.state.usage
         if ctx.deps.usage_limits.count_tokens_before_request:
             # Copy to avoid modifying the original usage object with the counted usage
-            usage = dataclasses.replace(usage)
+            usage = deepcopy(usage)
 
             counted_usage = await ctx.deps.model.count_tokens(message_history, model_settings, model_request_parameters)
             usage.incr(counted_usage)
@@ -534,21 +545,22 @@ class CallToolsNode(AgentNode[DepsT, NodeRunEndT]):
             # Ensure that the stream is only run once
 
             async def _run_stream() -> AsyncIterator[_messages.HandleResponseEvent]:  # noqa: C901
-                texts: list[str] = []
+                text = ''
                 tool_calls: list[_messages.ToolCallPart] = []
                 thinking_parts: list[_messages.ThinkingPart] = []
 
                 for part in self.model_response.parts:
                     if isinstance(part, _messages.TextPart):
-                        # ignore empty content for text parts, see #437
-                        if part.content:
-                            texts.append(part.content)
+                        text += part.content
                     elif isinstance(part, _messages.ToolCallPart):
                         tool_calls.append(part)
                     elif isinstance(part, _messages.BuiltinToolCallPart):
-                        yield _messages.BuiltinToolCallEvent(part)
+                        # Text parts before a built-in tool call are essentially thoughts,
+                        # not part of the final result output, so we reset the accumulated text
+                        text = ''
+                        yield _messages.BuiltinToolCallEvent(part)  # pyright: ignore[reportDeprecated]
                     elif isinstance(part, _messages.BuiltinToolReturnPart):
-                        yield _messages.BuiltinToolResultEvent(part)
+                        yield _messages.BuiltinToolResultEvent(part)  # pyright: ignore[reportDeprecated]
                     elif isinstance(part, _messages.ThinkingPart):
                         thinking_parts.append(part)
                     else:
@@ -561,9 +573,9 @@ class CallToolsNode(AgentNode[DepsT, NodeRunEndT]):
                 if tool_calls:
                     async for event in self._handle_tool_calls(ctx, tool_calls):
                         yield event
-                elif texts:
+                elif text:
                     # No events are emitted during the handling of text responses, so we don't need to yield anything
-                    self._next_node = await self._handle_text_response(ctx, texts)
+                    self._next_node = await self._handle_text_response(ctx, text)
                 elif thinking_parts:
                     # handle thinking-only responses (responses that contain only ThinkingPart instances)
                     # this can happen with models that support thinking mode when they don't provide
@@ -582,9 +594,16 @@ class CallToolsNode(AgentNode[DepsT, NodeRunEndT]):
                     if isinstance(ctx.deps.output_schema, _output.TextOutputSchema):
                         for message in reversed(ctx.state.message_history):
                             if isinstance(message, _messages.ModelResponse):
-                                last_texts = [p.content for p in message.parts if isinstance(p, _messages.TextPart)]
-                                if last_texts:
-                                    self._next_node = await self._handle_text_response(ctx, last_texts)
+                                text = ''
+                                for part in message.parts:
+                                    if isinstance(part, _messages.TextPart):
+                                        text += part.content
+                                    elif isinstance(part, _messages.BuiltinToolCallPart):
+                                        # Text parts before a built-in tool call are essentially thoughts,
+                                        # not part of the final result output, so we reset the accumulated text
+                                        text = ''  # pragma: no cover
+                                if text:
+                                    self._next_node = await self._handle_text_response(ctx, text)
                                     return
 
                     raise exceptions.UnexpectedModelBehavior('Received empty model response')
@@ -644,11 +663,9 @@ class CallToolsNode(AgentNode[DepsT, NodeRunEndT]):
     async def _handle_text_response(
         self,
         ctx: GraphRunContext[GraphAgentState, GraphAgentDeps[DepsT, NodeRunEndT]],
-        texts: list[str],
+        text: str,
     ) -> ModelRequestNode[DepsT, NodeRunEndT] | End[result.FinalResult[NodeRunEndT]]:
         output_schema = ctx.deps.output_schema
-
-        text = '\n\n'.join(texts)
         try:
             run_context = build_run_context(ctx)
             if isinstance(output_schema, _output.TextOutputSchema):
@@ -1086,12 +1103,11 @@ def build_agent_graph(
 
 
 async def _process_message_history(
-    state: GraphAgentState,
+    messages: list[_messages.ModelMessage],
     processors: Sequence[HistoryProcessor[DepsT]],
     run_context: RunContext[DepsT],
 ) -> list[_messages.ModelMessage]:
     """Process message history through a sequence of processors."""
-    messages = state.message_history
     for processor in processors:
         takes_ctx = is_takes_ctx(processor)
 
@@ -1109,8 +1125,12 @@ async def _process_message_history(
                 sync_processor = cast(_HistoryProcessorSync, processor)
                 messages = await run_in_executor(sync_processor, messages)
 
-    # Replaces the message history in the state with the processed messages
-    state.message_history = messages
+    if len(messages) == 0:
+        raise exceptions.UserError('Processed history cannot be empty.')
+
+    if not isinstance(messages[-1], _messages.ModelRequest):
+        raise exceptions.UserError('Processed history must end with a `ModelRequest`.')
+
     return messages
 
 

pydantic_ai/_cli.py

@@ -356,7 +356,7 @@ def handle_slash_command(
         except IndexError:
             console.print('[dim]No output available to copy.[/dim]')
         else:
-            text_to_copy = '\n\n'.join(part.content for part in parts if isinstance(part, TextPart))
+            text_to_copy = ''.join(part.content for part in parts if isinstance(part, TextPart))
             text_to_copy = text_to_copy.strip()
             if text_to_copy:
                 pyperclip.copy(text_to_copy)

pydantic_ai/_otel_messages.py

@@ -21,6 +21,7 @@ class ToolCallPart(TypedDict):
     id: str
     name: str
     arguments: NotRequired[JsonValue]
+    builtin: NotRequired[bool]  # Not (currently?) part of the spec, used by Logfire
 
 
 class ToolCallResponsePart(TypedDict):
@@ -28,6 +29,7 @@ class ToolCallResponsePart(TypedDict):
     id: str
     name: str
     result: NotRequired[JsonValue]
+    builtin: NotRequired[bool]  # Not (currently?) part of the spec, used by Logfire
 
 
 class MediaUrlPart(TypedDict):

pydantic_ai/_parts_manager.py

@@ -19,6 +19,8 @@ from typing import Any
 
 from pydantic_ai.exceptions import UnexpectedModelBehavior
 from pydantic_ai.messages import (
+    BuiltinToolCallPart,
+    BuiltinToolReturnPart,
     ModelResponsePart,
     ModelResponseStreamEvent,
     PartDeltaEvent,
@@ -226,11 +228,11 @@ class ModelResponsePartsManager:
         self,
         *,
         vendor_part_id: Hashable | None,
-        tool_name: str | None,
-        args: str | dict[str, Any] | None,
-        tool_call_id: str | None,
+        tool_name: str | None = None,
+        args: str | dict[str, Any] | None = None,
+        tool_call_id: str | None = None,
     ) -> ModelResponseStreamEvent | None:
-        """Handle or update a tool call, creating or updating a `ToolCallPart` or `ToolCallPartDelta`.
+        """Handle or update a tool call, creating or updating a `ToolCallPart`, `BuiltinToolCallPart`, or `ToolCallPartDelta`.
 
         Managed items remain as `ToolCallPartDelta`s until they have at least a tool_name, at which
         point they are upgraded to `ToolCallPart`s.
@@ -247,15 +249,17 @@ class ModelResponsePartsManager:
             tool_call_id: An optional string representing an identifier for this tool call.
 
         Returns:
-            - A `PartStartEvent` if a new ToolCallPart is created.
+            - A `PartStartEvent` if a new ToolCallPart or BuiltinToolCallPart is created.
             - A `PartDeltaEvent` if an existing part is updated.
             - `None` if no new event is emitted (e.g., the part is still incomplete).
 
         Raises:
             UnexpectedModelBehavior: If attempting to apply a tool call delta to a part that is not
-                a ToolCallPart or ToolCallPartDelta.
+                a ToolCallPart, BuiltinToolCallPart, or ToolCallPartDelta.
         """
-        existing_matching_part_and_index: tuple[ToolCallPartDelta | ToolCallPart, int] | None = None
+        existing_matching_part_and_index: tuple[ToolCallPartDelta | ToolCallPart | BuiltinToolCallPart, int] | None = (
+            None
+        )
 
         if vendor_part_id is None:
             # vendor_part_id is None, so check if the latest part is a matching tool call or delta to update
@@ -264,14 +268,14 @@ class ModelResponsePartsManager:
             if tool_name is None and self._parts:
                 part_index = len(self._parts) - 1
                 latest_part = self._parts[part_index]
-                if isinstance(latest_part, ToolCallPart | ToolCallPartDelta):  # pragma: no branch
+                if isinstance(latest_part, ToolCallPart | BuiltinToolCallPart | ToolCallPartDelta):  # pragma: no branch
                     existing_matching_part_and_index = latest_part, part_index
         else:
             # vendor_part_id is provided, so look up the corresponding part or delta
             part_index = self._vendor_id_to_part_index.get(vendor_part_id)
             if part_index is not None:
                 existing_part = self._parts[part_index]
-                if not isinstance(existing_part, ToolCallPartDelta | ToolCallPart):
+                if not isinstance(existing_part, ToolCallPartDelta | ToolCallPart | BuiltinToolCallPart):
                     raise UnexpectedModelBehavior(f'Cannot apply a tool call delta to {existing_part=}')
                 existing_matching_part_and_index = existing_part, part_index
 
@@ -284,7 +288,7 @@ class ModelResponsePartsManager:
             new_part_index = len(self._parts)
             self._parts.append(part)
             # Only emit a PartStartEvent if we have enough information to produce a full ToolCallPart
-            if isinstance(part, ToolCallPart):
+            if isinstance(part, ToolCallPart | BuiltinToolCallPart):
                 return PartStartEvent(index=new_part_index, part=part)
         else:
             # Update the existing part or delta with the new information
@@ -292,7 +296,7 @@ class ModelResponsePartsManager:
             delta = ToolCallPartDelta(tool_name_delta=tool_name, args_delta=args, tool_call_id=tool_call_id)
             updated_part = delta.apply(existing_part)
             self._parts[part_index] = updated_part
-            if isinstance(updated_part, ToolCallPart):
+            if isinstance(updated_part, ToolCallPart | BuiltinToolCallPart):
                 if isinstance(existing_part, ToolCallPartDelta):
                     # We just upgraded a delta to a full part, so emit a PartStartEvent
                     return PartStartEvent(index=part_index, part=updated_part)
@@ -337,7 +341,7 @@ class ModelResponsePartsManager:
         else:
             # vendor_part_id is provided, so find and overwrite or create a new ToolCallPart.
             maybe_part_index = self._vendor_id_to_part_index.get(vendor_part_id)
-            if maybe_part_index is not None:
+            if maybe_part_index is not None and isinstance(self._parts[maybe_part_index], ToolCallPart):
                 new_part_index = maybe_part_index
                 self._parts[new_part_index] = new_part
             else:
@@ -345,3 +349,69 @@ class ModelResponsePartsManager:
                 self._parts.append(new_part)
             self._vendor_id_to_part_index[vendor_part_id] = new_part_index
         return PartStartEvent(index=new_part_index, part=new_part)
+
+    def handle_builtin_tool_call_part(
+        self,
+        *,
+        vendor_part_id: Hashable | None,
+        part: BuiltinToolCallPart,
+    ) -> ModelResponseStreamEvent:
+        """Create or overwrite a BuiltinToolCallPart.
+
+        Args:
+            vendor_part_id: The vendor's ID for this tool call part. If not
+                None and an existing part is found, that part is overwritten.
+            part: The BuiltinToolCallPart.
+
+        Returns:
+            ModelResponseStreamEvent: A `PartStartEvent` indicating that a new tool call part
+            has been added to the manager, or replaced an existing part.
+        """
+        if vendor_part_id is None:
+            # vendor_part_id is None, so we unconditionally append a new BuiltinToolCallPart to the end of the list
+            new_part_index = len(self._parts)
+            self._parts.append(part)
+        else:
+            # vendor_part_id is provided, so find and overwrite or create a new BuiltinToolCallPart.
+            maybe_part_index = self._vendor_id_to_part_index.get(vendor_part_id)
+            if maybe_part_index is not None and isinstance(self._parts[maybe_part_index], BuiltinToolCallPart):
+                new_part_index = maybe_part_index
+                self._parts[new_part_index] = part
+            else:
+                new_part_index = len(self._parts)
+                self._parts.append(part)
+            self._vendor_id_to_part_index[vendor_part_id] = new_part_index
+        return PartStartEvent(index=new_part_index, part=part)
+
+    def handle_builtin_tool_return_part(
+        self,
+        *,
+        vendor_part_id: Hashable | None,
+        part: BuiltinToolReturnPart,
+    ) -> ModelResponseStreamEvent:
+        """Create or overwrite a BuiltinToolReturnPart.
+
+        Args:
+            vendor_part_id: The vendor's ID for this tool call part. If not
+                None and an existing part is found, that part is overwritten.
+            part: The BuiltinToolReturnPart.
+
+        Returns:
+            ModelResponseStreamEvent: A `PartStartEvent` indicating that a new tool call part
+            has been added to the manager, or replaced an existing part.
+        """
+        if vendor_part_id is None:
+            # vendor_part_id is None, so we unconditionally append a new BuiltinToolReturnPart to the end of the list
+            new_part_index = len(self._parts)
+            self._parts.append(part)
+        else:
+            # vendor_part_id is provided, so find and overwrite or create a new BuiltinToolReturnPart.
+            maybe_part_index = self._vendor_id_to_part_index.get(vendor_part_id)
+            if maybe_part_index is not None and isinstance(self._parts[maybe_part_index], BuiltinToolReturnPart):
+                new_part_index = maybe_part_index
+                self._parts[new_part_index] = part
+            else:
+                new_part_index = len(self._parts)
+                self._parts.append(part)
+            self._vendor_id_to_part_index[vendor_part_id] = new_part_index
+        return PartStartEvent(index=new_part_index, part=part)

pydantic_ai/_run_context.py

@@ -43,10 +43,17 @@ class RunContext(Generic[AgentDepsT]):
     tool_name: str | None = None
     """Name of the tool being called."""
     retry: int = 0
-    """Number of retries so far."""
+    """Number of retries of this tool so far."""
+    max_retries: int = 0
+    """The maximum number of retries of this tool."""
     run_step: int = 0
     """The current step in the run."""
     tool_call_approved: bool = False
     """Whether a tool call that required approval has now been approved."""
 
+    @property
+    def last_attempt(self) -> bool:
+        """Whether this is the last attempt at running this tool before an error is raised."""
+        return self.retry == self.max_retries
+
     __repr__ = _utils.dataclasses_no_defaults_repr

pydantic_ai/_tool_manager.py

@@ -147,6 +147,7 @@ class ToolManager(Generic[AgentDepsT]):
                 tool_name=name,
                 tool_call_id=call.tool_call_id,
                 retry=self.ctx.retries.get(name, 0),
+                max_retries=tool.max_retries,
             )
 
             pyd_allow_partial = 'trailing-strings' if allow_partial else 'off'

pydantic_ai/ag_ui.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 import json
 import uuid
 from collections.abc import AsyncIterator, Awaitable, Callable, Iterable, Mapping, Sequence
-from dataclasses import Field, dataclass, replace
+from dataclasses import Field, dataclass, field, replace
 from http import HTTPStatus
 from typing import (
     Any,
@@ -23,13 +23,15 @@ from typing import (
 )
 
 from pydantic import BaseModel, ValidationError
-from typing_extensions import assert_never
 
 from . import _utils
 from ._agent_graph import CallToolsNode, ModelRequestNode
 from .agent import AbstractAgent, AgentRun, AgentRunResult
 from .exceptions import UserError
 from .messages import (
+    BaseToolCallPart,
+    BuiltinToolCallPart,
+    BuiltinToolReturnPart,
     FunctionToolResultEvent,
     ModelMessage,
     ModelRequest,
@@ -123,6 +125,8 @@ SSE_CONTENT_TYPE: Final[str] = 'text/event-stream'
 OnCompleteFunc: TypeAlias = Callable[[AgentRunResult[Any]], None] | Callable[[AgentRunResult[Any]], Awaitable[None]]
 """Callback function type that receives the `AgentRunResult` of the completed run. Can be sync or async."""
 
+_BUILTIN_TOOL_CALL_ID_PREFIX: Final[str] = 'pyd_ai_builtin'
+
 
 class AGUIApp(Generic[AgentDepsT, OutputDataT], Starlette):
     """ASGI application for running Pydantic AI agents with AG-UI protocol support."""
@@ -487,20 +491,37 @@ async def _handle_model_request_event(  # noqa: C901
                 stream_ctx.part_end = TextMessageEndEvent(
                     message_id=message_id,
                 )
-            elif isinstance(part, ToolCallPart):  # pragma: no branch
+            elif isinstance(part, BaseToolCallPart):
+                tool_call_id = part.tool_call_id
+                if isinstance(part, BuiltinToolCallPart):
+                    builtin_tool_call_id = '|'.join(
+                        [_BUILTIN_TOOL_CALL_ID_PREFIX, part.provider_name or '', tool_call_id]
+                    )
+                    stream_ctx.builtin_tool_call_ids[tool_call_id] = builtin_tool_call_id
+                    tool_call_id = builtin_tool_call_id
+
                 message_id = stream_ctx.message_id or stream_ctx.new_message_id()
                 yield ToolCallStartEvent(
-                    tool_call_id=part.tool_call_id,
+                    tool_call_id=tool_call_id,
                     tool_call_name=part.tool_name,
                     parent_message_id=message_id,
                 )
                 if part.args:
                     yield ToolCallArgsEvent(
-                        tool_call_id=part.tool_call_id,
-                        delta=part.args if isinstance(part.args, str) else json.dumps(part.args),
+                        tool_call_id=tool_call_id,
+                        delta=part.args_as_json_str(),
                     )
                 stream_ctx.part_end = ToolCallEndEvent(
-                    tool_call_id=part.tool_call_id,
+                    tool_call_id=tool_call_id,
+                )
+            elif isinstance(part, BuiltinToolReturnPart):  # pragma: no branch
+                tool_call_id = stream_ctx.builtin_tool_call_ids[part.tool_call_id]
+                yield ToolCallResultEvent(
+                    message_id=stream_ctx.new_message_id(),
+                    type=EventType.TOOL_CALL_RESULT,
+                    role='tool',
+                    tool_call_id=tool_call_id,
+                    content=part.model_response_str(),
                 )
 
     elif isinstance(agent_event, PartDeltaEvent):
@@ -512,9 +533,12 @@ async def _handle_model_request_event(  # noqa: C901
                     delta=delta.content_delta,
                 )
         elif isinstance(delta, ToolCallPartDelta):  # pragma: no branch
-            assert delta.tool_call_id, '`ToolCallPartDelta.tool_call_id` must be set'
+            tool_call_id = delta.tool_call_id
+            assert tool_call_id, '`ToolCallPartDelta.tool_call_id` must be set'
+            if tool_call_id in stream_ctx.builtin_tool_call_ids:
+                tool_call_id = stream_ctx.builtin_tool_call_ids[tool_call_id]
             yield ToolCallArgsEvent(
-                tool_call_id=delta.tool_call_id,
+                tool_call_id=tool_call_id,
                 delta=delta.args_delta if isinstance(delta.args_delta, str) else json.dumps(delta.args_delta),
             )
         elif isinstance(delta, ThinkingPartDelta):  # pragma: no branch
@@ -550,24 +574,23 @@ async def _handle_tool_result_event(
     if not isinstance(result, ToolReturnPart):
         return
 
-    message_id = stream_ctx.new_message_id()
     yield ToolCallResultEvent(
-        message_id=message_id,
+        message_id=stream_ctx.new_message_id(),
         type=EventType.TOOL_CALL_RESULT,
         role='tool',
         tool_call_id=result.tool_call_id,
         content=result.model_response_str(),
     )
 
-    # Now check for  AG-UI events returned by the tool calls.
-    content = result.content
-    if isinstance(content, BaseEvent):
-        yield content
-    elif isinstance(content, str | bytes):  # pragma: no branch
+    # Now check for AG-UI events returned by the tool calls.
+    possible_event = result.metadata or result.content
+    if isinstance(possible_event, BaseEvent):
+        yield possible_event
+    elif isinstance(possible_event, str | bytes):  # pragma: no branch
         # Avoid iterable check for strings and bytes.
         pass
-    elif isinstance(content, Iterable):  # pragma: no branch
-        for item in content:  # type: ignore[reportUnknownMemberType]
+    elif isinstance(possible_event, Iterable):  # pragma: no branch
+        for item in possible_event:  # type: ignore[reportUnknownMemberType]
             if isinstance(item, BaseEvent):  # pragma: no branch
                 yield item
 
@@ -579,7 +602,9 @@ def _messages_from_ag_ui(messages: list[Message]) -> list[ModelMessage]:
     request_parts: list[ModelRequestPart] | None = None
     response_parts: list[ModelResponsePart] | None = None
     for msg in messages:
-        if isinstance(msg, UserMessage | SystemMessage | DeveloperMessage | ToolMessage):
+        if isinstance(msg, UserMessage | SystemMessage | DeveloperMessage) or (
+            isinstance(msg, ToolMessage) and not msg.tool_call_id.startswith(_BUILTIN_TOOL_CALL_ID_PREFIX)
+        ):
             if request_parts is None:
                 request_parts = []
                 result.append(ModelRequest(parts=request_parts))
@@ -589,44 +614,71 @@ def _messages_from_ag_ui(messages: list[Message]) -> list[ModelMessage]:
                 request_parts.append(UserPromptPart(content=msg.content))
             elif isinstance(msg, SystemMessage | DeveloperMessage):
                 request_parts.append(SystemPromptPart(content=msg.content))
-            elif isinstance(msg, ToolMessage):
-                tool_name = tool_calls.get(msg.tool_call_id)
+            else:
+                tool_call_id = msg.tool_call_id
+                tool_name = tool_calls.get(tool_call_id)
                 if tool_name is None:  # pragma: no cover
-                    raise _ToolCallNotFoundError(tool_call_id=msg.tool_call_id)
+                    raise _ToolCallNotFoundError(tool_call_id=tool_call_id)
 
                 request_parts.append(
                     ToolReturnPart(
                         tool_name=tool_name,
                         content=msg.content,
-                        tool_call_id=msg.tool_call_id,
+                        tool_call_id=tool_call_id,
                     )
                 )
-            else:
-                assert_never(msg)
 
-        elif isinstance(msg, AssistantMessage):
+        elif isinstance(msg, AssistantMessage) or (  # pragma: no branch
+            isinstance(msg, ToolMessage) and msg.tool_call_id.startswith(_BUILTIN_TOOL_CALL_ID_PREFIX)
+        ):
             if response_parts is None:
                 response_parts = []
                 result.append(ModelResponse(parts=response_parts))
                 request_parts = None
 
-            if msg.content:
-                response_parts.append(TextPart(content=msg.content))
-
-            if msg.tool_calls:
-                for tool_call in msg.tool_calls:
-                    tool_calls[tool_call.id] = tool_call.function.name
+            if isinstance(msg, AssistantMessage):
+                if msg.content:
+                    response_parts.append(TextPart(content=msg.content))
+
+                if msg.tool_calls:
+                    for tool_call in msg.tool_calls:
+                        tool_call_id = tool_call.id
+                        tool_name = tool_call.function.name
+                        tool_calls[tool_call_id] = tool_name
+
+                        if tool_call_id.startswith(_BUILTIN_TOOL_CALL_ID_PREFIX):
+                            _, provider_name, tool_call_id = tool_call_id.split('|', 2)
+                            response_parts.append(
+                                BuiltinToolCallPart(
+                                    tool_name=tool_name,
+                                    args=tool_call.function.arguments,
+                                    tool_call_id=tool_call_id,
+                                    provider_name=provider_name,
+                                )
+                            )
+                        else:
+                            response_parts.append(
+                                ToolCallPart(
+                                    tool_name=tool_name,
+                                    tool_call_id=tool_call_id,
+                                    args=tool_call.function.arguments,
+                                )
+                            )
+            else:
+                tool_call_id = msg.tool_call_id
+                tool_name = tool_calls.get(tool_call_id)
+                if tool_name is None:  # pragma: no cover
+                    raise _ToolCallNotFoundError(tool_call_id=tool_call_id)
+                _, provider_name, tool_call_id = tool_call_id.split('|', 2)
 
-                response_parts.extend(
-                    ToolCallPart(
-                        tool_name=tool_call.function.name,
-                        tool_call_id=tool_call.id,
-                        args=tool_call.function.arguments,
+                response_parts.append(
+                    BuiltinToolReturnPart(
+                        tool_name=tool_name,
+                        content=msg.content,
+                        tool_call_id=tool_call_id,
+                        provider_name=provider_name,
                     )
-                    for tool_call in msg.tool_calls
                 )
-        else:
-            assert_never(msg)
 
     return result
 
@@ -687,6 +739,7 @@ class _RequestStreamContext:
     message_id: str = ''
     part_end: BaseEvent | None = None
     thinking: bool = False
+    builtin_tool_call_ids: dict[str, str] = field(default_factory=dict)
 
     def new_message_id(self) -> str:
         """Generate a new message ID for the request stream.

pydantic_ai/agent/__init__.py

@@ -614,12 +614,10 @@ class Agent(AbstractAgent[AgentDepsT, OutputDataT]):
             instrumentation_settings = None
             tracer = NoOpTracer()
 
-        graph_deps = _agent_graph.GraphAgentDeps[
-            AgentDepsT, RunOutputDataT
-        ](
+        graph_deps = _agent_graph.GraphAgentDeps[AgentDepsT, RunOutputDataT](
             user_deps=deps,
             prompt=user_prompt,
-            new_message_index=0,  # This will be set in `UserPromptNode` based on the length of the cleaned message history
+            new_message_index=len(message_history) if message_history else 0,
             model=model_used,
             model_settings=model_settings,
             usage_limits=usage_limits,

pydantic_ai/builtin_tools.py

@@ -18,6 +18,9 @@ class AbstractBuiltinTool(ABC):
     The builtin tools are passed to the model as part of the `ModelRequestParameters`.
     """
 
+    kind: str = 'unknown_builtin_tool'
+    """Built-in tool identifier, this should be available on all built-in tools as a discriminator."""
+
 
 @dataclass(kw_only=True)
 class WebSearchTool(AbstractBuiltinTool):
@@ -80,6 +83,9 @@ class WebSearchTool(AbstractBuiltinTool):
     * Anthropic
     """
 
+    kind: str = 'web_search'
+    """The kind of tool."""
+
 
 class WebSearchUserLocation(TypedDict, total=False):
     """Allows you to localize search results based on a user's location.
@@ -113,6 +119,9 @@ class CodeExecutionTool(AbstractBuiltinTool):
     * Google
     """
 
+    kind: str = 'code_execution'
+    """The kind of tool."""
+
 
 class UrlContextTool(AbstractBuiltinTool):
     """Allows your agent to access contents from URLs.
@@ -121,3 +130,6 @@ class UrlContextTool(AbstractBuiltinTool):
 
     * Google
     """
+
+    kind: str = 'url_context'
+    """The kind of tool."""