Add `run_id` field to `ModelMessage` for reliable run grouping

[lionpeloux]

Description

Summary

Add a run_id field to ModelRequest and ModelResponse to enable reliable splitting and grouping of message history by agent run. This would provide a "handle" to identify which messages belong to a specific run, which is critical when manipulating, compacting, or resuming multi-turn conversations.

Problem

Currently, there is no reliable way to split or group a list[ModelMessage] history by run. While developers can work around this by iterating over new_messages() after each run and manually tracking boundaries, this approach:

1. Requires strong assumptions about message order and completeness
2. Is fragile when messages are manipulated, filtered, or reordered
3. Becomes error-prone in complex scenarios like:
   • Conversation compaction/summarization (as discussed in the message history docs)
   • Resuming conversations from persistent storage
   • Analyzing specific runs from long conversation histories
   • Debugging tool call sequences across runs

Proposed Solution

Add a run_id: str field to both ModelRequest and ModelResponse dataclasses:

@dataclass(repr=False)
class ModelRequest:
    """A request generated by Pydantic AI and sent to a model."""

    parts: Sequence[ModelRequestPart]

    _: KW_ONLY

    instructions: str | None = None
    run_id: str | None = None  # NEW: UUID identifying the run this message belongs to

    kind: Literal['request'] = 'request'

@dataclass(repr=False)
class ModelResponse:
    """A response from a model."""

    parts: Sequence[ModelResponsePart]

    _: KW_ONLY

    usage: RequestUsage = field(default_factory=RequestUsage)
    model_name: str | None = None
    timestamp: datetime = field(default_factory=_now_utc)
    kind: Literal['response'] = 'response'
    provider_name: str | None = None
    provider_details: dict[str, Any] | None = None
    provider_response_id: str | None = None
    finish_reason: FinishReason | None = None
    run_id: str | None = None  # NEW: UUID identifying the run this message belongs to

Implementation Details

1. Run ID Generation

The run_id should be generated once per agent run, likely when the graph execution begins or in the AgentRun initialization:

import uuid

# Generate once per run
run_id = str(uuid.uuid4())

2. Propagation

The run_id should be:

• Passed through the graph execution context (GraphAgentState)
• Stamped on all ModelRequest messages created during the run
• Stamped on all ModelResponse messages received during the run
• Preserved when messages are serialized/deserialized via ModelMessagesTypeAdapter

3. Backward Compatibility

Since run_id would be optional (str | None), existing code and serialized messages will continue to work:

• Old messages without run_id will deserialize with run_id=None
• New messages will have run_id populated
• No breaking changes to the public API

Benefits

1. Reliable filtering: [msg for msg in history if msg.run_id == target_run_id]
2. Run-aware grouping: itertools.groupby(history, key=lambda msg: msg.run_id)
3. Safer history processing: History processors can group by run and preserve run boundaries
4. Better debugging: Easily trace all messages from a problematic run
5. Cleaner conversation management: No need for manual index tracking when continuing conversations
6. Improved observability: Correlate messages with OpenTelemetry spans using the same run ID

Example Usage

from pydantic_ai import Agent

agent = Agent('openai:gpt-4o')

# Run 1
result1 = agent.run_sync('What is 2+2?')
run1_id = result1.new_messages()[0].run_id

# Run 2 (continuing conversation)
result2 = agent.run_sync('What about 3+3?', message_history=result1.new_messages())
run2_id = result2.new_messages()[0].run_id

# Now we can reliably filter by run
all_history = result2.all_messages()
run1_messages = [msg for msg in all_history if msg.run_id == run1_id]
run2_messages = [msg for msg in all_history if msg.run_id == run2_id]

Alternative Considered

As mentioned in the original Slack discussion, the current workaround is to use provider_metadata: dict[str, Any] on ModelResponse to manually add run_id after each run:

result = agent.run_sync('Hello')
for msg in result.new_messages():
    if isinstance(msg, ModelResponse):
        if msg.provider_metadata is None:
            msg.provider_metadata = {}
        msg.provider_metadata['run_id'] = str(uuid.uuid4())

However, this approach:

• Only works for ModelResponse, not ModelRequest
• Requires manual intervention after every run
• Doesn't work well with immutable dataclasses (requires mutation)
• Pollutes provider-specific metadata with framework-level concerns

Related Code

