workflow 5.0.0-beta.5 → 5.0.0-beta.51

package/docs/ai/chat-session-modeling.mdx

@@ -1,8 +1,8 @@
 ---
 title: Chat Session Modeling
-description: Model chat sessions at different architectural layers to control state ownership and handle interruptions.
+description: Model WorkflowAgent chat sessions at different architectural layers to control state ownership and handle interruptions.
 type: guide
-summary: Choose between single-turn and multi-turn workflow patterns for managing chat session state.
+summary: Choose between single-turn and multi-turn WorkflowAgent patterns for managing chat session state.
 prerequisites:
   - /docs/ai
   - /docs/foundations/workflows-and-steps
@@ -10,525 +10,278 @@ related:
   - /docs/ai/message-queueing
   - /docs/ai/resumable-streams
   - /docs/foundations/hooks
-  - /docs/api-reference/workflow-ai/durable-agent
   - /docs/api-reference/workflow/define-hook
 ---
 
-Chat sessions in AI agents can be modeled at different layers of your architecture. The choice affects state ownership and how you handle interruptions and reconnections.
+Chat sessions can be modeled at different layers of your architecture. The choice determines who owns message history, how long a workflow run stays active, and how clients reconnect after an interruption.
 
-While there are many ways to model chat sessions, the two most common categories are single-turn and multi-turn.
+Workflow 5 applications should use AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) for both patterns.
 
-## Single-Turn Workflows
+## Single-turn workflows
 
-Each user message triggers a new workflow run. The client or API route owns the conversation history and sends the full message array with each request.
+Each user turn starts a new workflow run. The client or API owns conversation history and sends the complete `UIMessage[]` array with every request.
 
-<Tabs items={['Workflow', 'API Route', 'Client']}>
+### Workflow
 
-<Tab value="Workflow">
+Convert UI messages to model messages inside the workflow. `WorkflowAgent` writes durable `ModelCallStreamPart` values to the run stream.
 
-```typescript title="workflows/chat/index.ts" lineNumbers
-import { DurableAgent } from "@workflow/ai/agent";
+```typescript title="workflows/chat.ts" lineNumbers
+import { WorkflowAgent, type ModelCallStreamPart } from "@ai-sdk/workflow";
+import { convertToModelMessages, type UIMessage } from "ai";
 import { getWritable } from "workflow";
