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.

[VaguelySerious]

@brenbitY2K

1. Is client-side persistence the recommended pattern?

No. We recommend either doing client-side or workflow-side persistence, depending on your specific needs. In most cases, this will be workflow-side persistence, since clients aren't guaranteed to be connected on workflow finish.

As of @workflow/ai@4.0.1-beta.46, you can persist messages like so:

export async function chat(initialUiMessages: UIMessage[]) {
  "use workflow";
  
  const writable = getWritable<UIMessageChunk>();
  const agent = new DurableAgent({
    // ...
  });

  const { uiMessages, messages: modelMessages } = await agent.stream({
    messages: convertToModelMessages(initialUiMessages),
    collectUIMessages: true,
    writable,
  });

  // If you want UIMessage[] persistence
  await saveMessages(uiMessages);
  // OR, if you want ModelMessage[] persistence
  await saveMessages(modelMessages);
}

2.a Will getRun(runId).getReadable({ startIndex: 0 }) still return all chunks?

Yes. The run writes to a durable stream even if no clients are connected, and this stream can be re-read at any point.

2.b Is there a TTL on chunk storage? How long can we rely on reconnection working?

This depends on the World you use. When deploying to Vercel, the current TTL on stream chunks is 30 days, and is displayed on the run detail view in the Vercel UI. This will later likely be set to 24h/1w/1m TTL for Hobby/Pro/Enterprise plans on Vercel, but is set to 30 days for all users during Beta.
The PostgreSQL World and Local World currently do not implement TTLs for streams. For other providers, see their code / documentation.

Note that you can always persist the stream after the model is done, by using a step to read the stream and pipe it into a DB.

3. If a user resumes a chat session for a run completed in absence, does onChatEnd fire?

Yes. I haven't tested this specifically as of yet, but onChatEnd triggers based on reading a UIMessageChunk where type === 'finish'. The workflow stream will keep this chunk, it will be re-played on reconnect, and when the client catches up to that message chunk, it will fire onChatEnd.