• pydantic_ai_slim/pydantic_ai/messages.py - Message dataclasses (lines 927-1367)
• pydantic_ai_slim/pydantic_ai/result.py - all_messages() and new_messages() methods
• pydantic_ai_slim/pydantic_ai/_agent_graph.py - Graph execution state
• pydantic_ai_slim/pydantic_ai/run.py - AgentRun class
• Message History Documentation

References

• Original Slack thread discussion (October 2, 2024)
• @DouweM suggestion to add ModelResponse.run_id field
• Feedback that all messages (Request & Response) should be stamped with a shared unique ID

References

No response

[DouweM]

@lionpeloux Sounds good, would you be up for submitting a PR?

[adtyavrdhn]

Yes, needed this recently. I did make do with new_messages() but this would be a great addition.

[DouweM]

@adtyavrdhn PR welcome :)

[adtyavrdhn]

I'll raise one in a day or two :)

[steventen]

Instead of just adding a single run_id field, could we spend the same effort to introduce a more flexible metadata field to ModelMessage? It would give us a more extensible way to tag or track messages.

One use case on my end: I need to track customized user messages that are derived from customer input. Right now, I’m adding special characters around the input and doing a transformation before showing it back to the customer. With a metadata field, I could store that info directly, which is a different kind of filtering on model messages than what run_id is used for.

[lionpeloux]

Proposed Implementation

I'd like to expand on the original proposal to add four fields that improve message tracking, observability, and flexibility:

Model Definitions

from uuid import UUID, uuid4

@dataclass(repr=False)
class ModelRequest:
    """A request generated by Pydantic AI and sent to a model."""
    
    parts: Sequence[ModelRequestPart]
    
    _: KW_ONLY
    
    instructions: str | None = None
    
    # NEW FIELDS
    run_id: UUID | None = field(default_factory=uuid4)
    """Unique identifier for this agent run. All messages in the same run share the same run_id."""
    
    timestamp: datetime = field(default_factory=_now_utc)
    """Framework timestamp indicating when this request was created by Pydantic AI."""
    
    metadata: dict[str, Any] | None = None
    """Optional user-defined metadata for application use (not sent to the LLM)."""
    
    kind: Literal['request'] = 'request'

@dataclass(repr=False)
class ModelResponse:
    """A response from a model."""
    
    parts: Sequence[ModelResponsePart]
    
    _: KW_ONLY
    
    usage: RequestUsage = field(default_factory=RequestUsage)
    model_name: str | None = None
    
    # MODIFIED FIELD
    timestamp: datetime = field(default_factory=_now_utc)
    """Framework timestamp indicating when this response was received by Pydantic AI.
    
    Note: This field now always represents the framework timestamp. For provider-supplied
    timestamps (e.g., OpenAI's created field), use provider_timestamp instead.
    """
    
    # NEW FIELDS
    provider_timestamp: datetime | None = None
    """Provider-supplied timestamp from the model API (e.g., OpenAI's created field).
    May be None if the provider doesn't supply a timestamp."""
    
    run_id: UUID | None = field(default_factory=uuid4)
    """Unique identifier for this agent run. All messages in the same run share the same run_id."""
    
    metadata: dict[str, Any] | None = None
    """Optional user-defined metadata for application use (not sent to the LLM)."""
    
    kind: Literal['response'] = 'response'
    provider_name: str | None = None
    provider_details: dict[str, Any] | None = None
    provider_response_id: str | None = None
    finish_reason: FinishReason | None = None

Rationale

Framework Timestamps (timestamp)

Having a framework-controlled timestamp on both ModelRequest and ModelResponse provides several benefits:

1. Consistent timing reference: The framework timestamp represents when Pydantic AI created/received the message, independent of provider behavior
2. Request latency tracking: Difference between request and response framework timestamps gives true round-trip time
3. Clock skew elimination: Provider timestamps may use different clock sources or timezones; framework timestamps are always UTC from the same source
4. Always available: Unlike provider timestamps (which may be missing, incorrectly formatted, or use non-standard precision), framework timestamps are guaranteed present

Example use case:

# Calculate actual API latency
request_msg = messages[0]  # ModelRequest
response_msg = messages[1]  # ModelResponse

latency = (response_msg.timestamp - request_msg.timestamp).total_seconds()
print(f"API call took {latency:.3f}s")

