Show one correct chat history as updates arrive
Section: DOC-MA-conversations-streaming-payloads#interpret-conversation-updates.
Show users whether their reply is still arriving, waiting for a tool or complete. Use the native API's conversation state and generation outcomes to keep each displayed message tied to the right run. Deployment-specific subscriptions can also provide updates, but their payloads are not interchangeable with the native response. This guide covers fields available through the state endpoint and generation operations.
Use this recipe after sending a question: keep its run identity, merge incoming or reloaded messages once, then mark the question complete only from a correlated outcome. You need the persisted history and the accepted run ID; a timestamp is not a replacement.
Step 1: Keep the thread, run and messages separate
Section: DOC-MA-conversations-streaming-payloads#keep-identities-distinct.
Store the conversation ID for future reads and the run ID for this submitted question. Merge messages using their stable identities and order them by numeric sequence. Use the identity reference to choose the identifier for each part of that recipe.
Preserve message sequence precision when merging the stored history.
For example, reloading a message you already displayed updates the same item. A message from a later run can belong in the history while still being the wrong evidence for completion of the earlier pending question.
Step 2: Display progress, then the correlated final outcome
Section: DOC-MA-conversations-streaming-payloads#render-and-reconcile.
Display partial streamed text as provisional. A model finish reason or a completed message can end one model attempt while a tool round or run continues. Use the returned status and run identity to interpret the outcome; missing or unknown status does not mean success. The generation outcome table covers completed, failed, cancelled, timed-out and waiting states.
Execute client tools only from complete pending calls and their current clientToolCursor, using the client-tool protocol. Do not execute incomplete argument fragments.
Usage data may arrive later than text or be absent. Missing counters are not zero cost. Display optional reasoning content separately from the answer. Send the next message to the same conversation; you do not need to assemble provider continuation data for the native API.
Finished result: each persisted message appears once, provisional content stays provisional until resolved, and the pending question receives its own known outcome or an explicit unresolved state. Missing usage remains unknown, and a tool callback refers to a complete pending call rather than argument fragments.
Upcoming recipe: merge replayed events without duplicating the reply
Status: Upcoming — not yet available.
Section: DOC-MA-conversations-streaming-payloads#event-identities-and-outcomes
Use this flow when a live reply must survive replay without duplicating a message:
- Keep the conversation, accepted run, attempt, persisted message and transport delivery identities distinct. Merge a repeated delivery by its event identity.
- Retain the resume cursor for replay. A timestamp cannot replace the cursor or event identity.
- Keep text and tool arguments provisional until the relevant item is complete; a finished message or tool round can still precede the run’s final outcome.
- Correlate the terminal outcome with the accepted run. For an unrecognized event, refresh state and keep the outcome unresolved until understood.
If two text chunks arrive before a run fails, leave those chunks visibly incomplete and show the failed outcome. Display optional reasoning separately. Late or missing usage stays late or missing, and attempt counters retain their measurement boundaries.
Finished result: replay does not add another message, and received text cannot turn a failed stream into a successful answer.
These event contracts are not yet available through the current state endpoint. Its existing fields are documented above.
Document ID: DOC-MA-conversations-streaming-payloads. Section identities and revisions.