Deprecate {FunctionToolCallEvent,FunctionToolResultEvent}.call_id in favor of tool_call_id (#2028)

Co-authored-by: Douwe Maan <douwe@pydantic.dev>

Author: proever

pydantic_ai_slim/pydantic_ai/_agent_graph.py

@@ -641,7 +641,6 @@ async def process_function_tools(  # noqa C901
     run_context = build_run_context(ctx)
 
     calls_to_run: list[tuple[Tool[DepsT], _messages.ToolCallPart]] = []
-    call_index_to_event_id: dict[int, str] = {}
     for call in tool_calls:
         if (
             call.tool_name == output_tool_name
@@ -668,7 +667,6 @@ async def process_function_tools(  # noqa C901
             else:
                 event = _messages.FunctionToolCallEvent(call)
                 yield event
-                call_index_to_event_id[len(calls_to_run)] = event.call_id
                 calls_to_run.append((tool, call))
         elif mcp_tool := await _tool_from_mcp_server(call.tool_name, ctx):
             if stub_function_tools:
@@ -683,7 +681,6 @@ async def process_function_tools(  # noqa C901
             else:
                 event = _messages.FunctionToolCallEvent(call)
                 yield event
-                call_index_to_event_id[len(calls_to_run)] = event.call_id
                 calls_to_run.append((mcp_tool, call))
         elif call.tool_name in output_schema.tools:
             # if tool_name is in output_schema, it means we found a output tool but an error occurred in
@@ -700,13 +697,13 @@ async def process_function_tools(  # noqa C901
                     content=content,
                     tool_call_id=call.tool_call_id,
                 )
-                yield _messages.FunctionToolResultEvent(part, tool_call_id=call.tool_call_id)
+                yield _messages.FunctionToolResultEvent(part)
                 output_parts.append(part)
         else:
             yield _messages.FunctionToolCallEvent(call)
 
             part = _unknown_tool(call.tool_name, call.tool_call_id, ctx)
-            yield _messages.FunctionToolResultEvent(part, tool_call_id=call.tool_call_id)
+            yield _messages.FunctionToolResultEvent(part)
             output_parts.append(part)
 
     if not calls_to_run:
@@ -738,7 +735,7 @@ async def process_function_tools(  # noqa C901
             for task in done:
                 index = tasks.index(task)
                 result = task.result()
-                yield _messages.FunctionToolResultEvent(result, tool_call_id=call_index_to_event_id[index])
+                yield _messages.FunctionToolResultEvent(result)
 
                 if isinstance(result, _messages.RetryPromptPart):
                     results_by_index[index] = result

pydantic_ai_slim/pydantic_ai/messages.py

@@ -11,7 +11,7 @@
 import pydantic
 import pydantic_core
 from opentelemetry._events import Event  # pyright: ignore[reportPrivateImportUsage]
-from typing_extensions import TypeAlias
+from typing_extensions import TypeAlias, deprecated
 
 from . import _utils
 from ._utils import (
@@ -1009,10 +1009,16 @@ class FunctionToolCallEvent:
     """Event type identifier, used as a discriminator."""
 
     @property
-    def call_id(self) -> str:
-        """An ID used for matching details about the call to its result. If present, defaults to the part's tool_call_id."""
+    def tool_call_id(self) -> str:
+        """An ID used for matching details about the call to its result."""
         return self.part.tool_call_id
 
+    @property
+    @deprecated('`call_id` is deprecated, use `tool_call_id` instead.')
+    def call_id(self) -> str:
+        """An ID used for matching details about the call to its result."""
+        return self.part.tool_call_id  # pragma: no cover
+
     __repr__ = _utils.dataclasses_no_defaults_repr
 
 
@@ -1022,11 +1028,14 @@ class FunctionToolResultEvent:
 
     result: ToolReturnPart | RetryPromptPart
     """The result of the call to the function tool."""
-    tool_call_id: str
-    """An ID used to match the result to its original call."""
     event_kind: Literal['function_tool_result'] = 'function_tool_result'
     """Event type identifier, used as a discriminator."""
 
+    @property
+    def tool_call_id(self) -> str:
+        """An ID used to match the result to its original call."""
+        return self.result.tool_call_id
+
     __repr__ = _utils.dataclasses_no_defaults_repr
 
 

tests/models/test_bedrock.py

@@ -413,8 +413,7 @@ async def get_temperature(city: str) -> str:
                     content='30°C',
                     tool_call_id='tooluse_lAG_zP8QRHmSYOwZzzaCqA',
                     timestamp=IsDatetime(),
-                ),
-                tool_call_id='tooluse_lAG_zP8QRHmSYOwZzzaCqA',
+                )
             ),
             PartStartEvent(index=0, part=TextPart(content='The')),
             FinalResultEvent(tool_name=None, tool_call_id=None),

tests/models/test_google.py

@@ -375,8 +375,7 @@ async def get_temperature(city: str) -> str:
             FunctionToolResultEvent(
                 result=ToolReturnPart(
                     tool_name='get_capital', content='Paris', tool_call_id=IsStr(), timestamp=IsDatetime()
-                ),
-                tool_call_id=IsStr(),
+                )
             ),
             PartStartEvent(
                 index=0,
@@ -386,8 +385,7 @@ async def get_temperature(city: str) -> str:
             FunctionToolResultEvent(
                 result=ToolReturnPart(
                     tool_name='get_temperature', content='30°C', tool_call_id=IsStr(), timestamp=IsDatetime()
-                ),
-                tool_call_id=IsStr(),
+                )
             ),
             PartStartEvent(index=0, part=TextPart(content='The temperature in Paris')),
             FinalResultEvent(tool_name=None, tool_call_id=None),

tests/test_streaming.py

@@ -988,8 +988,7 @@ def known_tool(x: int) -> int:
                     tool_name='unknown_tool',
                     tool_call_id=IsStr(),
                     timestamp=IsNow(tz=timezone.utc),
-                ),
-                tool_call_id=IsStr(),
+                )
             ),
             FunctionToolCallEvent(
                 part=ToolCallPart(tool_name='known_tool', args={'x': 5}, tool_call_id=IsStr()),
@@ -1000,8 +999,7 @@ def known_tool(x: int) -> int:
                     content=10,
                     tool_call_id=IsStr(),
                     timestamp=IsNow(tz=timezone.utc),
-                ),
-                tool_call_id=IsStr(),
+                )
             ),
             FunctionToolCallEvent(
                 part=ToolCallPart(
@@ -1052,8 +1050,7 @@ def call_final_result_with_bad_data(messages: list[ModelMessage], info: AgentInf
                     content='Output tool not used - result failed validation.',
                     tool_call_id=IsStr(),
                     timestamp=IsNow(tz=timezone.utc),
-                ),
-                tool_call_id=IsStr(),
+                )
             ),
         ]
     )
@@ -1080,3 +1077,20 @@ class CityLocation(BaseModel):
             ]
         )
         assert result.is_complete
+
+
+def test_function_tool_event_tool_call_id_properties():
+    """Ensure that the `tool_call_id` property on function tool events mirrors the underlying part's ID."""
+    # Prepare a ToolCallPart with a fixed ID
+    call_part = ToolCallPart(tool_name='sample_tool', args={'a': 1}, tool_call_id='call_id_123')
+    call_event = FunctionToolCallEvent(part=call_part)
+
+    # The event should expose the same `tool_call_id` as the part
+    assert call_event.tool_call_id == call_part.tool_call_id == 'call_id_123'
+
+    # Prepare a ToolReturnPart with a fixed ID
+    return_part = ToolReturnPart(tool_name='sample_tool', content='ok', tool_call_id='return_id_456')
+    result_event = FunctionToolResultEvent(result=return_part)
+
+    # The event should expose the same `tool_call_id` as the result part
+    assert result_event.tool_call_id == return_part.tool_call_id == 'return_id_456'