Add local timestamps to request and response models - include provider timestamp in provider_details

docs/agents.md

@@ -57,7 +57,7 @@ print(result.output)
 4. `result.output` will be a boolean indicating if the square is a winner. Pydantic performs the output validation, and it'll be typed as a `bool` since its type is derived from the `output_type` generic parameter of the agent.
 
 !!! tip "Agents are designed for reuse, like FastAPI Apps"
-    Agents are intended to be instantiated once (frequently as module globals) and reused throughout your application, similar to a small [FastAPI][fastapi.FastAPI] app or an [APIRouter][fastapi.APIRouter].
+    Agents can be instantiated once as a module global and reused throughout your application, similar to a small [FastAPI][fastapi.FastAPI] app or an [APIRouter][fastapi.APIRouter], or be created dynamically by a factory function like `get_agent('agent-type')`, whichever you prefer.
 
 ## Running Agents
 
@@ -321,6 +321,7 @@ async def main():
                         timestamp=datetime.datetime(...),
                     )
                 ],
+                timestamp=datetime.datetime(...),
                 run_id='...',
             )
         ),
@@ -385,6 +386,7 @@ async def main():
                             timestamp=datetime.datetime(...),
                         )
                     ],
+                    timestamp=datetime.datetime(...),
                     run_id='...',
                 )
             ),
@@ -1049,6 +1051,7 @@ with capture_run_messages() as messages:  # (2)!
                         timestamp=datetime.datetime(...),
                     )
                 ],
+                timestamp=datetime.datetime(...),
                 run_id='...',
             ),
             ModelResponse(
@@ -1073,6 +1076,7 @@ with capture_run_messages() as messages:  # (2)!
                         timestamp=datetime.datetime(...),
                     )
                 ],
+                timestamp=datetime.datetime(...),
                 run_id='...',
             ),
             ModelResponse(

docs/api/models/function.md

@@ -30,6 +30,7 @@ async def model_function(
                     timestamp=datetime.datetime(...),
                 )
             ],
+            timestamp=datetime.datetime(...),
             run_id='...',
         )
     ]

docs/deferred-tools.md

@@ -118,6 +118,7 @@ print(result.all_messages())
                 timestamp=datetime.datetime(...),
             )
         ],
+        timestamp=datetime.datetime(...),
         run_id='...',
     ),
     ModelResponse(
@@ -152,6 +153,7 @@ print(result.all_messages())
                 timestamp=datetime.datetime(...),
             )
         ],
+        timestamp=datetime.datetime(...),
         run_id='...',
     ),
     ModelRequest(
@@ -173,6 +175,7 @@ print(result.all_messages())
                 timestamp=datetime.datetime(...),
             ),
         ],
+        timestamp=datetime.datetime(...),
         run_id='...',
     ),
     ModelResponse(
@@ -197,6 +200,7 @@ print(result.all_messages())
                 timestamp=datetime.datetime(...),
             )
         ],
+        timestamp=datetime.datetime(...),
         run_id='...',
     ),
     ModelResponse(
@@ -324,6 +328,7 @@ async def main():
                     timestamp=datetime.datetime(...),
                 )
             ],
+            timestamp=datetime.datetime(...),
             run_id='...',
         ),
         ModelResponse(
@@ -350,6 +355,7 @@ async def main():
                     timestamp=datetime.datetime(...),
                 )
             ],
+            timestamp=datetime.datetime(...),
             run_id='...',
         ),
         ModelResponse(

docs/message-history.md

@@ -51,6 +51,7 @@ print(result.all_messages())
                 timestamp=datetime.datetime(...),
             ),
         ],
+        timestamp=datetime.datetime(...),
         run_id='...',
     ),
     ModelResponse(
@@ -95,6 +96,7 @@ async def main():
                         timestamp=datetime.datetime(...),
                     ),
                 ],
+                timestamp=datetime.datetime(...),
                 run_id='...',
             )
         ]