Provider Timestamps (provider_timestamp)

Important caveat: The current timestamp field on ModelResponse is ambiguous - it sometimes contains the provider's timestamp (e.g., OpenAI's response.created) and sometimes the framework timestamp (when provider doesn't supply one).

By introducing provider_timestamp, we:

• Clarify semantics: timestamp = framework, provider_timestamp = provider
• Preserve provider data: Don't lose the provider's timing information
• Maintain backward compatibility: Old messages without provider_timestamp will have it as None

Migration note: Code that currently relies on ModelResponse.timestamp being the provider timestamp will now get the framework timestamp instead. For most use cases this is fine (difference is typically milliseconds), but code that specifically needs provider timestamps should be updated to use provider_timestamp or timestamp as a fallback.

Run ID (run_id)

As described in the original issue, this enables reliable filtering and grouping of messages by agent run:

# Filter all messages from a specific run
run_messages = [msg for msg in history if msg.run_id == target_run_id]

# Group messages by run
from itertools import groupby
for run_id, messages in groupby(history, key=lambda m: m.run_id):
    print(f"Run {run_id}: {len(list(messages))} messages")

Metadata (metadata)

Similar to provider_details, this allows users to attach custom application data to messages:

# Tag messages with user/session info
result = agent.run_sync('Hello')
for msg in result.new_messages():
    if msg.metadata is None:
        msg.metadata = {}
    msg.metadata.update({
        'user_id': '123',
        'session_id': 'abc',
        'environment': 'production'
    })

Backward Compatibility

All new fields are optional with defaults, ensuring:

• ✅ Old serialized messages deserialize correctly (new fields default to None or auto-generated)
• ✅ No breaking changes to message structure
• ⚠️ Semantic change: ModelResponse.timestamp meaning shifts from "ambiguous provider-or-framework" to "always framework"

The semantic change is documented but should have minimal impact since the time difference is typically negligible for most applications.

---

Would this approach address your needs? Happy to iterate on the design!

[lionpeloux]

Instead of just adding a single run_id field, could we spend the same effort to introduce a more flexible metadata field to ModelMessage? It would give us a more extensible way to tag or track messages.

One use case on my end: I need to track customized user messages that are derived from customer input. Right now, I’m adding special characters around the input and doing a transformation before showing it back to the customer. With a metadata field, I could store that info directly, which is a different kind of filtering on model messages than what run_id is used for.

See my proposal. I think a msg metadata dict could be e great addition to bring flexibility.
At the moment i am using a YAML frontmatter in my text messages (user/ai) in markdown format.

[phemmer]

I have similar functionality in my own usages of PydanticAI. But I call it turn_id. I think that term might be more appropriate here as "turn" is the standardized term for a request and response from a model (including any tool calls and etc which occur during). While in pydantic-ai world, "run" comes from agent.run, I worry that "run" is too ambiguous and might be too easily misconstrued, difficult to document clearly, etc.

[DouweM]

@steventen @lionpeloux I agree we could use a metadata: dict[str, Any] field, but please file a new issue/PR as #3366 is already massive and both fields are useful.

@lionpeloux As for timestamps, check out #1996 -- PR also more than welcome.

---

I have similar functionality in my own usages of PydanticAI. But I call it turn_id. I think that term might be more appropriate here as "turn" is the standardized term for a request and response from a model (including any tool calls and etc which occur during). While in pydantic-ai world, "run" comes from agent.run, I worry that "run" is too ambiguous and might be too easily misconstrued, difficult to document clearly, etc.

@phemmer I agree it's worth discussing the naming a bit. As I understood it (and as implemented in that PR), the idea is that all messages generated by a specific agent.run* call (i.e. result.new_messages()) get the same ID, so run_id seems natural -- we talk about "agent runs" all over the docs, and each one of those would get its own ID.

Not having used other agent frameworks that use that terminology, turn_id suggests to me that each ModelRequest/ModelResponse pair gets the same ID, but a run could have multiple turns. Although "a request and response from a model (including any tool calls and etc which occur during)" in your message suggests that maybe the entire run would be considered a turn, and a new turn only starts when the user submits a new message (i.e. user prompt i.e. run)?

Either way we don't use the "turn" term anywhere in Pydantic AI, so I think our only option that is (at least internally) consistent would be run_id.

But I'm curious about the distinction you see and why run_id could be confusing.

[phemmer]

Not having used other agent frameworks that use that terminology, turn_id suggests to me that each ModelRequest/ModelResponse pair gets the same ID,

Unfortunately there's no dictionary of LLM terminology anywhere, so there can't really be any official definition. But generally most resources I see consider a turn to be the initial prompt from the user, and everything until the final response from the LLM. Tool calls are part of the turn. In my experience, there's less consensus on what a single request+response is called, but I sometimes see it referred to as a "round".

But I'm curious about the distinction you see and why run_id could be confusing.

I find it better to avoid overloaded terminology which can have multiple meanings within a context. Like when we say "run", it could mean running the application, or maybe running some code in the application, or an invocation of agent.run. And when you want to find or understand documentation, it's easier to do when the term has fewer potential meanings or different usages.
But yes, using a term which implies its relation to agent.run does potentially make one such meaning apparent.

In my particular case where I'm using turn_id, it's because the conversations are stored in a database, and in that context where the data is de-coupled from the framework, I think turn_id is more inherently understood than run_id, as "run" is a pydantic-ai specific term.

But 🤷 . If you call it run_id, I'm familiar enough with PydanticAI to know what it means. Not a hill to die on. Was just throwing it out for thought.

[steventen]

@DouweM I think run_id could be a bit confusing—for example, it's unclear which messages should be tagged with the new run_id. Some might assume only new messages need it, while others might think all messages passed into a run should share the new run_id since they’re involved in that run.

Also, conceptually, it feels like run_id belongs more at the Run level (maybe on the AgentRunResult object) rather than on individual messages.

Because of that, I proposed the flexible metadata field approach instead. This would let developers decide how they want to tag messages—whether by run_id, turn_id, user_id, or something else. We could even add a helper function or callback support on model message creation, that could easily help developer add a run_id or anything dynamically into the metadata.

After all, I think metadata would address the original problem (split or group a list[ModelMessage] history by run) raised in the issue in a more extensible way.

[DouweM]

@phemmer

In my particular case where I'm using turn_id, it's because the conversations are stored in a database, and in that context where the data is de-coupled from the framework, I think turn_id is more inherently understood than run_id, as "run" is a pydantic-ai specific term.

That makes sense, and I appreciate the context.

Having considered that, within the framework I still feel like run_id is the best option as it maps 1:1 to our "agent run" concept and we haven't used the turn term anywhere, so this'll be most readily understood to those who familiarize themselves with the framework, without requiring the introduction of a new term for something that basically already has a term (even if overloaded when looking at the broader context outside Pydantic AI).

---

@steventen

I think run_id could be a bit confusing—for example, it's unclear which messages should be tagged with the new run_id. Some might assume only new messages need it, while others might think all messages passed into a run should share the new run_id since they’re involved in that run.

Also, conceptually, it feels like run_id belongs more at the Run level (maybe on the AgentRunResult object) rather than on individual messages.

The run_id field will also be added to the run/result objects, and I'll make sure that the Model{Request,Response}.run_id docstring makes it clear that this is the ID of the run in which the message originated.

The docs already talk about things like "starting a new run with the message history from a previous run" and we distinguish between "all messages" and "new messages", so I think it's clear enough that there's a difference between message history that is passed into a run, and new messages that originated in that run, and since a message history can be used in multiple new runs, I don't think users would expect those messages to take on the ID of the new run. (In fact, we don't modify messages from history in any way.)

Because of that, I proposed the flexible metadata field approach instead. This would let developers decide how they want to tag messages—whether by run_id, turn_id, user_id, or something else. We could even add a helper function or callback support on model message creation, that could easily help developer add a run_id or anything dynamically into the metadata.

After all, I think metadata would address the original problem (split or group a list[ModelMessage] history by run) raised in the issue in a more extensible way.

I agree we should have metadata as well, but I don't see it as a clear replacement or improvement of having a run ID, and more as an orthogonal feature that could be used for the same thing but is less convenient for most users.

Since the concept of an agent run is so fundamental to Pydantic AI, and since messages always originate in an agent run (unless crafted manually) I think it makes have some tag to reflect that relationship out of the box, without requiring users to implement manual message history processing.

---

Don't take that as me not appreciating the feedback, I just think that run_id is the least bad of all options, and that we should also have metadata for situations that require more flexibility.