-import { flightBookingTools, FLIGHT_ASSISTANT_PROMPT } from "./steps/tools";
-import { convertToModelMessages, type UIMessage, type UIMessageChunk } from "ai";
+import { flightBookingTools, FLIGHT_ASSISTANT_PROMPT } from "./tools";
 
 export async function chat(messages: UIMessage[]) {
   "use workflow";
 
-  const writable = getWritable<UIMessageChunk>();
-
-  const agent = new DurableAgent({
-    model: "bedrock/claude-haiku-4-5-20251001-v1",
+  const agent = new WorkflowAgent({
+    model: "spacexai/grok-4.6",
     instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
 
-  await agent.stream({
-    messages: await convertToModelMessages(messages), // [!code highlight] Full history from client
-    writable,
+  return agent.stream({
+    messages: await convertToModelMessages(messages),
+    writable: getWritable<ModelCallStreamPart>(),
   });
 }
 ```
 
-</Tab>
+### API route
 
-<Tab value="API Route">
+Convert the durable model-call stream to AI SDK UI chunks at the response boundary:
 
 ```typescript title="app/api/chat/route.ts" lineNumbers
+import { createModelCallToUIChunkTransform } from "@ai-sdk/workflow";
 import { createUIMessageStreamResponse, type UIMessage } from "ai";
 import { start } from "workflow/api";
 import { chat } from "@/workflows/chat";
 
-export async function POST(req: Request) {
-  const { messages }: { messages: UIMessage[] } = await req.json();
-
-  const run = await start(chat, [messages]); // [!code highlight]
+export async function POST(request: Request) {
+  const { messages }: { messages: UIMessage[] } = await request.json();
+  const run = await start(chat, [messages]);
 
   return createUIMessageStreamResponse({
-    stream: run.readable,
-    headers: {
-      "x-workflow-run-id": run.runId, // [!code highlight] For stream reconnection
-    },
+    stream: run.readable.pipeThrough(createModelCallToUIChunkTransform()),
+    headers: { "x-workflow-run-id": run.runId },
   });
 }
 ```
 
-</Tab>
-
-<Tab value="Client">
+### Client
 
-Chat messages need to be stored somewhere—typically a database. In this example, we assume a route like `/chats/:id` passes the session ID, allowing us to fetch existing messages and persist new ones.
+`WorkflowChatTransport` reconnects when the HTTP connection ends before the workflow stream finishes:
 
-```typescript title="app/chats/[id]/page.tsx" lineNumbers
+```tsx title="app/chat.tsx" lineNumbers
 "use client";
 
 import { useChat } from "@ai-sdk/react";
-import { WorkflowChatTransport } from "@workflow/ai"; // [!code highlight]
-import { useParams } from "next/navigation";
+import { WorkflowChatTransport } from "@ai-sdk/workflow";
 import { useMemo } from "react";
 
-// Fetch existing messages from your backend
-async function getMessages(sessionId: string) { // [!code highlight]
-  const res = await fetch(`/api/chats/${sessionId}/messages`); // [!code highlight]
-  return res.json(); // [!code highlight]
-} // [!code highlight]
-
 export function Chat({ initialMessages }) {
-  const { id: sessionId } = useParams<{ id: string }>();
-
-  const transport = useMemo( // [!code highlight]
-    () => // [!code highlight]
-      new WorkflowChatTransport({ // [!code highlight]
-        api: "/api/chat", // [!code highlight]
-        onChatEnd: async () => { // [!code highlight]
-          // Persist the updated messages to the chat session // [!code highlight]
-          await fetch(`/api/chats/${sessionId}/messages`, { // [!code highlight]
-            method: "PUT", // [!code highlight]
-            headers: { "Content-Type": "application/json" }, // [!code highlight]
-            body: JSON.stringify({ messages }), // [!code highlight]
-          }); // [!code highlight]
-        }, // [!code highlight]
-      }), // [!code highlight]
-    [sessionId] // [!code highlight]
-  ); // [!code highlight]
-
-  const { messages, input, handleInputChange, handleSubmit } = useChat({
-    initialMessages, // [!code highlight] Loaded via getMessages(sessionId)
-    transport, // [!code highlight]
+  const transport = useMemo(
+    () => new WorkflowChatTransport({ api: "/api/chat" }),
+    []
+  );
+  const { messages, sendMessage } = useChat({
+    messages: initialMessages,
+    transport,
   });
 
-  return (
-    <form onSubmit={handleSubmit}>
-      {/* ... render messages ... */}
-      <input value={input} onChange={handleInputChange} />
-    </form>
-  );
+  // Render messages and call sendMessage({ text }) from your form.
 }
 ```
 
-</Tab>
-
-</Tabs>
-
-This is the pattern used in the [Building Durable AI Agents](/docs/ai) guide.
-
-In this pattern, the client owns conversation state, with the latest turn managed by the AI SDK's `useChat`, and past turns persisted to a user-managed database.
-
-Persisting the turn is usually done through either:
-
-- A step on the workflow that runs after `agent.stream()` and takes the message history from the agent return value (either `messages: ModelMessage[]` or `uiMessages: UIMessage[]`)
-- A hook on `useChat`in the client that calls an API to persist state (or localStorage, etc.), either on every new message, or `onFinish`
-- The resumable stream attached to the workflow (see [Resumable Streams](/docs/ai/resumable-streams))
-  - Note that user messages are not persisted to the stream by default, and need to be explicitly persisted separately
+Persist `UIMessage[]` in your application database. `WorkflowAgent.stream()` returns `ModelMessage[]`, but there is no general conversion from model messages back to UI messages with all UI metadata intact.
 
-## Multi-Turn Workflows
+Use the single-turn pattern when:
 
-A single workflow handles the entire conversation session across multiple turns, and owns the current conversation state. The clients/API routes inject new messages via hooks. The workflow run ID serves as the session identifier.
+- Your application already owns chat history
+- Each turn should run on the latest deployment
+- You want a simple request-to-run mapping
+- Approval responses or client-side tool results arrive as another message turn
 
-For a full example of an agent using multi-turn workflows, check out the Flight Booking App example in the [Workflow Examples](https://github.com/vercel/workflow-examples/tree/main/flight-booking-app) repository.
+## Multi-turn workflows
 
-A key challenge in multi-turn workflows is ensuring user messages appear in the correct order when replaying the stream (e.g., after a page refresh). Since the stream primarily contains AI responses, user messages must be explicitly marked in the stream so the client can reconstruct the full conversation.
+A single workflow run can own the model-message history for the whole session. It waits on a Hook between turns, and external callers resume the Hook with the next message. The workflow run ID becomes the session identifier.
 
-<Tabs items={['Workflow', 'API Routes', 'Hook Definition', 'Client Hook']}>
-
-<Tab value="Workflow">
+```typescript title="workflows/chat-session.ts" lineNumbers
+import { WorkflowAgent, type ModelCallStreamPart } from "@ai-sdk/workflow";
+import { type ModelMessage } from "ai";
+import { defineHook, getWorkflowMetadata, getWritable } from "workflow";
+import { z } from "zod";
+import { flightBookingTools, FLIGHT_ASSISTANT_PROMPT } from "./tools";
 
-```typescript title="workflows/chat/index.ts" lineNumbers
-import {
-  convertToModelMessages,
-  type UIMessageChunk,
-  type UIMessage,
-  type ModelMessage,
-} from "ai";
-import { DurableAgent } from "@workflow/ai/agent";
-import { getWritable, getWorkflowMetadata } from "workflow";
-import { chatMessageHook } from "./hooks/chat-message";
-import { flightBookingTools, FLIGHT_ASSISTANT_PROMPT } from "./steps/tools";
-import { writeUserMessageMarker, writeStreamClose } from "./steps/writer"; // [!code highlight]
+export const chatMessageHook = defineHook({
+  schema: z.object({ message: z.string() }),
+});
 
-export async function chat(initialMessages: UIMessage[]) {
+export async function chatSession(initialMessages: ModelMessage[]) {
   "use workflow";
 
-  const { workflowRunId: runId } = getWorkflowMetadata();
-  const writable = getWritable<UIMessageChunk>();
-  const messages: ModelMessage[] = await convertToModelMessages(initialMessages);
-
-  // Write markers for initial user messages (for replay) // [!code highlight]
-  for (const msg of initialMessages) { // [!code highlight]
-    if (msg.role === "user") { // [!code highlight]
-      const text = msg.parts.filter((p) => p.type === "text").map((p) => p.text).join(""); // [!code highlight]
-      if (text) await writeUserMessageMarker(writable, text, msg.id); // [!code highlight]
-    } // [!code highlight]
-  } // [!code highlight]
+  const { workflowRunId } = getWorkflowMetadata();
+  const hook = chatMessageHook.create({ token: workflowRunId });
+  const writable = getWritable<ModelCallStreamPart>();
+  let messages = [...initialMessages];
 
-  const agent = new DurableAgent({
-    model: "bedrock/claude-haiku-4-5-20251001-v1",
+  const agent = new WorkflowAgent({
+    model: "spacexai/grok-4.6",
     instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
 
-  // Use run ID as the hook token for easy resumption
-  const hook = chatMessageHook.create({ token: runId });
-  let turnNumber = 0;
-
-  while (true) {
-    turnNumber++;
+  const maxTurns = 100;
+  for (let turn = 0; turn < maxTurns; turn++) {
     const result = await agent.stream({
       messages,
       writable,
-      preventClose: true, // [!code highlight] Keep stream open for follow-ups
-      sendStart: turnNumber === 1,
+      preventClose: true,
       sendFinish: false,
     });
-    messages.push(...result.messages.slice(messages.length));
+    messages = result.messages;
 
-    // Wait for next user message via hook
-    const { message: followUp } = await hook;
-    if (followUp === "/done") break;
+    // Do not accept a follow-up that this run has no remaining turn to process.
+    if (turn === maxTurns - 1) break;
 
-    // Write marker and add to messages // [!code highlight]
-    const followUpId = `user-${runId}-${turnNumber}`; // [!code highlight]
-    await writeUserMessageMarker(writable, followUp, followUpId); // [!code highlight]
-    messages.push({ role: "user", content: followUp });
+    const { message } = await hook;
+    if (message === "/done") break;
+    messages = [...messages, { role: "user", content: message }];
   }
 
-  await writeStreamClose(writable); // [!code highlight]
   return { messages };
 }
 ```
 
-The `writeUserMessageMarker` helper writes a `data-workflow` chunk to mark user turns:
-
-```typescript title="workflows/chat/steps/writer.ts" lineNumbers
-import type { UIMessageChunk } from "ai";
-
-export async function writeUserMessageMarker( // [!code highlight]
-  writable: WritableStream<UIMessageChunk>,
-  content: string,
-  messageId: string
-) {
-  "use step"; // [!code highlight]
-  const writer = writable.getWriter();
-  try {
-    await writer.write({
-      type: "data-workflow", // [!code highlight]
-      data: { type: "user-message", id: messageId, content, timestamp: Date.now() }, // [!code highlight]
-    } as UIMessageChunk);
-  } finally {
-    writer.releaseLock();
-  }
-}
-
-export async function writeStreamClose(writable: WritableStream<UIMessageChunk>) {
-  const writer = writable.getWriter();
-  await writer.write({ type: "finish" });
-  await writer.close();
-}
-```
-
-</Tab>
+Create the Hook once, outside the loop. Recreating the same token on every turn causes a Hook conflict. Intermediate turns use `preventClose: true` with `sendFinish: false`; the workflow closes the durable stream and emits the final UI `finish` when the run returns.
 
-<Tab value="API Routes">
+### Start and resume the session
 
-Three endpoints: start a session, send follow-up messages, and reconnect to the stream.
+Use one route to create the run and a second route to deliver follow-up messages:
 
 ```typescript title="app/api/chat/route.ts" lineNumbers
-import { createUIMessageStreamResponse, type UIMessage } from "ai";
+import { convertToModelMessages, type UIMessage } from "ai";
 import { start } from "workflow/api";
-import { chat } from "@/workflows/chat";
-
-export async function POST(req: Request) {
-  const { initialMessage }: { initialMessage: UIMessage } = await req.json();
+import { chatSession } from "@/workflows/chat-session";
 
-  const run = await start(chat, [[initialMessage]]); // [!code highlight]
-
-  return createUIMessageStreamResponse({
-    stream: run.readable,
-    headers: {
-      "x-workflow-run-id": run.runId, // [!code highlight] For follow-ups and reconnection
-    },
-  });
+export async function POST(request: Request) {
+  const { messages }: { messages: UIMessage[] } = await request.json();
+  const run = await start(chatSession, [await convertToModelMessages(messages)]);
+  return Response.json({ runId: run.runId });
 }
 ```
 
-```typescript title="app/api/chat/[id]/route.ts" lineNumbers
-import { chatMessageHook } from "@/workflows/chat/hooks/chat-message";
+```typescript title="app/api/chat/[runId]/message/route.ts" lineNumbers
+import { chatMessageHook } from "@/workflows/chat-session";
 
 export async function POST(
-  req: Request,
-  { params }: { params: Promise<{ id: string }> }
+  request: Request,
+  { params }: { params: Promise<{ runId: string }> }
 ) {
-  const { id: runId } = await params;
-  const { message } = await req.json();
-
-  // Resume the hook using the workflow run ID // [!code highlight]
-  await chatMessageHook.resume(runId, { message }); // [!code highlight]
-
+  const { runId } = await params;
+  const { message }: { message: string } = await request.json();
+  await chatMessageHook.resume(runId, { message });
   return Response.json({ success: true });
 }
 ```
 
-```typescript title="app/api/chat/[id]/stream/route.ts" lineNumbers
+### Reconnect to the stream
+
+`WorkflowChatTransport` counts transformed UI chunks, while the durable stream stores raw `ModelCallStreamPart` values. Always replay the raw stream from index `0` and apply the UI cursor in `createModelCallToUIChunkTransform()`:
+
+{/* @skip-typecheck: requires AI SDK 7 and @ai-sdk/workflow */}
+```typescript title="app/api/chat/[runId]/stream/route.ts" lineNumbers
+import { createModelCallToUIChunkTransform } from "@ai-sdk/workflow";
 import { createUIMessageStreamResponse } from "ai";
 import { getRun } from "workflow/api";
 
 export async function GET(
   request: Request,
-  { params }: { params: Promise<{ id: string }> }
+  { params }: { params: Promise<{ runId: string }> }
 ) {
-  const { id } = await params;
-  const { searchParams } = new URL(request.url);
-  const startIndex = searchParams.get("startIndex");
-
-  const run = getRun(id); // [!code highlight]
-  const stream = run.getReadable({ // [!code highlight]
-    startIndex: startIndex ? parseInt(startIndex, 10) : undefined, // [!code highlight]
-  }); // [!code highlight]
-
-  return createUIMessageStreamResponse({ stream });
-}
-```
-
-</Tab>
-
-<Tab value="Hook Definition">
-
-```typescript title="workflows/chat/hooks/chat-message.ts" lineNumbers
-import { defineHook } from "workflow";
-import { z } from "zod";
-
-export const chatMessageHook = defineHook({
-  schema: z.object({
-    message: z.string(),
-  }),
-});
-```
-
-</Tab>
-
-<Tab value="Client Hook">
-
-A custom hook wraps `useChat` to manage the multi-turn session. It handles:
-
-- Routing between the initial message endpoint and follow-up endpoint
-- Reconstructing user messages from stream markers for correct ordering on replay
-
-```typescript title="hooks/use-multi-turn-chat.ts" lineNumbers
-"use client";
+  const { runId } = await params;
+  const startIndex = Number(
+    new URL(request.url).searchParams.get("startIndex") ?? "0"
+  );
 
-import type { UIMessage, UIDataTypes, ChatStatus } from "ai";
-import { useChat } from "@ai-sdk/react";
-import { WorkflowChatTransport } from "@workflow/ai";
-import { useState, useCallback, useMemo, useEffect, useRef } from "react";
+  if (!Number.isSafeInteger(startIndex) || startIndex < 0) {
+    return Response.json(
+      { error: "startIndex must be a non-negative safe integer" },
+      { status: 400 }
+    );
+  }
 
-const STORAGE_KEY = "workflow-run-id";
+  const run = getRun(runId);
+  const stream = run
+    .getReadable({ startIndex: 0 })
+    .pipeThrough(createModelCallToUIChunkTransform({ uiStartIndex: startIndex }));
 
-interface UserMessageData {
-  type: "user-message";
-  id: string;
-  content: string;
-  timestamp: number;
+  return createUIMessageStreamResponse({
+    stream,
+    headers: { "x-workflow-run-id": runId },
+  });
 }
+```
 
-export function useMultiTurnChat() {
-  const [runId, setRunId] = useState<string | null>(null);
-  const [shouldResume, setShouldResume] = useState(false);
-  const userMessagesRef = useRef<Map<string, UIMessage>>(new Map());
+Persist `UIMessage[]` separately if the client must reconstruct user messages and UI metadata after a refresh. The workflow-owned `ModelMessage[]` history is the model's durable context, not a replacement for an application chat table.
 
-  // Check for existing session on mount // [!code highlight]
-  useEffect(() => {
-    const storedRunId = localStorage.getItem(STORAGE_KEY);
-    if (storedRunId) {
-      setRunId(storedRunId);
-      setShouldResume(true);
-    }
-  }, []);
+### Persist and display the full session
 
-  const transport = useMemo(
-    () =>
-      new WorkflowChatTransport({
-        api: "/api/chat",
-        onChatSendMessage: (response) => {
-          const workflowRunId = response.headers.get("x-workflow-run-id");
-          if (workflowRunId) {
-            setRunId(workflowRunId);
-            localStorage.setItem(STORAGE_KEY, workflowRunId);
-          }
-        },
-        onChatEnd: () => {
-          setRunId(null);
-          localStorage.removeItem(STORAGE_KEY);
-          userMessagesRef.current.clear();
-        },
-        prepareReconnectToStreamRequest: ({ api, ...rest }) => {
-          const storedRunId = localStorage.getItem(STORAGE_KEY);
-          if (!storedRunId) throw new Error("No active session");
-          return { ...rest, api: `/api/chat/${storedRunId}/stream` };
-        },
-      }),
-    []
-  );
+A multi-turn chat has three related records with different responsibilities:
 
-  const { messages: rawMessages, sendMessage: baseSendMessage, status, stop, setMessages } =
-    useChat({ resume: shouldResume, transport });
-
-  // Reconstruct conversation order from stream markers // [!code highlight]
-  const messages = useMemo(() => { // [!code highlight]
-    const result: UIMessage[] = []; // [!code highlight]
-    const seenContent = new Set<string>(); // [!code highlight]
-    // [!code highlight]
-    // Collect content from optimistic user messages // [!code highlight]
-    for (const msg of rawMessages) { // [!code highlight]
-      if (msg.role === "user") { // [!code highlight]
-        const text = msg.parts.filter((p) => p.type === "text").map((p) => p.text).join(""); // [!code highlight]
-        if (text) seenContent.add(text); // [!code highlight]
-      } // [!code highlight]
-    } // [!code highlight]
-    // [!code highlight]
-    for (const msg of rawMessages) { // [!code highlight]
-      if (msg.role === "user") { // [!code highlight]
-        result.push(msg); // [!code highlight]
-        continue; // [!code highlight]
-      } // [!code highlight]
-      // [!code highlight]
-      if (msg.role === "assistant") { // [!code highlight]
-        // Process parts in order, splitting on user-message markers // [!code highlight]
-        let currentParts: typeof msg.parts = []; // [!code highlight]
-        let partIndex = 0; // [!code highlight]
-        // [!code highlight]
-        for (const part of msg.parts) { // [!code highlight]
-          if (part.type === "data-workflow" && "data" in part) { // [!code highlight]
-            const data = part.data as UserMessageData; // [!code highlight]
-            if (data?.type === "user-message") { // [!code highlight]
-              // Flush accumulated assistant parts // [!code highlight]
-              if (currentParts.length > 0) { // [!code highlight]
-                result.push({ ...msg, id: `${msg.id}-${partIndex++}`, parts: currentParts }); // [!code highlight]
-                currentParts = []; // [!code highlight]
-              } // [!code highlight]
-              // Add user message if not duplicate // [!code highlight]
-              if (!seenContent.has(data.content)) { // [!code highlight]
-                seenContent.add(data.content); // [!code highlight]
-                result.push({ id: data.id, role: "user", parts: [{ type: "text", text: data.content }] }); // [!code highlight]
-              } // [!code highlight]
-              continue; // [!code highlight]
-            } // [!code highlight]
-          } // [!code highlight]
-          currentParts.push(part); // [!code highlight]
-        } // [!code highlight]
-        // [!code highlight]
-        if (currentParts.length > 0) { // [!code highlight]
-          result.push({ ...msg, id: partIndex > 0 ? `${msg.id}-${partIndex}` : msg.id, parts: currentParts }); // [!code highlight]
-        } // [!code highlight]
-      } // [!code highlight]
-    } // [!code highlight]
-    return result; // [!code highlight]
-  }, [rawMessages]); // [!code highlight]
-
-  // Route messages to appropriate endpoint
-  const sendMessage = useCallback(
-    async (text: string) => {
-      if (runId) {
-        // Follow-up: send via hook resumption // [!code highlight]
-        await fetch(`/api/chat/${runId}`, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ message: text }),
-        });
-      } else {
-        // First message: start new workflow
-        await baseSendMessage({ text, metadata: { createdAt: Date.now() } });
-      }
-    },
-    [runId, baseSendMessage]
-  );
+1. **Workflow model history**: `ModelMessage[]` is the durable context sent back to the model on each turn.
+2. **Workflow run stream**: `ModelCallStreamPart` values contain durable model and tool output for live delivery and reconnection.
+3. **Application chat history**: `UIMessage[]` preserves user messages, display metadata, attachments, and application-specific parts.
 
-  const endSession = useCallback(async () => {
-    if (runId) {
-      await fetch(`/api/chat/${runId}`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ message: "/done" }),
-      });
-    }
-    setRunId(null);
-    setShouldResume(false);
-    localStorage.removeItem(STORAGE_KEY);
-    userMessagesRef.current.clear();
-    setMessages([]);
-  }, [runId, setMessages]);
-
-  return { messages, status, runId, sendMessage, endSession, stop };
-}
-```
-
-</Tab>
-
-</Tabs>
+When the user sends the first message, start the run, store its run ID with the application chat record, and connect to the run stream. For each follow-up, optimistically add and persist the user `UIMessage`, then resume `chatMessageHook` with the corresponding text. After a refresh, load the persisted UI messages and reconnect through the stream route above using the last persisted UI chunk cursor. If you persist only user messages, replay model output from the beginning and merge by stable message IDs.
 
-In this pattern, the workflow owns the entire conversation session. All messages are persisted in the workflow, and follow-up messages are injected via hooks. The workflow writes **user message markers** to the stream using `data-workflow` chunks, which allows the client to reconstruct the full conversation in the correct order when replaying the stream (e.g., after a page refresh).
+Do not treat the run stream as the only chat database. `WorkflowAgent` deliberately stores raw model-call parts, and user messages resumed through a Hook are not automatically written to that output stream. Keeping the application history separate avoids synthetic stream markers and preserves UI information that cannot be reconstructed from `ModelMessage[]`.
 
-The client hook processes these markers by:
+<Callout type="info">
+The reconnect route replays raw `ModelCallStreamPart` values from index `0` because raw parts and transformed UI chunks do not have matching indexes. `uiStartIndex` prevents already-delivered UI chunks from being sent to the client again, but the server still transforms the earlier raw history. For very long streams, split conversations into bounded runs until WorkflowAgent exposes a persisted raw-to-UI cursor mapping.
+</Callout>
 
-1. Iterating through message parts in order
-2. When a `user-message` marker is found, flushing any accumulated assistant content and inserting the user message
-3. Deduplicating against optimistic sends from the initial message
+Use the multi-turn pattern when:
 
-This ensures the conversation displays as User → AI → User → AI regardless of whether viewing live or replaying from the stream.
+- One workflow should own the session's model context
+- Backend events or other users need to inject messages through Hooks
+- Full-session tracing is more important than running every turn on the newest deployment
+- The application is prepared to manage a long-lived run and stream cursor
 
-## Choosing a Pattern
+## Choosing a pattern
 
-| Consideration | Single-Turn | Multi-Turn |
+| Consideration | Single-turn | Multi-turn |
 |--------------|-------------|------------|
-| State ownership | Client or API route | Workflow |
-| Message injection from backend | Requires stitching together runs | Native via hooks |
+| State ownership | Client or application database | Workflow for model context; application database for UI history |
+| Deployment version | Latest deployment per turn | Deployment that started the run |
+| Message injection | Start another run | Resume a Hook |
 | Workflow complexity | Lower | Higher |
-| Workflow time horizon | Minutes | Hours to indefinitely |
-| Observability scope | Per-turn traces | Full session traces |
+| Workflow time horizon | One model turn | Hours or longer |
+| Observability scope | Per turn | Full session |
 
-**Multi-turn is recommended for most production use-cases.** If you're starting fresh, go with multi-turn. It's more flexible and grows with your requirements. You don't need to maintain the chat history yourself and can offload all that to the workflow's built in persistence. It also enables native message injection and full session observability, which becomes increasingly valuable as your agent matures.
+**Multi-turn works well for new durable sessions.** The workflow owns model context, accepts messages from users and backend systems through the same Hook, and provides one full-session trace.
 
-**Single-turn works well when adapting existing architectures.** If you already have a system for managing message state, and want to adopt durable agents incrementally, single-turn workflows slot in with minimal changes. Each turn maps cleanly to an independent workflow run.
+**Single-turn works well when adapting an existing architecture.** If the application already manages message state and you want to adopt durable agents incrementally, one workflow run per turn requires fewer lifecycle changes and always uses the latest deployment.
 
-## Multiplayer Chat Sessions
+## Multiplayer chat sessions
 
-The multi-turn pattern also easily enables multi-player chat sessions. New messages can come from system events, external services, and other users. Since a `hook` injects messages into workflow at any point, and the entire history is a single stream that clients can reconnect to, it doesn't matter where the injected messages come from. Here are different use-cases for multi-player chat sessions:
+The multi-turn pattern also supports messages from system events, external services, and multiple users. Every source resumes the same Hook; the workflow queues those messages and processes them between model turns.
 
-<Tabs items={['System Event', 'External Service', 'Multiple Users']}>
+<Tabs items={['System event', 'External service', 'Multiple users']}>
 
-<Tab value="System Event">
+<Tab value="System event">
 
-Internal system events like scheduled tasks, background jobs, or database triggers can inject updates into an active conversation.
+Scheduled tasks, background jobs, or database triggers can inject updates into an active conversation:
 
 ```typescript title="app/api/internal/flight-update/route.ts" lineNumbers
-import { chatMessageHook } from "@/workflows/chat/hooks/chat-message";
+import { chatMessageHook } from "@/workflows/chat-session";
 
-// Called by your flight status monitoring system
-export async function POST(req: Request) {
-  const { runId, flightNumber, newStatus } = await req.json();
+export async function POST(request: Request) {
+  const { runId, flightNumber, newStatus } = await request.json();
 
-  await chatMessageHook.resume(runId, { // [!code highlight]
-    message: `[System] Flight ${flightNumber} status updated: ${newStatus}`, // [!code highlight]
-  }); // [!code highlight]
+  await chatMessageHook.resume(runId, {
+    message: `[System] Flight ${flightNumber} status updated: ${newStatus}`,
+  });
 
   return Response.json({ success: true });
 }
@@ -536,20 +289,20 @@ export async function POST(req: Request) {
 
 </Tab>
 
-<Tab value="External Service">
+<Tab value="External service">
 
-External webhooks from third-party services (Stripe, Twilio, etc.) can notify the conversation of events.
+A third-party webhook can notify the conversation about an external event:
 
 ```typescript title="app/api/webhooks/payment/route.ts" lineNumbers
-import { chatMessageHook } from "@/workflows/chat/hooks/chat-message";
+import { chatMessageHook } from "@/workflows/chat-session";
 
-export async function POST(req: Request) {
-  const { runId, paymentStatus, amount } = await req.json();
+export async function POST(request: Request) {
+  const { runId, paymentStatus, amount } = await request.json();
 
   if (paymentStatus === "succeeded") {
-    await chatMessageHook.resume(runId, { // [!code highlight]
-      message: `[Payment] Payment of $${amount.toFixed(2)} received. Your booking is confirmed!`, // [!code highlight]
-    }); // [!code highlight]
+    await chatMessageHook.resume(runId, {
+      message: `[Payment] Payment of $${amount.toFixed(2)} received. Your booking is confirmed.`,
+    });
   }
 
   return Response.json({ received: true });
@@ -558,38 +311,39 @@ export async function POST(req: Request) {
 
 </Tab>
 
-<Tab value="Multiple Users">
+<Tab value="Multiple users">
 
-Multiple human users can participate in the same conversation. Each user's client connects to the same workflow stream.
+Multiple authenticated users can participate in the same workflow-owned session. Include attribution when resuming the Hook:
 
-```typescript title="app/api/chat/[id]/route.ts" lineNumbers
-import { chatMessageHook } from "@/workflows/chat/hooks/chat-message";
+```typescript title="app/api/chat/[runId]/message/route.ts" lineNumbers
+import { chatMessageHook } from "@/workflows/chat-session";
 import { getUser } from "@/lib/auth";
 
 export async function POST(
-  req: Request,
-  { params }: { params: Promise<{ id: string }> }
+  request: Request,
+  { params }: { params: Promise<{ runId: string }> }
 ) {
-  const { id: runId } = await params;
-  const { message } = await req.json();
-  const user = await getUser(req); // [!code highlight]
+  const { runId } = await params;
+  const { message } = await request.json();
+  const user = await getUser(request);
 
-  // Inject message with user attribution // [!code highlight]
-  await chatMessageHook.resume(runId, { // [!code highlight]
-    message: `[${user.name}] ${message}`, // [!code highlight]
-  }); // [!code highlight]
+  await chatMessageHook.resume(runId, {
+    message: `[${user.name}] ${message}`,
+  });
 
   return Response.json({ success: true });
 }
 ```
 
+To preserve structured attribution across refreshes, persist the corresponding `UIMessage` using the application-history approach described above.
+
 </Tab>
 
 </Tabs>
 
-## Related Documentation
+## Related documentation
 
-- [Building Durable AI Agents](/docs/ai) - Foundation guide for durable agents
-- [Message Queueing](/docs/ai/message-queueing) - Queueing messages during tool execution
-- [`defineHook()` API Reference](/docs/api-reference/workflow/define-hook) - Hook configuration options
-- [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Full API documentation
+- [Building Durable AI Agents](/docs/ai): Foundation guide for WorkflowAgent
+- [Message Queueing](/docs/ai/message-queueing): Inject messages between model-call steps
+- [Resumable Streams](/docs/ai/resumable-streams): Reconnect to durable output
+- [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent): AI SDK API for durable, resumable agents