@@ -122,6 +124,7 @@ async def main():
                         timestamp=datetime.datetime(...),
                     ),
                 ],
+                timestamp=datetime.datetime(...),
                 run_id='...',
             ),
             ModelResponse(
@@ -178,6 +181,7 @@ print(result2.all_messages())
                 timestamp=datetime.datetime(...),
             ),
         ],
+        timestamp=datetime.datetime(...),
         run_id='...',
     ),
     ModelResponse(
@@ -198,6 +202,7 @@ print(result2.all_messages())
                 timestamp=datetime.datetime(...),
             )
         ],
+        timestamp=datetime.datetime(...),
         run_id='...',
     ),
     ModelResponse(
@@ -303,6 +308,7 @@ print(result2.all_messages())
                 timestamp=datetime.datetime(...),
             ),
         ],
+        timestamp=datetime.datetime(...),
         run_id='...',
     ),
     ModelResponse(
@@ -323,6 +329,7 @@ print(result2.all_messages())
                 timestamp=datetime.datetime(...),
             )
         ],
+        timestamp=datetime.datetime(...),
         run_id='...',
     ),
     ModelResponse(

docs/testing.md

@@ -128,6 +128,7 @@ async def test_forecast():
                     timestamp=IsNow(tz=timezone.utc),  # (7)!
                 ),
             ],
+            timestamp=IsNow(tz=timezone.utc),
             run_id=IsStr(),
         ),
         ModelResponse(
@@ -158,6 +159,7 @@ async def test_forecast():
                     timestamp=IsNow(tz=timezone.utc),
                 ),
             ],
+            timestamp=IsNow(tz=timezone.utc),
             run_id=IsStr(),
         ),
         ModelResponse(

docs/tools.md

@@ -88,6 +88,7 @@ print(dice_result.all_messages())
                 timestamp=datetime.datetime(...),
             ),
         ],
+        timestamp=datetime.datetime(...),
         run_id='...',
     ),
     ModelResponse(
@@ -110,6 +111,7 @@ print(dice_result.all_messages())
                 timestamp=datetime.datetime(...),
             )
         ],
+        timestamp=datetime.datetime(...),
         run_id='...',
     ),
     ModelResponse(
@@ -132,6 +134,7 @@ print(dice_result.all_messages())
                 timestamp=datetime.datetime(...),
             )
         ],
+        timestamp=datetime.datetime(...),
         run_id='...',
     ),
     ModelResponse(

pydantic_ai_slim/pydantic_ai/_a2a.py

@@ -25,6 +25,7 @@
     ToolCallPart,
     UserPromptPart,
     VideoUrl,
+    _utils,
 )
 
 from .agent import AbstractAgent, AgentDepsT, OutputDataT
@@ -200,7 +201,9 @@ def build_message_history(self, history: list[Message]) -> list[ModelMessage]:
         model_messages: list[ModelMessage] = []
         for message in history:
             if message['role'] == 'user':
-                model_messages.append(ModelRequest(parts=self._request_parts_from_a2a(message['parts'])))
+                model_messages.append(
+                    ModelRequest(parts=self._request_parts_from_a2a(message['parts']), timestamp=_utils.now_utc())
+                )
             else:
                 model_messages.append(ModelResponse(parts=self._response_parts_from_a2a(message['parts'])))
         return model_messages

pydantic_ai_slim/pydantic_ai/_agent_graph.py

@@ -19,7 +19,7 @@
 from pydantic_ai._function_schema import _takes_ctx as is_takes_ctx  # type: ignore
 from pydantic_ai._instrumentation import DEFAULT_INSTRUMENTATION_VERSION
 from pydantic_ai._tool_manager import ToolManager
-from pydantic_ai._utils import dataclasses_no_defaults_repr, get_union_args, is_async_callable, run_in_executor
+from pydantic_ai._utils import dataclasses_no_defaults_repr, get_union_args, is_async_callable, now_utc, run_in_executor
 from pydantic_ai.builtin_tools import AbstractBuiltinTool
 from pydantic_graph import BaseNode, GraphRunContext
 from pydantic_graph.beta import Graph, GraphBuilder
