Conversation history with timestamps: Per-Message timestamp for MESSAGES_SNAPSHOT

[kasuteru]

AG-UI defines an optional timestamp on every event. I would like to propose an optional timestamp on every durable Message as well, primarily so a frontend can preserve and display message time after history compaction.

Short summary: Why and what?

Knowing when a question was asked / answered and when an action was taken is often important for users, especially in the business context. The most prominent case is data agents - users must be able to see when a conversation took place to judge whether the data in the conversation might already be outdated.

Currently, when loading an old conversation or sharing a conversation with another user using AG-UI's MESSAGE_SNAPSHOT, this information is lost. I therefore propose adding a canonical, optional and fully backwards compatible timestamp field to BaseMessage:

interface BaseMessage {
  id: string
  role: string
  content?: string
  name?: string
  encryptedValue?: string
  timestamp?: number // <- New! Unix epoch milliseconds
}

Further details follow below - not sure what the process is here in AG-UI since this is the first time I am posting here - I am happy to write a PR / go into even more detail once maintainers agree this is something that makes sense in principle?

Why BaseEvent.timestamp is not enough

BaseEvent.timestamp is useful on the raw stream. For example, a producer can timestamp TEXT_MESSAGE_START, each TEXT_MESSAGE_CONTENT, and TEXT_MESSAGE_END. The final event is a reasonable time for an assistant reply to be considered complete.

However, it is event metadata, not message metadata:

{
  "type": "TEXT_MESSAGE_END",
  "messageId": "assistant-1",
  "timestamp": 1786096860000
}

The information becomes difficult to use after compaction. A compact history normally replaces a sequence of text, tool, and state events with a standard AG-UI MESSAGES_SNAPSHOT event:

{
  "type": "MESSAGES_SNAPSHOT",
  "timestamp": 1786100000000,
  "messages": [
    { "id": "user-1", "role": "user", "content": "Show material costs for July." },
    { "id": "assistant-1", "role": "assistant", "content": "July material costs were..." }
  ]
}

MESSAGES_SNAPSHOT is already an AG-UI standard state-management event. Its event-level timestamp says only when this snapshot was emitted. It does not say when user-1 was asked or when assistant-1 was completed. The original TEXT_MESSAGE_* events may no longer be retained in the compact projection, so a frontend cannot reconstruct those per-message times.

This is important for more than chat chronology. A data-agent user needs to judge whether a table, chart, or dataframe was produced before or after an upstream data refresh. It is also useful for exports, audit views, and chat channels.

Proposed semantics

Add optional timestamp?: number to BaseMessage, using Unix epoch milliseconds to match the existing BaseEvent.timestamp encoding.

• User message: time the server accepts the message into the thread.
• Assistant message in MESSAGES_SNAPSHOT: time the response is finalized and made durable for replay.
• Tool, activity, and reasoning message: time the message becomes durable or visible to the frontend.
• This is display/history metadata only. It MUST NOT become an event-ordering contract; stream order and existing IDs continue to define ordering.
• Producers that do not persist history, cannot determine the value, or do not implement this extension simply omit it.

Example:

{
  "type": "MESSAGES_SNAPSHOT",
  "messages": [
    {
      "id": "user-1",
      "role": "user",
      "content": "Show material costs for July.",
      "timestamp": 1786096800000
    },
    {
      "id": "assistant-1",
      "role": "assistant",
      "content": "July material costs were...",
      "timestamp": 1786096860000
    }
  ]
}

Why use the name timestamp

The existing protocol already uses timestamp for the same encoding and broad concept: a time associated with a protocol object. Reusing it makes the field easier to learn and avoids introducing competing createdAt, sentAt, and completedAt vocabularies.

The type makes the scope unambiguous:

Field	Scope	Meaning
BaseEvent.timestamp	One streamed event	When that event is created or emitted.
BaseMessage.timestamp	One durable message	When that message becomes a durable/visible item for history.

For live streaming, implementations may continue to expose event start/end timing through the existing event field. A compact snapshot contains completed durable messages, so one message-level timestamp is enough for the history-display use case.

Why a first-class field rather than a workaround

CUSTOM events, rawEvent, and adapter-specific metadata can carry this information today. They require a second correlation object or per-adapter convention, and consumers cannot rely on one portable shape.

AG-UI currently has no metadata or custom field on BaseMessage. Adding a generic bag would be less precise and typed SDKs may strip unknown fields. A narrow optional field is easier to specify and test across implementations.

This is backward compatible at the protocol level: existing producers omit it, and clients that do not display timestamps ignore it. It still requires a coordinated SDK update so typed parse-and-reserialize paths retain the field, especially the TypeScript Zod message schemas.

Suggested implementation after consensus

1. Add timestamp?: number to BaseMessage in TypeScript, Python, .NET, proto, and community SDK schemas.
2. Clarify BaseEvent.timestamp in the event documentation and recommend it for producers that support raw replay or audit/history displays.
3. Document the distinct message-timestamp semantics in the Messages and Serialization documentation.
4. Add cross-SDK fixtures that compact timestamped text events into a MESSAGES_SNAPSHOT, retain message timestamps through decode/re-encode, and accept older snapshots without them.

There is a related question in #2022 about BaseEvent.timestamp; I see this as complementary rather than a replacement. The maintainers' proposal discussion #2161 also explicitly weighs optional first-class fields against CUSTOM-event conventions.

[kasuteru]

This ties into #1160 - sending a AG-UI MESSAGE_SNAPSHOT via a defined endpoint would be the first and foremost use case of this. If this endpoint was included in the standard as well, even better. As discussed in the other thread, it would need to include additional metadata on conversation (threadID) level.