Best practices for message persistence with DurableAgent?

[brenbitY2K]

I'm building a chat application using DurableAgent with human-in-the-loop interactions via defineHook. The workflow can pause for extended periods (days) waiting for user input, which might come from the chat UI or from external triggers like email webhooks.

I want to understand the recommended patterns for:

1. Persisting chat messages to a database
2. Handling scenarios where the user isn't actively connected when the workflow completes

My Current Understanding

This could be way off, but this is what I've gathered from digging through the codebase:

Workflow starts → Agent streams → Hook suspends → Stream ends
[Time passes - no compute used]
Hook resumed → Workflow continues → Stream ends again (completed)

While we're suspended due to the hook, the messages still exist "in memory" for that workflow run, so no immediate need to save to the DB yet. When the workflow fully completes, that's when we need to worry about persisting the messages b/c the workflow is over and the next request has no memory of the prior messages (unless explicitly sent over obviously).

Message format challenge:

DurableAgent.stream() returns ModelMessage[], but we store messages as UIMessage[]. The createUIMessageStream wrapper on the client/server reconstructs UIMessage[] from stream chunks in its onFinish callback.

Since ModelMessage contains less information than UIMessage, the reliable place to get the full UIMessage format is from the stream consumer (client or proxy), not from the workflow itself. This is how most people use the AI SDK. We can't really do this in the workflow unless we set up some proxy server that reads the stream and runs createUIMessageStream just to be able to save during onFinish which kind of defeats the ergonomics of the Workflow SDK IMO.

Proposed Architecture

Based on the flight-booking-app pattern, I'm considering:

1. Client uses WorkflowChatTransport with onChatEnd callback
2. Client stores workflow run ID for reconnection
3. On page load, client checks for active workflow and reconnects if needed
4. Reconnection replays chunks → onChatEnd fires → ?
5. The ? is where my focus is. I imagine we just hit an endpoint like /api/chat/save with the latest messages

const { messages } = useChat({
  transport: new WorkflowChatTransport({
    onChatEnd: async ({ messages }) => {
      // Save to Postgres
      await fetch("/api/chats/save", { body: JSON.stringify({ chatId, messages }) });
    },
    prepareReconnectToStreamRequest: () => ({
      api: `/api/chat/${runId}/stream`,
    }),
  }),
});

Questions

1. Is client-side persistence the recommended pattern?

The flight-booking-app example uses localStorage. For production apps needing durable storage (Postgres), is having the client call a save endpoint in onChatEnd the intended approach?

2. Stream chunk retention after workflow completion

If a workflow completes while no client is connected, and the user opens the app later:

• Will getRun(runId).getReadable({ startIndex: 0 }) still return all chunks?
• Is there a TTL on chunk storage? How long can we rely on reconnection working?

3. Email/webhook resume with no client

Consider this scenario:

1. Workflow pauses at a hook waiting for user input
2. User receives email with a button that fires a webhook
3. Webhook resumes the hook, workflow runs to completion
4. User is NOT in the app at this time

When the user eventually opens the client, will reconnection work and onChatEnd fire? Or do we need a fallback persistence mechanism in the workflow itself for this case?

Summary

I want to confirm that the recommended architecture is:

• Client owns message persistence (via onChatEnd)
• Reconnection handles the "user was away" case
• Workflow itself doesn't need to save messages (stream chunks are durable)
• Server-side proxy is optional (just for auth if needed)

Is this correct, or are there patterns we're missing for production use cases? If we just saved messages as ModelMessage then there's really no issue here, but saving as UIMessage is a must.