@@ -229,7 +229,7 @@ async def run(  # noqa: C901
             if isinstance(last_message, _messages.ModelRequest) and self.user_prompt is None:
                 # Drop last message from history and reuse its parts
                 messages.pop()
-                next_message = _messages.ModelRequest(parts=last_message.parts)
+                next_message = _messages.ModelRequest(parts=last_message.parts, timestamp=now_utc())
 
                 # Extract `UserPromptPart` content from the popped message and add to `ctx.deps.prompt`
                 user_prompt_parts = [part for part in last_message.parts if isinstance(part, _messages.UserPromptPart)]
@@ -273,7 +273,7 @@ async def run(  # noqa: C901
             if self.user_prompt is not None:
                 parts.append(_messages.UserPromptPart(self.user_prompt))
 
-            next_message = _messages.ModelRequest(parts=parts)
+            next_message = _messages.ModelRequest(parts=parts, timestamp=now_utc())
 
         next_message.instructions = instructions
 
@@ -437,6 +437,7 @@ async def stream(
         assert not self._did_stream, 'stream() should only be called once per node'
 
         model_settings, model_request_parameters, message_history, run_context = await self._prepare_request(ctx)
+        self.request.timestamp = now_utc()
         async with ctx.deps.model.request_stream(
             message_history, model_settings, model_request_parameters, run_context
         ) as streamed_response:
@@ -469,6 +470,7 @@ async def _make_request(
             return self._result  # pragma: no cover
 
         model_settings, model_request_parameters, message_history, _ = await self._prepare_request(ctx)
+        self.request.timestamp = now_utc()
         model_response = await ctx.deps.model.request(message_history, model_settings, model_request_parameters)
         ctx.state.usage.requests += 1
 
@@ -625,7 +627,7 @@ async def _run_stream() -> AsyncIterator[_messages.HandleResponseEvent]:  # noqa
                     run_context = build_run_context(ctx)
                     instructions = await ctx.deps.get_instructions(run_context)
                     self._next_node = ModelRequestNode[DepsT, NodeRunEndT](
-                        _messages.ModelRequest(parts=[], instructions=instructions)
+                        _messages.ModelRequest(parts=[], instructions=instructions, timestamp=now_utc())
                     )
                     return
 
@@ -693,7 +695,7 @@ async def _run_stream() -> AsyncIterator[_messages.HandleResponseEvent]:  # noqa
                     run_context = build_run_context(ctx)
                     instructions = await ctx.deps.get_instructions(run_context)
                     self._next_node = ModelRequestNode[DepsT, NodeRunEndT](
-                        _messages.ModelRequest(parts=[e.tool_retry], instructions=instructions)
+                        _messages.ModelRequest(parts=[e.tool_retry], instructions=instructions, timestamp=now_utc())
                     )
 
             self._events_iterator = _run_stream()
@@ -735,7 +737,7 @@ async def _handle_tool_calls(
 
             instructions = await ctx.deps.get_instructions(run_context)
             self._next_node = ModelRequestNode[DepsT, NodeRunEndT](
-                _messages.ModelRequest(parts=output_parts, instructions=instructions)
+                _messages.ModelRequest(parts=output_parts, instructions=instructions, timestamp=now_utc())
             )
 
     async def _handle_text_response(
@@ -770,7 +772,7 @@ def _handle_final_result(
 
         # For backwards compatibility, append a new ModelRequest using the tool returns and retries
         if tool_responses:
-            messages.append(_messages.ModelRequest(parts=tool_responses, run_id=ctx.state.run_id))
+            messages.append(_messages.ModelRequest(parts=tool_responses, run_id=ctx.state.run_id, timestamp=now_utc()))
 
         return End(final_result)
 
@@ -1323,8 +1325,7 @@ def _clean_message_history(messages: list[_messages.ModelMessage]) -> list[_mess
                     key=lambda x: 0 if isinstance(x, _messages.ToolReturnPart | _messages.RetryPromptPart) else 1
                 )
                 merged_message = _messages.ModelRequest(
-                    parts=parts,
-                    instructions=last_message.instructions or message.instructions,
+                    parts=parts, instructions=last_message.instructions or message.instructions, timestamp=now_utc()
                 )
                 clean_messages[-1] = merged_message
             else:

pydantic_ai_slim/pydantic_ai/_mcp.py

@@ -4,7 +4,7 @@
 from collections.abc import Sequence
 from typing import Literal
 
-from . import exceptions, messages
+from . import _utils, exceptions, messages
 
 try:
     from mcp import types as mcp_types
@@ -44,15 +44,15 @@ def map_from_mcp_params(params: mcp_types.CreateMessageRequestParams) -> list[me
             # role is assistant
             # if there are any request parts, add a request message wrapping them
             if request_parts:
-                pai_messages.append(messages.ModelRequest(parts=request_parts))
+                pai_messages.append(messages.ModelRequest(parts=request_parts, timestamp=_utils.now_utc()))
                 request_parts = []
 
             response_parts.append(map_from_sampling_content(content))
 
     if response_parts:
         pai_messages.append(messages.ModelResponse(parts=response_parts))
     if request_parts:
-        pai_messages.append(messages.ModelRequest(parts=request_parts))
+        pai_messages.append(messages.ModelRequest(parts=request_parts, timestamp=_utils.now_utc()))
     return pai_messages
 
 

pydantic_ai_slim/pydantic_ai/agent/__init__.py

@@ -508,6 +508,7 @@ async def main():
                                 timestamp=datetime.datetime(...),
                             )
                         ],
+                        timestamp=datetime.datetime(...),
                         run_id='...',
                     )
                 ),

pydantic_ai_slim/pydantic_ai/agent/abstract.py

@@ -559,7 +559,11 @@ async def on_complete() -> None:
 
                                 # For backwards compatibility, append a new ModelRequest using the tool returns and retries
                                 if parts:
-                                    messages.append(_messages.ModelRequest(parts, run_id=graph_ctx.state.run_id))
+                                    messages.append(
+                                        _messages.ModelRequest(
+                                            parts, run_id=graph_ctx.state.run_id, timestamp=_utils.now_utc()
+                                        )
+                                    )
 
                                 await agent_run.next(_agent_graph.SetFinalResult(final_result))
 
@@ -1004,6 +1008,7 @@ async def main():
                                 timestamp=datetime.datetime(...),
                             )
                         ],
+                        timestamp=datetime.datetime(...),
                         run_id='...',
                     )
                 ),

pydantic_ai_slim/pydantic_ai/agent/wrapper.py

@@ -164,6 +164,7 @@ async def main():
                                 timestamp=datetime.datetime(...),
                             )
                         ],
+                        timestamp=datetime.datetime(...),
                         run_id='...',
                     )
                 ),

pydantic_ai_slim/pydantic_ai/durable_exec/dbos/_agent.py

@@ -823,6 +823,7 @@ async def main():
                                 timestamp=datetime.datetime(...),
                             )
                         ],
+                        timestamp=datetime.datetime(...),
                         run_id='...',
                     )
                 ),

pydantic_ai_slim/pydantic_ai/durable_exec/prefect/_agent.py

@@ -768,6 +768,7 @@ async def main():
                                 timestamp=datetime.datetime(...),
                             )
                         ],
+                        timestamp=datetime.datetime(...),
                         run_id='...',
                     )
                 ),

pydantic_ai_slim/pydantic_ai/durable_exec/temporal/_agent.py

@@ -842,6 +842,7 @@ async def main():
                                 timestamp=datetime.datetime(...),
                             )
                         ],
+                        timestamp=datetime.datetime(...),
                         run_id='...',
                     )
                 ),