[AGUI] BaseMessage message_id uniqueness semantics - per-thread or globally unique or something else?

[mjod]

In agent_framework_ag_ui._workflow_run.py:L968, executor activities use message_id=f"executor:{executor_id}" without including the run_id or some unique identifier:

yield ActivitySnapshotEvent(
    message_id=f"executor:{executor_id}" if executor_id else generate_event_id(),
    activity_type="executor",
    content=executor_payload,
)

Issue:
When a user sends multiple prompts (separate workflow runs), the same message_id is reused across runs. For example:

• Run 1: message_id="executor:synthesizer"
• Run 2: message_id="executor:synthesizer" (same ID!)
  This could cause UI issues where activities from Run 2 overwrite/update activities from Run 1. Also how we are configuring the DB to store Messages we originally assumed message_id was unique. As mentioned here. In that code block it says id: string // Unique identifier for the message

When ActivitySnapshotEvent is converted to an ActivityMessage, the message_id becomes the message's id field. Our implementation stores these in a database where id is expected to be unique(or so we thought). Without run-scoping, multiple runs using the same executor (e.g., "executor:synthesizer") generate duplicate IDs, causing newer runs to overwrite activities from previous runs. We are still early on this development so maybe our understanding is off and that should be the case and we need to update how we store Messages.

Question:
Should message_id be scoped to the run(or really just general uniqueness)? For example:
message_id=f"{run_id}:executor:{executor_id}" if executor_id else generate_event_id()
Or is the current behavior intentional, and UIs/DBs should handle this differently? It seems like if its missing the generate_event_id() gives it a random uuid which makes me think it should be unique each time.
And a more general question about message_id for all AGUI types, should they always be unique or just unique within that specific thread?

Version: agent_framework_ag_ui==1.0.0

Thanks all, appreciate all the hard work in this package!

[farfromexact]

Your collision concern is valid if the database key is global. I would preserve a stable message_id within one workflow run so incremental ActivitySnapshotEvent updates can target the same activity, but include the run identity in persistence so a second run cannot overwrite the first.

A useful split is:

wire message_id: stable for one activity during one run
storage key: thread_id + run_id + message_id

I would avoid making message_id alone the primary key unless the protocol explicitly guarantees uniqueness across runs and threads. If the wire contract requires broader uniqueness, adding run_id to the generated executor ID is safer than relying on executor_id alone. Either way, add a regression test that runs the same executor twice, replays both runs, and verifies that updates from run 2 cannot mutate run 1. It is also worth deciding whether a UI needs cross-run deduplication or only within-run updates; those are different requirements.

[moonbox3]

Thanks for digging into this. Your collision concern is valid.

ActivitySnapshotEvent.message_id identifies the target ActivityMessage. AG-UI clients use that ID to locate and replace an existing activity in the message collection. Reusing an ID for updates to the same logical activity is expected. For example, an activity’s in-progress and completed snapshots should share an ID. Reusing it for a distinct activity in a later run can replace the earlier activity, as you observed.

The AG-UI documentation describes a message ID as unique but does not explicitly define whether that means globally unique or thread-scoped. At minimum, it must be unique among distinct messages that can coexist in the same thread-level message collection. Applications therefore should not rely on message_id alone as a globally unique database key; scoping it by the application or tenant and thread_id is safer.

For the reported cross-run case, including the run ID would prevent the collision while preserving updates to one executor activity during that run:

message_id=f"{run_id}:executor:{executor_id}" if executor_id else generate_event_id()

There is one additional case to consider: if the same executor can have multiple distinct invocations within a single run, run_id + executor_id would still collide. If those invocations should appear as separate activities, the ID also needs an invocation-specific component that remains stable from the invoked event through its completed or failed event.

So yes, the current executor:{executor_id} value is insufficient across runs. I'm going to convert this discussion to an issue to better track it. I'll add regression coverage for running the same executor in consecutive runs on one thread. Thanks for catching it.

[moonbox3]

Tracking as #7338. Please follow along there.

[mjod]

Thanks @moonbox3 for the explanation. Appreciate your thoughts on message_id, originally thought it was referring to global uniqueness but thread/user scoped makes sense. Didn't even think of multiple of the same executor in a single run but your right about the collision there, good catch.