Idiomatic way to handle final message in `onChatMessage`

[O4epegb]

Potentially this is not an agents issue even, but it feels "buggy" that onFinish callback of toUIMessageStreamResponse does not have id of the last message (responseMessage or last message in messages).

Example might explain it better:

export class ChatAgent extends AIChatAgent<Env> {
  async onChatMessage() {
    // ......
    return result.toUIMessageStreamResponse({
      originalMessages: this.messages,
      onFinish: ({ messages, responseMessage }) => {
        // neither of these has id for the last message
        console.log("Chat finished. Final messages:", messages);
        console.log("Final response message:", responseMessage);

        setTimeout(() => {
          // here you can actually grab latest message and it has an id
          // but it feels hacky that you have to wait for the next tick to get it
          // not sure if this is a correct way
          console.log(this.messages);
        });
      }
    });
  }
}

[threepointone]

Thanks for the clear example — this is mostly a layering mismatch between the Vercel AI SDK’s toUIMessageStreamResponse({ onFinish }) and what AIChatAgent does afterward.

The SDK’s onFinish runs when the UI message stream finishes building its snapshot. That snapshot is not guaranteed to carry the same message id that the agent framework assigns or rewrites while it consumes the SSE stream (e.g. from the start chunk’s messageId), persists the transcript, and updates this.messages. So seeing a missing id there, while this.messages has it on the next tick, is expected rather than a bug in Agents.

What to use instead

For “turn is done and I need the finalized assistant message (including id)” use the onChatResponse lifecycle hook on AIChatAgent. It runs after the assistant message for that turn has been persisted, with the turn lock released, and receives a ChatResponseResult that includes message (the finalized assistant UIMessage), requestId, continuation, and status (completed | error | aborted).

protected async onChatResponse(result: ChatResponseResult) {
  if (result.status === "completed") {
    const id = result.message.id;
    // ...
  }
}

If you need model-level completion metadata (tokens, provider finishReason, etc.), wire streamText({ onFinish }) on the streamText result — that is separate from toUIMessageStreamResponse({ onFinish }).

We have not yet updated the main developer documentation to steer people away from relying on toUIMessageStreamResponse’s onFinish for persisted message ids; we will do so as soon as we can. In the meantime, packages/ai-chat includes onChatResponse and ChatResponseResult in its API surface, and the repo’s docs/chat-agents.md section on onChatResponse has more detail and examples.

[threepointone]

I'll leave this issue until we update the docs. lmk if onChatResponse solves your problem

[O4epegb]

I'll leave this issue until we update the docs. lmk if onChatResponse solves your problem

Oh, I see now, it was added quite recently which is why I didn't see it before (wanted to create this issue like a month ago but forgot and didn't double check any new versions for new stuff, sorry)

Anyway, that's great, exactly what I've needed, thanks a lot!

[threepointone]

docs in cloudflare/cloudflare-docs#29764