Access ModelRequest-ModelResponse timestamps and duration as fields

[lionpeloux]

Description

Context

@Kludex suggested opening an issue based on this Slack thread.

I believe that access to the request–response duration for a model call should be a built-in metric, on par with what is provided in usage.

Currently, you have to manually iter() through the agent graph to track inner request–response timings, which is cumbersome.

Problem

ModelResponse holds a timestamp, but it is somewhat unreliable, as it is defined as:

The timestamp of the response. If the model provides a timestamp in the response (as OpenAI does), that will be used.

Conversely, ModelRequest does not have a timestamp. Its individual parts do, presumably at build time, but the full request itself is not timestamped when it is actually sent.

ModelResponse does have a timestamp—presumably when the response is received—but its parts do not, which makes sense since all parts arrive in the same response.

This leads to ambiguity and unnecessary work for anyone wanting to measure or log latency.

Proposal

• Add a timestamp field (local, UTC) to ModelRequest, marking the actual send time.
• Clarify the timestamp in ModelResponse as the local time the response was received.
• Add a provider_timestamp field to ModelResponse (if available, otherwise None).
• Add a duration field (timedelta or float in seconds) to ModelResponse, computed as response.timestamp - request.timestamp.
• (Optional) Add a duration field to agent runs, to capture total run time.

Note also that the graph persistent API tracks both ts (timestamp) and duration for NodeSnapshot and NodeSnapshot

References

No response

[corytomlinson]

Very happy to see this getting some attention. As part of this could you please ensure the timestamp precision is the same on all parts? Currently response parts have lower precision which can cause things to get out of order when parsing conversation history...

[fortzi]

I second @corytomlinson's comment about the timestamps implying a different order than the actual order due to the precision issue.

[moshest]

I also would prefer to use local timestamps when the messages are created and received. I think it's the most reliable way to use timestamps and do order by.

[JulianSprung]

+1 just ran into this issue.

I was assuming I could rely on the mesage/part timestamp in the ModelRequest/ModelResponse to store and retrieve conversations - and was very surprised that my conversation was our of order as responses don't have microseconds and hence can be show before the request which has microseconds.

Seems like something basic I would expect from the AI Agent framework and not requiring me to check precision and if only seconds create my own timestamps.
Or am I using it the wrong way? I couldn't find any docs or issues.

       messages: list[ModelMessage]  = ....    

       """Store new messages from the conversation to the database"""
       
        for message in messages:
            for part in message.parts:
                if part.part_kind in ["system-prompt", "tool-call"]:
                    continue
                if message.kind == "request" and part.part_kind == "user-prompt":
                    role = "user"
                    text_content = part.content
                    timestamp = part.timestamp
                elif message.kind == "response" and part.part_kind == "text":
                    role = "assistant"
                    text_content = part.content
                    timestamp = message.timestamp ### only has second precision -> out of order problem

                    # Also feels less consistent that the part in the response doesn't have a timestamp like the request:
                    timestamp = getattr(part, 'timestamp', None) or message.timestamp

                    # So it requires to ensure timestamp has microseconds for consistent ordering
                    # MEans, If missing microseconds, add current microseconds to maintain correct ordering
                    if timestamp and timestamp.microsecond == 0:
                        current_time = datetime.now(timezone.utc)
                        timestamp = timestamp.replace(microsecond=current_time.microsecond)

[DouweM]

@JulianSprung I agree we should improve this, I've put it on my list for the near future. A PR would also be welcome.