From 704b0021bb42c91c7c72760e83b37986ce2a23b7 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 13:44:32 -0800
Subject: [PATCH 01/38] [docs] Add AI Agent docs

---
 .../docs/ai-agents/human-in-the-loop.mdx      | 307 ++++++++++++++++++
 docs/content/docs/ai-agents/index.mdx         | 237 ++++++++++++++
 docs/content/docs/ai-agents/meta.json         |  10 +
 .../docs/ai-agents/resumable-streams.mdx      | 210 ++++++++++++
 .../docs/ai-agents/sleep-and-delays.mdx       | 219 +++++++++++++
 docs/content/docs/meta.json                   |   1 +
 6 files changed, 984 insertions(+)
 create mode 100644 docs/content/docs/ai-agents/human-in-the-loop.mdx
 create mode 100644 docs/content/docs/ai-agents/index.mdx
 create mode 100644 docs/content/docs/ai-agents/meta.json
 create mode 100644 docs/content/docs/ai-agents/resumable-streams.mdx
 create mode 100644 docs/content/docs/ai-agents/sleep-and-delays.mdx

diff --git a/docs/content/docs/ai-agents/human-in-the-loop.mdx b/docs/content/docs/ai-agents/human-in-the-loop.mdx
new file mode 100644
index 000000000..c5e1ee0fb
--- /dev/null
+++ b/docs/content/docs/ai-agents/human-in-the-loop.mdx
@@ -0,0 +1,307 @@
+---
+title: Human-in-the-Loop
+---
+
+Some agent actions require human approval before proceeding - deploying to production, sending emails to customers, or making financial transactions. Workflow DevKit's webhook and hook primitives enable "human-in-the-loop" patterns where workflows pause until a human takes action.
+
+## Creating an Approval Tool
+
+Add a tool that pauses the agent until a human approves or rejects:
+
+```typescript title="ai/tools/human-approval.ts" lineNumbers
+import { tool } from 'ai';
+import { createWebhook, getWritable } from 'workflow'; // [!code highlight]
+import { z } from 'zod';
+import type { UIMessageChunk } from 'ai';
+
+async function emitApprovalRequest(
+  { url, message }: { url: string; message: string },
+  { toolCallId }: { toolCallId: string }
+) {
+  'use step';
+
+  const writable = getWritable<UIMessageChunk>();
+  const writer = writable.getWriter();
+
+  await writer.write({
+    id: toolCallId,
+    type: 'data-approval-required',
+    data: { url, message },
+  });
+
+  writer.releaseLock();
+}
+
+async function executeHumanApproval(
+  { message }: { message: string },
+  { toolCallId }: { toolCallId: string }
+) {
+  // Note: No "use step" - webhooks are workflow-level primitives // [!code highlight]
+
+  const webhook = createWebhook(); // [!code highlight]
+
+  // Emit the approval URL to the UI
+  await emitApprovalRequest(
+    { url: webhook.url, message },
+    { toolCallId }
+  );
+
+  // Workflow pauses here until the webhook is called // [!code highlight]
+  await webhook; // [!code highlight]
+
+  return 'Approval received. Proceeding with action.';
+}
+
+export const humanApproval = tool({
+  description: 'Request human approval before proceeding with an action',
+  inputSchema: z.object({
+    message: z.string().describe('Description of what needs approval'),
+  }),
+  execute: executeHumanApproval,
+});
+```
+
+<Callout type="info">
+The `createWebhook()` function must be called from within a workflow context, not from a step. This is why `executeHumanApproval` does not have `"use step"`.
+</Callout>
+
+## How It Works
+
+1. The agent calls the `humanApproval` tool with a message describing what needs approval
+2. `createWebhook()` generates a unique URL that can resume the workflow
+3. The tool emits a data chunk containing the approval URL to the UI
+4. The workflow pauses at `await webhook` - no compute resources are consumed
+5. When a human visits the webhook URL, the workflow resumes
+6. The tool returns and the agent continues with the approved action
+
+## Handling the Approval UI
+
+The UI receives a data chunk with type `data-approval-required`. Display an approval button that triggers the webhook:
+
+```typescript title="components/approval-button.tsx" lineNumbers
+'use client';
+
+interface ApprovalData {
+  url: string;
+  message: string;
+}
+
+export function ApprovalButton({ data }: { data: ApprovalData }) {
+  const handleApprove = async () => {
+    await fetch(data.url, { method: 'POST' });
+  };
+
+  return (
+    <div>
+      <p>{data.message}</p>
+      <button onClick={handleApprove}>Approve</button>
+    </div>
+  );
+}
+```
+
+## Receiving Approval Data
+
+To receive data from the approval action (such as approve/reject status or comments), read the webhook request body:
+
+```typescript title="ai/tools/human-approval.ts" lineNumbers
+async function executeHumanApproval(
+  { message }: { message: string },
+  { toolCallId }: { toolCallId: string }
+) {
+  const webhook = createWebhook();
+
+  await emitApprovalRequest({ url: webhook.url, message }, { toolCallId });
+
+  const request = await webhook; // [!code highlight]
+  const { approved, comment } = await request.json(); // [!code highlight]
+
+  if (!approved) {
+    return `Action rejected: ${comment}`;
+  }
+
+  return `Approved with comment: ${comment}`;
+}
+```
+
+The UI sends the approval data in the request body:
+
+```typescript lineNumbers
+const handleApprove = async () => {
+  await fetch(data.url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ approved: true, comment: 'Looks good!' }),
+  });
+};
+
+const handleReject = async () => {
+  await fetch(data.url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ approved: false, comment: 'Not ready yet' }),
+  });
+};
+```
+
+## Using Hooks for Type-Safe Approvals
+
+For stronger type safety, use [`defineHook()`](/docs/api-reference/workflow/define-hook) with a schema:
+
+```typescript title="ai/tools/deployment-approval.ts" lineNumbers
+import { tool } from 'ai';
+import { defineHook, getWritable } from 'workflow';
+import { z } from 'zod';
+import type { UIMessageChunk } from 'ai';
+
+// Define a typed hook for deployment approvals
+const deploymentApprovalHook = defineHook({ // [!code highlight]
+  schema: z.object({ // [!code highlight]
+    approved: z.boolean(), // [!code highlight]
+    approvedBy: z.string(), // [!code highlight]
+    environment: z.enum(['staging', 'production']), // [!code highlight]
+  }), // [!code highlight]
+}); // [!code highlight]
+
+async function emitDeploymentApproval(
+  token: string,
+  environment: string,
+  toolCallId: string
+) {
+  'use step';
+
+  const writable = getWritable<UIMessageChunk>();
+  const writer = writable.getWriter();
+
+  await writer.write({
+    id: toolCallId,
+    type: 'data-deployment-approval',
+    data: { token, environment },
+  });
+
+  writer.releaseLock();
+}
+
+async function executeDeploymentApproval(
+  { environment }: { environment: 'staging' | 'production' },
+  { toolCallId }: { toolCallId: string }
+) {
+  const hook = deploymentApprovalHook.create(); // [!code highlight]
+
+  await emitDeploymentApproval(hook.token, environment, toolCallId);
+
+  const approval = await hook; // [!code highlight]
+
+  if (!approval.approved) {
+    return `Deployment to ${environment} rejected by ${approval.approvedBy}`;
+  }
+
+  return `Deployment to ${environment} approved by ${approval.approvedBy}`;
+}
+
+export const deploymentApproval = tool({
+  description: 'Request approval for a deployment',
+  inputSchema: z.object({
+    environment: z.enum(['staging', 'production']),
+  }),
+  execute: executeDeploymentApproval,
+});
+```
+
+Resume the hook from your approval API:
+
+```typescript title="app/api/approve-deployment/route.ts" lineNumbers
+import { deploymentApprovalHook } from '@/ai/tools/deployment-approval';
+
+export async function POST(request: Request) {
+  const { token, approved, approvedBy, environment } = await request.json();
+
+  try {
+    // Schema validation happens automatically // [!code highlight]
+    await deploymentApprovalHook.resume(token, { // [!code highlight]
+      approved, // [!code highlight]
+      approvedBy, // [!code highlight]
+      environment, // [!code highlight]
+    }); // [!code highlight]
+
+    return Response.json({ success: true });
+  } catch (error) {
+    return Response.json(
+      { error: 'Invalid token or validation failed' },
+      { status: 400 }
+    );
+  }
+}
+```
+
+## Use Cases
+
+### Email Approval
+
+Wait for approval before sending an email to customers:
+
+```typescript lineNumbers
+async function executeSendEmail(
+  { recipients, subject, body }: EmailParams,
+  { toolCallId }: { toolCallId: string }
+) {
+  const webhook = createWebhook();
+
+  await emitEmailApproval({
+    url: webhook.url,
+    recipients,
+    subject,
+    preview: body.substring(0, 200),
+  }, toolCallId);
+
+  const request = await webhook;
+  const { approved } = await request.json();
+
+  if (!approved) {
+    return 'Email cancelled by user';
+  }
+
+  await sendEmail({ recipients, subject, body });
+  return `Email sent to ${recipients.length} recipients`;
+}
+```
+
+### Multi-Step Approval
+
+Chain multiple approvals for high-risk actions:
+
+```typescript lineNumbers
+export async function criticalActionWorkflow(action: string) {
+  'use workflow';
+
+  // First approval: Team lead
+  const leadApproval = await requestApproval({
+    role: 'team-lead',
+    action,
+  });
+
+  if (!leadApproval.approved) {
+    return { status: 'rejected', stage: 'team-lead' };
+  }
+
+  // Second approval: Manager
+  const managerApproval = await requestApproval({
+    role: 'manager',
+    action,
+  });
+
+  if (!managerApproval.approved) {
+    return { status: 'rejected', stage: 'manager' };
+  }
+
+  await executeCriticalAction(action);
+  return { status: 'completed' };
+}
+```
+
+## Related Documentation
+
+- [Hooks & Webhooks](/docs/foundations/hooks) - Complete guide to hooks and webhooks
+- [`createWebhook()` API Reference](/docs/api-reference/workflow/create-webhook) - Webhook configuration options
+- [`defineHook()` API Reference](/docs/api-reference/workflow/define-hook) - Type-safe hook definitions
+
diff --git a/docs/content/docs/ai-agents/index.mdx b/docs/content/docs/ai-agents/index.mdx
new file mode 100644
index 000000000..7f9e653c2
--- /dev/null
+++ b/docs/content/docs/ai-agents/index.mdx
@@ -0,0 +1,237 @@
+---
+title: Building Durable AI Agents
+---
+
+<Callout type="warn">
+`@workflow/ai` is in public beta and should be considered experimental.
+</Callout>
+
+AI agents are built on the primitive of LLM and tool-call loops, often with additional processes for data fetching, resource provisioning, or reacting to external events. Workflow DevKit allows you to designate these loops as stateful, resumable workflows, with LLM calls, tool calls, and other async operations as individual, retryable, observable steps.
+
+This guide walks through converting a basic AI SDK agent into a durable agent using Workflow DevKit.
+
+## Why Durable Agents?
+
+Building production-ready AI agents typically requires solving several challenges:
+
+- **Durability**: Queue management, tracking sub-jobs, and handling task execution across failures
+- **Reliability**: Error handling, retries, and recovery from partial failures
+- **Observability**: Storing messages, emitting traces, and debugging agent behavior
+- **Resumability**: Persisting state to a database, managing stream providers for reconnection
+- **Long-running operations**: Sleep, delays, and month-long workflows without idle costs
+- **Human approval loops**: Queues, async workers, and database-backed state management
+
+Workflow DevKit provides these capabilities out of the box. Your agent becomes a workflow, your tools become steps, and the framework handles interplay with your existing infrastructure.
+
+## Getting Started
+
+Start with a Next.js application using the AI SDK's `Agent` class:
+
+```typescript title="app/api/chat/route.ts" lineNumbers
+import { createUIMessageStreamResponse, Agent, stepCountIs } from 'ai';
+import { tools } from '@/ai/tools';
+
+export async function POST(req: Request) {
+  const { messages, modelId } = await req.json();
+
+  const agent = new Agent({
+    model: modelId,
+    system: 'You are a helpful assistant.',
+    tools: tools(),
+    stopWhen: stepCountIs(20),
+  });
+
+  const stream = agent.stream({ messages });
+
+  return createUIMessageStreamResponse({
+    stream: stream.toUIMessageStream(),
+  });
+}
+```
+
+### Step 1: Install Dependencies
+
+Add the Workflow DevKit packages to your project:
+
+```bash
+npm install workflow @workflow/ai
+```
+
+### Step 2: Create a Workflow Function
+
+Move the agent logic into a separate workflow function:
+
+```typescript title="app/api/chat/workflow.ts" lineNumbers
+import { DurableAgent } from '@workflow/ai/agent'; // [!code highlight]
+import { getWritable } from 'workflow'; // [!code highlight]
+import { stepCountIs } from 'ai';
+import { tools } from '@/ai/tools';
+import type { ModelMessage, UIMessageChunk } from 'ai';
+
+export async function chatWorkflow({
+  messages,
+  modelId,
+}: {
+  messages: ModelMessage[];
+  modelId: string;
+}) {
+  'use workflow'; // [!code highlight]
+
+  const writable = getWritable<UIMessageChunk>(); // [!code highlight]
+
+  const agent = new DurableAgent({ // [!code highlight]
+    model: modelId,
+    system: 'You are a helpful assistant.',
+    tools: tools(),
+  });
+
+  await agent.stream({ // [!code highlight]
+    messages,
+    writable,
+    stopWhen: stepCountIs(20),
+  });
+}
+```
+
+Key changes:
+
+- Replace `Agent` with [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) from `@workflow/ai/agent`
+- Add the `"use workflow"` directive to mark this as a workflow function
+- Use [`getWritable()`](/docs/api-reference/workflow/get-writable) to get a stream for agent output
+- Pass the `writable` to `agent.stream()` instead of returning a stream directly
+
+### Step 3: Update the API Route
+
+Replace the agent call with [`start()`](/docs/api-reference/workflow-api/start) to run the workflow:
+
+```typescript title="app/api/chat/route.ts" lineNumbers
+import { createUIMessageStreamResponse, convertToModelMessages } from 'ai';
+import { start } from 'workflow/api'; // [!code highlight]
+import { chatWorkflow } from './workflow'; // [!code highlight]
+
+export async function POST(req: Request) {
+  const { messages, modelId } = await req.json();
+  const modelMessages = convertToModelMessages(messages);
+
+  const run = await start(chatWorkflow, [{ messages: modelMessages, modelId }]); // [!code highlight]
+
+  return createUIMessageStreamResponse({
+    stream: run.readable, // [!code highlight]
+  });
+}
+```
+
+### Step 4: Convert Tools to Steps
+
+Mark tool execution functions with `"use step"` to make them durable. This enables automatic retries and observability:
+
+```typescript title="ai/tools/search-web.ts" lineNumbers
+import { tool } from 'ai';
+import { z } from 'zod';
+
+async function executeSearch({ query }: { query: string }) {
+  'use step'; // [!code highlight]
+
+  const response = await fetch(`https://api.search.com?q=${query}`);
+  return response.json();
+}
+
+export const searchWeb = tool({
+  description: 'Search the web for information',
+  inputSchema: z.object({ query: z.string() }),
+  execute: executeSearch,
+});
+```
+
+With `"use step"`:
+
+- The tool execution runs in a separate step with full Node.js access
+- Failed tool calls are automatically retried (up to 3 times by default)
+- Each tool execution appears as a discrete step in observability tools
+- Results are persisted, so replays skip already-completed tools
+
+### Step 5: Stream Progress Updates from Tools
+
+Tools can emit progress updates to the same stream the agent uses. This allows the UI to display tool status:
+
+```typescript title="ai/tools/run-command.ts" lineNumbers
+import { tool } from 'ai';
+import { getWritable } from 'workflow'; // [!code highlight]
+import { z } from 'zod';
+import type { UIMessageChunk } from 'ai';
+
+async function executeRunCommand(
+  { command }: { command: string },
+  { toolCallId }: { toolCallId: string }
+) {
+  'use step';
+
+  const writable = getWritable<UIMessageChunk>(); // [!code highlight]
+  const writer = writable.getWriter(); // [!code highlight]
+
+  // Emit a progress update // [!code highlight]
+  await writer.write({ // [!code highlight]
+    id: toolCallId, // [!code highlight]
+    type: 'data-run-command', // [!code highlight]
+    data: { command, status: 'executing' }, // [!code highlight]
+  }); // [!code highlight]
+
+  const result = await runCommand(command);
+
+  await writer.write({ // [!code highlight]
+    id: toolCallId, // [!code highlight]
+    type: 'data-run-command', // [!code highlight]
+    data: { command, status: 'done', result }, // [!code highlight]
+  }); // [!code highlight]
+
+  writer.releaseLock(); // [!code highlight]
+
+  return result;
+}
+
+export const runCommand = tool({
+  description: 'Run a shell command',
+  inputSchema: z.object({ command: z.string() }),
+  execute: executeRunCommand,
+});
+```
+
+The UI can handle these data chunks to display real-time progress.
+
+## Running the Workflow
+
+Run your development server, then open the observability dashboard to see your workflow in action:
+
+```bash
+npx workflow web
+```
+
+This opens a local dashboard showing:
+
+- All workflow runs and their status
+- Individual step executions with timing
+- Errors and retry attempts
+- Stream data flowing through the workflow
+
+## Next Steps
+
+Now that you have a basic durable agent, explore these additional capabilities:
+
+<Cards>
+  <Card title="Resumable Streams" href="/docs/ai-agents/resumable-streams">
+    Enable clients to reconnect to interrupted streams without losing data.
+  </Card>
+  <Card title="Sleep and Delays" href="/docs/ai-agents/sleep-and-delays">
+    Add native sleep functionality for time-based workflows.
+  </Card>
+  <Card title="Human-in-the-Loop" href="/docs/ai-agents/human-in-the-loop">
+    Implement approval workflows that wait for human input.
+  </Card>
+</Cards>
+
+## Related Documentation
+
+- [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Full API documentation
+- [Workflows and Steps](/docs/foundations/workflows-and-steps) - Core concepts
+- [Streaming](/docs/foundations/streaming) - In-depth streaming guide
+- [Errors and Retries](/docs/foundations/errors-and-retries) - Error handling patterns
diff --git a/docs/content/docs/ai-agents/meta.json b/docs/content/docs/ai-agents/meta.json
new file mode 100644
index 000000000..3595e6aeb
--- /dev/null
+++ b/docs/content/docs/ai-agents/meta.json
@@ -0,0 +1,10 @@
+{
+  "title": "AI Agents",
+  "pages": [
+    "index",
+    "resumable-streams",
+    "sleep-and-delays",
+    "human-in-the-loop"
+  ],
+  "defaultOpen": true
+}
diff --git a/docs/content/docs/ai-agents/resumable-streams.mdx b/docs/content/docs/ai-agents/resumable-streams.mdx
new file mode 100644
index 000000000..1c79502ab
--- /dev/null
+++ b/docs/content/docs/ai-agents/resumable-streams.mdx
@@ -0,0 +1,210 @@
+---
+title: Resumable Streams
+---
+
+<Callout type="warn">
+The `@workflow/ai` package is currently in active development and should be considered experimental.
+</Callout>
+
+When building chat interfaces, network interruptions or page refreshes can break the connection to an in-progress agent. Workflow DevKit provides [`WorkflowChatTransport`](/docs/api-reference/workflow-ai/workflow-chat-transport), a drop-in transport for the AI SDK that enables automatic stream reconnection.
+
+## The Problem
+
+A typical chat application loses state when:
+- The user refreshes the page during a response
+- Network connectivity drops temporarily
+- Serverless function timeouts occur mid-stream
+
+With a standard chat implementation, users must resend their message and wait for the entire response again.
+
+## The Solution
+
+`WorkflowChatTransport` solves this by:
+1. Tracking the workflow run ID returned from your API
+2. Automatically reconnecting to the stream from the last received chunk
+3. Storing the run ID for session resumption across page loads
+
+## Implementation
+
+### Step 1: Return the Run ID from Your API
+
+Modify your chat endpoint to include the workflow run ID in a response header:
+
+```typescript title="app/api/chat/route.ts" lineNumbers
+import { createUIMessageStreamResponse, convertToModelMessages } from 'ai';
+import { start } from 'workflow/api';
+import { chatWorkflow } from './workflow';
+
+export async function POST(req: Request) {
+  const { messages, modelId } = await req.json();
+  const modelMessages = convertToModelMessages(messages);
+
+  const run = await start(chatWorkflow, [{ messages: modelMessages, modelId }]);
+
+  return createUIMessageStreamResponse({
+    stream: run.readable,
+    headers: {
+      'x-workflow-run-id': run.runId, // [!code highlight]
+    },
+  });
+}
+```
+
+### Step 2: Add a Stream Reconnection Endpoint
+
+Create an endpoint that returns the stream for an existing run:
+
+```typescript title="app/api/chat/[id]/stream/route.ts" lineNumbers
+import { createUIMessageStreamResponse } from 'ai';
+import { getRun } from 'workflow/api'; // [!code highlight]
+
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  const { searchParams } = new URL(request.url);
+
+  // Client provides the last chunk index they received
+  const startIndexParam = searchParams.get('startIndex'); // [!code highlight]
+  const startIndex = startIndexParam
+    ? parseInt(startIndexParam, 10)
+    : undefined;
+
+  const run = getRun(id); // [!code highlight]
+  const stream = run.getReadable({ startIndex }); // [!code highlight]
+
+  return createUIMessageStreamResponse({ stream });
+}
+```
+
+The `startIndex` parameter ensures the client only receives chunks it missed, avoiding duplicate data.
+
+### Step 3: Use WorkflowChatTransport in the Client
+
+Replace the default transport in `useChat` with `WorkflowChatTransport`:
+
+```typescript title="app/chat.tsx" lineNumbers
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import { WorkflowChatTransport } from '@workflow/ai'; // [!code highlight]
+import { useMemo, useState } from 'react';
+
+export function Chat() {
+  const [input, setInput] = useState('');
+
+  // Check for an active workflow run on mount
+  const activeRunId = useMemo(() => { // [!code highlight]
+    if (typeof window === 'undefined') return; // [!code highlight]
+    return localStorage.getItem('active-workflow-run-id') ?? undefined; // [!code highlight]
+  }, []); // [!code highlight]
+
+  const { messages, sendMessage, status } = useChat({
+    resume: Boolean(activeRunId), // [!code highlight]
+    transport: new WorkflowChatTransport({ // [!code highlight]
+      api: '/api/chat',
+
+      // Store the run ID when a new chat starts
+      onChatSendMessage: (response, options) => { // [!code highlight]
+        const workflowRunId = response.headers.get('x-workflow-run-id'); // [!code highlight]
+        if (workflowRunId) { // [!code highlight]
+          localStorage.setItem('active-workflow-run-id', workflowRunId); // [!code highlight]
+        } // [!code highlight]
+      }, // [!code highlight]
+
+      // Clear the run ID when the chat completes
+      onChatEnd: () => { // [!code highlight]
+        localStorage.removeItem('active-workflow-run-id'); // [!code highlight]
+      }, // [!code highlight]
+
+      // Use the stored run ID for reconnection
+      prepareReconnectToStreamRequest: ({ api, ...rest }) => { // [!code highlight]
+        const runId = localStorage.getItem('active-workflow-run-id'); // [!code highlight]
+        if (!runId) throw new Error('No active workflow run ID found'); // [!code highlight]
+        return { // [!code highlight]
+          ...rest, // [!code highlight]
+          api: `/api/chat/${encodeURIComponent(runId)}/stream`, // [!code highlight]
+        }; // [!code highlight]
+      }, // [!code highlight]
+
+      maxConsecutiveErrors: 5,
+    }), // [!code highlight]
+  });
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong> {m.content}
+        </div>
+      ))}
+      <form
+        onSubmit={(e) => {
+          e.preventDefault();
+          sendMessage({ text: input });
+          setInput('');
+        }}
+      >
+        <input
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          placeholder="Type a message..."
+        />
+      </form>
+    </div>
+  );
+}
+```
+
+## How It Works
+
+1. When the user sends a message, `WorkflowChatTransport` makes a POST to `/api/chat`
+2. The API starts a workflow and returns the run ID in the `x-workflow-run-id` header
+3. `onChatSendMessage` stores this run ID in localStorage
+4. If the stream is interrupted before receiving a "finish" chunk, the transport automatically reconnects
+5. `prepareReconnectToStreamRequest` builds the reconnection URL using the stored run ID
+6. The reconnection endpoint returns the stream from where the client left off
+7. When the stream completes, `onChatEnd` clears the stored run ID
+
+## Handling Page Refreshes
+
+The `resume` option tells `useChat` to attempt reconnection on mount. Combined with localStorage persistence, this enables seamless recovery:
+
+```typescript lineNumbers
+const activeRunId = useMemo(() => {
+  if (typeof window === 'undefined') return;
+  return localStorage.getItem('active-workflow-run-id') ?? undefined;
+}, []);
+
+const { messages, sendMessage } = useChat({
+  resume: Boolean(activeRunId), // Attempt to resume if a run ID exists // [!code highlight]
+  transport: new WorkflowChatTransport({ /* ... */ }),
+});
+```
+
+When the user refreshes the page:
+1. The component checks localStorage for an active run ID
+2. If found, `resume: true` triggers a reconnection attempt
+3. The transport fetches the stream from the last known position
+4. Messages continue appearing where they left off
+
+## Error Handling
+
+Configure retry behavior with `maxConsecutiveErrors`:
+
+```typescript lineNumbers
+new WorkflowChatTransport({
+  maxConsecutiveErrors: 5, // Give up after 5 consecutive failures // [!code highlight]
+  // ...
+})
+```
+
+The transport automatically retries reconnection on network errors. After reaching the limit, it stops attempting and surfaces the error.
+
+## Related Documentation
+
+- [`WorkflowChatTransport` API Reference](/docs/api-reference/workflow-ai/workflow-chat-transport) - Full configuration options
+- [Streaming](/docs/foundations/streaming) - Understanding workflow streams
+- [`getRun()` API Reference](/docs/api-reference/workflow-api/get-run) - Retrieving existing runs
+
diff --git a/docs/content/docs/ai-agents/sleep-and-delays.mdx b/docs/content/docs/ai-agents/sleep-and-delays.mdx
new file mode 100644
index 000000000..ec286a912
--- /dev/null
+++ b/docs/content/docs/ai-agents/sleep-and-delays.mdx
@@ -0,0 +1,219 @@
+---
+title: Sleep and Delays
+---
+
+AI agents sometimes need to pause execution - waiting before retrying an operation, implementing rate limiting, or scheduling future actions. Workflow DevKit's [`sleep()`](/docs/api-reference/workflow/sleep) function enables time-based delays without consuming compute resources.
+
+## Adding a Sleep Tool
+
+Create a tool that allows the agent to pause for a specified duration:
+
+```typescript title="ai/tools/sleep.ts" lineNumbers
+import { tool } from 'ai';
+import { getWritable, sleep } from 'workflow'; // [!code highlight]
+import { z } from 'zod';
+import type { UIMessageChunk } from 'ai';
+
+const inputSchema = z.object({
+  durationMs: z.number().describe('Duration to sleep in milliseconds'),
+});
+
+async function reportSleep(
+  { durationMs }: { durationMs: number },
+  { toolCallId }: { toolCallId: string }
+) {
+  'use step';
+
+  const writable = getWritable<UIMessageChunk>();
+  const writer = writable.getWriter();
+
+  const seconds = Math.ceil(durationMs / 1000);
+
+  await writer.write({
+    id: toolCallId,
+    type: 'data-wait',
+    data: { text: `Sleeping for ${seconds} seconds` },
+  });
+
+  writer.releaseLock();
+}
+
+async function executeSleep(
+  { durationMs }: z.infer<typeof inputSchema>,
+  { toolCallId }: { toolCallId: string }
+) {
+  // Note: No "use step" here - sleep is a workflow-level function // [!code highlight]
+
+  await reportSleep({ durationMs }, { toolCallId });
+  await sleep(durationMs); // [!code highlight]
+
+  return `Slept for ${durationMs}ms`;
+}
+
+export const sleepTool = tool({
+  description: 'Pause execution for a specified duration',
+  inputSchema,
+  execute: executeSleep,
+});
+```
+
+<Callout type="info">
+The `sleep()` function must be called from within a workflow context, not from within a step. This is why `executeSleep` does not have `"use step"` - it runs in the workflow context where `sleep()` is available.
+</Callout>
+
+## How Sleep Works
+
+When `sleep()` is called:
+
+1. The workflow records the wake-up time in the event log
+2. The workflow suspends, releasing all compute resources
+3. At the specified time, the workflow resumes execution
+
+This differs from `setTimeout` or `await new Promise(resolve => setTimeout(resolve, ms))`:
+- No compute resources are consumed during the sleep
+- The workflow survives restarts, deploys, and infrastructure changes
+- Sleep durations can span hours, days, or months
+
+## Duration Formats
+
+The `sleep()` function accepts multiple duration formats:
+
+```typescript lineNumbers
+// Milliseconds (number)
+await sleep(5000);
+
+// Duration strings
+await sleep('30s');      // 30 seconds
+await sleep('5m');       // 5 minutes
+await sleep('2h');       // 2 hours
+await sleep('1d');       // 1 day
+await sleep('1 month');  // 1 month
+
+// Date instance
+await sleep(new Date('2025-12-31T23:59:59Z'));
+```
+
+## Emitting Progress Updates
+
+When sleeping for long durations, emit a progress update so the UI can display the waiting state:
+
+```typescript title="ai/tools/schedule-task.ts" lineNumbers
+import { tool } from 'ai';
+import { getWritable, sleep } from 'workflow';
+import { z } from 'zod';
+import type { UIMessageChunk } from 'ai';
+
+async function emitWaitingStatus(message: string, toolCallId: string) {
+  'use step';
+
+  const writable = getWritable<UIMessageChunk>();
+  const writer = writable.getWriter();
+
+  await writer.write({
+    id: toolCallId,
+    type: 'data-wait',
+    data: { text: message },
+  });
+
+  writer.releaseLock();
+}
+
+async function executeScheduleTask(
+  { delayMinutes, taskName }: { delayMinutes: number; taskName: string },
+  { toolCallId }: { toolCallId: string }
+) {
+  await emitWaitingStatus(
+    `Scheduled "${taskName}" to run in ${delayMinutes} minutes`,
+    toolCallId
+  );
+
+  await sleep(`${delayMinutes}m`); // [!code highlight]
+
+  return `Task "${taskName}" is now ready to execute`;
+}
+
+export const scheduleTask = tool({
+  description: 'Schedule a task to run after a delay',
+  inputSchema: z.object({
+    delayMinutes: z.number(),
+    taskName: z.string(),
+  }),
+  execute: executeScheduleTask,
+});
+```
+
+## Use Cases
+
+### Rate Limiting
+
+When hitting API rate limits, sleep before retrying:
+
+```typescript lineNumbers
+async function callRateLimitedAPI(endpoint: string) {
+  'use step';
+
+  const response = await fetch(endpoint);
+
+  if (response.status === 429) {
+    const retryAfter = response.headers.get('Retry-After');
+    throw new RetryableError('Rate limited', {
+      retryAfter: retryAfter ? parseInt(retryAfter) * 1000 : '1m',
+    });
+  }
+
+  return response.json();
+}
+```
+
+### Scheduled Notifications
+
+Send a reminder after a delay:
+
+```typescript lineNumbers
+async function executeReminder(
+  { message, delayHours }: { message: string; delayHours: number }
+) {
+  await sleep(`${delayHours}h`);
+  await sendNotification(message);
+
+  return `Reminder sent: ${message}`;
+}
+```
+
+### Polling with Backoff
+
+Poll for a result with increasing delays:
+
+```typescript lineNumbers
+export async function pollForResult(jobId: string) {
+  'use workflow';
+
+  let attempt = 0;
+  const maxAttempts = 10;
+
+  while (attempt < maxAttempts) {
+    const result = await checkJobStatus(jobId);
+
+    if (result.status === 'complete') {
+      return result.data;
+    }
+
+    attempt++;
+    await sleep(Math.min(1000 * 2 ** attempt, 60000)); // Exponential backoff, max 1 minute
+  }
+
+  throw new Error('Job did not complete in time');
+}
+
+async function checkJobStatus(jobId: string) {
+  'use step';
+  // Check job status...
+}
+```
+
+## Related Documentation
+
+- [`sleep()` API Reference](/docs/api-reference/workflow/sleep) - Full API documentation
+- [Workflows and Steps](/docs/foundations/workflows-and-steps) - Understanding workflow context
+- [Errors and Retries](/docs/foundations/errors-and-retries) - Using `RetryableError` with delays
+
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index b527dc11f..74cc963af 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -4,6 +4,7 @@
     "---",
     "getting-started",
     "foundations",
+    "ai-agents",
     "how-it-works",
     "observability",
     "deploying",

From 0a65357bac50b2da1104a61b48c4978402583df1 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 13:44:53 -0800
Subject: [PATCH 02/38] Fix scrolling of left sidebar

---
 docs/components/geistdocs/docs-layout.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/components/geistdocs/docs-layout.tsx b/docs/components/geistdocs/docs-layout.tsx
index a4ae61e79..800e262ee 100644
--- a/docs/components/geistdocs/docs-layout.tsx
+++ b/docs/components/geistdocs/docs-layout.tsx
@@ -18,7 +18,7 @@ export const DocsLayout = ({
     }}
     sidebar={{
       className:
-        'md:static md:sticky md:top-16 md:h-fit md:w-auto! bg-background! md:bg-transparent! border-none transition-none',
+        'md:static md:sticky md:top-16 md:max-h-[calc(100vh-4rem)] md:overflow-y-auto md:w-auto! bg-background! md:bg-transparent! border-none transition-none',
       collapsible: false,
       components: {
         Folder,

From eb49e18ad39cae523ccf0bdcf877e839e379ad59 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 13:52:45 -0800
Subject: [PATCH 03/38] Polish

---
 docs/content/docs/ai-agents/index.mdx             | 13 ++++---------
 docs/content/docs/ai-agents/resumable-streams.mdx |  8 +++-----
 2 files changed, 7 insertions(+), 14 deletions(-)

diff --git a/docs/content/docs/ai-agents/index.mdx b/docs/content/docs/ai-agents/index.mdx
index 7f9e653c2..289aa5311 100644
--- a/docs/content/docs/ai-agents/index.mdx
+++ b/docs/content/docs/ai-agents/index.mdx
@@ -2,10 +2,6 @@
 title: Building Durable AI Agents
 ---
 
-<Callout type="warn">
-`@workflow/ai` is in public beta and should be considered experimental.
-</Callout>
-
 AI agents are built on the primitive of LLM and tool-call loops, often with additional processes for data fetching, resource provisioning, or reacting to external events. Workflow DevKit allows you to designate these loops as stateful, resumable workflows, with LLM calls, tool calls, and other async operations as individual, retryable, observable steps.
 
 This guide walks through converting a basic AI SDK agent into a durable agent using Workflow DevKit.
@@ -14,12 +10,11 @@ This guide walks through converting a basic AI SDK agent into a durable agent us
 
 Building production-ready AI agents typically requires solving several challenges:
 
-- **Durability**: Queue management, tracking sub-jobs, and handling task execution across failures
+- **Durability**: Splitting calls into async jobs, managing associated workers, queuing, and data persistence
 - **Reliability**: Error handling, retries, and recovery from partial failures
-- **Observability**: Storing messages, emitting traces, and debugging agent behavior
-- **Resumability**: Persisting state to a database, managing stream providers for reconnection
-- **Long-running operations**: Sleep, delays, and month-long workflows without idle costs
-- **Human approval loops**: Queues, async workers, and database-backed state management
+- **Observability**: Storing messages and emitting traces, often using external services for observability
+- **Resumability**: Repeatedly persisting and loading state from a database, storing streams in a separate service, and managing stream reconnects
+- **Long-running operations and human approval loops**: Wiring up queues, async workers, and connecting state to your existing API and interface
 
 Workflow DevKit provides these capabilities out of the box. Your agent becomes a workflow, your tools become steps, and the framework handles interplay with your existing infrastructure.
 
diff --git a/docs/content/docs/ai-agents/resumable-streams.mdx b/docs/content/docs/ai-agents/resumable-streams.mdx
index 1c79502ab..5c3c6e97c 100644
--- a/docs/content/docs/ai-agents/resumable-streams.mdx
+++ b/docs/content/docs/ai-agents/resumable-streams.mdx
@@ -2,15 +2,12 @@
 title: Resumable Streams
 ---
 
-<Callout type="warn">
-The `@workflow/ai` package is currently in active development and should be considered experimental.
-</Callout>
-
 When building chat interfaces, network interruptions or page refreshes can break the connection to an in-progress agent. Workflow DevKit provides [`WorkflowChatTransport`](/docs/api-reference/workflow-ai/workflow-chat-transport), a drop-in transport for the AI SDK that enables automatic stream reconnection.
 
 ## The Problem
 
 A typical chat application loses state when:
+
 - The user refreshes the page during a response
 - Network connectivity drops temporarily
 - Serverless function timeouts occur mid-stream
@@ -20,6 +17,7 @@ With a standard chat implementation, users must resend their message and wait fo
 ## The Solution
 
 `WorkflowChatTransport` solves this by:
+
 1. Tracking the workflow run ID returned from your API
 2. Automatically reconnecting to the stream from the last received chunk
 3. Storing the run ID for session resumption across page loads
@@ -184,6 +182,7 @@ const { messages, sendMessage } = useChat({
 ```
 
 When the user refreshes the page:
+
 1. The component checks localStorage for an active run ID
 2. If found, `resume: true` triggers a reconnection attempt
 3. The transport fetches the stream from the last known position
@@ -207,4 +206,3 @@ The transport automatically retries reconnection on network errors. After reachi
 - [`WorkflowChatTransport` API Reference](/docs/api-reference/workflow-ai/workflow-chat-transport) - Full configuration options
 - [Streaming](/docs/foundations/streaming) - Understanding workflow streams
 - [`getRun()` API Reference](/docs/api-reference/workflow-api/get-run) - Retrieving existing runs
-

From e83bbf3aded04f28c45950c3f73633d04c5c9ea2 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 13:54:55 -0800
Subject: [PATCH 04/38] Empty changeset

---
 .changeset/three-hands-open.md | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 .changeset/three-hands-open.md

diff --git a/.changeset/three-hands-open.md b/.changeset/three-hands-open.md
new file mode 100644
index 000000000..a845151cc
--- /dev/null
+++ b/.changeset/three-hands-open.md
@@ -0,0 +1,2 @@
+---
+---

From 8e8acab994dd6c4e3a70939427f9ce2535db2f7c Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 14:06:19 -0800
Subject: [PATCH 05/38] Polish

---
 docs/content/docs/ai-agents/index.mdx | 15 +++++++--------
 docs/content/docs/ai-agents/meta.json |  2 +-
 2 files changed, 8 insertions(+), 9 deletions(-)

diff --git a/docs/content/docs/ai-agents/index.mdx b/docs/content/docs/ai-agents/index.mdx
index 289aa5311..a5aacfd2e 100644
--- a/docs/content/docs/ai-agents/index.mdx
+++ b/docs/content/docs/ai-agents/index.mdx
@@ -2,21 +2,20 @@
 title: Building Durable AI Agents
 ---
 
-AI agents are built on the primitive of LLM and tool-call loops, often with additional processes for data fetching, resource provisioning, or reacting to external events. Workflow DevKit allows you to designate these loops as stateful, resumable workflows, with LLM calls, tool calls, and other async operations as individual, retryable, observable steps.
+AI agents are built on the primitive of LLM and tool-call loops, often with additional processes for data fetching, resource provisioning, or reacting to external events. Workflow DevKit makes your agents production-ready, by turning your agents into durable, resumable workflows, and managing your LLM calls, tool executions, and other async operations as retryable and observable steps.
 
 This guide walks through converting a basic AI SDK agent into a durable agent using Workflow DevKit.
 
 ## Why Durable Agents?
 
-Building production-ready AI agents typically requires solving several challenges:
+Aside from the usual challenges of getting your long-running tasks to be production-ready, building mature AI agents typically requires solving several additional **challenges**:
 
-- **Durability**: Splitting calls into async jobs, managing associated workers, queuing, and data persistence
-- **Reliability**: Error handling, retries, and recovery from partial failures
-- **Observability**: Storing messages and emitting traces, often using external services for observability
-- **Resumability**: Repeatedly persisting and loading state from a database, storing streams in a separate service, and managing stream reconnects
-- **Long-running operations and human approval loops**: Wiring up queues, async workers, and connecting state to your existing API and interface
+- **Durability**: Persisting chat sessions and turning all LLM and tool calls into separate async jobs, with workers, queues, and state management, which repeatedly save and re-load state from a database.
+- **Observability**: Using services to collect traces and metrics, separately storing your messages and user history, and then combining them to get a complete picture of your agent's behavior.
+- **Resumability**: Separately from storing messages for replayability, most LLM calls are streams, and recovering from a call failure without re-doing the entire call requires piping and storing streams separately from your messages, usually in a separate service.
+- **Human-in-the-loop**: Your client, API, and async job orchestration need to work together to create, track, route to, and display human approval requests, or similar webhook operations. If your stack is disjointed, this simple feature becomes a major orchestration challenge.
 
-Workflow DevKit provides these capabilities out of the box. Your agent becomes a workflow, your tools become steps, and the framework handles interplay with your existing infrastructure.
+Workflow DevKit provides all of these capabilities out of the box. Your agent becomes a workflow, your tools become steps, and the framework handles interplay with your existing infrastructure.
 
 ## Getting Started
 
diff --git a/docs/content/docs/ai-agents/meta.json b/docs/content/docs/ai-agents/meta.json
index 3595e6aeb..872b5d978 100644
--- a/docs/content/docs/ai-agents/meta.json
+++ b/docs/content/docs/ai-agents/meta.json
@@ -6,5 +6,5 @@
     "sleep-and-delays",
     "human-in-the-loop"
   ],
-  "defaultOpen": true
+  "defaultOpen": false
 }

From 51e7aaca374b9fa410dbf5bb3983f7fe059787b9 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 14:20:27 -0800
Subject: [PATCH 06/38] Move to new section

---
 docs/app/guides/[[...slug]]/page.tsx          | 123 ++++++++++
 docs/app/guides/layout.tsx                    |  43 ++++
 docs/app/guides/page.tsx                      |   5 +
 docs/app/layout.tsx                           |   4 +
 docs/content/docs/ai-agents/index.mdx         |  28 +--
 docs/content/docs/meta.json                   |   1 -
 .../ai-agents/human-in-the-loop.mdx           |   0
 docs/content/guides/ai-agents/index.mdx       | 231 ++++++++++++++++++
 .../{docs => guides}/ai-agents/meta.json      |   2 +-
 .../ai-agents/resumable-streams.mdx           |   0
 .../ai-agents/sleep-and-delays.mdx            |   0
 docs/content/guides/meta.json                 |   3 +
 docs/lib/geistdocs/source.ts                  |  18 +-
 docs/source.config.ts                         |  13 +
 14 files changed, 453 insertions(+), 18 deletions(-)
 create mode 100644 docs/app/guides/[[...slug]]/page.tsx
 create mode 100644 docs/app/guides/layout.tsx
 create mode 100644 docs/app/guides/page.tsx
 rename docs/content/{docs => guides}/ai-agents/human-in-the-loop.mdx (100%)
 create mode 100644 docs/content/guides/ai-agents/index.mdx
 rename docs/content/{docs => guides}/ai-agents/meta.json (85%)
 rename docs/content/{docs => guides}/ai-agents/resumable-streams.mdx (100%)
 rename docs/content/{docs => guides}/ai-agents/sleep-and-delays.mdx (100%)
 create mode 100644 docs/content/guides/meta.json

diff --git a/docs/app/guides/[[...slug]]/page.tsx b/docs/app/guides/[[...slug]]/page.tsx
new file mode 100644
index 000000000..b8db99716
--- /dev/null
+++ b/docs/app/guides/[[...slug]]/page.tsx
@@ -0,0 +1,123 @@
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+import { createRelativeLink } from 'fumadocs-ui/mdx';
+import { notFound } from 'next/navigation';
+import { AskAI } from '@/components/geistdocs/ask-ai';
+import { CopyPage } from '@/components/geistdocs/copy-page';
+import {
+  DocsBody,
+  DocsDescription,
+  DocsPage,
+  DocsTitle,
+} from '@/components/geistdocs/docs-page';
+import { EditSource } from '@/components/geistdocs/edit-source';
+import { Feedback } from '@/components/geistdocs/feedback';
+import { getMDXComponents } from '@/components/geistdocs/mdx-components';
+import { OpenInChat } from '@/components/geistdocs/open-in-chat';
+import { ScrollTop } from '@/components/geistdocs/scroll-top';
+import { TableOfContents } from '@/components/geistdocs/toc';
+import * as AccordionComponents from '@/components/ui/accordion';
+import { Badge } from '@/components/ui/badge';
+import {
+  getGuidesLLMText,
+  getPageImage,
+  guidesSource,
+} from '@/lib/geistdocs/source';
+import { TSDoc } from '@/lib/tsdoc';
+import type { Metadata } from 'next';
+
+const Page = async (props: PageProps<'/guides/[[...slug]]'>) => {
+  const params = await props.params;
+
+  const page = guidesSource.getPage(params.slug);
+
+  if (!page) {
+    notFound();
+  }
+
+  const markdown = await getGuidesLLMText(page);
+  const MDX = page.data.body;
+
+  return (
+    <DocsPage
+      slug={params.slug}
+      tableOfContent={{
+        component: (
+          <TableOfContents>
+            <EditSource path={page.path} />
+            <ScrollTop />
+            <Feedback />
+            <CopyPage text={markdown} />
+            <AskAI href={page.url} />
+            <OpenInChat href={page.url} />
+          </TableOfContents>
+        ),
+      }}
+      toc={page.data.toc}
+    >
+      <DocsTitle>{page.data.title}</DocsTitle>
+      <DocsDescription>{page.data.description}</DocsDescription>
+      <DocsBody>
+        <MDX
+          components={getMDXComponents({
+            a: createRelativeLink(guidesSource, page),
+
+            // Add your custom components here
+            Badge,
+            TSDoc,
+            Step,
+            Steps,
+            ...AccordionComponents,
+            Tabs,
+            Tab,
+          })}
+        />
+      </DocsBody>
+    </DocsPage>
+  );
+};
+
+export const generateStaticParams = () =>
+  guidesSource.generateParams().map((params) => ({
+    slug: params.slug,
+  }));
+
+export const generateMetadata = async (
+  props: PageProps<'/guides/[[...slug]]'>
+): Promise<Metadata> => {
+  const params = await props.params;
+  const page = guidesSource.getPage(params.slug);
+
+  if (!page) {
+    notFound();
+  }
+
+  const { segments, url } = getPageImage(page);
+
+  return {
+    title: page.data.title,
+    description: page.data.description,
+    openGraph: {
+      title: page.data.title,
+      description: page.data.description,
+      type: 'article',
+      url: page.url,
+      images: [
+        {
+          url,
+          width: 1200,
+          height: 630,
+          alt: segments.join(' - '),
+        },
+      ],
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title: page.data.title,
+      description: page.data.description,
+      images: [url],
+    },
+  };
+};
+
+export default Page;
diff --git a/docs/app/guides/layout.tsx b/docs/app/guides/layout.tsx
new file mode 100644
index 000000000..073b0a599
--- /dev/null
+++ b/docs/app/guides/layout.tsx
@@ -0,0 +1,43 @@
+import { DocsLayout as FumadocsDocsLayout } from 'fumadocs-ui/layouts/docs';
+import { Folder, Item, Separator } from '@/components/geistdocs/sidebar';
+import { guidesSource } from '@/lib/geistdocs/source';
+
+export const GuidesLayout = ({
+  children,
+}: Pick<LayoutProps<'/guides'>, 'children'>) => (
+  <FumadocsDocsLayout
+    containerProps={{
+      className:
+        'md:grid md:grid-cols-[286px_1fr_286px] md:pl-0! md:mx-auto! md:w-full md:max-w-(--fd-layout-width)!',
+    }}
+    nav={{
+      enabled: false,
+    }}
+    searchToggle={{
+      enabled: false,
+    }}
+    sidebar={{
+      className:
+        'md:static md:sticky md:top-16 md:max-h-[calc(100vh-4rem)] md:overflow-y-auto md:w-auto! bg-background! md:bg-transparent! border-none transition-none',
+      collapsible: false,
+      components: {
+        Folder,
+        Item,
+        Separator,
+      },
+    }}
+    tabMode="auto"
+    themeSwitch={{
+      enabled: false,
+    }}
+    tree={guidesSource.pageTree}
+  >
+    {children}
+  </FumadocsDocsLayout>
+);
+
+const Layout = ({ children }: LayoutProps<'/guides'>) => (
+  <GuidesLayout>{children}</GuidesLayout>
+);
+
+export default Layout;
diff --git a/docs/app/guides/page.tsx b/docs/app/guides/page.tsx
new file mode 100644
index 000000000..1822f3150
--- /dev/null
+++ b/docs/app/guides/page.tsx
@@ -0,0 +1,5 @@
+import { redirect } from 'next/navigation';
+
+export default function GuidesPage() {
+  redirect('/guides/ai-agents');
+}
diff --git a/docs/app/layout.tsx b/docs/app/layout.tsx
index b6ec2738e..a25ff356d 100644
--- a/docs/app/layout.tsx
+++ b/docs/app/layout.tsx
@@ -28,6 +28,10 @@ const links = [
     label: 'Docs',
     href: '/docs',
   },
+  {
+    label: 'Guides',
+    href: '/guides',
+  },
   {
     label: 'Examples',
     href: 'https://github.com/vercel/workflow-examples',
diff --git a/docs/content/docs/ai-agents/index.mdx b/docs/content/docs/ai-agents/index.mdx
index a5aacfd2e..2f8fcf187 100644
--- a/docs/content/docs/ai-agents/index.mdx
+++ b/docs/content/docs/ai-agents/index.mdx
@@ -32,7 +32,6 @@ export async function POST(req: Request) {
     model: modelId,
     system: 'You are a helpful assistant.',
     tools: tools(),
-    stopWhen: stepCountIs(20),
   });
 
   const stream = agent.stream({ messages });
@@ -62,7 +61,7 @@ import { stepCountIs } from 'ai';
 import { tools } from '@/ai/tools';
 import type { ModelMessage, UIMessageChunk } from 'ai';
 
-export async function chatWorkflow({
+export async function chatWorkflow({ // [!code highlight]
   messages,
   modelId,
 }: {
@@ -79,10 +78,9 @@ export async function chatWorkflow({
     tools: tools(),
   });
 
-  await agent.stream({ // [!code highlight]
+  await agent.stream({
     messages,
     writable,
-    stopWhen: stepCountIs(20),
   });
 }
 ```
@@ -107,6 +105,7 @@ export async function POST(req: Request) {
   const { messages, modelId } = await req.json();
   const modelMessages = convertToModelMessages(messages);
 
+  // This will start the workflow in the background
   const run = await start(chatWorkflow, [{ messages: modelMessages, modelId }]); // [!code highlight]
 
   return createUIMessageStreamResponse({
@@ -144,9 +143,11 @@ With `"use step"`:
 - Each tool execution appears as a discrete step in observability tools
 - Results are persisted, so replays skip already-completed tools
 
+Note that any side-effects or network operations need to be run inside step functions, not in your workflow code.
+
 ### Step 5: Stream Progress Updates from Tools
 
-Tools can emit progress updates to the same stream the agent uses. This allows the UI to display tool status:
+Tools can emit progress updates to the same stream the agent uses. This allows the UI to display tool status and live updates from steps, without having to manually wire up streams:
 
 ```typescript title="ai/tools/run-command.ts" lineNumbers
 import { tool } from 'ai';
@@ -194,32 +195,29 @@ The UI can handle these data chunks to display real-time progress.
 
 ## Running the Workflow
 
-Run your development server, then open the observability dashboard to see your workflow in action:
+Run your development server, kick off a chat session, and then open the observability dashboard to see your workflow running live:
 
 ```bash
 npx workflow web
 ```
 
-This opens a local dashboard showing:
-
-- All workflow runs and their status
-- Individual step executions with timing
-- Errors and retry attempts
-- Stream data flowing through the workflow
+This opens a local dashboard showing all your workflow runs, with trace-viewers showing detailed views of each run, errors, retries, timing, and more.
+The UI also allows you to cancel, re-run, and start new runs.
 
 ## Next Steps
 
-Now that you have a basic durable agent, explore these additional capabilities:
+Now that you have a basic durable agent, it's a short step to adding additional capabilities like resumable streams, sleep and delays, and human-in-the-loop.
 
 <Cards>
   <Card title="Resumable Streams" href="/docs/ai-agents/resumable-streams">
     Enable clients to reconnect to interrupted streams without losing data.
   </Card>
   <Card title="Sleep and Delays" href="/docs/ai-agents/sleep-and-delays">
-    Add native sleep functionality for time-based workflows.
+    Add native sleep functionality to allow your workflows to pause and resume, enable work on schedules, and more.
   </Card>
   <Card title="Human-in-the-Loop" href="/docs/ai-agents/human-in-the-loop">
-    Implement approval workflows that wait for human input.
+    Implement approval workflows that wait for human input or other external events,
+    like PR updates, webhooks, and more.
   </Card>
 </Cards>
 
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index 74cc963af..b527dc11f 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -4,7 +4,6 @@
     "---",
     "getting-started",
     "foundations",
-    "ai-agents",
     "how-it-works",
     "observability",
     "deploying",
diff --git a/docs/content/docs/ai-agents/human-in-the-loop.mdx b/docs/content/guides/ai-agents/human-in-the-loop.mdx
similarity index 100%
rename from docs/content/docs/ai-agents/human-in-the-loop.mdx
rename to docs/content/guides/ai-agents/human-in-the-loop.mdx
diff --git a/docs/content/guides/ai-agents/index.mdx b/docs/content/guides/ai-agents/index.mdx
new file mode 100644
index 000000000..d3d8b7b87
--- /dev/null
+++ b/docs/content/guides/ai-agents/index.mdx
@@ -0,0 +1,231 @@
+---
+title: Building Durable AI Agents
+---
+
+AI agents are built on the primitive of LLM and tool-call loops, often with additional processes for data fetching, resource provisioning, or reacting to external events. Workflow DevKit makes your agents production-ready, by turning your agents into durable, resumable workflows, and managing your LLM calls, tool executions, and other async operations as retryable and observable steps.
+
+This guide walks through converting a basic AI SDK agent into a durable agent using Workflow DevKit.
+
+## Why Durable Agents?
+
+Aside from the usual challenges of getting your long-running tasks to be production-ready, building mature AI agents typically requires solving several additional **challenges**:
+
+- **Durability**: Persisting chat sessions and turning all LLM and tool calls into separate async jobs, with workers, queues, and state management, which repeatedly save and re-load state from a database.
+- **Observability**: Using services to collect traces and metrics, separately storing your messages and user history, and then combining them to get a complete picture of your agent's behavior.
+- **Resumability**: Separately from storing messages for replayability, most LLM calls are streams, and recovering from a call failure without re-doing the entire call requires piping and storing streams separately from your messages, usually in a separate service.
+- **Human-in-the-loop**: Your client, API, and async job orchestration need to work together to create, track, route to, and display human approval requests, or similar webhook operations. If your stack is disjointed, this simple feature becomes a major orchestration challenge.
+
+Workflow DevKit provides all of these capabilities out of the box. Your agent becomes a workflow, your tools become steps, and the framework handles interplay with your existing infrastructure.
+
+## Getting Started
+
+Start with a Next.js application using the AI SDK's `Agent` class:
+
+```typescript title="app/api/chat/route.ts" lineNumbers
+import { createUIMessageStreamResponse, Agent, stepCountIs } from 'ai';
+import { tools } from '@/ai/tools';
+
+export async function POST(req: Request) {
+  const { messages, modelId } = await req.json();
+
+  const agent = new Agent({
+    model: modelId,
+    system: 'You are a helpful assistant.',
+    tools: tools(),
+    stopWhen: stepCountIs(20),
+  });
+
+  const stream = agent.stream({ messages });
+
+  return createUIMessageStreamResponse({
+    stream: stream.toUIMessageStream(),
+  });
+}
+```
+
+### Step 1: Install Dependencies
+
+Add the Workflow DevKit packages to your project:
+
+```bash
+npm install workflow @workflow/ai
+```
+
+### Step 2: Create a Workflow Function
+
+Move the agent logic into a separate workflow function:
+
+```typescript title="app/api/chat/workflow.ts" lineNumbers
+import { DurableAgent } from '@workflow/ai/agent'; // [!code highlight]
+import { getWritable } from 'workflow'; // [!code highlight]
+import { stepCountIs } from 'ai';
+import { tools } from '@/ai/tools';
+import type { ModelMessage, UIMessageChunk } from 'ai';
+
+export async function chatWorkflow({
+  messages,
+  modelId,
+}: {
+  messages: ModelMessage[];
+  modelId: string;
+}) {
+  'use workflow'; // [!code highlight]
+
+  const writable = getWritable<UIMessageChunk>(); // [!code highlight]
+
+  const agent = new DurableAgent({ // [!code highlight]
+    model: modelId,
+    system: 'You are a helpful assistant.',
+    tools: tools(),
+  });
+
+  await agent.stream({ // [!code highlight]
+    messages,
+    writable,
+    stopWhen: stepCountIs(20),
+  });
+}
+```
+
+Key changes:
+
+- Replace `Agent` with [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) from `@workflow/ai/agent`
+- Add the `"use workflow"` directive to mark this as a workflow function
+- Use [`getWritable()`](/docs/api-reference/workflow/get-writable) to get a stream for agent output
+- Pass the `writable` to `agent.stream()` instead of returning a stream directly
+
+### Step 3: Update the API Route
+
+Replace the agent call with [`start()`](/docs/api-reference/workflow-api/start) to run the workflow:
+
+```typescript title="app/api/chat/route.ts" lineNumbers
+import { createUIMessageStreamResponse, convertToModelMessages } from 'ai';
+import { start } from 'workflow/api'; // [!code highlight]
+import { chatWorkflow } from './workflow'; // [!code highlight]
+
+export async function POST(req: Request) {
+  const { messages, modelId } = await req.json();
+  const modelMessages = convertToModelMessages(messages);
+
+  const run = await start(chatWorkflow, [{ messages: modelMessages, modelId }]); // [!code highlight]
+
+  return createUIMessageStreamResponse({
+    stream: run.readable, // [!code highlight]
+  });
+}
+```
+
+### Step 4: Convert Tools to Steps
+
+Mark tool execution functions with `"use step"` to make them durable. This enables automatic retries and observability:
+
+```typescript title="ai/tools/search-web.ts" lineNumbers
+import { tool } from 'ai';
+import { z } from 'zod';
+
+async function executeSearch({ query }: { query: string }) {
+  'use step'; // [!code highlight]
+
+  const response = await fetch(`https://api.search.com?q=${query}`);
+  return response.json();
+}
+
+export const searchWeb = tool({
+  description: 'Search the web for information',
+  inputSchema: z.object({ query: z.string() }),
+  execute: executeSearch,
+});
+```
+
+With `"use step"`:
+
+- The tool execution runs in a separate step with full Node.js access
+- Failed tool calls are automatically retried (up to 3 times by default)
+- Each tool execution appears as a discrete step in observability tools
+- Results are persisted, so replays skip already-completed tools
+
+### Step 5: Stream Progress Updates from Tools
+
+Tools can emit progress updates to the same stream the agent uses. This allows the UI to display tool status:
+
+```typescript title="ai/tools/run-command.ts" lineNumbers
+import { tool } from 'ai';
+import { getWritable } from 'workflow'; // [!code highlight]
+import { z } from 'zod';
+import type { UIMessageChunk } from 'ai';
+
+async function executeRunCommand(
+  { command }: { command: string },
+  { toolCallId }: { toolCallId: string }
+) {
+  'use step';
+
+  const writable = getWritable<UIMessageChunk>(); // [!code highlight]
+  const writer = writable.getWriter(); // [!code highlight]
+
+  // Emit a progress update // [!code highlight]
+  await writer.write({ // [!code highlight]
+    id: toolCallId, // [!code highlight]
+    type: 'data-run-command', // [!code highlight]
+    data: { command, status: 'executing' }, // [!code highlight]
+  }); // [!code highlight]
+
+  const result = await runCommand(command);
+
+  await writer.write({ // [!code highlight]
+    id: toolCallId, // [!code highlight]
+    type: 'data-run-command', // [!code highlight]
+    data: { command, status: 'done', result }, // [!code highlight]
+  }); // [!code highlight]
+
+  writer.releaseLock(); // [!code highlight]
+
+  return result;
+}
+
+export const runCommand = tool({
+  description: 'Run a shell command',
+  inputSchema: z.object({ command: z.string() }),
+  execute: executeRunCommand,
+});
+```
+
+The UI can handle these data chunks to display real-time progress.
+
+## Running the Workflow
+
+Run your development server, then open the observability dashboard to see your workflow in action:
+
+```bash
+npx workflow web
+```
+
+This opens a local dashboard showing:
+
+- All workflow runs and their status
+- Individual step executions with timing
+- Errors and retry attempts
+- Stream data flowing through the workflow
+
+## Next Steps
+
+Now that you have a basic durable agent, explore these additional capabilities:
+
+<Cards>
+  <Card title="Resumable Streams" href="/guides/ai-agents/resumable-streams">
+    Enable clients to reconnect to interrupted streams without losing data.
+  </Card>
+  <Card title="Sleep and Delays" href="/guides/ai-agents/sleep-and-delays">
+    Add native sleep functionality for time-based workflows.
+  </Card>
+  <Card title="Human-in-the-Loop" href="/guides/ai-agents/human-in-the-loop">
+    Implement approval workflows that wait for human input.
+  </Card>
+</Cards>
+
+## Related Documentation
+
+- [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Full API documentation
+- [Workflows and Steps](/docs/foundations/workflows-and-steps) - Core concepts
+- [Streaming](/docs/foundations/streaming) - In-depth streaming guide
+- [Errors and Retries](/docs/foundations/errors-and-retries) - Error handling patterns
diff --git a/docs/content/docs/ai-agents/meta.json b/docs/content/guides/ai-agents/meta.json
similarity index 85%
rename from docs/content/docs/ai-agents/meta.json
rename to docs/content/guides/ai-agents/meta.json
index 872b5d978..3595e6aeb 100644
--- a/docs/content/docs/ai-agents/meta.json
+++ b/docs/content/guides/ai-agents/meta.json
@@ -6,5 +6,5 @@
     "sleep-and-delays",
     "human-in-the-loop"
   ],
-  "defaultOpen": false
+  "defaultOpen": true
 }
diff --git a/docs/content/docs/ai-agents/resumable-streams.mdx b/docs/content/guides/ai-agents/resumable-streams.mdx
similarity index 100%
rename from docs/content/docs/ai-agents/resumable-streams.mdx
rename to docs/content/guides/ai-agents/resumable-streams.mdx
diff --git a/docs/content/docs/ai-agents/sleep-and-delays.mdx b/docs/content/guides/ai-agents/sleep-and-delays.mdx
similarity index 100%
rename from docs/content/docs/ai-agents/sleep-and-delays.mdx
rename to docs/content/guides/ai-agents/sleep-and-delays.mdx
diff --git a/docs/content/guides/meta.json b/docs/content/guides/meta.json
new file mode 100644
index 000000000..94799779e
--- /dev/null
+++ b/docs/content/guides/meta.json
@@ -0,0 +1,3 @@
+{
+  "pages": ["ai-agents"]
+}
diff --git a/docs/lib/geistdocs/source.ts b/docs/lib/geistdocs/source.ts
index b7c5bd58a..8bd3ead59 100644
--- a/docs/lib/geistdocs/source.ts
+++ b/docs/lib/geistdocs/source.ts
@@ -1,6 +1,6 @@
 import { type InferPageType, loader } from 'fumadocs-core/source';
 import { lucideIconsPlugin } from 'fumadocs-core/source/lucide-icons';
-import { docs } from '@/.source';
+import { docs, guides } from '@/.source';
 
 // See https://fumadocs.dev/docs/headless/source-api for more info
 export const source = loader({
@@ -9,6 +9,12 @@ export const source = loader({
   plugins: [lucideIconsPlugin()],
 });
 
+export const guidesSource = loader({
+  baseUrl: '/guides',
+  source: guides.toFumadocsSource(),
+  plugins: [lucideIconsPlugin()],
+});
+
 export const getPageImage = (page: InferPageType<typeof source>) => {
   const segments = [...page.slugs, 'image.png'];
 
@@ -25,3 +31,13 @@ export const getLLMText = async (page: InferPageType<typeof source>) => {
 
 ${processed}`;
 };
+
+export const getGuidesLLMText = async (
+  page: InferPageType<typeof guidesSource>
+) => {
+  const processed = await page.data.getText('processed');
+
+  return `# ${page.data.title}
+
+${processed}`;
+};
diff --git a/docs/source.config.ts b/docs/source.config.ts
index ae3996d7a..e20b5c9d7 100644
--- a/docs/source.config.ts
+++ b/docs/source.config.ts
@@ -21,6 +21,19 @@ export const docs = defineDocs({
   },
 });
 
+export const guides = defineDocs({
+  dir: 'content/guides',
+  docs: {
+    schema: frontmatterSchema,
+    postprocess: {
+      includeProcessedMarkdown: true,
+    },
+  },
+  meta: {
+    schema: metaSchema,
+  },
+});
+
 export default defineConfig({
   mdxOptions: {
     remarkPlugins: [remarkMdxMermaid],

From 108ac78a5dc50a13d6b5c956d62172d647d59461 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 14:27:03 -0800
Subject: [PATCH 07/38] Polish

---
 docs/content/guides/ai-agents/index.mdx | 49 +++++++++++++++++++++----
 1 file changed, 41 insertions(+), 8 deletions(-)

diff --git a/docs/content/guides/ai-agents/index.mdx b/docs/content/guides/ai-agents/index.mdx
index d3d8b7b87..db547de21 100644
--- a/docs/content/guides/ai-agents/index.mdx
+++ b/docs/content/guides/ai-agents/index.mdx
@@ -19,10 +19,11 @@ Workflow DevKit provides all of these capabilities out of the box. Your agent be
 
 ## Getting Started
 
-Start with a Next.js application using the AI SDK's `Agent` class:
+We start out with a basic Next.js application using the AI SDK's `Agent` class,
+which is a simple wrapper around AI SDK's `streamText` function. It comes with a basic tool for reading web pages.
 
 ```typescript title="app/api/chat/route.ts" lineNumbers
-import { createUIMessageStreamResponse, Agent, stepCountIs } from 'ai';
+import { createUIMessageStreamResponse, Experimental_Agent as Agent, stepCountIs } from 'ai';
 import { tools } from '@/ai/tools';
 
 export async function POST(req: Request) {
@@ -31,7 +32,7 @@ export async function POST(req: Request) {
   const agent = new Agent({
     model: modelId,
     system: 'You are a helpful assistant.',
-    tools: tools(),
+    tools,
     stopWhen: stepCountIs(20),
   });
 
@@ -43,7 +44,26 @@ export async function POST(req: Request) {
 }
 ```
 
-### Step 1: Install Dependencies
+```typescript title="ai/tools" lineNumbers
+import { tool } from 'ai';
+import { z } from 'zod';
+
+export const tools = {
+  searchWeb: tool({
+    description: 'Read a web page and return the content',
+    inputSchema: z.object({ url: z.string() }),
+    execute: async ({ url }: { url: string }) => {
+      const response = await fetch(url);
+      return response.text();
+    },
+  }),
+};
+```
+
+<Steps>
+
+<Step>
+### Install Dependencies
 
 Add the Workflow DevKit packages to your project:
 
@@ -51,7 +71,10 @@ Add the Workflow DevKit packages to your project:
 npm install workflow @workflow/ai
 ```
 
-### Step 2: Create a Workflow Function
+</Step>
+
+<Step>
+### Create a Workflow Function
 
 Move the agent logic into a separate workflow function:
 
@@ -93,8 +116,10 @@ Key changes:
 - Add the `"use workflow"` directive to mark this as a workflow function
 - Use [`getWritable()`](/docs/api-reference/workflow/get-writable) to get a stream for agent output
 - Pass the `writable` to `agent.stream()` instead of returning a stream directly
+</Step>
 
-### Step 3: Update the API Route
+<Step>
+### Update the API Route
 
 Replace the agent call with [`start()`](/docs/api-reference/workflow-api/start) to run the workflow:
 
@@ -115,7 +140,10 @@ export async function POST(req: Request) {
 }
 ```
 
-### Step 4: Convert Tools to Steps
+</Step>
+
+<Step>
+### Convert Tools to Steps
 
 Mark tool execution functions with `"use step"` to make them durable. This enables automatic retries and observability:
 
@@ -143,8 +171,10 @@ With `"use step"`:
 - Failed tool calls are automatically retried (up to 3 times by default)
 - Each tool execution appears as a discrete step in observability tools
 - Results are persisted, so replays skip already-completed tools
+</Step>
 
-### Step 5: Stream Progress Updates from Tools
+<Step>
+### Stream Progress Updates from Tools
 
 Tools can emit progress updates to the same stream the agent uses. This allows the UI to display tool status:
 
@@ -191,6 +221,9 @@ export const runCommand = tool({
 ```
 
 The UI can handle these data chunks to display real-time progress.
+</Step>
+
+</Steps>
 
 ## Running the Workflow
 

From b04412d6c8a7283cb0a2fd49dc99020f422b3800 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 14:44:49 -0800
Subject: [PATCH 08/38] Show more code snippets and full state

---
 docs/content/guides/ai-agents/index.mdx | 332 ++++++++++++++++++++++--
 1 file changed, 315 insertions(+), 17 deletions(-)

diff --git a/docs/content/guides/ai-agents/index.mdx b/docs/content/guides/ai-agents/index.mdx
index db547de21..d9c1bb7a4 100644
--- a/docs/content/guides/ai-agents/index.mdx
+++ b/docs/content/guides/ai-agents/index.mdx
@@ -22,6 +22,10 @@ Workflow DevKit provides all of these capabilities out of the box. Your agent be
 We start out with a basic Next.js application using the AI SDK's `Agent` class,
 which is a simple wrapper around AI SDK's `streamText` function. It comes with a basic tool for reading web pages.
 
+<Tabs items={['API Route', 'Tools', 'Client']}>
+
+<Tab value="API Route">
+
 ```typescript title="app/api/chat/route.ts" lineNumbers
 import { createUIMessageStreamResponse, Experimental_Agent as Agent, stepCountIs } from 'ai';
 import { tools } from '@/ai/tools';
@@ -44,7 +48,11 @@ export async function POST(req: Request) {
 }
 ```
 
-```typescript title="ai/tools" lineNumbers
+</Tab>
+
+<Tab value="Tools">
+
+```typescript title="ai/tools/index.ts" lineNumbers
 import { tool } from 'ai';
 import { z } from 'zod';
 
@@ -60,6 +68,52 @@ export const tools = {
 };
 ```
 
+</Tab>
+
+<Tab value="Client">
+
+```typescript title="app/chat.tsx" lineNumbers
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+
+export function Chat() {
+  const { messages, input, handleInputChange, handleSubmit } = useChat({
+    api: '/api/chat',
+  });
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong>
+          {m.parts.map((part, i) => {
+            if (part.type === 'text') {
+              return <span key={i}>{part.text}</span>;
+            }
+            if (part.type === 'tool-invocation') {
+              return <div key={i}>Calling {part.toolInvocation.toolName}...</div>;
+            }
+            return null;
+          })}
+        </div>
+      ))}
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Type a message..."
+        />
+      </form>
+    </div>
+  );
+}
+```
+
+</Tab>
+
+</Tabs>
+
 <Steps>
 
 <Step>
@@ -176,16 +230,20 @@ With `"use step"`:
 <Step>
 ### Stream Progress Updates from Tools
 
-Tools can emit progress updates to the same stream the agent uses. This allows the UI to display tool status:
+Tools can emit progress updates to the same stream the agent uses. This allows the UI to display tool status.
+
+<Tabs items={['Tool', 'Client']}>
 
-```typescript title="ai/tools/run-command.ts" lineNumbers
+<Tab value="Tool">
+
+```typescript title="ai/tools/search-web.ts" lineNumbers
 import { tool } from 'ai';
-import { getWritable } from 'workflow'; // [!code highlight]
+import { getWritable } from 'workflow';
 import { z } from 'zod';
 import type { UIMessageChunk } from 'ai';
 
-async function executeRunCommand(
-  { command }: { command: string },
+async function executeSearch(
+  { url }: { url: string },
   { toolCallId }: { toolCallId: string }
 ) {
   'use step';
@@ -196,31 +254,97 @@ async function executeRunCommand(
   // Emit a progress update // [!code highlight]
   await writer.write({ // [!code highlight]
     id: toolCallId, // [!code highlight]
-    type: 'data-run-command', // [!code highlight]
-    data: { command, status: 'executing' }, // [!code highlight]
+    type: 'data-search-web', // [!code highlight]
+    data: { url, status: 'fetching' }, // [!code highlight]
   }); // [!code highlight]
 
-  const result = await runCommand(command);
+  const response = await fetch(url);
+  const content = await response.text();
 
   await writer.write({ // [!code highlight]
     id: toolCallId, // [!code highlight]
-    type: 'data-run-command', // [!code highlight]
-    data: { command, status: 'done', result }, // [!code highlight]
+    type: 'data-search-web', // [!code highlight]
+    data: { url, status: 'done' }, // [!code highlight]
   }); // [!code highlight]
 
   writer.releaseLock(); // [!code highlight]
 
-  return result;
+  return content;
 }
 
-export const runCommand = tool({
-  description: 'Run a shell command',
-  inputSchema: z.object({ command: z.string() }),
-  execute: executeRunCommand,
+export const searchWeb = tool({
+  description: 'Read a web page and return the content',
+  inputSchema: z.object({ url: z.string() }),
+  execute: executeSearch,
 });
 ```
 
-The UI can handle these data chunks to display real-time progress.
+</Tab>
+
+<Tab value="Client">
+
+Handle the `data-search-web` chunks in your client to display progress:
+
+```typescript title="app/chat.tsx" lineNumbers
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import type { DataUIPart } from 'ai';
+
+type DataPart =
+  | { type: 'data-search-web'; data: { url: string; status: string } };
+
+export function Chat() {
+  const [toolStatus, setToolStatus] = useState<Record<string, DataPart['data']>>({});
+
+  const { messages, input, handleInputChange, handleSubmit } = useChat({
+    api: '/api/chat',
+    onData: (part: DataUIPart<DataPart>) => { // [!code highlight]
+      if (part.type === 'data-search-web') { // [!code highlight]
+        setToolStatus((prev) => ({ ...prev, [part.id]: part.data })); // [!code highlight]
+      } // [!code highlight]
+    }, // [!code highlight]
+  });
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong>
+          {m.parts.map((part, i) => {
+            if (part.type === 'text') {
+              return <span key={i}>{part.text}</span>;
+            }
+            if (part.type === 'tool-invocation') {
+              const status = toolStatus[part.toolInvocation.toolCallId]; // [!code highlight]
+              return (
+                <div key={i}>
+                  {status?.status === 'fetching' // [!code highlight]
+                    ? `Fetching ${status.url}...` // [!code highlight]
+                    : `Called ${part.toolInvocation.toolName}`} // [!code highlight]
+                </div>
+              );
+            }
+            return null;
+          })}
+        </div>
+      ))}
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Type a message..."
+        />
+      </form>
+    </div>
+  );
+}
+```
+
+</Tab>
+
+</Tabs>
+
 </Step>
 
 </Steps>
@@ -256,6 +380,180 @@ Now that you have a basic durable agent, explore these additional capabilities:
   </Card>
 </Cards>
 
+## Complete Example
+
+Here is the complete code for the durable agent after all the steps above:
+
+<Tabs items={['API Route', 'Workflow', 'Tools', 'Client']}>
+
+<Tab value="API Route">
+
+```typescript title="app/api/chat/route.ts" lineNumbers
+import { createUIMessageStreamResponse, convertToModelMessages } from 'ai';
+import { start } from 'workflow/api';
+import { chatWorkflow } from './workflow';
+
+export async function POST(req: Request) {
+  const { messages, modelId } = await req.json();
+  const modelMessages = convertToModelMessages(messages);
+
+  const run = await start(chatWorkflow, [{ messages: modelMessages, modelId }]);
+
+  return createUIMessageStreamResponse({
+    stream: run.readable,
+  });
+}
+```
+
+</Tab>
+
+<Tab value="Workflow">
+
+```typescript title="app/api/chat/workflow.ts" lineNumbers
+import { DurableAgent } from '@workflow/ai/agent';
+import { getWritable } from 'workflow';
+import { stepCountIs } from 'ai';
+import { tools } from '@/ai/tools';
+import type { ModelMessage, UIMessageChunk } from 'ai';
+
+export async function chatWorkflow({
+  messages,
+  modelId,
+}: {
+  messages: ModelMessage[];
+  modelId: string;
+}) {
+  'use workflow';
+
+  const writable = getWritable<UIMessageChunk>();
+
+  const agent = new DurableAgent({
+    model: modelId,
+    system: 'You are a helpful assistant.',
+    tools,
+  });
+
+  await agent.stream({
+    messages,
+    writable,
+    stopWhen: stepCountIs(20),
+  });
+}
+```
+
+</Tab>
+
+<Tab value="Tools">
+
+```typescript title="ai/tools/index.ts" lineNumbers
+import { tool } from 'ai';
+import { getWritable } from 'workflow';
+import { z } from 'zod';
+import type { UIMessageChunk } from 'ai';
+
+async function executeSearch(
+  { url }: { url: string },
+  { toolCallId }: { toolCallId: string }
+) {
+  'use step';
+
+  const writable = getWritable<UIMessageChunk>();
+  const writer = writable.getWriter();
+
+  await writer.write({
+    id: toolCallId,
+    type: 'data-search-web',
+    data: { url, status: 'fetching' },
+  });
+
+  const response = await fetch(url);
+  const content = await response.text();
+
+  await writer.write({
+    id: toolCallId,
+    type: 'data-search-web',
+    data: { url, status: 'done' },
+  });
+
+  writer.releaseLock();
+
+  return content;
+}
+
+export const tools = {
+  searchWeb: tool({
+    description: 'Read a web page and return the content',
+    inputSchema: z.object({ url: z.string() }),
+    execute: executeSearch,
+  }),
+};
+```
+
+</Tab>
+
+<Tab value="Client">
+
+```typescript title="app/chat.tsx" lineNumbers
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import { useState } from 'react';
+import type { DataUIPart } from 'ai';
+
+type DataPart =
+  | { type: 'data-search-web'; data: { url: string; status: string } };
+
+export function Chat() {
+  const [toolStatus, setToolStatus] = useState<Record<string, DataPart['data']>>({});
+
+  const { messages, input, handleInputChange, handleSubmit } = useChat({
+    api: '/api/chat',
+    onData: (part: DataUIPart<DataPart>) => {
+      if (part.type === 'data-search-web') {
+        setToolStatus((prev) => ({ ...prev, [part.id]: part.data }));
+      }
+    },
+  });
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong>
+          {m.parts.map((part, i) => {
+            if (part.type === 'text') {
+              return <span key={i}>{part.text}</span>;
+            }
+            if (part.type === 'tool-invocation') {
+              const status = toolStatus[part.toolInvocation.toolCallId];
+              return (
+                <div key={i}>
+                  {status?.status === 'fetching'
+                    ? `Fetching ${status.url}...`
+                    : `Called ${part.toolInvocation.toolName}`}
+                </div>
+              );
+            }
+            return null;
+          })}
+        </div>
+      ))}
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Type a message..."
+        />
+      </form>
+    </div>
+  );
+}
+```
+
+</Tab>
+
+</Tabs>
+
 ## Related Documentation
 
 - [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Full API documentation

From 4811a94edd941ab17279b3bcd761b91040665db3 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 14:49:17 -0800
Subject: [PATCH 09/38] Fix

---
 docs/content/guides/ai-agents/index.mdx | 37 ++++++++-----------------
 1 file changed, 11 insertions(+), 26 deletions(-)

diff --git a/docs/content/guides/ai-agents/index.mdx b/docs/content/guides/ai-agents/index.mdx
index d9c1bb7a4..0d90cc982 100644
--- a/docs/content/guides/ai-agents/index.mdx
+++ b/docs/content/guides/ai-agents/index.mdx
@@ -283,27 +283,16 @@ export const searchWeb = tool({
 
 <Tab value="Client">
 
-Handle the `data-search-web` chunks in your client to display progress:
+Handle the `data-search-web` chunks in your client to display progress. Data parts are stored in the message, so you can find the latest status directly:
 
 ```typescript title="app/chat.tsx" lineNumbers
 'use client';
 
 import { useChat } from '@ai-sdk/react';
-import type { DataUIPart } from 'ai';
-
-type DataPart =
-  | { type: 'data-search-web'; data: { url: string; status: string } };
 
 export function Chat() {
-  const [toolStatus, setToolStatus] = useState<Record<string, DataPart['data']>>({});
-
   const { messages, input, handleInputChange, handleSubmit } = useChat({
     api: '/api/chat',
-    onData: (part: DataUIPart<DataPart>) => { // [!code highlight]
-      if (part.type === 'data-search-web') { // [!code highlight]
-        setToolStatus((prev) => ({ ...prev, [part.id]: part.data })); // [!code highlight]
-      } // [!code highlight]
-    }, // [!code highlight]
   });
 
   return (
@@ -316,7 +305,11 @@ export function Chat() {
               return <span key={i}>{part.text}</span>;
             }
             if (part.type === 'tool-invocation') {
-              const status = toolStatus[part.toolInvocation.toolCallId]; // [!code highlight]
+              // Find the latest data part for this tool call // [!code highlight]
+              const dataPart = m.parts.findLast( // [!code highlight]
+                (p) => p.type === 'data' && p.id === part.toolInvocation.toolCallId // [!code highlight]
+              ); // [!code highlight]
+              const status = dataPart?.type === 'data' ? dataPart.data : null; // [!code highlight]
               return (
                 <div key={i}>
                   {status?.status === 'fetching' // [!code highlight]
@@ -497,22 +490,10 @@ export const tools = {
 'use client';
 
 import { useChat } from '@ai-sdk/react';
-import { useState } from 'react';
-import type { DataUIPart } from 'ai';
-
-type DataPart =
-  | { type: 'data-search-web'; data: { url: string; status: string } };
 
 export function Chat() {
-  const [toolStatus, setToolStatus] = useState<Record<string, DataPart['data']>>({});
-
   const { messages, input, handleInputChange, handleSubmit } = useChat({
     api: '/api/chat',
-    onData: (part: DataUIPart<DataPart>) => {
-      if (part.type === 'data-search-web') {
-        setToolStatus((prev) => ({ ...prev, [part.id]: part.data }));
-      }
-    },
   });
 
   return (
@@ -525,7 +506,11 @@ export function Chat() {
               return <span key={i}>{part.text}</span>;
             }
             if (part.type === 'tool-invocation') {
-              const status = toolStatus[part.toolInvocation.toolCallId];
+              // Find the latest data part for this tool call
+              const dataPart = m.parts.findLast(
+                (p) => p.type === 'data' && p.id === part.toolInvocation.toolCallId
+              );
+              const status = dataPart?.type === 'data' ? dataPart.data : null;
               return (
                 <div key={i}>
                   {status?.status === 'fetching'

From da6e94eb35f70379d1f3015a392940348dfd773c Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 14:49:27 -0800
Subject: [PATCH 10/38] Delete previous

---
 docs/content/docs/ai-agents/index.mdx | 229 --------------------------
 1 file changed, 229 deletions(-)
 delete mode 100644 docs/content/docs/ai-agents/index.mdx

diff --git a/docs/content/docs/ai-agents/index.mdx b/docs/content/docs/ai-agents/index.mdx
deleted file mode 100644
index 2f8fcf187..000000000
--- a/docs/content/docs/ai-agents/index.mdx
+++ /dev/null
@@ -1,229 +0,0 @@
----
-title: Building Durable AI Agents
----
-
-AI agents are built on the primitive of LLM and tool-call loops, often with additional processes for data fetching, resource provisioning, or reacting to external events. Workflow DevKit makes your agents production-ready, by turning your agents into durable, resumable workflows, and managing your LLM calls, tool executions, and other async operations as retryable and observable steps.
-
-This guide walks through converting a basic AI SDK agent into a durable agent using Workflow DevKit.
-
-## Why Durable Agents?
-
-Aside from the usual challenges of getting your long-running tasks to be production-ready, building mature AI agents typically requires solving several additional **challenges**:
-
-- **Durability**: Persisting chat sessions and turning all LLM and tool calls into separate async jobs, with workers, queues, and state management, which repeatedly save and re-load state from a database.
-- **Observability**: Using services to collect traces and metrics, separately storing your messages and user history, and then combining them to get a complete picture of your agent's behavior.
-- **Resumability**: Separately from storing messages for replayability, most LLM calls are streams, and recovering from a call failure without re-doing the entire call requires piping and storing streams separately from your messages, usually in a separate service.
-- **Human-in-the-loop**: Your client, API, and async job orchestration need to work together to create, track, route to, and display human approval requests, or similar webhook operations. If your stack is disjointed, this simple feature becomes a major orchestration challenge.
-
-Workflow DevKit provides all of these capabilities out of the box. Your agent becomes a workflow, your tools become steps, and the framework handles interplay with your existing infrastructure.
-
-## Getting Started
-
-Start with a Next.js application using the AI SDK's `Agent` class:
-
-```typescript title="app/api/chat/route.ts" lineNumbers
-import { createUIMessageStreamResponse, Agent, stepCountIs } from 'ai';
-import { tools } from '@/ai/tools';
-
-export async function POST(req: Request) {
-  const { messages, modelId } = await req.json();
-
-  const agent = new Agent({
-    model: modelId,
-    system: 'You are a helpful assistant.',
-    tools: tools(),
-  });
-
-  const stream = agent.stream({ messages });
-
-  return createUIMessageStreamResponse({
-    stream: stream.toUIMessageStream(),
-  });
-}
-```
-
-### Step 1: Install Dependencies
-
-Add the Workflow DevKit packages to your project:
-
-```bash
-npm install workflow @workflow/ai
-```
-
-### Step 2: Create a Workflow Function
-
-Move the agent logic into a separate workflow function:
-
-```typescript title="app/api/chat/workflow.ts" lineNumbers
-import { DurableAgent } from '@workflow/ai/agent'; // [!code highlight]
-import { getWritable } from 'workflow'; // [!code highlight]
-import { stepCountIs } from 'ai';
-import { tools } from '@/ai/tools';
-import type { ModelMessage, UIMessageChunk } from 'ai';
-
-export async function chatWorkflow({ // [!code highlight]
-  messages,
-  modelId,
-}: {
-  messages: ModelMessage[];
-  modelId: string;
-}) {
-  'use workflow'; // [!code highlight]
-
-  const writable = getWritable<UIMessageChunk>(); // [!code highlight]
-
-  const agent = new DurableAgent({ // [!code highlight]
-    model: modelId,
-    system: 'You are a helpful assistant.',
-    tools: tools(),
-  });
-
-  await agent.stream({
-    messages,
-    writable,
-  });
-}
-```
-
-Key changes:
-
-- Replace `Agent` with [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) from `@workflow/ai/agent`
-- Add the `"use workflow"` directive to mark this as a workflow function
-- Use [`getWritable()`](/docs/api-reference/workflow/get-writable) to get a stream for agent output
-- Pass the `writable` to `agent.stream()` instead of returning a stream directly
-
-### Step 3: Update the API Route
-
-Replace the agent call with [`start()`](/docs/api-reference/workflow-api/start) to run the workflow:
-
-```typescript title="app/api/chat/route.ts" lineNumbers
-import { createUIMessageStreamResponse, convertToModelMessages } from 'ai';
-import { start } from 'workflow/api'; // [!code highlight]
-import { chatWorkflow } from './workflow'; // [!code highlight]
-
-export async function POST(req: Request) {
-  const { messages, modelId } = await req.json();
-  const modelMessages = convertToModelMessages(messages);
-
-  // This will start the workflow in the background
-  const run = await start(chatWorkflow, [{ messages: modelMessages, modelId }]); // [!code highlight]
-
-  return createUIMessageStreamResponse({
-    stream: run.readable, // [!code highlight]
-  });
-}
-```
-
-### Step 4: Convert Tools to Steps
-
-Mark tool execution functions with `"use step"` to make them durable. This enables automatic retries and observability:
-
-```typescript title="ai/tools/search-web.ts" lineNumbers
-import { tool } from 'ai';
-import { z } from 'zod';
-
-async function executeSearch({ query }: { query: string }) {
-  'use step'; // [!code highlight]
-
-  const response = await fetch(`https://api.search.com?q=${query}`);
-  return response.json();
-}
-
-export const searchWeb = tool({
-  description: 'Search the web for information',
-  inputSchema: z.object({ query: z.string() }),
-  execute: executeSearch,
-});
-```
-
-With `"use step"`:
-
-- The tool execution runs in a separate step with full Node.js access
-- Failed tool calls are automatically retried (up to 3 times by default)
-- Each tool execution appears as a discrete step in observability tools
-- Results are persisted, so replays skip already-completed tools
-
-Note that any side-effects or network operations need to be run inside step functions, not in your workflow code.
-
-### Step 5: Stream Progress Updates from Tools
-
-Tools can emit progress updates to the same stream the agent uses. This allows the UI to display tool status and live updates from steps, without having to manually wire up streams:
-
-```typescript title="ai/tools/run-command.ts" lineNumbers
-import { tool } from 'ai';
-import { getWritable } from 'workflow'; // [!code highlight]
-import { z } from 'zod';
-import type { UIMessageChunk } from 'ai';
-
-async function executeRunCommand(
-  { command }: { command: string },
-  { toolCallId }: { toolCallId: string }
-) {
-  'use step';
-
-  const writable = getWritable<UIMessageChunk>(); // [!code highlight]
-  const writer = writable.getWriter(); // [!code highlight]
-
-  // Emit a progress update // [!code highlight]
-  await writer.write({ // [!code highlight]
-    id: toolCallId, // [!code highlight]
-    type: 'data-run-command', // [!code highlight]
-    data: { command, status: 'executing' }, // [!code highlight]
-  }); // [!code highlight]
-
-  const result = await runCommand(command);
-
-  await writer.write({ // [!code highlight]
-    id: toolCallId, // [!code highlight]
-    type: 'data-run-command', // [!code highlight]
-    data: { command, status: 'done', result }, // [!code highlight]
-  }); // [!code highlight]
-
-  writer.releaseLock(); // [!code highlight]
-
-  return result;
-}
-
-export const runCommand = tool({
-  description: 'Run a shell command',
-  inputSchema: z.object({ command: z.string() }),
-  execute: executeRunCommand,
-});
-```
-
-The UI can handle these data chunks to display real-time progress.
-
-## Running the Workflow
-
-Run your development server, kick off a chat session, and then open the observability dashboard to see your workflow running live:
-
-```bash
-npx workflow web
-```
-
-This opens a local dashboard showing all your workflow runs, with trace-viewers showing detailed views of each run, errors, retries, timing, and more.
-The UI also allows you to cancel, re-run, and start new runs.
-
-## Next Steps
-
-Now that you have a basic durable agent, it's a short step to adding additional capabilities like resumable streams, sleep and delays, and human-in-the-loop.
-
-<Cards>
-  <Card title="Resumable Streams" href="/docs/ai-agents/resumable-streams">
-    Enable clients to reconnect to interrupted streams without losing data.
-  </Card>
-  <Card title="Sleep and Delays" href="/docs/ai-agents/sleep-and-delays">
-    Add native sleep functionality to allow your workflows to pause and resume, enable work on schedules, and more.
-  </Card>
-  <Card title="Human-in-the-Loop" href="/docs/ai-agents/human-in-the-loop">
-    Implement approval workflows that wait for human input or other external events,
-    like PR updates, webhooks, and more.
-  </Card>
-</Cards>
-
-## Related Documentation
-
-- [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Full API documentation
-- [Workflows and Steps](/docs/foundations/workflows-and-steps) - Core concepts
-- [Streaming](/docs/foundations/streaming) - In-depth streaming guide
-- [Errors and Retries](/docs/foundations/errors-and-retries) - Error handling patterns

From 2b3c67201283acd67a05852d22ecb642b4105b78 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 14:52:48 -0800
Subject: [PATCH 11/38] fix

---
 docs/content/guides/ai-agents/index.mdx | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/docs/content/guides/ai-agents/index.mdx b/docs/content/guides/ai-agents/index.mdx
index 0d90cc982..064d33f91 100644
--- a/docs/content/guides/ai-agents/index.mdx
+++ b/docs/content/guides/ai-agents/index.mdx
@@ -37,7 +37,6 @@ export async function POST(req: Request) {
     model: modelId,
     system: 'You are a helpful assistant.',
     tools,
-    stopWhen: stepCountIs(20),
   });
 
   const stream = agent.stream({ messages });
@@ -125,6 +124,19 @@ Add the Workflow DevKit packages to your project:
 npm install workflow @workflow/ai
 ```
 
+and extend the NextJS compiler to transform the code:
+
+```typescript title="next.config.ts" lineNumbers
+import { withWorkflow } from 'workflow/next';
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  // ... rest of your Next.js config
+};
+
+export default withWorkflow(nextConfig);
+```
+
 </Step>
 
 <Step>

From 7f3514ff76d8e0e6d25bf22ec6091f650b3f6efd Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 15:02:50 -0800
Subject: [PATCH 12/38] Fix routing

---
 docs/app/guides/[[...slug]]/page.tsx          |  62 +++++---
 docs/app/guides/page.tsx                      |   5 -
 .../guides/ai-agents/human-in-the-loop.mdx    | 103 +++++++++++++
 .../guides/ai-agents/resumable-streams.mdx    | 145 +++++++++++++++++-
 .../guides/ai-agents/sleep-and-delays.mdx     |  52 +++++++
 5 files changed, 341 insertions(+), 26 deletions(-)
 delete mode 100644 docs/app/guides/page.tsx

diff --git a/docs/app/guides/[[...slug]]/page.tsx b/docs/app/guides/[[...slug]]/page.tsx
index b8db99716..6a795537b 100644
--- a/docs/app/guides/[[...slug]]/page.tsx
+++ b/docs/app/guides/[[...slug]]/page.tsx
@@ -1,15 +1,16 @@
 import { Step, Steps } from 'fumadocs-ui/components/steps';
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+import {
+  DocsBody as FumadocsDocsBody,
+  DocsDescription as FumadocsDocsDescription,
+  DocsPage as FumadocsDocsPage,
+  DocsTitle as FumadocsDocsTitle,
+} from 'fumadocs-ui/page';
 import { createRelativeLink } from 'fumadocs-ui/mdx';
-import { notFound } from 'next/navigation';
+import { notFound, redirect } from 'next/navigation';
+import type { CSSProperties } from 'react';
 import { AskAI } from '@/components/geistdocs/ask-ai';
 import { CopyPage } from '@/components/geistdocs/copy-page';
-import {
-  DocsBody,
-  DocsDescription,
-  DocsPage,
-  DocsTitle,
-} from '@/components/geistdocs/docs-page';
 import { EditSource } from '@/components/geistdocs/edit-source';
 import { Feedback } from '@/components/geistdocs/feedback';
 import { getMDXComponents } from '@/components/geistdocs/mdx-components';
@@ -24,11 +25,21 @@ import {
   guidesSource,
 } from '@/lib/geistdocs/source';
 import { TSDoc } from '@/lib/tsdoc';
+import { cn } from '@/lib/utils';
 import type { Metadata } from 'next';
 
+const containerStyle = {
+  '--fd-nav-height': '4rem',
+} as CSSProperties;
+
 const Page = async (props: PageProps<'/guides/[[...slug]]'>) => {
   const params = await props.params;
 
+  // Redirect /guides to /guides/ai-agents
+  if (!params.slug || params.slug.length === 0) {
+    redirect('/guides/ai-agents');
+  }
+
   const page = guidesSource.getPage(params.slug);
 
   if (!page) {
@@ -39,8 +50,14 @@ const Page = async (props: PageProps<'/guides/[[...slug]]'>) => {
   const MDX = page.data.body;
 
   return (
-    <DocsPage
-      slug={params.slug}
+    <FumadocsDocsPage
+      full={page.data.full}
+      toc={page.data.toc}
+      article={{ className: 'max-w-[754px]' }}
+      container={{
+        style: containerStyle,
+        className: 'col-span-2',
+      }}
       tableOfContent={{
         component: (
           <TableOfContents>
@@ -53,11 +70,12 @@ const Page = async (props: PageProps<'/guides/[[...slug]]'>) => {
           </TableOfContents>
         ),
       }}
-      toc={page.data.toc}
     >
-      <DocsTitle>{page.data.title}</DocsTitle>
-      <DocsDescription>{page.data.description}</DocsDescription>
-      <DocsBody>
+      <FumadocsDocsTitle className={cn('text-4xl tracking-tight')}>
+        {page.data.title}
+      </FumadocsDocsTitle>
+      <FumadocsDocsDescription>{page.data.description}</FumadocsDocsDescription>
+      <FumadocsDocsBody className={cn('mx-auto w-full')}>
         <MDX
           components={getMDXComponents({
             a: createRelativeLink(guidesSource, page),
@@ -72,20 +90,28 @@ const Page = async (props: PageProps<'/guides/[[...slug]]'>) => {
             Tab,
           })}
         />
-      </DocsBody>
-    </DocsPage>
+      </FumadocsDocsBody>
+    </FumadocsDocsPage>
   );
 };
 
-export const generateStaticParams = () =>
-  guidesSource.generateParams().map((params) => ({
+export const generateStaticParams = () => [
+  { slug: [] }, // Root redirect
+  ...guidesSource.generateParams().map((params) => ({
     slug: params.slug,
-  }));
+  })),
+];
 
 export const generateMetadata = async (
   props: PageProps<'/guides/[[...slug]]'>
 ): Promise<Metadata> => {
   const params = await props.params;
+
+  // Root path redirects, no metadata needed
+  if (!params.slug || params.slug.length === 0) {
+    return { title: 'Guides' };
+  }
+
   const page = guidesSource.getPage(params.slug);
 
   if (!page) {
diff --git a/docs/app/guides/page.tsx b/docs/app/guides/page.tsx
deleted file mode 100644
index 1822f3150..000000000
--- a/docs/app/guides/page.tsx
+++ /dev/null
@@ -1,5 +0,0 @@
-import { redirect } from 'next/navigation';
-
-export default function GuidesPage() {
-  redirect('/guides/ai-agents');
-}
diff --git a/docs/content/guides/ai-agents/human-in-the-loop.mdx b/docs/content/guides/ai-agents/human-in-the-loop.mdx
index c5e1ee0fb..834984505 100644
--- a/docs/content/guides/ai-agents/human-in-the-loop.mdx
+++ b/docs/content/guides/ai-agents/human-in-the-loop.mdx
@@ -299,6 +299,109 @@ export async function criticalActionWorkflow(action: string) {
 }
 ```
 
+## Complete Example
+
+A human approval tool with UI component:
+
+<Tabs items={['Tool', 'UI Component']}>
+
+<Tab value="Tool">
+
+```typescript title="ai/tools/human-approval.ts" lineNumbers
+import { tool } from 'ai';
+import { createWebhook, getWritable } from 'workflow';
+import { z } from 'zod';
+import type { UIMessageChunk } from 'ai';
+
+async function emitApprovalRequest(
+  { url, message }: { url: string; message: string },
+  { toolCallId }: { toolCallId: string }
+) {
+  'use step';
+
+  const writable = getWritable<UIMessageChunk>();
+  const writer = writable.getWriter();
+
+  await writer.write({
+    id: toolCallId,
+    type: 'data-approval-required',
+    data: { url, message },
+  });
+
+  writer.releaseLock();
+}
+
+async function executeHumanApproval(
+  { message }: { message: string },
+  { toolCallId }: { toolCallId: string }
+) {
+  // No "use step" - webhooks are workflow-level primitives
+  const webhook = createWebhook();
+
+  await emitApprovalRequest({ url: webhook.url, message }, { toolCallId });
+
+  const request = await webhook;
+  const { approved, comment } = await request.json();
+
+  if (!approved) {
+    return `Action rejected: ${comment}`;
+  }
+
+  return `Approved with comment: ${comment}`;
+}
+
+export const humanApproval = tool({
+  description: 'Request human approval before proceeding with an action',
+  inputSchema: z.object({
+    message: z.string().describe('Description of what needs approval'),
+  }),
+  execute: executeHumanApproval,
+});
+```
+
+</Tab>
+
+<Tab value="UI Component">
+
+```typescript title="components/approval-button.tsx" lineNumbers
+'use client';
+
+interface ApprovalData {
+  url: string;
+  message: string;
+}
+
+export function ApprovalButton({ data }: { data: ApprovalData }) {
+  const handleApprove = async () => {
+    await fetch(data.url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ approved: true, comment: 'Approved' }),
+    });
+  };
+
+  const handleReject = async () => {
+    await fetch(data.url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ approved: false, comment: 'Rejected' }),
+    });
+  };
+
+  return (
+    <div>
+      <p>{data.message}</p>
+      <button onClick={handleApprove}>Approve</button>
+      <button onClick={handleReject}>Reject</button>
+    </div>
+  );
+}
+```
+
+</Tab>
+
+</Tabs>
+
 ## Related Documentation
 
 - [Hooks & Webhooks](/docs/foundations/hooks) - Complete guide to hooks and webhooks
diff --git a/docs/content/guides/ai-agents/resumable-streams.mdx b/docs/content/guides/ai-agents/resumable-streams.mdx
index 5c3c6e97c..634edbd02 100644
--- a/docs/content/guides/ai-agents/resumable-streams.mdx
+++ b/docs/content/guides/ai-agents/resumable-streams.mdx
@@ -24,7 +24,10 @@ With a standard chat implementation, users must resend their message and wait fo
 
 ## Implementation
 
-### Step 1: Return the Run ID from Your API
+<Steps>
+
+<Step>
+### Return the Run ID from Your API
 
 Modify your chat endpoint to include the workflow run ID in a response header:
 
@@ -48,7 +51,10 @@ export async function POST(req: Request) {
 }
 ```
 
-### Step 2: Add a Stream Reconnection Endpoint
+</Step>
+
+<Step>
+### Add a Stream Reconnection Endpoint
 
 Create an endpoint that returns the stream for an existing run:
 
@@ -78,7 +84,10 @@ export async function GET(
 
 The `startIndex` parameter ensures the client only receives chunks it missed, avoiding duplicate data.
 
-### Step 3: Use WorkflowChatTransport in the Client
+</Step>
+
+<Step>
+### Use `WorkflowChatTransport` in the Client
 
 Replace the default transport in `useChat` with `WorkflowChatTransport`:
 
@@ -155,6 +164,10 @@ export function Chat() {
 }
 ```
 
+</Step>
+
+</Steps>
+
 ## How It Works
 
 1. When the user sends a message, `WorkflowChatTransport` makes a POST to `/api/chat`
@@ -201,6 +214,132 @@ new WorkflowChatTransport({
 
 The transport automatically retries reconnection on network errors. After reaching the limit, it stops attempting and surfaces the error.
 
+## Complete Example
+
+<Tabs items={['API Route', 'Reconnect Endpoint', 'Client']}>
+
+<Tab value="API Route">
+
+```typescript title="app/api/chat/route.ts" lineNumbers
+import { createUIMessageStreamResponse, convertToModelMessages } from 'ai';
+import { start } from 'workflow/api';
+import { chatWorkflow } from './workflow';
+
+export async function POST(req: Request) {
+  const { messages, modelId } = await req.json();
+  const modelMessages = convertToModelMessages(messages);
+
+  const run = await start(chatWorkflow, [{ messages: modelMessages, modelId }]);
+
+  return createUIMessageStreamResponse({
+    stream: run.readable,
+    headers: {
+      'x-workflow-run-id': run.runId,
+    },
+  });
+}
+```
+
+</Tab>
+
+<Tab value="Reconnect Endpoint">
+
+```typescript title="app/api/chat/[id]/stream/route.ts" lineNumbers
+import { createUIMessageStreamResponse } from 'ai';
+import { getRun } from 'workflow/api';
+
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  const { searchParams } = new URL(request.url);
+
+  const startIndexParam = searchParams.get('startIndex');
+  const startIndex = startIndexParam
+    ? parseInt(startIndexParam, 10)
+    : undefined;
+
+  const run = getRun(id);
+  const stream = run.getReadable({ startIndex });
+
+  return createUIMessageStreamResponse({ stream });
+}
+```
+
+</Tab>
+
+<Tab value="Client">
+
+```typescript title="app/chat.tsx" lineNumbers
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import { WorkflowChatTransport } from '@workflow/ai';
+import { useMemo, useState } from 'react';
+
+export function Chat() {
+  const [input, setInput] = useState('');
+
+  const activeRunId = useMemo(() => {
+    if (typeof window === 'undefined') return;
+    return localStorage.getItem('active-workflow-run-id') ?? undefined;
+  }, []);
+
+  const { messages, sendMessage, status } = useChat({
+    resume: Boolean(activeRunId),
+    transport: new WorkflowChatTransport({
+      api: '/api/chat',
+      onChatSendMessage: (response) => {
+        const workflowRunId = response.headers.get('x-workflow-run-id');
+        if (workflowRunId) {
+          localStorage.setItem('active-workflow-run-id', workflowRunId);
+        }
+      },
+      onChatEnd: () => {
+        localStorage.removeItem('active-workflow-run-id');
+      },
+      prepareReconnectToStreamRequest: ({ api, ...rest }) => {
+        const runId = localStorage.getItem('active-workflow-run-id');
+        if (!runId) throw new Error('No active workflow run ID found');
+        return {
+          ...rest,
+          api: `/api/chat/${encodeURIComponent(runId)}/stream`,
+        };
+      },
+      maxConsecutiveErrors: 5,
+    }),
+  });
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong> {m.content}
+        </div>
+      ))}
+      <form
+        onSubmit={(e) => {
+          e.preventDefault();
+          sendMessage({ text: input });
+          setInput('');
+        }}
+      >
+        <input
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          placeholder="Type a message..."
+        />
+      </form>
+    </div>
+  );
+}
+```
+
+</Tab>
+
+</Tabs>
+
 ## Related Documentation
 
 - [`WorkflowChatTransport` API Reference](/docs/api-reference/workflow-ai/workflow-chat-transport) - Full configuration options
diff --git a/docs/content/guides/ai-agents/sleep-and-delays.mdx b/docs/content/guides/ai-agents/sleep-and-delays.mdx
index ec286a912..5c816c1a1 100644
--- a/docs/content/guides/ai-agents/sleep-and-delays.mdx
+++ b/docs/content/guides/ai-agents/sleep-and-delays.mdx
@@ -211,6 +211,58 @@ async function checkJobStatus(jobId: string) {
 }
 ```
 
+## Complete Example
+
+A sleep tool that pauses the agent for a specified duration:
+
+```typescript title="ai/tools/sleep.ts" lineNumbers
+import { tool } from 'ai';
+import { getWritable, sleep } from 'workflow';
+import { z } from 'zod';
+import type { UIMessageChunk } from 'ai';
+
+const inputSchema = z.object({
+  durationMs: z.number().describe('Duration to sleep in milliseconds'),
+});
+
+async function reportSleep(
+  { durationMs }: { durationMs: number },
+  { toolCallId }: { toolCallId: string }
+) {
+  'use step';
+
+  const writable = getWritable<UIMessageChunk>();
+  const writer = writable.getWriter();
+
+  const seconds = Math.ceil(durationMs / 1000);
+
+  await writer.write({
+    id: toolCallId,
+    type: 'data-wait',
+    data: { text: `Sleeping for ${seconds} seconds` },
+  });
+
+  writer.releaseLock();
+}
+
+async function executeSleep(
+  { durationMs }: z.infer<typeof inputSchema>,
+  { toolCallId }: { toolCallId: string }
+) {
+  // No "use step" - sleep is a workflow-level function
+  await reportSleep({ durationMs }, { toolCallId });
+  await sleep(durationMs);
+
+  return `Slept for ${durationMs}ms`;
+}
+
+export const sleepTool = tool({
+  description: 'Pause execution for a specified duration',
+  inputSchema,
+  execute: executeSleep,
+});
+```
+
 ## Related Documentation
 
 - [`sleep()` API Reference](/docs/api-reference/workflow/sleep) - Full API documentation

From 11edb5ba5fb62969888974eda595ef5a25744807 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 15:18:43 -0800
Subject: [PATCH 13/38] Add nice graphic

---
 docs/app/guides/[[...slug]]/page.tsx          |  2 +
 docs/components/guides/agent-traces.tsx       | 94 +++++++++++++++++++
 docs/content/guides/ai-agents/index.mdx       |  2 +
 .../guides/ai-agents/resumable-streams.mdx    |  4 +-
 4 files changed, 100 insertions(+), 2 deletions(-)
 create mode 100644 docs/components/guides/agent-traces.tsx

diff --git a/docs/app/guides/[[...slug]]/page.tsx b/docs/app/guides/[[...slug]]/page.tsx
index 6a795537b..c88aa11ce 100644
--- a/docs/app/guides/[[...slug]]/page.tsx
+++ b/docs/app/guides/[[...slug]]/page.tsx
@@ -14,6 +14,7 @@ import { CopyPage } from '@/components/geistdocs/copy-page';
 import { EditSource } from '@/components/geistdocs/edit-source';
 import { Feedback } from '@/components/geistdocs/feedback';
 import { getMDXComponents } from '@/components/geistdocs/mdx-components';
+import { AgentTraces } from '@/components/guides/agent-traces';
 import { OpenInChat } from '@/components/geistdocs/open-in-chat';
 import { ScrollTop } from '@/components/geistdocs/scroll-top';
 import { TableOfContents } from '@/components/geistdocs/toc';
@@ -81,6 +82,7 @@ const Page = async (props: PageProps<'/guides/[[...slug]]'>) => {
             a: createRelativeLink(guidesSource, page),
 
             // Add your custom components here
+            AgentTraces,
             Badge,
             TSDoc,
             Step,
diff --git a/docs/components/guides/agent-traces.tsx b/docs/components/guides/agent-traces.tsx
new file mode 100644
index 000000000..6232b1b51
--- /dev/null
+++ b/docs/components/guides/agent-traces.tsx
@@ -0,0 +1,94 @@
+'use client';
+
+import { motion } from 'motion/react';
+import { cn } from '@/lib/utils';
+
+const rows = [
+  {
+    label: 'chatWorkflow',
+    className:
+      'bg-[#E1F0FF] dark:bg-[#00254D] border-[#99CEFF] text-[#0070F3] dark:border-[#0067D6] dark:text-[#52AEFF]',
+    start: 0,
+    duration: 100,
+  },
+  {
+    label: 'agent.stream',
+    className:
+      'bg-[#DCF6DC] dark:bg-[#1B311E] border-[#99E59F] text-[#46A758] dark:border-[#297C3B] dark:text-[#6CDA76]',
+    start: 2,
+    duration: 16,
+  },
+  {
+    label: 'searchWeb',
+    className:
+      'bg-[#FFF4E5] dark:bg-[#3D2800] border-[#FFCC80] text-[#F5A623] dark:border-[#9A6700] dark:text-[#FFCA28]',
+    start: 20,
+    duration: 13,
+  },
+  {
+    label: 'agent.stream',
+    className:
+      'bg-[#DCF6DC] dark:bg-[#1B311E] border-[#99E59F] text-[#46A758] dark:border-[#297C3B] dark:text-[#6CDA76]',
+    start: 37,
+    duration: 16,
+  },
+  {
+    label: 'waitForHumanApproval',
+    className:
+      'bg-[#FCE7F3] dark:bg-[#4A1D34] border-[#F9A8D4] text-[#EC4899] dark:border-[#BE185D] dark:text-[#F472B6]',
+    start: 57,
+    duration: 24,
+  },
+  {
+    label: 'agent.stream',
+    className:
+      'bg-[#DCF6DC] dark:bg-[#1B311E] border-[#99E59F] text-[#46A758] dark:border-[#297C3B] dark:text-[#6CDA76]',
+    start: 84,
+    duration: 16,
+  },
+];
+
+export const AgentTraces = () => (
+  <div className="not-prose my-8 rounded-lg border bg-card p-4 sm:p-6">
+    <div className="space-y-2 w-full">
+      {rows.map((row, index) => (
+        <div
+          key={`${row.label}-${index}`}
+          className="flex flex-col overflow-hidden"
+          style={{
+            marginLeft: `${row.start}%`,
+            width: `${row.duration}%`,
+          }}
+        >
+          <div className="relative h-6 w-full">
+            <motion.div
+              initial={{ width: 0, opacity: 0 }}
+              whileInView={{ width: 'auto', opacity: 1 }}
+              viewport={{ once: true, amount: 0.8 }}
+              transition={{
+                duration: 0.55,
+                delay: index * 0.12,
+                ease: [0.22, 1, 0.36, 1],
+              }}
+              className={cn(
+                'h-full rounded-sm border overflow-hidden',
+                row.className
+              )}
+            >
+              <div className="flex justify-between items-center h-full px-2">
+                <span className="text-[10px] sm:text-[11px] font-mono font-medium text-foreground truncate leading-none">
+                  {row.label}
+                </span>
+                {index === 0 && (
+                  <span className="text-[10px] sm:text-[11px] hidden sm:inline leading-none">
+                    {row.duration}ms
+                  </span>
+                )}
+              </div>
+            </motion.div>
+          </div>
+        </div>
+      ))}
+    </div>
+  </div>
+);
diff --git a/docs/content/guides/ai-agents/index.mdx b/docs/content/guides/ai-agents/index.mdx
index 064d33f91..a2e12273f 100644
--- a/docs/content/guides/ai-agents/index.mdx
+++ b/docs/content/guides/ai-agents/index.mdx
@@ -4,6 +4,8 @@ title: Building Durable AI Agents
 
 AI agents are built on the primitive of LLM and tool-call loops, often with additional processes for data fetching, resource provisioning, or reacting to external events. Workflow DevKit makes your agents production-ready, by turning your agents into durable, resumable workflows, and managing your LLM calls, tool executions, and other async operations as retryable and observable steps.
 
+<AgentTraces />
+
 This guide walks through converting a basic AI SDK agent into a durable agent using Workflow DevKit.
 
 ## Why Durable Agents?
diff --git a/docs/content/guides/ai-agents/resumable-streams.mdx b/docs/content/guides/ai-agents/resumable-streams.mdx
index 634edbd02..59aa79482 100644
--- a/docs/content/guides/ai-agents/resumable-streams.mdx
+++ b/docs/content/guides/ai-agents/resumable-streams.mdx
@@ -216,9 +216,9 @@ The transport automatically retries reconnection on network errors. After reachi
 
 ## Complete Example
 
-<Tabs items={['API Route', 'Reconnect Endpoint', 'Client']}>
+<Tabs items={['Chat Endpoint', 'Reconnect Endpoint', 'Client']}>
 
-<Tab value="API Route">
+<Tab value="Chat Endpoint">
 
 ```typescript title="app/api/chat/route.ts" lineNumbers
 import { createUIMessageStreamResponse, convertToModelMessages } from 'ai';

From 64d72657bd8b415078ae4dd9ba7dc07de23adb52 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 15:20:34 -0800
Subject: [PATCH 14/38] Polish

---
 docs/content/guides/ai-agents/index.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/content/guides/ai-agents/index.mdx b/docs/content/guides/ai-agents/index.mdx
index a2e12273f..72adbbe72 100644
--- a/docs/content/guides/ai-agents/index.mdx
+++ b/docs/content/guides/ai-agents/index.mdx
@@ -22,7 +22,7 @@ Workflow DevKit provides all of these capabilities out of the box. Your agent be
 ## Getting Started
 
 We start out with a basic Next.js application using the AI SDK's `Agent` class,
-which is a simple wrapper around AI SDK's `streamText` function. It comes with a basic tool for reading web pages.
+which is a simple wrapper around AI SDK's `streamText` function. It comes with a simple tool for reading web pages.
 
 <Tabs items={['API Route', 'Tools', 'Client']}>
 

From afdb0b196f0d832dff93740d28c72927ac81c121 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 15:31:34 -0800
Subject: [PATCH 15/38] Package install polish

---
 docs/content/guides/ai-agents/index.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/content/guides/ai-agents/index.mdx b/docs/content/guides/ai-agents/index.mdx
index 72adbbe72..8452267d2 100644
--- a/docs/content/guides/ai-agents/index.mdx
+++ b/docs/content/guides/ai-agents/index.mdx
@@ -122,8 +122,8 @@ export function Chat() {
 
 Add the Workflow DevKit packages to your project:
 
-```bash
-npm install workflow @workflow/ai
+```package-install
+npm i workflow @workflow/ai
 ```
 
 and extend the NextJS compiler to transform the code:

From 465c18d466ef30ec1df4a37e6345457deb58a457 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 15:52:30 -0800
Subject: [PATCH 16/38] CHanges

---
 .../guides/ai-agents/defining-tools.mdx       | 323 +++++++++++++++++
 .../guides/ai-agents/human-in-the-loop.mdx    | 324 +++++++++++++-----
 docs/content/guides/ai-agents/meta.json       |   1 +
 .../guides/ai-agents/sleep-and-delays.mdx     | 154 ++-------
 packages/ai/docs.md                           | 213 ++++++++++++
 5 files changed, 804 insertions(+), 211 deletions(-)
 create mode 100644 docs/content/guides/ai-agents/defining-tools.mdx
 create mode 100644 packages/ai/docs.md

diff --git a/docs/content/guides/ai-agents/defining-tools.mdx b/docs/content/guides/ai-agents/defining-tools.mdx
new file mode 100644
index 000000000..602db68ed
--- /dev/null
+++ b/docs/content/guides/ai-agents/defining-tools.mdx
@@ -0,0 +1,323 @@
+---
+title: Defining Tool Calls
+---
+
+Tools are the primary way AI agents interact with the outside world. In Workflow DevKit, tools can be implemented as workflow steps for automatic retries and persistence, or they can use workflow-level primitives like `sleep()` and webhooks. This guide covers the patterns and best practices for defining tools in durable agents.
+
+## Tool Structure
+
+Every tool has three key parts:
+
+1. **Input Schema** - A Zod schema defining what the LLM can pass to the tool
+2. **Description** - A natural language description helping the LLM decide when to use the tool
+3. **Execute Function** - The logic that runs when the tool is called
+
+```typescript title="ai/tools/search-web.ts" lineNumbers
+import { tool } from 'ai';
+import { z } from 'zod';
+
+export const searchWeb = tool({
+  description: 'Search the web for information',
+  inputSchema: z.object({
+    query: z.string().describe('The search query'),
+    maxResults: z.number().optional().describe('Maximum number of results'),
+  }),
+  execute: async ({ query, maxResults = 5 }) => {
+    // Tool implementation
+    return { results: [] };
+  },
+});
+```
+
+## The Execute Function Context
+
+The execute function receives two arguments:
+
+1. **Input** - The validated input matching your schema
+2. **Options** - Context about the tool call, including:
+   - `toolCallId` - Unique identifier for this invocation
+   - `messages` - The conversation history up to and including this tool call
+
+```typescript lineNumbers
+execute: async (input, options) => {
+  const { toolCallId, messages } = options;
+  
+  // toolCallId: Use for correlating stream chunks with this tool call
+  // messages: Access the full conversation context
+  
+  return result;
+}
+```
+
+## Accessing Conversation Messages
+
+Tools can access the full conversation history through the `messages` option. This is useful when your tool needs context about what was discussed:
+
+```typescript title="ai/tools/summarize-conversation.ts" lineNumbers
+import { tool } from 'ai';
+import { z } from 'zod';
+
+export const summarizeConversation = tool({
+  description: 'Summarize the conversation so far',
+  inputSchema: z.object({
+    focus: z.string().optional().describe('What aspect to focus on'),
+  }),
+  execute: async ({ focus }, { messages }) => { // [!code highlight]
+    // messages contains the full LanguageModelV2Prompt
+    const userMessages = messages
+      .filter(m => m.role === 'user')
+      .map(m => {
+        // Extract text content from the message
+        const textParts = m.content
+          .filter(p => p.type === 'text')
+          .map(p => p.text);
+        return textParts.join(' ');
+      });
+
+    // Use the conversation context in your tool logic
+    return {
+      messageCount: messages.length,
+      userMessageCount: userMessages.length,
+      summary: `Conversation about: ${userMessages.slice(-3).join(', ')}`,
+    };
+  },
+});
+```
+
+The messages follow the `LanguageModelV2Prompt` format from the AI SDK, which includes:
+- User messages with text and file content
+- Assistant messages with text and tool calls
+- Tool result messages from previous tool executions
+
+## Streaming from Tools
+
+Tools can emit real-time updates to the UI by writing to the workflow's output stream. This must be done within a step function:
+
+<Steps>
+
+<Step>
+### Create a Step for Stream Writes
+
+Since `getWritable()` requires the step context, create a separate step function for emitting chunks:
+
+```typescript lineNumbers
+import { getWritable } from 'workflow';
+import type { UIMessageChunk } from 'ai';
+
+async function emitProgress(
+  { status, url }: { status: string; url?: string },
+  { toolCallId }: { toolCallId: string }
+) {
+  'use step'; // [!code highlight]
+
+  const writable = getWritable<UIMessageChunk>();
+  const writer = writable.getWriter();
+
+  await writer.write({
+    id: toolCallId,
+    type: 'data-status',
+    data: { status, url },
+  });
+
+  writer.releaseLock();
+}
+```
+</Step>
+
+<Step>
+### Call from the Execute Function
+
+The execute function can call this step to emit progress:
+
+```typescript lineNumbers
+async function executeSearchWeb(
+  { query }: { query: string },
+  { toolCallId }: { toolCallId: string }
+) {
+  await emitProgress({ status: 'searching', url: query }, { toolCallId }); // [!code highlight]
+
+  const results = await performSearch(query);
+
+  await emitProgress({ status: 'complete' }, { toolCallId }); // [!code highlight]
+
+  return results;
+}
+```
+</Step>
+
+</Steps>
+
+### Why Separate Steps?
+
+The `getWritable()` function is only available within steps, not at the workflow level. This is because:
+
+1. Steps provide the transactional boundary for stream writes
+2. Each step's writes are persisted and can be replayed on recovery
+3. The workflow context handles orchestration, not I/O
+
+## Workflow-Level vs Step-Level Tools
+
+Tools can run at two levels, with different capabilities:
+
+### Step-Level Tools
+
+When your execute function uses `"use step"`, the entire tool runs as a retryable step:
+
+```typescript lineNumbers
+async function executeWithRetries({ data }: { data: string }) {
+  'use step'; // [!code highlight]
+
+  // ✅ Can use getWritable()
+  // ✅ Automatic retries on transient failures
+  // ✅ Results persisted in event log
+  // ❌ Cannot call sleep() or createWebhook()
+
+  const result = await fetch(`https://api.example.com?q=${data}`);
+  return result.json();
+}
+```
+
+### Workflow-Level Tools
+
+When your execute function does NOT use `"use step"`, it runs in the workflow context:
+
+```typescript lineNumbers
+async function executeWithPause({ duration }: { duration: number }) {
+  // No "use step" - runs at workflow level // [!code highlight]
+
+  // ❌ Cannot use getWritable() directly
+  // ✅ Can call sleep()
+  // ✅ Can call createWebhook()
+  // ✅ Can call step functions
+
+  await reportStatus('pausing'); // Step function for streaming
+  await sleep(duration);         // Workflow-level function
+
+  return 'Resumed after pause';
+}
+```
+
+### Combining Both Levels
+
+Most tools combine both approaches - use step functions for I/O and retryable operations, while keeping the execute function at the workflow level for orchestration:
+
+```typescript title="ai/tools/fetch-with-progress.ts" lineNumbers
+import { tool } from 'ai';
+import { getWritable, sleep } from 'workflow';
+import { z } from 'zod';
+import type { UIMessageChunk } from 'ai';
+
+// Step function: handles streaming
+async function emitFetchStatus(
+  { url, status }: { url: string; status: 'fetching' | 'complete' | 'retrying' },
+  { toolCallId }: { toolCallId: string }
+) {
+  'use step';
+
+  const writable = getWritable<UIMessageChunk>();
+  const writer = writable.getWriter();
+
+  await writer.write({
+    id: toolCallId,
+    type: 'data-fetch-status',
+    data: { url, status },
+  });
+
+  writer.releaseLock();
+}
+
+// Step function: handles the actual fetch with retries
+async function performFetch(url: string) {
+  'use step';
+
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Fetch failed: ${response.status}`);
+  }
+  return response.json();
+}
+
+// Workflow-level execute: orchestrates steps
+async function executeFetchWithProgress(
+  { url }: { url: string },
+  { toolCallId }: { toolCallId: string }
+) {
+  await emitFetchStatus({ url, status: 'fetching' }, { toolCallId });
+
+  const result = await performFetch(url);
+
+  await emitFetchStatus({ url, status: 'complete' }, { toolCallId });
+
+  return result;
+}
+
+export const fetchWithProgress = tool({
+  description: 'Fetch a URL and report progress',
+  inputSchema: z.object({
+    url: z.string().url(),
+  }),
+  execute: executeFetchWithProgress,
+});
+```
+
+## Custom Data Chunk Types
+
+When emitting data chunks, use descriptive type names that your UI can handle:
+
+```typescript lineNumbers
+// In your tool
+await writer.write({
+  id: toolCallId,
+  type: 'data-run-command',  // Custom type
+  data: { 
+    command: 'npm install',
+    cwd: '/project',
+  },
+});
+
+await writer.write({
+  id: toolCallId,
+  type: 'data-file-created',  // Another custom type
+  data: { 
+    path: '/project/package.json',
+    size: 1234,
+  },
+});
+```
+
+The UI handles these custom types by checking the part type:
+
+```typescript title="components/chat.tsx" lineNumbers
+{messages.map((m) => (
+  <div key={m.id}>
+    {m.parts.map((part, i) => {
+      if (part.type === 'text') {
+        return <span key={i}>{part.text}</span>;
+      }
+      if (part.type === 'data-run-command') {
+        return (
+          <div key={i} className="terminal">
+            $ {part.data.command}
+          </div>
+        );
+      }
+      if (part.type === 'data-file-created') {
+        return (
+          <div key={i} className="file-badge">
+            Created: {part.data.path}
+          </div>
+        );
+      }
+      return null;
+    })}
+  </div>
+))}
+```
+
+## Related Documentation
+
+- [Building Durable AI Agents](/guides/ai-agents) - Getting started with durable agents
+- [Streaming](/docs/foundations/streaming) - How streaming works in Workflow DevKit
+- [Workflows and Steps](/docs/foundations/workflows-and-steps) - Understanding the execution model
+- [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Complete API documentation
+
diff --git a/docs/content/guides/ai-agents/human-in-the-loop.mdx b/docs/content/guides/ai-agents/human-in-the-loop.mdx
index 834984505..f7b6fd82b 100644
--- a/docs/content/guides/ai-agents/human-in-the-loop.mdx
+++ b/docs/content/guides/ai-agents/human-in-the-loop.mdx
@@ -4,14 +4,49 @@ title: Human-in-the-Loop
 
 Some agent actions require human approval before proceeding - deploying to production, sending emails to customers, or making financial transactions. Workflow DevKit's webhook and hook primitives enable "human-in-the-loop" patterns where workflows pause until a human takes action.
 
+## How It Works
+
+<Steps>
+
+<Step>
+The agent calls a tool (like `humanApproval`) with a message describing what needs approval.
+</Step>
+
+<Step>
+`createWebhook()` generates a unique URL that can resume the workflow.
+</Step>
+
+<Step>
+The tool emits a data chunk containing the approval URL to the UI.
+</Step>
+
+<Step>
+The workflow pauses at `await webhook` - no compute resources are consumed.
+</Step>
+
+<Step>
+When a human clicks approve/reject and the webhook URL is called, the workflow resumes.
+</Step>
+
+<Step>
+The tool receives any data sent with the webhook (approval status, comments) and returns.
+</Step>
+
+</Steps>
+
 ## Creating an Approval Tool
 
 Add a tool that pauses the agent until a human approves or rejects:
 
+<Steps>
+
+<Step>
+### Create the Emit Helper
+
+First, create a step function to emit the approval request to the UI:
+
 ```typescript title="ai/tools/human-approval.ts" lineNumbers
-import { tool } from 'ai';
-import { createWebhook, getWritable } from 'workflow'; // [!code highlight]
-import { z } from 'zod';
+import { getWritable } from 'workflow';
 import type { UIMessageChunk } from 'ai';
 
 async function emitApprovalRequest(
@@ -31,6 +66,18 @@ async function emitApprovalRequest(
 
   writer.releaseLock();
 }
+```
+</Step>
+
+<Step>
+### Implement the Execute Function
+
+The execute function creates a webhook and waits for approval:
+
+```typescript title="ai/tools/human-approval.ts" lineNumbers
+import { tool } from 'ai';
+import { createWebhook } from 'workflow'; // [!code highlight]
+import { z } from 'zod';
 
 async function executeHumanApproval(
   { message }: { message: string },
@@ -47,9 +94,14 @@ async function executeHumanApproval(
   );
 
   // Workflow pauses here until the webhook is called // [!code highlight]
-  await webhook; // [!code highlight]
+  const request = await webhook; // [!code highlight]
+  const { approved, comment } = await request.json(); // [!code highlight]
 
-  return 'Approval received. Proceeding with action.';
+  if (!approved) {
+    return `Action rejected: ${comment || 'No reason provided'}`;
+  }
+
+  return `Approved${comment ? ` with comment: ${comment}` : ''}`;
 }
 
 export const humanApproval = tool({
@@ -64,104 +116,149 @@ export const humanApproval = tool({
 <Callout type="info">
 The `createWebhook()` function must be called from within a workflow context, not from a step. This is why `executeHumanApproval` does not have `"use step"`.
 </Callout>
+</Step>
 
-## How It Works
-
-1. The agent calls the `humanApproval` tool with a message describing what needs approval
-2. `createWebhook()` generates a unique URL that can resume the workflow
-3. The tool emits a data chunk containing the approval URL to the UI
-4. The workflow pauses at `await webhook` - no compute resources are consumed
-5. When a human visits the webhook URL, the workflow resumes
-6. The tool returns and the agent continues with the approved action
+</Steps>
 
 ## Handling the Approval UI
 
-The UI receives a data chunk with type `data-approval-required`. Display an approval button that triggers the webhook:
+The UI receives a data chunk with type `data-approval-required`. Build a component that displays the approval request and handles the user's decision:
+
+<Steps>
+
+<Step>
+### Create the Approval Component
 
 ```typescript title="components/approval-button.tsx" lineNumbers
 'use client';
 
+import { useState } from 'react';
+
 interface ApprovalData {
   url: string;
   message: string;
 }
 
 export function ApprovalButton({ data }: { data: ApprovalData }) {
-  const handleApprove = async () => {
-    await fetch(data.url, { method: 'POST' });
+  const [comment, setComment] = useState('');
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [isComplete, setIsComplete] = useState(false);
+
+  const handleSubmit = async (approved: boolean) => {
+    setIsSubmitting(true);
+    try {
+      await fetch(data.url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ approved, comment }),
+      });
+      setIsComplete(true);
+    } finally {
+      setIsSubmitting(false);
+    }
   };
 
+  if (isComplete) {
+    return <div className="text-muted-foreground">Response submitted</div>;
+  }
+
   return (
-    <div>
-      <p>{data.message}</p>
-      <button onClick={handleApprove}>Approve</button>
+    <div className="border rounded-lg p-4 space-y-4">
+      <p className="font-medium">{data.message}</p>
+
+      <textarea
+        value={comment}
+        onChange={(e) => setComment(e.target.value)}
+        placeholder="Add a comment (optional)..."
+        className="w-full border rounded p-2 text-sm"
+        rows={2}
+      />
+
+      <div className="flex gap-2">
+        <button
+          onClick={() => handleSubmit(true)}
+          disabled={isSubmitting}
+          className="px-4 py-2 bg-green-600 text-white rounded hover:bg-green-700 disabled:opacity-50"
+        >
+          {isSubmitting ? 'Submitting...' : 'Approve'}
+        </button>
+        <button
+          onClick={() => handleSubmit(false)}
+          disabled={isSubmitting}
+          className="px-4 py-2 bg-red-600 text-white rounded hover:bg-red-700 disabled:opacity-50"
+        >
+          {isSubmitting ? 'Submitting...' : 'Reject'}
+        </button>
+      </div>
     </div>
   );
 }
 ```
+</Step>
 
-## Receiving Approval Data
+<Step>
+### Render in Your Chat
 
-To receive data from the approval action (such as approve/reject status or comments), read the webhook request body:
+Handle the custom data chunk type in your message renderer:
 
-```typescript title="ai/tools/human-approval.ts" lineNumbers
-async function executeHumanApproval(
-  { message }: { message: string },
-  { toolCallId }: { toolCallId: string }
-) {
-  const webhook = createWebhook();
+```typescript title="components/chat.tsx" lineNumbers
+import { ApprovalButton } from './approval-button';
 
-  await emitApprovalRequest({ url: webhook.url, message }, { toolCallId });
+// Inside your message rendering:
+{m.parts.map((part, i) => {
+  if (part.type === 'text') {
+    return <span key={i}>{part.text}</span>;
+  }
+  if (part.type === 'data-approval-required') {
+    return <ApprovalButton key={i} data={part.data} />;
+  }
+  return null;
+})}
+```
+</Step>
 
-  const request = await webhook; // [!code highlight]
-  const { approved, comment } = await request.json(); // [!code highlight]
+</Steps>
 
-  if (!approved) {
-    return `Action rejected: ${comment}`;
-  }
+## Programmatic Hook Resumption
 
-  return `Approved with comment: ${comment}`;
-}
-```
+For scenarios where you need your backend code to resume a workflow (not just UI interactions), or when you want type-safe validation of approval data, use [`defineHook()`](/docs/api-reference/workflow/define-hook). This approach is useful for:
 
-The UI sends the approval data in the request body:
+- Backend services that need to approve/reject based on business logic
+- External systems that call your API to resume workflows
+- Type-safe validation of approval data with Zod schemas
 
-```typescript lineNumbers
-const handleApprove = async () => {
-  await fetch(data.url, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ approved: true, comment: 'Looks good!' }),
-  });
-};
+<Tabs items={['Hook Definition', 'Tool Implementation', 'API Route']}>
 
-const handleReject = async () => {
-  await fetch(data.url, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ approved: false, comment: 'Not ready yet' }),
-  });
-};
+<Tab value="Hook Definition">
+
+Define a typed hook with a Zod schema for validation:
+
+```typescript title="ai/hooks/deployment-approval.ts" lineNumbers
+import { defineHook } from 'workflow';
+import { z } from 'zod';
+
+// Export the hook so it can be used in both the tool and API routes
+export const deploymentApprovalHook = defineHook({
+  schema: z.object({
+    approved: z.boolean(),
+    approvedBy: z.string(),
+    environment: z.enum(['staging', 'production']),
+    notes: z.string().optional(),
+  }),
+});
 ```
+</Tab>
 
-## Using Hooks for Type-Safe Approvals
+<Tab value="Tool Implementation">
 
-For stronger type safety, use [`defineHook()`](/docs/api-reference/workflow/define-hook) with a schema:
+Use the hook in your tool instead of `createWebhook()`:
 
 ```typescript title="ai/tools/deployment-approval.ts" lineNumbers
 import { tool } from 'ai';
-import { defineHook, getWritable } from 'workflow';
+import { getWritable } from 'workflow';
 import { z } from 'zod';
 import type { UIMessageChunk } from 'ai';
-
-// Define a typed hook for deployment approvals
-const deploymentApprovalHook = defineHook({ // [!code highlight]
-  schema: z.object({ // [!code highlight]
-    approved: z.boolean(), // [!code highlight]
-    approvedBy: z.string(), // [!code highlight]
-    environment: z.enum(['staging', 'production']), // [!code highlight]
-  }), // [!code highlight]
-}); // [!code highlight]
+import { deploymentApprovalHook } from '../hooks/deployment-approval';
 
 async function emitDeploymentApproval(
   token: string,
@@ -207,22 +304,26 @@ export const deploymentApproval = tool({
   execute: executeDeploymentApproval,
 });
 ```
+</Tab>
+
+<Tab value="API Route">
 
-Resume the hook from your approval API:
+Resume the hook from your backend API:
 
 ```typescript title="app/api/approve-deployment/route.ts" lineNumbers
-import { deploymentApprovalHook } from '@/ai/tools/deployment-approval';
+import { deploymentApprovalHook } from '@/ai/hooks/deployment-approval';
 
 export async function POST(request: Request) {
-  const { token, approved, approvedBy, environment } = await request.json();
+  const { token, approved, approvedBy, environment, notes } = await request.json();
 
   try {
     // Schema validation happens automatically // [!code highlight]
     await deploymentApprovalHook.resume(token, { // [!code highlight]
-      approved, // [!code highlight]
-      approvedBy, // [!code highlight]
-      environment, // [!code highlight]
-    }); // [!code highlight]
+      approved,
+      approvedBy,
+      environment,
+      notes,
+    });
 
     return Response.json({ success: true });
   } catch (error) {
@@ -234,6 +335,14 @@ export async function POST(request: Request) {
 }
 ```
 
+This API can be called by:
+- Your UI components (passing the token from the data chunk)
+- Backend services that need to programmatically approve/reject
+- External systems via API integration
+</Tab>
+
+</Tabs>
+
 ## Use Cases
 
 ### Email Approval
@@ -301,7 +410,7 @@ export async function criticalActionWorkflow(action: string) {
 
 ## Complete Example
 
-A human approval tool with UI component:
+A full human approval implementation with tool and UI component:
 
 <Tabs items={['Tool', 'UI Component']}>
 
@@ -335,7 +444,6 @@ async function executeHumanApproval(
   { message }: { message: string },
   { toolCallId }: { toolCallId: string }
 ) {
-  // No "use step" - webhooks are workflow-level primitives
   const webhook = createWebhook();
 
   await emitApprovalRequest({ url: webhook.url, message }, { toolCallId });
@@ -344,10 +452,10 @@ async function executeHumanApproval(
   const { approved, comment } = await request.json();
 
   if (!approved) {
-    return `Action rejected: ${comment}`;
+    return `Action rejected${comment ? `: ${comment}` : ''}`;
   }
 
-  return `Approved with comment: ${comment}`;
+  return `Approved${comment ? ` with comment: ${comment}` : ''}`;
 }
 
 export const humanApproval = tool({
@@ -366,33 +474,64 @@ export const humanApproval = tool({
 ```typescript title="components/approval-button.tsx" lineNumbers
 'use client';
 
+import { useState } from 'react';
+
 interface ApprovalData {
   url: string;
   message: string;
 }
 
 export function ApprovalButton({ data }: { data: ApprovalData }) {
-  const handleApprove = async () => {
-    await fetch(data.url, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ approved: true, comment: 'Approved' }),
-    });
+  const [comment, setComment] = useState('');
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [isComplete, setIsComplete] = useState(false);
+
+  const handleSubmit = async (approved: boolean) => {
+    setIsSubmitting(true);
+    try {
+      await fetch(data.url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ approved, comment }),
+      });
+      setIsComplete(true);
+    } finally {
+      setIsSubmitting(false);
+    }
   };
 
-  const handleReject = async () => {
-    await fetch(data.url, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ approved: false, comment: 'Rejected' }),
-    });
-  };
+  if (isComplete) {
+    return <div className="text-muted-foreground">Response submitted</div>;
+  }
 
   return (
-    <div>
-      <p>{data.message}</p>
-      <button onClick={handleApprove}>Approve</button>
-      <button onClick={handleReject}>Reject</button>
+    <div className="border rounded-lg p-4 space-y-4">
+      <p className="font-medium">{data.message}</p>
+
+      <textarea
+        value={comment}
+        onChange={(e) => setComment(e.target.value)}
+        placeholder="Add a comment (optional)..."
+        className="w-full border rounded p-2 text-sm"
+        rows={2}
+      />
+
+      <div className="flex gap-2">
+        <button
+          onClick={() => handleSubmit(true)}
+          disabled={isSubmitting}
+          className="px-4 py-2 bg-green-600 text-white rounded hover:bg-green-700 disabled:opacity-50"
+        >
+          {isSubmitting ? 'Submitting...' : 'Approve'}
+        </button>
+        <button
+          onClick={() => handleSubmit(false)}
+          disabled={isSubmitting}
+          className="px-4 py-2 bg-red-600 text-white rounded hover:bg-red-700 disabled:opacity-50"
+        >
+          {isSubmitting ? 'Submitting...' : 'Reject'}
+        </button>
+      </div>
     </div>
   );
 }
@@ -407,4 +546,3 @@ export function ApprovalButton({ data }: { data: ApprovalData }) {
 - [Hooks & Webhooks](/docs/foundations/hooks) - Complete guide to hooks and webhooks
 - [`createWebhook()` API Reference](/docs/api-reference/workflow/create-webhook) - Webhook configuration options
 - [`defineHook()` API Reference](/docs/api-reference/workflow/define-hook) - Type-safe hook definitions
-
diff --git a/docs/content/guides/ai-agents/meta.json b/docs/content/guides/ai-agents/meta.json
index 3595e6aeb..8809538fe 100644
--- a/docs/content/guides/ai-agents/meta.json
+++ b/docs/content/guides/ai-agents/meta.json
@@ -2,6 +2,7 @@
   "title": "AI Agents",
   "pages": [
     "index",
+    "defining-tools",
     "resumable-streams",
     "sleep-and-delays",
     "human-in-the-loop"
diff --git a/docs/content/guides/ai-agents/sleep-and-delays.mdx b/docs/content/guides/ai-agents/sleep-and-delays.mdx
index 5c816c1a1..d3470febe 100644
--- a/docs/content/guides/ai-agents/sleep-and-delays.mdx
+++ b/docs/content/guides/ai-agents/sleep-and-delays.mdx
@@ -1,13 +1,23 @@
 ---
-title: Sleep and Delays
+title: Sleep, Suspense, and Scheduling
 ---
 
-AI agents sometimes need to pause execution - waiting before retrying an operation, implementing rate limiting, or scheduling future actions. Workflow DevKit's [`sleep()`](/docs/api-reference/workflow/sleep) function enables time-based delays without consuming compute resources.
+AI agents sometimes need to pause execution in order to schedule recurring or future actions, wait before retrying an operation (e.g. for rate limiting), or wait for external state to be available. Workflow DevKit's [`sleep()`](/docs/api-reference/workflow/sleep) function enables Agents to pause execution without consuming compute resources, and resume at specified times.
+This sleep operation survives restarts, deploys, and infrastructure changes, and the duration can span seconds, hours, days, or months.
+
+<Callout type="info">
+See the [`sleep()` API Reference](/docs/api-reference/workflow/sleep) for the full list of supported duration formats and detailed API documentation.
+</Callout>
 
 ## Adding a Sleep Tool
 
 Create a tool that allows the agent to pause for a specified duration:
 
+<Steps>
+
+<Step>
+### Define the Tool
+
 ```typescript title="ai/tools/sleep.ts" lineNumbers
 import { tool } from 'ai';
 import { getWritable, sleep } from 'workflow'; // [!code highlight]
@@ -57,52 +67,26 @@ export const sleepTool = tool({
 });
 ```
 
-<Callout type="info">
-The `sleep()` function must be called from within a workflow context, not from within a step. This is why `executeSleep` does not have `"use step"` - it runs in the workflow context where `sleep()` is available.
-</Callout>
-
-## How Sleep Works
-
-When `sleep()` is called:
-
-1. The workflow records the wake-up time in the event log
-2. The workflow suspends, releasing all compute resources
-3. At the specified time, the workflow resumes execution
+</Step>
 
-This differs from `setTimeout` or `await new Promise(resolve => setTimeout(resolve, ms))`:
-- No compute resources are consumed during the sleep
-- The workflow survives restarts, deploys, and infrastructure changes
-- Sleep durations can span hours, days, or months
+<Step>
+### Understand the Context Requirement
 
-## Duration Formats
+The `sleep()` function must be called from within a workflow context, not from within a step. This is why `executeSleep` does not have `"use step"` - it runs in the workflow context where `sleep()` is available.
+</Step>
 
-The `sleep()` function accepts multiple duration formats:
-
-```typescript lineNumbers
-// Milliseconds (number)
-await sleep(5000);
-
-// Duration strings
-await sleep('30s');      // 30 seconds
-await sleep('5m');       // 5 minutes
-await sleep('2h');       // 2 hours
-await sleep('1d');       // 1 day
-await sleep('1 month');  // 1 month
-
-// Date instance
-await sleep(new Date('2025-12-31T23:59:59Z'));
-```
+</Steps>
 
 ## Emitting Progress Updates
 
 When sleeping for long durations, emit a progress update so the UI can display the waiting state:
 
-```typescript title="ai/tools/schedule-task.ts" lineNumbers
-import { tool } from 'ai';
-import { getWritable, sleep } from 'workflow';
-import { z } from 'zod';
-import type { UIMessageChunk } from 'ai';
+<Steps>
+
+<Step>
+### Create an Emit Helper
 
+```typescript lineNumbers
 async function emitWaitingStatus(message: string, toolCallId: string) {
   'use step';
 
@@ -117,7 +101,14 @@ async function emitWaitingStatus(message: string, toolCallId: string) {
 
   writer.releaseLock();
 }
+```
 
+</Step>
+
+<Step>
+### Use in Tool Execution
+
+```typescript lineNumbers
 async function executeScheduleTask(
   { delayMinutes, taskName }: { delayMinutes: number; taskName: string },
   { toolCallId }: { toolCallId: string }
@@ -131,22 +122,17 @@ async function executeScheduleTask(
 
   return `Task "${taskName}" is now ready to execute`;
 }
-
-export const scheduleTask = tool({
-  description: 'Schedule a task to run after a delay',
-  inputSchema: z.object({
-    delayMinutes: z.number(),
-    taskName: z.string(),
-  }),
-  execute: executeScheduleTask,
-});
 ```
 
+</Step>
+
+</Steps>
+
 ## Use Cases
 
 ### Rate Limiting
 
-When hitting API rate limits, sleep before retrying:
+When hitting API rate limits, use `RetryableError` with a delay:
 
 ```typescript lineNumbers
 async function callRateLimitedAPI(endpoint: string) {
@@ -165,21 +151,6 @@ async function callRateLimitedAPI(endpoint: string) {
 }
 ```
 
-### Scheduled Notifications
-
-Send a reminder after a delay:
-
-```typescript lineNumbers
-async function executeReminder(
-  { message, delayHours }: { message: string; delayHours: number }
-) {
-  await sleep(`${delayHours}h`);
-  await sendNotification(message);
-
-  return `Reminder sent: ${message}`;
-}
-```
-
 ### Polling with Backoff
 
 Poll for a result with increasing delays:
@@ -211,61 +182,8 @@ async function checkJobStatus(jobId: string) {
 }
 ```
 
-## Complete Example
-
-A sleep tool that pauses the agent for a specified duration:
-
-```typescript title="ai/tools/sleep.ts" lineNumbers
-import { tool } from 'ai';
-import { getWritable, sleep } from 'workflow';
-import { z } from 'zod';
-import type { UIMessageChunk } from 'ai';
-
-const inputSchema = z.object({
-  durationMs: z.number().describe('Duration to sleep in milliseconds'),
-});
-
-async function reportSleep(
-  { durationMs }: { durationMs: number },
-  { toolCallId }: { toolCallId: string }
-) {
-  'use step';
-
-  const writable = getWritable<UIMessageChunk>();
-  const writer = writable.getWriter();
-
-  const seconds = Math.ceil(durationMs / 1000);
-
-  await writer.write({
-    id: toolCallId,
-    type: 'data-wait',
-    data: { text: `Sleeping for ${seconds} seconds` },
-  });
-
-  writer.releaseLock();
-}
-
-async function executeSleep(
-  { durationMs }: z.infer<typeof inputSchema>,
-  { toolCallId }: { toolCallId: string }
-) {
-  // No "use step" - sleep is a workflow-level function
-  await reportSleep({ durationMs }, { toolCallId });
-  await sleep(durationMs);
-
-  return `Slept for ${durationMs}ms`;
-}
-
-export const sleepTool = tool({
-  description: 'Pause execution for a specified duration',
-  inputSchema,
-  execute: executeSleep,
-});
-```
-
 ## Related Documentation
 
-- [`sleep()` API Reference](/docs/api-reference/workflow/sleep) - Full API documentation
+- [`sleep()` API Reference](/docs/api-reference/workflow/sleep) - Full API documentation with all duration formats
 - [Workflows and Steps](/docs/foundations/workflows-and-steps) - Understanding workflow context
 - [Errors and Retries](/docs/foundations/errors-and-retries) - Using `RetryableError` with delays
-
diff --git a/packages/ai/docs.md b/packages/ai/docs.md
new file mode 100644
index 000000000..887bae54a
--- /dev/null
+++ b/packages/ai/docs.md
@@ -0,0 +1,213 @@
+# DurableAgent Architecture and State Propagation
+
+This document explains how `DurableAgent` integrates with Workflow DevKit, how state is stored and propagated between workflow and tool call steps.
+
+## Overview
+
+`DurableAgent` is a class for building AI-powered agents within workflows. It enables AI agents to:
+
+- Maintain state across workflow steps
+- Call tools with automatic retries
+- Handle interruptions and resumptions gracefully
+
+## Core Components
+
+### 1. DurableAgent (`durable-agent.ts`)
+
+The main orchestrator that:
+
+- Accepts a model, tools, and system prompt
+- Manages the conversation loop via `stream()` method
+- Delegates LLM streaming to `streamTextIterator`
+- Executes tools when the model makes tool calls
+
+### 2. StreamTextIterator (`stream-text-iterator.ts`)
+
+An async generator that:
+
+- Maintains the `conversationPrompt` (message history as `LanguageModelV2Prompt`)
+- Calls `doStreamStep` to stream LLM responses
+- Yields tool calls when the model requests them
+- Receives tool results and adds them to the conversation
+- Returns the final conversation when done
+
+### 3. DoStreamStep (`do-stream-step.ts`)
+
+A workflow step function (marked with `"use step"`) that:
+
+- Initializes the language model
+- Calls `model.doStream()` with the conversation prompt
+- Transforms LLM stream chunks to `UIMessageChunk` format
+- Writes chunks to the writable stream
+- Returns tool calls and finish reason
+
+## State Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                          DurableAgent.stream()                          │
+│                         (Workflow Context)                              │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         streamTextIterator()                            │
+│                         (Workflow Context)                              │
+│                                                                         │
+│   ┌─────────────────────────────────────────────────────────────────┐   │
+│   │  conversationPrompt: LanguageModelV2Prompt                      │   │
+│   │  - Mutable copy of the initial prompt                           │   │
+│   │  - Grows as assistant/tool messages are added                   │   │
+│   └─────────────────────────────────────────────────────────────────┘   │
+│                                    │                                    │
+│                                    ▼                                    │
+│   ┌───────────────────────────────────────────────────────────────┐     │
+│   │              while (!done) loop                                │     │
+│   │                                                                │     │
+│   │   1. Call doStreamStep() with conversationPrompt              │     │
+│   │      (This is a "use step" function - runs in step runtime)   │     │
+│   │                                                                │     │
+│   │   2. If finish reason is "tool-calls":                        │     │
+│   │      - Add assistant message with tool calls to prompt        │     │
+│   │      - yield toolCalls (pause, wait for tool results)         │     │
+│   │      - Receive toolResults from DurableAgent                  │     │
+│   │      - Add tool message with results to prompt                │     │
+│   │      - Check stop conditions                                  │     │
+│   │                                                                │     │
+│   │   3. If finish reason is "stop":                              │     │
+│   │      - Add final assistant message to prompt                  │     │
+│   │      - Set done = true                                        │     │
+│   └───────────────────────────────────────────────────────────────┘     │
+│                                    │                                    │
+│                                    ▼                                    │
+│   return conversationPrompt (final message history)                     │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+         ┌──────────────────────────┼──────────────────────────┐
+         │                          │                          │
+         ▼                          ▼                          ▼
+┌─────────────────┐    ┌─────────────────────┐    ┌─────────────────┐
+│   executeTool   │    │    executeTool      │    │   executeTool   │
+│   (tool #1)     │    │    (tool #2)        │    │   (tool #n)     │
+│                 │    │                     │    │                 │
+│ tool.execute(   │    │ tool.execute(       │    │ tool.execute(   │
+│   input,        │    │   input,            │    │   input,        │
+│   {             │    │   {                 │    │   {             │
+│     toolCallId, │    │     toolCallId,     │    │     toolCallId, │
+│     messages,   │◄───│     messages,       │◄───│     messages,   │
+│   }             │    │   }                 │    │   }             │
+│ )               │    │ )                   │    │ )               │
+└─────────────────┘    └─────────────────────┘    └─────────────────┘
+         │                          │                          │
+         └──────────────────────────┼──────────────────────────┘
+                                    │
+                                    ▼
+                          Tool Results returned
+                          to streamTextIterator
+```
+
+## State Propagation
+
+### Message History Flow
+
+1. **Initial Messages**: User provides `messages` to `agent.stream()`
+2. **Prompt Standardization**: Messages are converted to `LanguageModelV2Prompt` format
+3. **Iterator Maintains State**: `streamTextIterator` keeps a mutable `conversationPrompt`
+4. **LLM Responses Added**: After each LLM call, assistant messages are appended
+5. **Tool Results Added**: After tool execution, tool messages with results are appended
+6. **Final Return**: The complete conversation history is returned from `stream()`
+
+### Message Format
+
+The internal format is `LanguageModelV2Prompt`, an array of messages with roles:
+
+- `system`: System prompt (if provided)
+- `user`: User messages with text/image content
+- `assistant`: Model responses, including tool call requests
+- `tool`: Tool execution results
+
+### The Messages Problem (This TODO)
+
+When a tool's `execute` function is called, the AI SDK expects to receive the conversation history so tools can have context about what led to the tool call:
+
+```typescript
+tool.execute(input, {
+  toolCallId: string,
+  messages: ModelMessage[],  // <-- The conversation history
+  abortSignal?: AbortSignal,
+})
+```
+
+**Current State**: `messages` is passed as an empty array `[]`
+**Desired State**: `messages` should contain the conversation history up to the point of the tool call
+
+## Implementation Details
+
+### Why Messages Matter for Tools
+
+Tools may need conversation context to:
+
+1. Understand the full request context
+2. Make decisions based on prior tool results
+3. Provide more accurate responses
+4. Implement conversation-aware functionality
+
+### Current Implementation Gap
+
+In `executeTool()`:
+
+```typescript
+const toolResult = await tool.execute(input.value, {
+  toolCallId: toolCall.toolCallId,
+  // TODO: pass the proper messages to the tool
+  messages: [],  // <-- Currently empty
+});
+```
+
+The challenge: `executeTool` doesn't have access to `conversationPrompt` because it's maintained inside `streamTextIterator`.
+
+### Solution Approach
+
+To fix this, we need to:
+
+1. Modify `streamTextIterator` to yield both tool calls AND the current messages
+2. Update `DurableAgent.stream()` to extract messages from the yield value
+3. Pass messages through to `executeTool()`
+
+## Workflow DevKit Integration
+
+### Step Functions
+
+`doStreamStep` is marked with `"use step"`, meaning:
+
+- It runs in the step runtime (full Node.js access)
+- Results are automatically persisted to the event log
+- Automatic retry on failures
+- Workflow suspends while step executes
+
+### Stream Handling
+
+- Streams (`WritableStream<UIMessageChunk>`) are serializable across workflow boundaries
+- The writable stream receives LLM response chunks in real-time
+- Tool outputs are also written to the stream for UI updates
+
+### Durability
+
+The workflow's event log stores:
+
+- Step function results (including LLM responses)
+- Tool execution results
+- Conversation state between invocations
+
+This enables:
+
+- Resume after failures
+- Replay for debugging
+- Long-running conversations that survive serverless timeouts
+
+## Related Files
+
+- `packages/ai/src/agent/durable-agent.ts` - Main DurableAgent class
+- `packages/ai/src/agent/stream-text-iterator.ts` - Async generator for LLM streaming
+- `packages/ai/src/agent/do-stream-step.ts` - Step function for LLM calls
+- `packages/ai/src/agent/tools-to-model-tools.ts` - Tool schema conversion

From 5dada9187b0578c52d0bd463c733ac65a6c06395 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 16:07:46 -0800
Subject: [PATCH 17/38] Human in the loop polish

---
 .../guides/ai-agents/human-in-the-loop.mdx    | 218 +++---------------
 1 file changed, 36 insertions(+), 182 deletions(-)

diff --git a/docs/content/guides/ai-agents/human-in-the-loop.mdx b/docs/content/guides/ai-agents/human-in-the-loop.mdx
index f7b6fd82b..19ec00858 100644
--- a/docs/content/guides/ai-agents/human-in-the-loop.mdx
+++ b/docs/content/guides/ai-agents/human-in-the-loop.mdx
@@ -2,22 +2,20 @@
 title: Human-in-the-Loop
 ---
 
-Some agent actions require human approval before proceeding - deploying to production, sending emails to customers, or making financial transactions. Workflow DevKit's webhook and hook primitives enable "human-in-the-loop" patterns where workflows pause until a human takes action.
+An extremely common feature necessary for running AI agents in production is the ability to wait for human input or external events before proceeding.
+
+Workflow DevKit's webhook and hook primitives enable "human-in-the-loop" patterns where workflows pause until a human takes action, allowing smooth resumption of workflows even after days of inactivity, and provides stability across code deployments.
 
 ## How It Works
 
 <Steps>
 
 <Step>
-The agent calls a tool (like `humanApproval`) with a message describing what needs approval.
-</Step>
-
-<Step>
-`createWebhook()` generates a unique URL that can resume the workflow.
+`createWebhook()` or `createHook()` generates a unique URL (or token) that can resume a workflow. This can be packaged as a tool for the Agent to call, or used directly in your backend code.
 </Step>
 
 <Step>
-The tool emits a data chunk containing the approval URL to the UI.
+The workflow emits a data chunk containing the webhook URL, sending it to the consumer of the workflow, such as a chat UI, or an external service.
 </Step>
 
 <Step>
@@ -25,11 +23,11 @@ The workflow pauses at `await webhook` - no compute resources are consumed.
 </Step>
 
 <Step>
-When a human clicks approve/reject and the webhook URL is called, the workflow resumes.
+The consumer of the workflow calls the webhook URL, sending data back to the workflow.
 </Step>
 
 <Step>
-The tool receives any data sent with the webhook (approval status, comments) and returns.
+The workflow receives any data sent with the webhook (approval status, comments) and resumes execution.
 </Step>
 
 </Steps>
@@ -41,42 +39,13 @@ Add a tool that pauses the agent until a human approves or rejects:
 <Steps>
 
 <Step>
-### Create the Emit Helper
-
-First, create a step function to emit the approval request to the UI:
-
-```typescript title="ai/tools/human-approval.ts" lineNumbers
-import { getWritable } from 'workflow';
-import type { UIMessageChunk } from 'ai';
-
-async function emitApprovalRequest(
-  { url, message }: { url: string; message: string },
-  { toolCallId }: { toolCallId: string }
-) {
-  'use step';
-
-  const writable = getWritable<UIMessageChunk>();
-  const writer = writable.getWriter();
-
-  await writer.write({
-    id: toolCallId,
-    type: 'data-approval-required',
-    data: { url, message },
-  });
-
-  writer.releaseLock();
-}
-```
-</Step>
-
-<Step>
-### Implement the Execute Function
+### Implement the tool
 
 The execute function creates a webhook and waits for approval:
 
 ```typescript title="ai/tools/human-approval.ts" lineNumbers
-import { tool } from 'ai';
-import { createWebhook } from 'workflow'; // [!code highlight]
+import { tool, type UIMessageChunk } from 'ai';
+import { createWebhook, getWritable } from 'workflow'; // [!code highlight]
 import { z } from 'zod';
 
 async function executeHumanApproval(
@@ -111,6 +80,25 @@ export const humanApproval = tool({
   }),
   execute: executeHumanApproval,
 });
+
+// This is just a helper function to emit the approval request to the UI
+async function emitApprovalRequest(
+  { url, message }: { url: string; message: string },
+  { toolCallId }: { toolCallId: string }
+) {
+  'use step';
+
+  const writable = getWritable<UIMessageChunk>();
+  const writer = writable.getWriter();
+
+  await writer.write({
+    id: toolCallId,
+    type: 'data-approval-required',
+    data: { url, message },
+  });
+
+  writer.releaseLock();
+}
 ```
 
 <Callout type="info">
@@ -118,17 +106,11 @@ The `createWebhook()` function must be called from within a workflow context, no
 </Callout>
 </Step>
 
-</Steps>
-
-## Handling the Approval UI
-
-The UI receives a data chunk with type `data-approval-required`. Build a component that displays the approval request and handles the user's decision:
-
-<Steps>
-
 <Step>
 ### Create the Approval Component
 
+The UI receives a data chunk with type `data-approval-required`. Build a component that displays the approval request and handles the user's decision. Instead of giving the human UI to resolve this hook, this could also be sent to an external service, e.g. as a payment provider callback.
+
 ```typescript title="components/approval-button.tsx" lineNumbers
 'use client';
 
@@ -194,6 +176,7 @@ export function ApprovalButton({ data }: { data: ApprovalData }) {
   );
 }
 ```
+
 </Step>
 
 <Step>
@@ -215,6 +198,7 @@ import { ApprovalButton } from './approval-button';
   return null;
 })}
 ```
+
 </Step>
 
 </Steps>
@@ -247,6 +231,7 @@ export const deploymentApprovalHook = defineHook({
   }),
 });
 ```
+
 </Tab>
 
 <Tab value="Tool Implementation">
@@ -304,6 +289,7 @@ export const deploymentApproval = tool({
   execute: executeDeploymentApproval,
 });
 ```
+
 </Tab>
 
 <Tab value="API Route">
@@ -336,6 +322,7 @@ export async function POST(request: Request) {
 ```
 
 This API can be called by:
+
 - Your UI components (passing the token from the data chunk)
 - Backend services that need to programmatically approve/reject
 - External systems via API integration
@@ -408,139 +395,6 @@ export async function criticalActionWorkflow(action: string) {
 }
 ```
 
-## Complete Example
-
-A full human approval implementation with tool and UI component:
-
-<Tabs items={['Tool', 'UI Component']}>
-
-<Tab value="Tool">
-
-```typescript title="ai/tools/human-approval.ts" lineNumbers
-import { tool } from 'ai';
-import { createWebhook, getWritable } from 'workflow';
-import { z } from 'zod';
-import type { UIMessageChunk } from 'ai';
-
-async function emitApprovalRequest(
-  { url, message }: { url: string; message: string },
-  { toolCallId }: { toolCallId: string }
-) {
-  'use step';
-
-  const writable = getWritable<UIMessageChunk>();
-  const writer = writable.getWriter();
-
-  await writer.write({
-    id: toolCallId,
-    type: 'data-approval-required',
-    data: { url, message },
-  });
-
-  writer.releaseLock();
-}
-
-async function executeHumanApproval(
-  { message }: { message: string },
-  { toolCallId }: { toolCallId: string }
-) {
-  const webhook = createWebhook();
-
-  await emitApprovalRequest({ url: webhook.url, message }, { toolCallId });
-
-  const request = await webhook;
-  const { approved, comment } = await request.json();
-
-  if (!approved) {
-    return `Action rejected${comment ? `: ${comment}` : ''}`;
-  }
-
-  return `Approved${comment ? ` with comment: ${comment}` : ''}`;
-}
-
-export const humanApproval = tool({
-  description: 'Request human approval before proceeding with an action',
-  inputSchema: z.object({
-    message: z.string().describe('Description of what needs approval'),
-  }),
-  execute: executeHumanApproval,
-});
-```
-
-</Tab>
-
-<Tab value="UI Component">
-
-```typescript title="components/approval-button.tsx" lineNumbers
-'use client';
-
-import { useState } from 'react';
-
-interface ApprovalData {
-  url: string;
-  message: string;
-}
-
-export function ApprovalButton({ data }: { data: ApprovalData }) {
-  const [comment, setComment] = useState('');
-  const [isSubmitting, setIsSubmitting] = useState(false);
-  const [isComplete, setIsComplete] = useState(false);
-
-  const handleSubmit = async (approved: boolean) => {
-    setIsSubmitting(true);
-    try {
-      await fetch(data.url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ approved, comment }),
-      });
-      setIsComplete(true);
-    } finally {
-      setIsSubmitting(false);
-    }
-  };
-
-  if (isComplete) {
-    return <div className="text-muted-foreground">Response submitted</div>;
-  }
-
-  return (
-    <div className="border rounded-lg p-4 space-y-4">
-      <p className="font-medium">{data.message}</p>
-
-      <textarea
-        value={comment}
-        onChange={(e) => setComment(e.target.value)}
-        placeholder="Add a comment (optional)..."
-        className="w-full border rounded p-2 text-sm"
-        rows={2}
-      />
-
-      <div className="flex gap-2">
-        <button
-          onClick={() => handleSubmit(true)}
-          disabled={isSubmitting}
-          className="px-4 py-2 bg-green-600 text-white rounded hover:bg-green-700 disabled:opacity-50"
-        >
-          {isSubmitting ? 'Submitting...' : 'Approve'}
-        </button>
-        <button
-          onClick={() => handleSubmit(false)}
-          disabled={isSubmitting}
-          className="px-4 py-2 bg-red-600 text-white rounded hover:bg-red-700 disabled:opacity-50"
-        >
-          {isSubmitting ? 'Submitting...' : 'Reject'}
-        </button>
-      </div>
-    </div>
-  );
-}
-```
-
-</Tab>
-
-</Tabs>
-
 ## Related Documentation
 
 - [Hooks & Webhooks](/docs/foundations/hooks) - Complete guide to hooks and webhooks

From 6db66ecfa0c96fcd493402b09fc121d09db16371 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 16:15:58 -0800
Subject: [PATCH 18/38] Polish sleep docs

---
 .../guides/ai-agents/human-in-the-loop.mdx    |  2 +-
 .../guides/ai-agents/sleep-and-delays.mdx     | 88 ++++++++-----------
 2 files changed, 39 insertions(+), 51 deletions(-)

diff --git a/docs/content/guides/ai-agents/human-in-the-loop.mdx b/docs/content/guides/ai-agents/human-in-the-loop.mdx
index 19ec00858..ae7c76a3d 100644
--- a/docs/content/guides/ai-agents/human-in-the-loop.mdx
+++ b/docs/content/guides/ai-agents/human-in-the-loop.mdx
@@ -4,7 +4,7 @@ title: Human-in-the-Loop
 
 An extremely common feature necessary for running AI agents in production is the ability to wait for human input or external events before proceeding.
 
-Workflow DevKit's webhook and hook primitives enable "human-in-the-loop" patterns where workflows pause until a human takes action, allowing smooth resumption of workflows even after days of inactivity, and provides stability across code deployments.
+Workflow DevKit's [webhook](/docs/api-reference/workflow/create-webhook) and [hook](/docs/api-reference/workflow/define-hook) primitives enable "human-in-the-loop" patterns where workflows pause until a human takes action, allowing smooth resumption of workflows even after days of inactivity, and provides stability across code deployments.
 
 ## How It Works
 
diff --git a/docs/content/guides/ai-agents/sleep-and-delays.mdx b/docs/content/guides/ai-agents/sleep-and-delays.mdx
index d3470febe..b02a8d58f 100644
--- a/docs/content/guides/ai-agents/sleep-and-delays.mdx
+++ b/docs/content/guides/ai-agents/sleep-and-delays.mdx
@@ -18,6 +18,10 @@ Create a tool that allows the agent to pause for a specified duration:
 <Step>
 ### Define the Tool
 
+First, we make the `sleep()` function available to the AI Agent by packaging it as a tool.
+
+Note that the `sleep()` function must be called from within a workflow context, not from within a step. This is why `executeSleep` does not have `"use step"` - it runs in the workflow context where `sleep()` is available.
+
 ```typescript title="ai/tools/sleep.ts" lineNumbers
 import { tool } from 'ai';
 import { getWritable, sleep } from 'workflow'; // [!code highlight]
@@ -28,33 +32,12 @@ const inputSchema = z.object({
   durationMs: z.number().describe('Duration to sleep in milliseconds'),
 });
 
-async function reportSleep(
-  { durationMs }: { durationMs: number },
-  { toolCallId }: { toolCallId: string }
-) {
-  'use step';
-
-  const writable = getWritable<UIMessageChunk>();
-  const writer = writable.getWriter();
-
-  const seconds = Math.ceil(durationMs / 1000);
-
-  await writer.write({
-    id: toolCallId,
-    type: 'data-wait',
-    data: { text: `Sleeping for ${seconds} seconds` },
-  });
-
-  writer.releaseLock();
-}
-
 async function executeSleep(
   { durationMs }: z.infer<typeof inputSchema>,
   { toolCallId }: { toolCallId: string }
 ) {
   // Note: No "use step" here - sleep is a workflow-level function // [!code highlight]
 
-  await reportSleep({ durationMs }, { toolCallId });
   await sleep(durationMs); // [!code highlight]
 
   return `Slept for ${durationMs}ms`;
@@ -70,58 +53,61 @@ export const sleepTool = tool({
 </Step>
 
 <Step>
-### Understand the Context Requirement
-
-The `sleep()` function must be called from within a workflow context, not from within a step. This is why `executeSleep` does not have `"use step"` - it runs in the workflow context where `sleep()` is available.
-</Step>
-
-</Steps>
+### Emitting status updates
 
-## Emitting Progress Updates
-
-When sleeping for long durations, emit a progress update so the UI can display the waiting state:
-
-<Steps>
-
-<Step>
-### Create an Emit Helper
+We want the UI to display the waiting state, so we emit a new chunk type `data-wait`, that the UI can then consume.
 
 ```typescript lineNumbers
-async function emitWaitingStatus(message: string, toolCallId: string) {
+// This is just a helper function to emit the sleep status to the UI
+async function emitSleepStatus(
+  { durationMs }: { durationMs: number },
+  { toolCallId }: { toolCallId: string }
+) {
   'use step';
 
   const writable = getWritable<UIMessageChunk>();
   const writer = writable.getWriter();
 
+  const seconds = Math.ceil(durationMs / 1000);
+
   await writer.write({
     id: toolCallId,
     type: 'data-wait',
-    data: { text: message },
+    data: { text: `Sleeping for ${seconds} seconds` },
   });
 
   writer.releaseLock();
 }
 ```
 
-</Step>
-
-<Step>
-### Use in Tool Execution
+Then modify the tool execution to emit the status update:
 
 ```typescript lineNumbers
-async function executeScheduleTask(
-  { delayMinutes, taskName }: { delayMinutes: number; taskName: string },
+async function executeSleep(
+  { durationMs }: z.infer<typeof inputSchema>,
   { toolCallId }: { toolCallId: string }
 ) {
-  await emitWaitingStatus(
-    `Scheduled "${taskName}" to run in ${delayMinutes} minutes`,
-    toolCallId
-  );
+  await emitSleepStatus({ durationMs }, { toolCallId }); // [!code highlight]
+  await sleep(durationMs);
+}
+```
+
+</Step>
 
-  await sleep(`${delayMinutes}m`); // [!code highlight]
+<Step>
+### Show the tool status in the UI
 
-  return `Task "${taskName}" is now ready to execute`;
-}
+```typescript lineNumbers
+// In your message rendering logic:
+{message.parts.map((part, i) => {
+  if (part.type === 'text') {
+    return <span key={i}>{part.text}</span>;
+  }
+  if (part.type === 'data-wait') { // [!code highlight]
+    return <div key={i}><WaitIcon />{part.data.text}...</div>; // [!code highlight]
+  } // [!code highlight]
+  return null;
+})}
 ```
 
 </Step>
@@ -130,6 +116,8 @@ async function executeScheduleTask(
 
 ## Use Cases
 
+Aside from providing `sleep()` as a tool, there are other use cases for Agents that commonly call for suspension and resumption.
+
 ### Rate Limiting
 
 When hitting API rate limits, use `RetryableError` with a delay:

From 596f7adfdba4526849a9dd8f1172e4a6f2c7e9fb Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 16:36:01 -0800
Subject: [PATCH 19/38] Tool polish

---
 .../guides/ai-agents/defining-tools.mdx       | 43 +++++--------------
 1 file changed, 10 insertions(+), 33 deletions(-)

diff --git a/docs/content/guides/ai-agents/defining-tools.mdx b/docs/content/guides/ai-agents/defining-tools.mdx
index 602db68ed..34c80b254 100644
--- a/docs/content/guides/ai-agents/defining-tools.mdx
+++ b/docs/content/guides/ai-agents/defining-tools.mdx
@@ -2,15 +2,11 @@
 title: Defining Tool Calls
 ---
 
-Tools are the primary way AI agents interact with the outside world. In Workflow DevKit, tools can be implemented as workflow steps for automatic retries and persistence, or they can use workflow-level primitives like `sleep()` and webhooks. This guide covers the patterns and best practices for defining tools in durable agents.
+In Workflow DevKit, tools usually defined as [steps](/docs/foundations/workflows-and-steps). Since steps run in isolation, `DurableAgent` provides common abstractions for giving steps access to tool context. There are also some cases where tools might run inside the workflow context, as opposed to the step context, e.g. when using `sleep()` or `createWebhook()`. This guide covers the patterns and best practices for defining tools in durable agents.
 
-## Tool Structure
+## Tool Structure and Context
 
-Every tool has three key parts:
-
-1. **Input Schema** - A Zod schema defining what the LLM can pass to the tool
-2. **Description** - A natural language description helping the LLM decide when to use the tool
-3. **Execute Function** - The logic that runs when the tool is called
+Workflow DevKit uses the same abstraction for tools as the AI SDK, see [the AI SDK documentation on tools](https://ai-sdk.dev/docs/foundations/tools). Here's an example tool definition:
 
 ```typescript title="ai/tools/search-web.ts" lineNumbers
 import { tool } from 'ai';
@@ -29,29 +25,14 @@ export const searchWeb = tool({
 });
 ```
 
-## The Execute Function Context
-
-The execute function receives two arguments:
+Tools passed to `DurableAgent` are invoked with additional context. Every `execute` function receives two arguments:
 
 1. **Input** - The validated input matching your schema
 2. **Options** - Context about the tool call, including:
    - `toolCallId` - Unique identifier for this invocation
-   - `messages` - The conversation history up to and including this tool call
-
-```typescript lineNumbers
-execute: async (input, options) => {
-  const { toolCallId, messages } = options;
-  
-  // toolCallId: Use for correlating stream chunks with this tool call
-  // messages: Access the full conversation context
-  
-  return result;
-}
-```
-
-## Accessing Conversation Messages
+   - `messages` - The full conversation history up to and including this tool call
 
-Tools can access the full conversation history through the `messages` option. This is useful when your tool needs context about what was discussed:
+This allows tools to access the full conversation history through the `messages` option, which is useful when your tool needs context about what was discussed:
 
 ```typescript title="ai/tools/summarize-conversation.ts" lineNumbers
 import { tool } from 'ai';
@@ -84,11 +65,6 @@ export const summarizeConversation = tool({
 });
 ```
 
-The messages follow the `LanguageModelV2Prompt` format from the AI SDK, which includes:
-- User messages with text and file content
-- Assistant messages with text and tool calls
-- Tool result messages from previous tool executions
-
 ## Streaming from Tools
 
 Tools can emit real-time updates to the UI by writing to the workflow's output stream. This must be done within a step function:
@@ -122,6 +98,7 @@ async function emitProgress(
   writer.releaseLock();
 }
 ```
+
 </Step>
 
 <Step>
@@ -143,6 +120,7 @@ async function executeSearchWeb(
   return results;
 }
 ```
+
 </Step>
 
 </Steps>
@@ -269,7 +247,7 @@ When emitting data chunks, use descriptive type names that your UI can handle:
 await writer.write({
   id: toolCallId,
   type: 'data-run-command',  // Custom type
-  data: { 
+  data: {
     command: 'npm install',
     cwd: '/project',
   },
@@ -278,7 +256,7 @@ await writer.write({
 await writer.write({
   id: toolCallId,
   type: 'data-file-created',  // Another custom type
-  data: { 
+  data: {
     path: '/project/package.json',
     size: 1234,
   },
@@ -320,4 +298,3 @@ The UI handles these custom types by checking the part type:
 - [Streaming](/docs/foundations/streaming) - How streaming works in Workflow DevKit
 - [Workflows and Steps](/docs/foundations/workflows-and-steps) - Understanding the execution model
 - [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Complete API documentation
-

From 756a11c708bbace5a32304df515b6eb3057145c5 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 16:53:45 -0800
Subject: [PATCH 20/38] Move sections

---
 .../content/docs/ai-agents/defining-tools.mdx | 109 +++++
 docs/content/docs/ai-agents/index.mdx         |  41 ++
 docs/content/docs/ai-agents/meta.json         |   5 +
 docs/content/docs/meta.json                   |   1 +
 .../guides/ai-agents/defining-tools.mdx       | 300 -------------
 docs/content/guides/ai-agents/index.mdx       |   2 +
 .../guides/ai-agents/message-queueing.mdx     | 411 ++++++++++++++++++
 docs/content/guides/ai-agents/meta.json       |   4 +-
 8 files changed, 571 insertions(+), 302 deletions(-)
 create mode 100644 docs/content/docs/ai-agents/defining-tools.mdx
 create mode 100644 docs/content/docs/ai-agents/index.mdx
 create mode 100644 docs/content/docs/ai-agents/meta.json
 delete mode 100644 docs/content/guides/ai-agents/defining-tools.mdx
 create mode 100644 docs/content/guides/ai-agents/message-queueing.mdx

diff --git a/docs/content/docs/ai-agents/defining-tools.mdx b/docs/content/docs/ai-agents/defining-tools.mdx
new file mode 100644
index 000000000..036843041
--- /dev/null
+++ b/docs/content/docs/ai-agents/defining-tools.mdx
@@ -0,0 +1,109 @@
+---
+title: Defining Tools
+---
+
+Tools in Workflow DevKit follow the same structure as [AI SDK tools](https://ai-sdk.dev/docs/foundations/tools), but with additional context provided by `DurableAgent`. This page covers the key concepts for defining tools in durable agents.
+
+<Callout>
+For a complete walkthrough with examples, see the **[Building Durable AI Agents](/guides/ai-agents)** guide.
+</Callout>
+
+## Tool Execute Context
+
+When `DurableAgent` invokes a tool, the execute function receives additional context:
+
+```typescript lineNumbers
+execute: async (input, options) => {
+  const { toolCallId, messages } = options;
+  
+  // toolCallId: Unique identifier for correlating stream chunks
+  // messages: Full conversation history (LanguageModelV2Prompt format)
+  
+  return result;
+}
+```
+
+### Accessing Conversation Messages
+
+Tools can access the full conversation history through the `messages` option:
+
+```typescript lineNumbers
+export const summarizeConversation = tool({
+  description: 'Summarize the conversation so far',
+  inputSchema: z.object({
+    focus: z.string().optional(),
+  }),
+  execute: async ({ focus }, { messages }) => { // [!code highlight]
+    const userMessages = messages
+      .filter(m => m.role === 'user')
+      .map(m => m.content.filter(p => p.type === 'text').map(p => p.text).join(' '));
+
+    return { summary: userMessages.slice(-3).join(', ') };
+  },
+});
+```
+
+## Streaming from Tools
+
+Tools can emit real-time updates by writing to the workflow's output stream. Since `getWritable()` requires the step context, streaming must be done in a step function:
+
+```typescript lineNumbers
+async function emitProgress(status: string, toolCallId: string) {
+  'use step'; // [!code highlight]
+
+  const writable = getWritable<UIMessageChunk>();
+  const writer = writable.getWriter();
+
+  await writer.write({
+    id: toolCallId,
+    type: 'data-status',
+    data: { status },
+  });
+
+  writer.releaseLock();
+}
+
+async function executeSearch({ query }: { query: string }, { toolCallId }: { toolCallId: string }) {
+  await emitProgress('searching', toolCallId);
+  const results = await performSearch(query);
+  await emitProgress('complete', toolCallId);
+  return results;
+}
+```
+
+## Step-Level vs Workflow-Level
+
+Tools can run at two levels with different capabilities:
+
+| Capability | Step-Level (`"use step"`) | Workflow-Level |
+|------------|---------------------------|----------------|
+| `getWritable()` | ✅ | ❌ |
+| Automatic retries | ✅ | ❌ |
+| `sleep()` | ❌ | ✅ |
+| `createWebhook()` | ❌ | ✅ |
+
+Most tools combine both: use step functions for I/O operations, and keep the execute function at the workflow level for orchestration:
+
+```typescript lineNumbers
+// Step: handles I/O with retries
+async function performFetch(url: string) {
+  'use step';
+  const response = await fetch(url);
+  return response.json();
+}
+
+// Workflow-level: orchestrates steps and can use sleep()
+async function executeFetchWithDelay({ url }: { url: string }) {
+  const result = await performFetch(url);
+  await sleep('5s'); // Only available at workflow level
+  return result;
+}
+```
+
+## Related
+
+- [Building Durable AI Agents](/guides/ai-agents) - Complete guide with examples
+- [Streaming](/docs/foundations/streaming) - How streaming works
+- [Workflows and Steps](/docs/foundations/workflows-and-steps) - Understanding execution contexts
+- [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Full API documentation
+
diff --git a/docs/content/docs/ai-agents/index.mdx b/docs/content/docs/ai-agents/index.mdx
new file mode 100644
index 000000000..8282f365c
--- /dev/null
+++ b/docs/content/docs/ai-agents/index.mdx
@@ -0,0 +1,41 @@
+---
+title: AI & Agents
+---
+
+Workflow DevKit provides first-class support for building durable AI agents through the `@workflow/ai` package. This package integrates with the [AI SDK](https://ai-sdk.dev) to provide production-ready agent primitives.
+
+## Guide
+
+For a complete walkthrough of building AI agents with Workflow DevKit, see the **[Building Durable AI Agents](/guides/ai-agents)** guide, which covers:
+
+- Converting AI SDK agents to durable agents
+- Implementing resumable streams
+- Adding sleep and scheduling capabilities
+- Human-in-the-loop approval patterns
+
+## Core Concepts
+
+<Cards>
+  <Card title="Defining Tools" href="/docs/ai-agents/defining-tools">
+    Learn how to define tools for durable agents, including streaming from tools and accessing conversation context.
+  </Card>
+</Cards>
+
+## API Reference
+
+The `@workflow/ai` package exports the following:
+
+<Cards>
+  <Card title="DurableAgent" href="/docs/api-reference/workflow-ai/durable-agent">
+    The main class for creating AI agents that maintain state across workflow steps, call tools, and handle interruptions.
+  </Card>
+  <Card title="WorkflowChatTransport" href="/docs/api-reference/workflow-ai/workflow-chat-transport">
+    AI SDK transport for reliable message streaming with automatic reconnection and resumption.
+  </Card>
+</Cards>
+
+## Related
+
+- [Streaming](/docs/foundations/streaming) - How streaming works in Workflow DevKit
+- [Workflows and Steps](/docs/foundations/workflows-and-steps) - Understanding the execution model
+- [Hooks & Webhooks](/docs/foundations/hooks) - Pausing workflows for external events
diff --git a/docs/content/docs/ai-agents/meta.json b/docs/content/docs/ai-agents/meta.json
new file mode 100644
index 000000000..14aa95e51
--- /dev/null
+++ b/docs/content/docs/ai-agents/meta.json
@@ -0,0 +1,5 @@
+{
+  "title": "AI & Agents",
+  "pages": ["defining-tools"],
+  "defaultOpen": true
+}
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index b527dc11f..89a95d728 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -6,6 +6,7 @@
     "foundations",
     "how-it-works",
     "observability",
+    "ai-agents",
     "deploying",
     "errors",
     "api-reference"
diff --git a/docs/content/guides/ai-agents/defining-tools.mdx b/docs/content/guides/ai-agents/defining-tools.mdx
deleted file mode 100644
index 34c80b254..000000000
--- a/docs/content/guides/ai-agents/defining-tools.mdx
+++ /dev/null
@@ -1,300 +0,0 @@
----
-title: Defining Tool Calls
----
-
-In Workflow DevKit, tools usually defined as [steps](/docs/foundations/workflows-and-steps). Since steps run in isolation, `DurableAgent` provides common abstractions for giving steps access to tool context. There are also some cases where tools might run inside the workflow context, as opposed to the step context, e.g. when using `sleep()` or `createWebhook()`. This guide covers the patterns and best practices for defining tools in durable agents.
-
-## Tool Structure and Context
-
-Workflow DevKit uses the same abstraction for tools as the AI SDK, see [the AI SDK documentation on tools](https://ai-sdk.dev/docs/foundations/tools). Here's an example tool definition:
-
-```typescript title="ai/tools/search-web.ts" lineNumbers
-import { tool } from 'ai';
-import { z } from 'zod';
-
-export const searchWeb = tool({
-  description: 'Search the web for information',
-  inputSchema: z.object({
-    query: z.string().describe('The search query'),
-    maxResults: z.number().optional().describe('Maximum number of results'),
-  }),
-  execute: async ({ query, maxResults = 5 }) => {
-    // Tool implementation
-    return { results: [] };
-  },
-});
-```
-
-Tools passed to `DurableAgent` are invoked with additional context. Every `execute` function receives two arguments:
-
-1. **Input** - The validated input matching your schema
-2. **Options** - Context about the tool call, including:
-   - `toolCallId` - Unique identifier for this invocation
-   - `messages` - The full conversation history up to and including this tool call
-
-This allows tools to access the full conversation history through the `messages` option, which is useful when your tool needs context about what was discussed:
-
-```typescript title="ai/tools/summarize-conversation.ts" lineNumbers
-import { tool } from 'ai';
-import { z } from 'zod';
-
-export const summarizeConversation = tool({
-  description: 'Summarize the conversation so far',
-  inputSchema: z.object({
-    focus: z.string().optional().describe('What aspect to focus on'),
-  }),
-  execute: async ({ focus }, { messages }) => { // [!code highlight]
-    // messages contains the full LanguageModelV2Prompt
-    const userMessages = messages
-      .filter(m => m.role === 'user')
-      .map(m => {
-        // Extract text content from the message
-        const textParts = m.content
-          .filter(p => p.type === 'text')
-          .map(p => p.text);
-        return textParts.join(' ');
-      });
-
-    // Use the conversation context in your tool logic
-    return {
-      messageCount: messages.length,
-      userMessageCount: userMessages.length,
-      summary: `Conversation about: ${userMessages.slice(-3).join(', ')}`,
-    };
-  },
-});
-```
-
-## Streaming from Tools
-
-Tools can emit real-time updates to the UI by writing to the workflow's output stream. This must be done within a step function:
-
-<Steps>
-
-<Step>
-### Create a Step for Stream Writes
-
-Since `getWritable()` requires the step context, create a separate step function for emitting chunks:
-
-```typescript lineNumbers
-import { getWritable } from 'workflow';
-import type { UIMessageChunk } from 'ai';
-
-async function emitProgress(
-  { status, url }: { status: string; url?: string },
-  { toolCallId }: { toolCallId: string }
-) {
-  'use step'; // [!code highlight]
-
-  const writable = getWritable<UIMessageChunk>();
-  const writer = writable.getWriter();
-
-  await writer.write({
-    id: toolCallId,
-    type: 'data-status',
-    data: { status, url },
-  });
-
-  writer.releaseLock();
-}
-```
-
-</Step>
-
-<Step>
-### Call from the Execute Function
-
-The execute function can call this step to emit progress:
-
-```typescript lineNumbers
-async function executeSearchWeb(
-  { query }: { query: string },
-  { toolCallId }: { toolCallId: string }
-) {
-  await emitProgress({ status: 'searching', url: query }, { toolCallId }); // [!code highlight]
-
-  const results = await performSearch(query);
-
-  await emitProgress({ status: 'complete' }, { toolCallId }); // [!code highlight]
-
-  return results;
-}
-```
-
-</Step>
-
-</Steps>
-
-### Why Separate Steps?
-
-The `getWritable()` function is only available within steps, not at the workflow level. This is because:
-
-1. Steps provide the transactional boundary for stream writes
-2. Each step's writes are persisted and can be replayed on recovery
-3. The workflow context handles orchestration, not I/O
-
-## Workflow-Level vs Step-Level Tools
-
-Tools can run at two levels, with different capabilities:
-
-### Step-Level Tools
-
-When your execute function uses `"use step"`, the entire tool runs as a retryable step:
-
-```typescript lineNumbers
-async function executeWithRetries({ data }: { data: string }) {
-  'use step'; // [!code highlight]
-
-  // ✅ Can use getWritable()
-  // ✅ Automatic retries on transient failures
-  // ✅ Results persisted in event log
-  // ❌ Cannot call sleep() or createWebhook()
-
-  const result = await fetch(`https://api.example.com?q=${data}`);
-  return result.json();
-}
-```
-
-### Workflow-Level Tools
-
-When your execute function does NOT use `"use step"`, it runs in the workflow context:
-
-```typescript lineNumbers
-async function executeWithPause({ duration }: { duration: number }) {
-  // No "use step" - runs at workflow level // [!code highlight]
-
-  // ❌ Cannot use getWritable() directly
-  // ✅ Can call sleep()
-  // ✅ Can call createWebhook()
-  // ✅ Can call step functions
-
-  await reportStatus('pausing'); // Step function for streaming
-  await sleep(duration);         // Workflow-level function
-
-  return 'Resumed after pause';
-}
-```
-
-### Combining Both Levels
-
-Most tools combine both approaches - use step functions for I/O and retryable operations, while keeping the execute function at the workflow level for orchestration:
-
-```typescript title="ai/tools/fetch-with-progress.ts" lineNumbers
-import { tool } from 'ai';
-import { getWritable, sleep } from 'workflow';
-import { z } from 'zod';
-import type { UIMessageChunk } from 'ai';
-
-// Step function: handles streaming
-async function emitFetchStatus(
-  { url, status }: { url: string; status: 'fetching' | 'complete' | 'retrying' },
-  { toolCallId }: { toolCallId: string }
-) {
-  'use step';
-
-  const writable = getWritable<UIMessageChunk>();
-  const writer = writable.getWriter();
-
-  await writer.write({
-    id: toolCallId,
-    type: 'data-fetch-status',
-    data: { url, status },
-  });
-
-  writer.releaseLock();
-}
-
-// Step function: handles the actual fetch with retries
-async function performFetch(url: string) {
-  'use step';
-
-  const response = await fetch(url);
-  if (!response.ok) {
-    throw new Error(`Fetch failed: ${response.status}`);
-  }
-  return response.json();
-}
-
-// Workflow-level execute: orchestrates steps
-async function executeFetchWithProgress(
-  { url }: { url: string },
-  { toolCallId }: { toolCallId: string }
-) {
-  await emitFetchStatus({ url, status: 'fetching' }, { toolCallId });
-
-  const result = await performFetch(url);
-
-  await emitFetchStatus({ url, status: 'complete' }, { toolCallId });
-
-  return result;
-}
-
-export const fetchWithProgress = tool({
-  description: 'Fetch a URL and report progress',
-  inputSchema: z.object({
-    url: z.string().url(),
-  }),
-  execute: executeFetchWithProgress,
-});
-```
-
-## Custom Data Chunk Types
-
-When emitting data chunks, use descriptive type names that your UI can handle:
-
-```typescript lineNumbers
-// In your tool
-await writer.write({
-  id: toolCallId,
-  type: 'data-run-command',  // Custom type
-  data: {
-    command: 'npm install',
-    cwd: '/project',
-  },
-});
-
-await writer.write({
-  id: toolCallId,
-  type: 'data-file-created',  // Another custom type
-  data: {
-    path: '/project/package.json',
-    size: 1234,
-  },
-});
-```
-
-The UI handles these custom types by checking the part type:
-
-```typescript title="components/chat.tsx" lineNumbers
-{messages.map((m) => (
-  <div key={m.id}>
-    {m.parts.map((part, i) => {
-      if (part.type === 'text') {
-        return <span key={i}>{part.text}</span>;
-      }
-      if (part.type === 'data-run-command') {
-        return (
-          <div key={i} className="terminal">
-            $ {part.data.command}
-          </div>
-        );
-      }
-      if (part.type === 'data-file-created') {
-        return (
-          <div key={i} className="file-badge">
-            Created: {part.data.path}
-          </div>
-        );
-      }
-      return null;
-    })}
-  </div>
-))}
-```
-
-## Related Documentation
-
-- [Building Durable AI Agents](/guides/ai-agents) - Getting started with durable agents
-- [Streaming](/docs/foundations/streaming) - How streaming works in Workflow DevKit
-- [Workflows and Steps](/docs/foundations/workflows-and-steps) - Understanding the execution model
-- [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Complete API documentation
diff --git a/docs/content/guides/ai-agents/index.mdx b/docs/content/guides/ai-agents/index.mdx
index 8452267d2..c17020371 100644
--- a/docs/content/guides/ai-agents/index.mdx
+++ b/docs/content/guides/ai-agents/index.mdx
@@ -555,6 +555,8 @@ export function Chat() {
 
 ## Related Documentation
 
+- [AI & Agents Overview](/docs/ai-agents) - Documentation hub for AI agent features
+- [Defining Tools](/docs/ai-agents/defining-tools) - Tool patterns and execute context
 - [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Full API documentation
 - [Workflows and Steps](/docs/foundations/workflows-and-steps) - Core concepts
 - [Streaming](/docs/foundations/streaming) - In-depth streaming guide
diff --git a/docs/content/guides/ai-agents/message-queueing.mdx b/docs/content/guides/ai-agents/message-queueing.mdx
new file mode 100644
index 000000000..19338d466
--- /dev/null
+++ b/docs/content/guides/ai-agents/message-queueing.mdx
@@ -0,0 +1,411 @@
+---
+title: Queueing User Messages
+---
+
+In some scenarios, you want to queue new messages into an ongoing AI agent conversation. For example, when a user sends follow-up messages while the agent is still processing, or when external events need to influence the conversation mid-stream.
+
+Workflow DevKit's [`createWebhook()`](/docs/api-reference/workflow/create-webhook) enables this pattern: creating a webhook that can be called multiple times, iterating over incoming requests, and continuing the agent conversation with each new message.
+
+## How It Works
+
+<Steps>
+
+<Step>
+A webhook is created and its URL is sent to the client, allowing them to send follow-up messages.
+</Step>
+
+<Step>
+The agent processes the initial message and returns the updated conversation history.
+</Step>
+
+<Step>
+The workflow enters a loop, waiting for webhook calls using `for await...of`.
+</Step>
+
+<Step>
+Each webhook call triggers another `agent.stream()` with the new message appended to the conversation.
+</Step>
+
+<Step>
+A special command (like `/done`) signals the end of the conversation.
+</Step>
+
+</Steps>
+
+## Implementation
+
+<Steps>
+
+<Step>
+### Create the Chat Workflow
+
+The workflow creates a webhook and loops over incoming messages:
+
+```typescript title="ai/chat-workflow.ts" lineNumbers
+import { DurableAgent } from '@workflow/ai/agent';
+import type { ModelMessage, UIMessageChunk } from 'ai';
+import { createWebhook, getWritable } from 'workflow';
+
+export async function chatWorkflow(initialMessage: string) {
+  'use workflow';
+
+  const writable = getWritable<UIMessageChunk>();
+
+  // Create a webhook for receiving follow-up messages // [!code highlight]
+  const webhook = createWebhook(); // [!code highlight]
+
+  // Emit the webhook URL to the client
+  await emitWebhookUrl(webhook.url);
+
+  const agent = new DurableAgent({
+    model: 'anthropic/claude-sonnet',
+    system: 'You are a helpful assistant.',
+  });
+
+  // Start with the initial message
+  const messages: ModelMessage[] = [
+    { role: 'user', content: initialMessage },
+  ];
+
+  // Process the initial message // [!code highlight]
+  const { messages: updatedMessages } = await agent.stream({ // [!code highlight]
+    writable, // [!code highlight]
+    messages, // [!code highlight]
+    preventClose: true, // Keep stream open for follow-ups // [!code highlight]
+  }); // [!code highlight]
+  messages.push(...updatedMessages.slice(messages.length));
+
+  // Loop over incoming webhook requests // [!code highlight]
+  for await (const request of webhook) { // [!code highlight]
+    const { message } = await request.json();
+
+    // Check for end-of-conversation signal
+    if (message === '/done') {
+      break;
+    }
+
+    // Add the new user message
+    messages.push({ role: 'user', content: message });
+
+    // Continue the conversation // [!code highlight]
+    const { messages: latestMessages } = await agent.stream({ // [!code highlight]
+      writable, // [!code highlight]
+      messages, // [!code highlight]
+      preventClose: true, // [!code highlight]
+      sendStart: false, // Don't send another start chunk // [!code highlight]
+    }); // [!code highlight]
+    messages.push(...latestMessages.slice(messages.length));
+  }
+
+  // Close the stream when done
+  await closeStream(writable);
+
+  return { messages };
+}
+
+async function emitWebhookUrl(url: string) {
+  'use step';
+
+  const writable = getWritable<UIMessageChunk>();
+  const writer = writable.getWriter();
+
+  await writer.write({
+    type: 'data-chat-webhook',
+    data: { url },
+  });
+
+  writer.releaseLock();
+}
+
+async function closeStream(writable: WritableStream<UIMessageChunk>) {
+  'use step';
+
+  const writer = writable.getWriter();
+  await writer.write({ type: 'finish' });
+  writer.releaseLock();
+  await writable.close();
+}
+```
+
+<Callout type="info">
+The `for await...of` syntax iterates over webhook requests as they arrive. Each iteration waits for the next request, allowing the workflow to suspend without consuming resources.
+</Callout>
+
+</Step>
+
+<Step>
+### Client-Side: Send Follow-Up Messages
+
+The client receives the webhook URL and can send messages directly:
+
+```typescript title="lib/chat-api.ts" lineNumbers
+export async function sendMessage(webhookUrl: string, message: string) {
+  await fetch(webhookUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ message }),
+  });
+}
+
+export async function endConversation(webhookUrl: string) {
+  await fetch(webhookUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ message: '/done' }),
+  });
+}
+```
+
+</Step>
+
+<Step>
+### Build the Chat Component
+
+A React component that handles the conversation:
+
+```typescript title="components/chat.tsx" lineNumbers
+'use client';
+
+import { useState, useEffect } from 'react';
+import { sendMessage, endConversation } from '@/lib/chat-api';
+
+interface ChatProps {
+  webhookUrl: string | null;
+  onEnd?: () => void;
+}
+
+export function Chat({ webhookUrl, onEnd }: ChatProps) {
+  const [input, setInput] = useState('');
+  const [isSending, setIsSending] = useState(false);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!webhookUrl || !input.trim()) return;
+
+    setIsSending(true);
+    try {
+      await sendMessage(webhookUrl, input);
+      setInput('');
+    } finally {
+      setIsSending(false);
+    }
+  };
+
+  const handleEnd = async () => {
+    if (!webhookUrl) return;
+    await endConversation(webhookUrl);
+    onEnd?.();
+  };
+
+  return (
+    <div className="space-y-4">
+      <form onSubmit={handleSubmit} className="flex gap-2">
+        <input
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          placeholder="Type a message..."
+          className="flex-1 border rounded px-3 py-2"
+          disabled={!webhookUrl || isSending}
+        />
+        <button
+          type="submit"
+          disabled={!webhookUrl || isSending}
+          className="px-4 py-2 bg-blue-600 text-white rounded disabled:opacity-50"
+        >
+          Send
+        </button>
+      </form>
+
+      <button
+        onClick={handleEnd}
+        disabled={!webhookUrl}
+        className="text-sm text-gray-500 hover:text-gray-700"
+      >
+        End conversation
+      </button>
+    </div>
+  );
+}
+```
+
+</Step>
+
+</Steps>
+
+## Use Cases
+
+### Multi-Turn Chat with Tools
+
+Allow users to continue chatting while the agent has access to tools:
+
+```typescript lineNumbers
+import { DurableAgent } from '@workflow/ai/agent';
+import type { ModelMessage, UIMessageChunk } from 'ai';
+import { createWebhook, getWritable } from 'workflow';
+import { searchTool, calculatorTool } from './tools';
+
+export async function chatWithToolsWorkflow(initialMessage: string) {
+  'use workflow';
+
+  const writable = getWritable<UIMessageChunk>();
+  const webhook = createWebhook();
+
+  await emitWebhookUrl(webhook.url);
+
+  const agent = new DurableAgent({
+    model: 'anthropic/claude-sonnet',
+    system: 'You are a helpful assistant with access to search and calculation tools.',
+    tools: {
+      search: searchTool,
+      calculate: calculatorTool,
+    },
+  });
+
+  const messages: ModelMessage[] = [
+    { role: 'user', content: initialMessage },
+  ];
+
+  // Process initial message (agent may call tools)
+  const { messages: updated } = await agent.stream({
+    writable,
+    messages,
+    preventClose: true,
+  });
+  messages.push(...updated.slice(messages.length));
+
+  // Continue conversation with follow-ups
+  for await (const request of webhook) {
+    const { message } = await request.json();
+
+    if (message === '/done') break;
+
+    messages.push({ role: 'user', content: message });
+
+    const { messages: latest } = await agent.stream({
+      writable,
+      messages,
+      preventClose: true,
+      sendStart: false,
+    });
+    messages.push(...latest.slice(messages.length));
+  }
+
+  await closeStream(writable);
+  return { messages };
+}
+```
+
+### Collaborative Sessions
+
+Multiple users can send messages to the same conversation:
+
+```typescript lineNumbers
+export async function collaborativeChatWorkflow() {
+  'use workflow';
+
+  const writable = getWritable<UIMessageChunk>();
+  const webhook = createWebhook();
+
+  // Share this URL with all participants
+  await emitWebhookUrl(webhook.url);
+
+  const agent = new DurableAgent({
+    model: 'anthropic/claude-sonnet',
+    system: 'You are facilitating a group discussion. Address participants by name when they identify themselves.',
+  });
+
+  const messages: ModelMessage[] = [];
+
+  for await (const request of webhook) {
+    const { message, username } = await request.json();
+
+    if (message === '/done') break;
+
+    // Include the username in the message
+    const formattedMessage = username
+      ? `[${username}]: ${message}`
+      : message;
+
+    messages.push({ role: 'user', content: formattedMessage });
+
+    const { messages: latest } = await agent.stream({
+      writable,
+      messages,
+      preventClose: true,
+      sendStart: messages.length === 1, // Only send start on first message
+    });
+    messages.push(...latest.slice(messages.length));
+  }
+
+  await closeStream(writable);
+  return { messages };
+}
+```
+
+### Timeout-Based Auto-Close
+
+Automatically end the conversation after a period of inactivity:
+
+```typescript lineNumbers
+import { createWebhook, getWritable, sleep } from 'workflow';
+
+export async function chatWithTimeoutWorkflow(initialMessage: string) {
+  'use workflow';
+
+  const writable = getWritable<UIMessageChunk>();
+  const webhook = createWebhook();
+  const TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+
+  await emitWebhookUrl(webhook.url);
+
+  const agent = new DurableAgent({
+    model: 'anthropic/claude-sonnet',
+    system: 'You are a helpful assistant.',
+  });
+
+  const messages: ModelMessage[] = [
+    { role: 'user', content: initialMessage },
+  ];
+
+  const { messages: updated } = await agent.stream({
+    writable,
+    messages,
+    preventClose: true,
+  });
+  messages.push(...updated.slice(messages.length));
+
+  // Race between webhook messages and timeout
+  let timedOut = false;
+
+  for await (const request of webhook) {
+    const { message } = await request.json();
+
+    if (message === '/done') break;
+
+    messages.push({ role: 'user', content: message });
+
+    const { messages: latest } = await agent.stream({
+      writable,
+      messages,
+      preventClose: true,
+      sendStart: false,
+    });
+    messages.push(...latest.slice(messages.length));
+  }
+
+  if (timedOut) {
+    // Notify the user the session expired
+    await emitTimeout(writable);
+  }
+
+  await closeStream(writable);
+  return { messages, timedOut };
+}
+```
+
+## Related Documentation
+
+- [Human-in-the-Loop](/guides/ai-agents/human-in-the-loop) - Using hooks for approval workflows
+- [Hooks & Webhooks](/docs/foundations/hooks) - Complete guide to hooks and webhooks
+- [`createWebhook()` API Reference](/docs/api-reference/workflow/create-webhook) - Webhook configuration options
+- [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Full API documentation
diff --git a/docs/content/guides/ai-agents/meta.json b/docs/content/guides/ai-agents/meta.json
index 8809538fe..e588f4657 100644
--- a/docs/content/guides/ai-agents/meta.json
+++ b/docs/content/guides/ai-agents/meta.json
@@ -2,10 +2,10 @@
   "title": "AI Agents",
   "pages": [
     "index",
-    "defining-tools",
     "resumable-streams",
     "sleep-and-delays",
-    "human-in-the-loop"
+    "human-in-the-loop",
+    "message-queueing"
   ],
   "defaultOpen": true
 }

From 739f7320b402fa0b2d3a6e1dfa2aa9551edbea67 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 17:00:33 -0800
Subject: [PATCH 21/38] love these graphs

---
 docs/components/guides/agent-traces.tsx       | 183 +++++++++++-------
 .../guides/ai-agents/message-queueing.mdx     |   4 +
 2 files changed, 118 insertions(+), 69 deletions(-)

diff --git a/docs/components/guides/agent-traces.tsx b/docs/components/guides/agent-traces.tsx
index 6232b1b51..1e44a0243 100644
--- a/docs/components/guides/agent-traces.tsx
+++ b/docs/components/guides/agent-traces.tsx
@@ -3,92 +3,137 @@
 import { motion } from 'motion/react';
 import { cn } from '@/lib/utils';
 
-const rows = [
+// Color presets for trace rows
+const colors = {
+  workflow:
+    'bg-[#E1F0FF] dark:bg-[#00254D] border-[#99CEFF] text-[#0070F3] dark:border-[#0067D6] dark:text-[#52AEFF]',
+  stream:
+    'bg-[#DCF6DC] dark:bg-[#1B311E] border-[#99E59F] text-[#46A758] dark:border-[#297C3B] dark:text-[#6CDA76]',
+  tool: 'bg-[#FFF4E5] dark:bg-[#3D2800] border-[#FFCC80] text-[#F5A623] dark:border-[#9A6700] dark:text-[#FFCA28]',
+  approval:
+    'bg-[#FCE7F3] dark:bg-[#4A1D34] border-[#F9A8D4] text-[#EC4899] dark:border-[#BE185D] dark:text-[#F472B6]',
+  webhook:
+    'bg-[#EDE9FE] dark:bg-[#2E1065] border-[#C4B5FD] text-[#7C3AED] dark:border-[#6D28D9] dark:text-[#A78BFA]',
+};
+
+type TraceRow = {
+  label: string;
+  className: string;
+  start: number;
+  duration: number;
+};
+
+const defaultRows: TraceRow[] = [
   {
     label: 'chatWorkflow',
-    className:
-      'bg-[#E1F0FF] dark:bg-[#00254D] border-[#99CEFF] text-[#0070F3] dark:border-[#0067D6] dark:text-[#52AEFF]',
+    className: colors.workflow,
     start: 0,
     duration: 100,
   },
+  { label: 'agent.stream', className: colors.stream, start: 2, duration: 16 },
+  { label: 'searchWeb', className: colors.tool, start: 20, duration: 13 },
+  { label: 'agent.stream', className: colors.stream, start: 37, duration: 16 },
   {
-    label: 'agent.stream',
-    className:
-      'bg-[#DCF6DC] dark:bg-[#1B311E] border-[#99E59F] text-[#46A758] dark:border-[#297C3B] dark:text-[#6CDA76]',
-    start: 2,
-    duration: 16,
+    label: 'waitForHumanApproval',
+    className: colors.approval,
+    start: 57,
+    duration: 24,
   },
+  { label: 'agent.stream', className: colors.stream, start: 84, duration: 16 },
+];
+
+const messageQueueRows: TraceRow[] = [
   {
-    label: 'searchWeb',
-    className:
-      'bg-[#FFF4E5] dark:bg-[#3D2800] border-[#FFCC80] text-[#F5A623] dark:border-[#9A6700] dark:text-[#FFCA28]',
-    start: 20,
-    duration: 13,
+    label: 'chatWorkflow',
+    className: colors.workflow,
+    start: 0,
+    duration: 100,
   },
+  { label: 'agent.stream', className: colors.stream, start: 2, duration: 16 },
   {
-    label: 'agent.stream',
-    className:
-      'bg-[#DCF6DC] dark:bg-[#1B311E] border-[#99E59F] text-[#46A758] dark:border-[#297C3B] dark:text-[#6CDA76]',
-    start: 37,
-    duration: 16,
+    label: 'hook.enqueue()',
+    className: colors.webhook,
+    start: 18,
+    duration: 18,
   },
   {
-    label: 'waitForHumanApproval',
-    className:
-      'bg-[#FCE7F3] dark:bg-[#4A1D34] border-[#F9A8D4] text-[#EC4899] dark:border-[#BE185D] dark:text-[#F472B6]',
-    start: 57,
-    duration: 24,
+    label: 'tool.checkDB()',
+    className: colors.tool,
+    start: 18,
+    duration: 18,
   },
+  { label: 'agent.stream', className: colors.stream, start: 36, duration: 16 },
   {
-    label: 'agent.stream',
-    className:
-      'bg-[#DCF6DC] dark:bg-[#1B311E] border-[#99E59F] text-[#46A758] dark:border-[#297C3B] dark:text-[#6CDA76]',
-    start: 84,
-    duration: 16,
+    label: 'hook.enqueue()',
+    className: colors.webhook,
+    start: 52,
+    duration: 18,
   },
+  {
+    label: 'tool.search()',
+    className: colors.tool,
+    start: 52,
+    duration: 18,
+  },
+  { label: 'agent.stream', className: colors.stream, start: 70, duration: 16 },
 ];
 
-export const AgentTraces = () => (
-  <div className="not-prose my-8 rounded-lg border bg-card p-4 sm:p-6">
-    <div className="space-y-2 w-full">
-      {rows.map((row, index) => (
-        <div
-          key={`${row.label}-${index}`}
-          className="flex flex-col overflow-hidden"
-          style={{
-            marginLeft: `${row.start}%`,
-            width: `${row.duration}%`,
-          }}
-        >
-          <div className="relative h-6 w-full">
-            <motion.div
-              initial={{ width: 0, opacity: 0 }}
-              whileInView={{ width: 'auto', opacity: 1 }}
-              viewport={{ once: true, amount: 0.8 }}
-              transition={{
-                duration: 0.55,
-                delay: index * 0.12,
-                ease: [0.22, 1, 0.36, 1],
-              }}
-              className={cn(
-                'h-full rounded-sm border overflow-hidden',
-                row.className
-              )}
-            >
-              <div className="flex justify-between items-center h-full px-2">
-                <span className="text-[10px] sm:text-[11px] font-mono font-medium text-foreground truncate leading-none">
-                  {row.label}
-                </span>
-                {index === 0 && (
-                  <span className="text-[10px] sm:text-[11px] hidden sm:inline leading-none">
-                    {row.duration}ms
-                  </span>
+const variants = {
+  default: defaultRows,
+  'message-queue': messageQueueRows,
+} as const;
+
+type Variant = keyof typeof variants;
+
+interface AgentTracesProps {
+  variant?: Variant;
+}
+
+export const AgentTraces = ({ variant = 'default' }: AgentTracesProps) => {
+  const rows = variants[variant];
+
+  return (
+    <div className="not-prose my-8 rounded-lg border bg-card p-4 sm:p-6">
+      <div className="space-y-2 w-full">
+        {rows.map((row, index) => (
+          <div
+            key={`${row.label}-${index}`}
+            className="flex flex-col overflow-hidden"
+            style={{
+              marginLeft: `${row.start}%`,
+              width: `${row.duration}%`,
+            }}
+          >
+            <div className="relative h-6 w-full">
+              <motion.div
+                initial={{ width: 0, opacity: 0 }}
+                whileInView={{ width: 'auto', opacity: 1 }}
+                viewport={{ once: true, amount: 0.8 }}
+                transition={{
+                  duration: 0.55,
+                  delay: index * 0.12,
+                  ease: [0.22, 1, 0.36, 1],
+                }}
+                className={cn(
+                  'h-full rounded-sm border overflow-hidden',
+                  row.className
                 )}
-              </div>
-            </motion.div>
+              >
+                <div className="flex justify-between items-center h-full px-2">
+                  <span className="text-[10px] sm:text-[11px] font-mono font-medium text-foreground truncate leading-none">
+                    {row.label}
+                  </span>
+                  {index === 0 && (
+                    <span className="text-[10px] sm:text-[11px] hidden sm:inline leading-none">
+                      {row.duration}ms
+                    </span>
+                  )}
+                </div>
+              </motion.div>
+            </div>
           </div>
-        </div>
-      ))}
+        ))}
+      </div>
     </div>
-  </div>
-);
+  );
+};
diff --git a/docs/content/guides/ai-agents/message-queueing.mdx b/docs/content/guides/ai-agents/message-queueing.mdx
index 19338d466..1f3009c09 100644
--- a/docs/content/guides/ai-agents/message-queueing.mdx
+++ b/docs/content/guides/ai-agents/message-queueing.mdx
@@ -2,10 +2,14 @@
 title: Queueing User Messages
 ---
 
+import { AgentTraces } from '@/components/guides/agent-traces';
+
 In some scenarios, you want to queue new messages into an ongoing AI agent conversation. For example, when a user sends follow-up messages while the agent is still processing, or when external events need to influence the conversation mid-stream.
 
 Workflow DevKit's [`createWebhook()`](/docs/api-reference/workflow/create-webhook) enables this pattern: creating a webhook that can be called multiple times, iterating over incoming requests, and continuing the agent conversation with each new message.
 
+<AgentTraces variant="message-queue" />
+
 ## How It Works
 
 <Steps>

From dad2a63fd71dd114efe052bb22214fb7fc3803d1 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 17:04:34 -0800
Subject: [PATCH 22/38] remove auto-close example

---
 .../guides/ai-agents/message-queueing.mdx     | 61 -------------------
 1 file changed, 61 deletions(-)

diff --git a/docs/content/guides/ai-agents/message-queueing.mdx b/docs/content/guides/ai-agents/message-queueing.mdx
index 1f3009c09..bfce508bb 100644
--- a/docs/content/guides/ai-agents/message-queueing.mdx
+++ b/docs/content/guides/ai-agents/message-queueing.mdx
@@ -346,67 +346,6 @@ export async function collaborativeChatWorkflow() {
 }
 ```
 
-### Timeout-Based Auto-Close
-
-Automatically end the conversation after a period of inactivity:
-
-```typescript lineNumbers
-import { createWebhook, getWritable, sleep } from 'workflow';
-
-export async function chatWithTimeoutWorkflow(initialMessage: string) {
-  'use workflow';
-
-  const writable = getWritable<UIMessageChunk>();
-  const webhook = createWebhook();
-  const TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
-
-  await emitWebhookUrl(webhook.url);
-
-  const agent = new DurableAgent({
-    model: 'anthropic/claude-sonnet',
-    system: 'You are a helpful assistant.',
-  });
-
-  const messages: ModelMessage[] = [
-    { role: 'user', content: initialMessage },
-  ];
-
-  const { messages: updated } = await agent.stream({
-    writable,
-    messages,
-    preventClose: true,
-  });
-  messages.push(...updated.slice(messages.length));
-
-  // Race between webhook messages and timeout
-  let timedOut = false;
-
-  for await (const request of webhook) {
-    const { message } = await request.json();
-
-    if (message === '/done') break;
-
-    messages.push({ role: 'user', content: message });
-
-    const { messages: latest } = await agent.stream({
-      writable,
-      messages,
-      preventClose: true,
-      sendStart: false,
-    });
-    messages.push(...latest.slice(messages.length));
-  }
-
-  if (timedOut) {
-    // Notify the user the session expired
-    await emitTimeout(writable);
-  }
-
-  await closeStream(writable);
-  return { messages, timedOut };
-}
-```
-
 ## Related Documentation
 
 - [Human-in-the-Loop](/guides/ai-agents/human-in-the-loop) - Using hooks for approval workflows

From 249bf54dbcbf0ab929b1aae04dc22a08b4471808 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 17:30:24 -0800
Subject: [PATCH 23/38] Queueing

---
 docs/components/guides/agent-traces.tsx       |   8 +-
 .../guides/ai-agents/message-queueing.mdx     | 408 ++++++++----------
 2 files changed, 178 insertions(+), 238 deletions(-)

diff --git a/docs/components/guides/agent-traces.tsx b/docs/components/guides/agent-traces.tsx
index 1e44a0243..3bc495c03 100644
--- a/docs/components/guides/agent-traces.tsx
+++ b/docs/components/guides/agent-traces.tsx
@@ -53,8 +53,8 @@ const messageQueueRows: TraceRow[] = [
   {
     label: 'hook.enqueue()',
     className: colors.webhook,
-    start: 18,
-    duration: 18,
+    start: 12,
+    duration: 24,
   },
   {
     label: 'tool.checkDB()',
@@ -66,8 +66,8 @@ const messageQueueRows: TraceRow[] = [
   {
     label: 'hook.enqueue()',
     className: colors.webhook,
-    start: 52,
-    duration: 18,
+    start: 46,
+    duration: 24,
   },
   {
     label: 'tool.search()',
diff --git a/docs/content/guides/ai-agents/message-queueing.mdx b/docs/content/guides/ai-agents/message-queueing.mdx
index bfce508bb..9385be044 100644
--- a/docs/content/guides/ai-agents/message-queueing.mdx
+++ b/docs/content/guides/ai-agents/message-queueing.mdx
@@ -6,7 +6,9 @@ import { AgentTraces } from '@/components/guides/agent-traces';
 
 In some scenarios, you want to queue new messages into an ongoing AI agent conversation. For example, when a user sends follow-up messages while the agent is still processing, or when external events need to influence the conversation mid-stream.
 
-Workflow DevKit's [`createWebhook()`](/docs/api-reference/workflow/create-webhook) enables this pattern: creating a webhook that can be called multiple times, iterating over incoming requests, and continuing the agent conversation with each new message.
+Workflow DevKit's [`defineHook()`](/docs/api-reference/workflow/define-hook) enables this pattern: defining a typed hook that can be resumed programmatically via an API endpoint, allowing both users and backend systems to enqueue messages for an existing workflow run.
+
+Messages get queued until the next tool call gets executed, and then get flushed to the AI call with the tool call results.
 
 <AgentTraces variant="message-queue" />
 
@@ -15,19 +17,19 @@ Workflow DevKit's [`createWebhook()`](/docs/api-reference/workflow/create-webhoo
 <Steps>
 
 <Step>
-A webhook is created and its URL is sent to the client, allowing them to send follow-up messages.
+A hook is defined with a schema for incoming messages, and the workflow creates instances of this hook in a loop.
 </Step>
 
 <Step>
-The agent processes the initial message and returns the updated conversation history.
+The agent processes messages and returns the updated conversation history.
 </Step>
 
 <Step>
-The workflow enters a loop, waiting for webhook calls using `for await...of`.
+The workflow waits for the hook to be resumed, then processes the new message.
 </Step>
 
 <Step>
-Each webhook call triggers another `agent.stream()` with the new message appended to the conversation.
+An API endpoint accepts a `runId` and `message`, resuming the hook programmatically.
 </Step>
 
 <Step>
@@ -38,317 +40,255 @@ A special command (like `/done`) signals the end of the conversation.
 
 ## Implementation
 
-<Steps>
+<Tabs items={['Workflow', 'API Routes', 'Hook Definition']}>
 
-<Step>
-### Create the Chat Workflow
+<Tab value="Workflow">
 
-The workflow creates a webhook and loops over incoming messages:
+The workflow creates hook instances in a loop, waiting for each message:
 
-```typescript title="ai/chat-workflow.ts" lineNumbers
+```typescript title="app/api/chat/workflow.ts" lineNumbers
 import { DurableAgent } from '@workflow/ai/agent';
 import type { ModelMessage, UIMessageChunk } from 'ai';
-import { createWebhook, getWritable } from 'workflow';
+import { getWritable } from 'workflow';
+import { chatMessageHook } from '@/ai/hooks/chat-message';
 
 export async function chatWorkflow(initialMessage: string) {
   'use workflow';
 
   const writable = getWritable<UIMessageChunk>();
 
-  // Create a webhook for receiving follow-up messages // [!code highlight]
-  const webhook = createWebhook(); // [!code highlight]
+  const agent = new DurableAgent({ /* ... agent setup */ })
 
-  // Emit the webhook URL to the client
-  await emitWebhookUrl(webhook.url);
+  const hook = chatMessageHook.create(); // [!code highlight]
 
-  const agent = new DurableAgent({
-    model: 'anthropic/claude-sonnet',
-    system: 'You are a helpful assistant.',
-  });
-
-  // Start with the initial message
-  const messages: ModelMessage[] = [
-    { role: 'user', content: initialMessage },
-  ];
+  while (true) { // [!code highlight]
 
-  // Process the initial message // [!code highlight]
-  const { messages: updatedMessages } = await agent.stream({ // [!code highlight]
-    writable, // [!code highlight]
-    messages, // [!code highlight]
-    preventClose: true, // Keep stream open for follow-ups // [!code highlight]
-  }); // [!code highlight]
-  messages.push(...updatedMessages.slice(messages.length));
-
-  // Loop over incoming webhook requests // [!code highlight]
-  for await (const request of webhook) { // [!code highlight]
-    const { message } = await request.json();
+    // Do a stream step
+    const { messages: latest } = await agent.stream({
+      writable,
+      messages,
+      preventClose: true, // [!code highlight] keep agent open for follow-ups
+    });
 
-    // Check for end-of-conversation signal
+    // Then check if any messages have been queued, or wait for a new one to arrive
+    const { message, username } = await hook; // [!code highlight]
     if (message === '/done') {
       break;
     }
-
-    // Add the new user message
-    messages.push({ role: 'user', content: message });
-
-    // Continue the conversation // [!code highlight]
-    const { messages: latestMessages } = await agent.stream({ // [!code highlight]
-      writable, // [!code highlight]
-      messages, // [!code highlight]
-      preventClose: true, // [!code highlight]
-      sendStart: false, // Don't send another start chunk // [!code highlight]
-    }); // [!code highlight]
-    messages.push(...latestMessages.slice(messages.length));
+    const content = username ? `[${username}]: ${message}` : message;
+    messages.push({ role: 'user', content }); // [!code highlight] add to conversation
   }
 
-  // Close the stream when done
-  await closeStream(writable);
+  // [... close stream]
 
   return { messages };
 }
-
-async function emitWebhookUrl(url: string) {
-  'use step';
-
-  const writable = getWritable<UIMessageChunk>();
-  const writer = writable.getWriter();
-
-  await writer.write({
-    type: 'data-chat-webhook',
-    data: { url },
-  });
-
-  writer.releaseLock();
-}
-
-async function closeStream(writable: WritableStream<UIMessageChunk>) {
-  'use step';
-
-  const writer = writable.getWriter();
-  await writer.write({ type: 'finish' });
-  writer.releaseLock();
-  await writable.close();
-}
 ```
 
 <Callout type="info">
-The `for await...of` syntax iterates over webhook requests as they arrive. Each iteration waits for the next request, allowing the workflow to suspend without consuming resources.
+Each `chatMessageHook.create()` generates a new hook instance. The workflow suspends at `await hook` until the hook is resumed via the API.
 </Callout>
 
-</Step>
+</Tab>
 
-<Step>
-### Client-Side: Send Follow-Up Messages
+<Tab value="API Routes">
 
-The client receives the webhook URL and can send messages directly:
+Two endpoints: one to start the workflow, one to enqueue messages:
 
-```typescript title="lib/chat-api.ts" lineNumbers
-export async function sendMessage(webhookUrl: string, message: string) {
-  await fetch(webhookUrl, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ message }),
-  });
-}
+```typescript title="app/api/chat/route.ts" lineNumbers
+import { createUIMessageStreamResponse, convertToModelMessages } from 'ai';
+import { start } from 'workflow/api';
+import { chatWorkflow } from './workflow';
+
+export async function POST(req: Request) {
+  const { message } = await req.json();
+
+  const run = await start(chatWorkflow, [message]); // [!code highlight]
 
-export async function endConversation(webhookUrl: string) {
-  await fetch(webhookUrl, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ message: '/done' }),
+  return createUIMessageStreamResponse({
+    stream: run.readable,
+    headers: {
+      'X-Run-Id': run.id, // Return runId to client // [!code highlight]
+    },
   });
 }
 ```
 
-</Step>
+```typescript title="app/api/chat/message/route.ts" lineNumbers
+import { chatMessageHook } from '@/ai/hooks/chat-message';
 
-<Step>
-### Build the Chat Component
+export async function POST(req: Request) {
+  const { runId, message, username } = await req.json();
 
-A React component that handles the conversation:
+  try {
+    await chatMessageHook.resume(runId, { message, username }); // [!code highlight]
+    return Response.json({ success: true });
+  } catch (error) {
+    return Response.json(
+      { error: 'Failed to enqueue message' },
+      { status: 400 }
+    );
+  }
+}
+```
 
-```typescript title="components/chat.tsx" lineNumbers
-'use client';
+This API can be called by:
 
-import { useState, useEffect } from 'react';
-import { sendMessage, endConversation } from '@/lib/chat-api';
+- **UI clients** sending follow-up messages
+- **Backend services** injecting system events
+- **External systems** via API integration
 
-interface ChatProps {
-  webhookUrl: string | null;
-  onEnd?: () => void;
-}
+</Tab>
 
-export function Chat({ webhookUrl, onEnd }: ChatProps) {
-  const [input, setInput] = useState('');
-  const [isSending, setIsSending] = useState(false);
+<Tab value="Hook Definition">
 
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    if (!webhookUrl || !input.trim()) return;
+Define a typed hook for incoming messages:
 
-    setIsSending(true);
-    try {
-      await sendMessage(webhookUrl, input);
-      setInput('');
-    } finally {
-      setIsSending(false);
-    }
-  };
-
-  const handleEnd = async () => {
-    if (!webhookUrl) return;
-    await endConversation(webhookUrl);
-    onEnd?.();
-  };
-
-  return (
-    <div className="space-y-4">
-      <form onSubmit={handleSubmit} className="flex gap-2">
-        <input
-          value={input}
-          onChange={(e) => setInput(e.target.value)}
-          placeholder="Type a message..."
-          className="flex-1 border rounded px-3 py-2"
-          disabled={!webhookUrl || isSending}
-        />
-        <button
-          type="submit"
-          disabled={!webhookUrl || isSending}
-          className="px-4 py-2 bg-blue-600 text-white rounded disabled:opacity-50"
-        >
-          Send
-        </button>
-      </form>
-
-      <button
-        onClick={handleEnd}
-        disabled={!webhookUrl}
-        className="text-sm text-gray-500 hover:text-gray-700"
-      >
-        End conversation
-      </button>
-    </div>
-  );
-}
+```typescript title="ai/hooks/chat-message.ts" lineNumbers
+import { defineHook } from 'workflow';
+import { z } from 'zod';
+
+export const chatMessageHook = defineHook({
+  schema: z.object({
+    message: z.string(),
+    username: z.string().optional(),
+  }),
+});
 ```
 
-</Step>
+</Tab>
 
-</Steps>
+</Tabs>
 
-## Use Cases
+## Client Integration
 
-### Multi-Turn Chat with Tools
+The client stores the `runId` from the initial response and uses it for follow-ups:
 
-Allow users to continue chatting while the agent has access to tools:
+```typescript title="hooks/use-chat-with-queue.ts" lineNumbers
+'use client';
 
-```typescript lineNumbers
-import { DurableAgent } from '@workflow/ai/agent';
-import type { ModelMessage, UIMessageChunk } from 'ai';
-import { createWebhook, getWritable } from 'workflow';
-import { searchTool, calculatorTool } from './tools';
+import { useState, useCallback } from 'react';
 
-export async function chatWithToolsWorkflow(initialMessage: string) {
-  'use workflow';
+export function useChatWithQueue() {
+  const [runId, setRunId] = useState<string | null>(null);
 
-  const writable = getWritable<UIMessageChunk>();
-  const webhook = createWebhook();
+  const startChat = useCallback(async (message: string) => {
+    const response = await fetch('/api/chat', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ message }),
+    });
 
-  await emitWebhookUrl(webhook.url);
+    // Store runId for follow-up messages // [!code highlight]
+    const id = response.headers.get('X-Run-Id'); // [!code highlight]
+    setRunId(id); // [!code highlight]
 
-  const agent = new DurableAgent({
-    model: 'anthropic/claude-sonnet',
-    system: 'You are a helpful assistant with access to search and calculation tools.',
-    tools: {
-      search: searchTool,
-      calculate: calculatorTool,
-    },
-  });
+    return response.body; // Stream for UI rendering
+  }, []);
 
-  const messages: ModelMessage[] = [
-    { role: 'user', content: initialMessage },
-  ];
+  const sendMessage = useCallback(async (message: string) => {
+    if (!runId) return;
 
-  // Process initial message (agent may call tools)
-  const { messages: updated } = await agent.stream({
-    writable,
-    messages,
-    preventClose: true,
-  });
-  messages.push(...updated.slice(messages.length));
+    await fetch('/api/chat/message', { // [!code highlight]
+      method: 'POST', // [!code highlight]
+      headers: { 'Content-Type': 'application/json' }, // [!code highlight]
+      body: JSON.stringify({ runId, message }), // [!code highlight]
+    }); // [!code highlight]
+  }, [runId]);
+
+  const endChat = useCallback(async () => {
+    if (!runId) return;
+    await fetch('/api/chat/message', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ runId, message: '/done' }),
+    });
+    setRunId(null);
+  }, [runId]);
 
-  // Continue conversation with follow-ups
-  for await (const request of webhook) {
-    const { message } = await request.json();
+  return { runId, startChat, sendMessage, endChat };
+}
+```
 
-    if (message === '/done') break;
+## Use Cases
 
-    messages.push({ role: 'user', content: message });
+### System Event Injection
 
-    const { messages: latest } = await agent.stream({
-      writable,
-      messages,
-      preventClose: true,
-      sendStart: false,
-    });
-    messages.push(...latest.slice(messages.length));
-  }
+Backend services can inject messages based on external events:
 
-  await closeStream(writable);
-  return { messages };
+```typescript title="app/api/webhooks/payment/route.ts" lineNumbers
+import { chatMessageHook } from '@/ai/hooks/chat-message';
+
+export async function POST(req: Request) {
+  const { runId, paymentStatus, amount } = await req.json();
+
+  // Inject payment notification into the conversation // [!code highlight]
+  await chatMessageHook.resume(runId, { // [!code highlight]
+    message: `Payment ${paymentStatus}: $${amount}`, // [!code highlight]
+    username: 'system', // [!code highlight]
+  }); // [!code highlight]
+
+  return Response.json({ success: true });
 }
 ```
 
 ### Collaborative Sessions
 
-Multiple users can send messages to the same conversation:
+Multiple users can send messages to the same conversation by sharing the `runId`:
 
 ```typescript lineNumbers
-export async function collaborativeChatWorkflow() {
-  'use workflow';
+// Any participant can enqueue messages using the shared runId
+await fetch('/api/chat/message', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    runId: sharedRunId,
+    message: 'I have a question about that',
+    username: 'Alice',
+  }),
+});
+```
 
-  const writable = getWritable<UIMessageChunk>();
-  const webhook = createWebhook();
+### Scheduled Follow-ups
 
-  // Share this URL with all participants
-  await emitWebhookUrl(webhook.url);
+Use `sleep()` in combination with hooks for time-delayed messages:
 
-  const agent = new DurableAgent({
-    model: 'anthropic/claude-sonnet',
-    system: 'You are facilitating a group discussion. Address participants by name when they identify themselves.',
-  });
+```typescript lineNumbers
+import { sleep } from 'workflow';
 
-  const messages: ModelMessage[] = [];
+export async function chatWithRemindersWorkflow(initialMessage: string) {
+  'use workflow';
 
-  for await (const request of webhook) {
-    const { message, username } = await request.json();
+  // ... agent setup (see "Building Durable AI Agents" guide)
 
-    if (message === '/done') break;
+  while (true) {
+    const hook = chatMessageHook.create();
 
-    // Include the username in the message
-    const formattedMessage = username
-      ? `[${username}]: ${message}`
-      : message;
+    // Race between user message and reminder timeout // [!code highlight]
+    const result = await Promise.race([ // [!code highlight]
+      hook.then((data) => ({ type: 'message' as const, data })), // [!code highlight]
+      sleep('5m').then(() => ({ type: 'timeout' as const })), // [!code highlight]
+    ]); // [!code highlight]
 
-    messages.push({ role: 'user', content: formattedMessage });
+    if (result.type === 'timeout') {
+      messages.push({
+        role: 'user',
+        content: '[System: User has been idle for 5 minutes]',
+      });
+    } else if (result.data.message === '/done') {
+      break;
+    } else {
+      messages.push({ role: 'user', content: result.data.message });
+    }
 
-    const { messages: latest } = await agent.stream({
-      writable,
-      messages,
-      preventClose: true,
-      sendStart: messages.length === 1, // Only send start on first message
-    });
-    messages.push(...latest.slice(messages.length));
+    // Continue conversation...
   }
-
-  await closeStream(writable);
-  return { messages };
 }
 ```
 
 ## Related Documentation
 
+- [Building Durable AI Agents](/guides/ai-agents) - Complete guide to creating durable agents
 - [Human-in-the-Loop](/guides/ai-agents/human-in-the-loop) - Using hooks for approval workflows
-- [Hooks & Webhooks](/docs/foundations/hooks) - Complete guide to hooks and webhooks
-- [`createWebhook()` API Reference](/docs/api-reference/workflow/create-webhook) - Webhook configuration options
-- [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Full API documentation
+- [Sleep and Delays](/guides/ai-agents/sleep-and-delays) - Time-based workflow patterns
+- [`defineHook()` API Reference](/docs/api-reference/workflow/define-hook) - Hook configuration options

From 634df7f02fe3aefd92c7e91ed6417b28c15e7c7c Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 18:10:33 -0800
Subject: [PATCH 24/38] prepareStep, queueing, and modeling

---
 .../workflow-ai/durable-agent.mdx             | 119 ++++++-
 .../ai-agents/chat-session-modeling.mdx       | 294 ++++++++++++++++
 .../guides/ai-agents/message-queueing.mdx     | 327 +++++-------------
 docs/content/guides/ai-agents/meta.json       |   1 +
 4 files changed, 496 insertions(+), 245 deletions(-)
 create mode 100644 docs/content/guides/ai-agents/chat-session-modeling.mdx

diff --git a/docs/content/docs/api-reference/workflow-ai/durable-agent.mdx b/docs/content/docs/api-reference/workflow-ai/durable-agent.mdx
index 33fed12c3..acbd3fb97 100644
--- a/docs/content/docs/api-reference/workflow-ai/durable-agent.mdx
+++ b/docs/content/docs/api-reference/workflow-ai/durable-agent.mdx
@@ -74,6 +74,26 @@ import type { DurableAgentStreamOptions } from "@workflow/ai/agent";
 export default DurableAgentStreamOptions;`}
 />
 
+### PrepareStepInfo
+
+Information passed to the `prepareStep` callback:
+
+<TSDoc
+definition={`
+import type { PrepareStepInfo } from "@workflow/ai/agent";
+export default PrepareStepInfo;`}
+/>
+
+### PrepareStepResult
+
+Return type from the `prepareStep` callback:
+
+<TSDoc
+definition={`
+import type { PrepareStepResult } from "@workflow/ai/agent";
+export default PrepareStepResult;`}
+/>
+
 ## Key Features
 
 - **Durable Execution**: Agents can be interrupted and resumed without losing state
@@ -87,6 +107,7 @@ export default DurableAgentStreamOptions;`}
 - Tools can use core library features like `sleep()` and Hooks within their `execute` functions
 - The agent processes tool calls iteratively until completion
 - The `stream()` method returns `{ messages }` containing the full conversation history, including initial messages, assistant responses, and tool results
+- The `prepareStep` callback runs before each step and can modify the model or messages dynamically
 
 ## Examples
 
@@ -300,8 +321,104 @@ async function agentWithLibraryFeaturesWorkflow(userRequest: string) {
 }
 ```
 
+### Dynamic Context with prepareStep
+
+Use `prepareStep` to modify settings before each step in the agent loop:
+
+```typescript
+import { DurableAgent } from '@workflow/ai/agent';
+import { getWritable } from 'workflow';
+import type { UIMessageChunk } from 'ai';
+
+async function agentWithPrepareStep(userMessage: string) {
+  'use workflow';
+
+  const agent = new DurableAgent({
+    model: 'openai/gpt-4.1-mini', // Default model
+    system: 'You are a helpful assistant.',
+  });
+
+  await agent.stream({
+    messages: [{ role: 'user', content: userMessage }],
+    writable: getWritable<UIMessageChunk>(),
+    prepareStep: async ({ stepNumber, messages }) => {
+      // Switch to a stronger model for complex reasoning after initial steps
+      if (stepNumber > 2 && messages.length > 10) {
+        return {
+          model: 'anthropic/claude-sonnet-4.5',
+        };
+      }
+
+      // Trim context if messages grow too large
+      if (messages.length > 20) {
+        return {
+          messages: [
+            messages[0], // Keep system message
+            ...messages.slice(-10), // Keep last 10 messages
+          ],
+        };
+      }
+
+      return {}; // No changes
+    },
+  });
+}
+```
+
+### Message Injection with prepareStep
+
+Inject messages from external sources (like hooks) before each LLM call:
+
+```typescript
+import { DurableAgent } from '@workflow/ai/agent';
+import { getWritable, defineHook } from 'workflow';
+import type { UIMessageChunk } from 'ai';
+
+const messageHook = defineHook<{ message: string }>();
+
+async function agentWithMessageQueue(initialMessage: string) {
+  'use workflow';
+
+  const messageQueue: Array<{ role: 'user'; content: string }> = [];
+
+  // Listen for incoming messages via hook
+  const hook = messageHook.create();
+  hook.then(({ message }) => {
+    messageQueue.push({ role: 'user', content: message });
+  });
+
+  const agent = new DurableAgent({
+    model: 'anthropic/claude-haiku-4.5',
+    system: 'You are a helpful assistant.',
+  });
+
+  await agent.stream({
+    messages: [{ role: 'user', content: initialMessage }],
+    writable: getWritable<UIMessageChunk>(),
+    prepareStep: ({ messages }) => {
+      // Inject queued messages before the next step
+      if (messageQueue.length > 0) {
+        const newMessages = messageQueue.splice(0);
+        return {
+          messages: [
+            ...messages,
+            ...newMessages.map(m => ({
+              role: m.role,
+              content: [{ type: 'text' as const, text: m.content }],
+            })),
+          ],
+        };
+      }
+      return {};
+    },
+  });
+}
+```
+
 ## See Also
 
+- [Building Durable AI Agents](/guides/ai-agents) - Complete guide to creating durable agents
+- [Queueing User Messages](/guides/ai-agents/message-queueing) - Using prepareStep for message injection
 - [WorkflowChatTransport](/docs/api-reference/workflow-ai/workflow-chat-transport) - Transport layer for AI SDK streams
 - [Workflows and Steps](/docs/foundations/workflows-and-steps) - Understanding workflow fundamentals
-- [AI SDK Documentation](https://ai-sdk.dev/docs) - AI SDK documentation reference
+- [AI SDK Loop Control](https://ai-sdk.dev/docs/agents/loop-control) - AI SDK's agent loop control patterns
diff --git a/docs/content/guides/ai-agents/chat-session-modeling.mdx b/docs/content/guides/ai-agents/chat-session-modeling.mdx
new file mode 100644
index 000000000..47b8ede25
--- /dev/null
+++ b/docs/content/guides/ai-agents/chat-session-modeling.mdx
@@ -0,0 +1,294 @@
+---
+title: Chat Session Modeling
+---
+
+Chat sessions in AI agents can be modeled at different layers of your architecture. The choice affects state ownership, latency characteristics, and how you handle interruptions and reconnections. Workflow DevKit supports two primary patterns.
+
+## Single-Turn Workflows
+
+Each user message triggers a new workflow run. The client owns the conversation history and sends the full message array with each request.
+
+<Tabs items={['Workflow', 'API Route', 'Client']}>
+
+<Tab value="Workflow">
+
+```typescript title="app/api/chat/workflow.ts" lineNumbers
+import { DurableAgent } from '@workflow/ai/agent';
+import { getWritable } from 'workflow';
+import type { ModelMessage, UIMessageChunk } from 'ai';
+
+export async function chatWorkflow(messages: ModelMessage[]) {
+  'use workflow';
+
+  const writable = getWritable<UIMessageChunk>();
+
+  const agent = new DurableAgent({
+    model: 'anthropic/claude-sonnet-4',
+    system: 'You are a helpful assistant.',
+    tools: { /* ... */ },
+  });
+
+  const { messages: result } = await agent.stream({
+    messages, // [!code highlight] Full history from client
+    writable,
+  });
+
+  return { messages: result };
+}
+```
+
+</Tab>
+
+<Tab value="API Route">
+
+```typescript title="app/api/chat/route.ts" lineNumbers
+import { createUIMessageStreamResponse, convertToModelMessages } from 'ai';
+import { start } from 'workflow/api';
+import { chatWorkflow } from './workflow';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const modelMessages = convertToModelMessages(messages);
+
+  const run = await start(chatWorkflow, [modelMessages]); // [!code highlight]
+
+  return createUIMessageStreamResponse({
+    stream: run.readable,
+  });
+}
+```
+
+</Tab>
+
+<Tab value="Client">
+
+```typescript title="app/chat.tsx" lineNumbers
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+
+export function Chat() {
+  const { messages, input, handleInputChange, handleSubmit } = useChat({
+    api: '/api/chat', // [!code highlight] AI SDK manages message history
+  });
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* ... render messages ... */}
+      <input value={input} onChange={handleInputChange} />
+    </form>
+  );
+}
+```
+
+</Tab>
+
+</Tabs>
+
+**Characteristics:**
+
+- Client owns conversation state (via AI SDK's `useChat`)
+- Each turn is independently retryable
+- Simpler server-side logic; no cross-turn state management
+- Workflow results are self-contained
+
+This is the pattern shown at the start of [Building Durable AI Agents](/guides/ai-agents).
+
+## Multi-Turn Workflows
+
+A single workflow handles the entire conversation session. The server owns conversation state, and clients inject new messages via hooks.
+
+<Tabs items={['Workflow', 'API Routes', 'Hook Definition', 'Client']}>
+
+<Tab value="Workflow">
+
+```typescript title="app/api/chat/workflow.ts" lineNumbers
+import { DurableAgent } from '@workflow/ai/agent';
+import { getWritable } from 'workflow';
+import { chatMessageHook } from '@/ai/hooks/chat-message';
+import type { ModelMessage, UIMessageChunk } from 'ai';
+
+export async function chatWorkflow(threadId: string, initialMessage: string) {
+  'use workflow';
+
+  const writable = getWritable<UIMessageChunk>();
+  const messages: ModelMessage[] = [{ role: 'user', content: initialMessage }];
+
+  const agent = new DurableAgent({
+    model: 'anthropic/claude-sonnet-4',
+    system: 'You are a helpful assistant.',
+    tools: { /* ... */ },
+  });
+
+  // Create hook with thread-specific token for resumption // [!code highlight]
+  const hook = chatMessageHook.create({ token: `thread:${threadId}` }); // [!code highlight]
+
+  while (true) {
+    // Process current messages
+    const { messages: result } = await agent.stream({
+      messages,
+      writable,
+      preventClose: true, // [!code highlight] Keep stream open for follow-ups
+    });
+    messages.push(...result.slice(messages.length));
+
+    // Wait for next user message // [!code highlight]
+    const { message } = await hook; // [!code highlight]
+    if (message === '/done') break;
+
+    messages.push({ role: 'user', content: message });
+  }
+
+  return { messages };
+}
+```
+
+</Tab>
+
+<Tab value="API Routes">
+
+Two endpoints: one to start the session, one to send follow-up messages.
+
+```typescript title="app/api/chat/route.ts" lineNumbers
+import { createUIMessageStreamResponse } from 'ai';
+import { start } from 'workflow/api';
+import { chatWorkflow } from './workflow';
+
+export async function POST(req: Request) {
+  const { threadId, message } = await req.json();
+
+  const run = await start(chatWorkflow, [threadId, message]); // [!code highlight]
+
+  return createUIMessageStreamResponse({
+    stream: run.readable,
+    headers: { 'X-Thread-Id': threadId },
+  });
+}
+```
+
+```typescript title="app/api/chat/message/route.ts" lineNumbers
+import { chatMessageHook } from '@/ai/hooks/chat-message';
+
+export async function POST(req: Request) {
+  const { threadId, message } = await req.json();
+
+  await chatMessageHook.resume(`thread:${threadId}`, { message }); // [!code highlight]
+
+  return Response.json({ success: true });
+}
+```
+
+</Tab>
+
+<Tab value="Hook Definition">
+
+```typescript title="ai/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">
+
+```typescript title="hooks/use-multi-turn-chat.ts" lineNumbers
+'use client';
+
+import { useState, useCallback } from 'react';
+
+export function useMultiTurnChat() {
+  const [threadId, setThreadId] = useState<string | null>(null);
+
+  const startSession = useCallback(async (message: string) => {
+    const newThreadId = crypto.randomUUID();
+    setThreadId(newThreadId);
+
+    const response = await fetch('/api/chat', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ threadId: newThreadId, message }),
+    });
+
+    return response.body; // Stream for UI rendering
+  }, []);
+
+  const sendMessage = useCallback(async (message: string) => {
+    if (!threadId) return;
+
+    await fetch('/api/chat/message', { // [!code highlight]
+      method: 'POST', // [!code highlight]
+      headers: { 'Content-Type': 'application/json' }, // [!code highlight]
+      body: JSON.stringify({ threadId, message }), // [!code highlight]
+    }); // [!code highlight]
+  }, [threadId]);
+
+  const endSession = useCallback(async () => {
+    if (!threadId) return;
+    await fetch('/api/chat/message', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ threadId, message: '/done' }),
+    });
+    setThreadId(null);
+  }, [threadId]);
+
+  return { threadId, startSession, sendMessage, endSession };
+}
+```
+
+</Tab>
+
+</Tabs>
+
+**Characteristics:**
+
+- Server owns conversation state
+- Single workflow spans the entire session
+- Enables multi-party injection (webhooks, system events, other users)
+- Workflow can coordinate cross-turn behavior (reminders, timeouts)
+
+## Choosing a Pattern
+
+| Consideration | Single-Turn | Multi-Turn |
+|--------------|-------------|------------|
+| State ownership | Client | Server |
+| Message injection from backend | Requires external coordination | Native via hooks |
+| Session continuity after client disconnect | Lost (new run per turn) | Preserved |
+| Workflow complexity | Lower | Higher |
+| Observability scope | Per-turn traces | Full session traces |
+
+**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. Server-owned state, native message injection, and full session observability become increasingly valuable as your agent matures.
+
+**Single-turn works well when adapting existing architectures.** If you already have client-side message state management (e.g., via AI SDK's `useChat`), single-turn workflows slot in with minimal changes. Each turn maps cleanly to an independent workflow run.
+
+## Multi-Party Injection
+
+The multi-turn pattern enables backend systems to inject messages into active conversations:
+
+```typescript title="app/api/webhooks/order-update/route.ts" lineNumbers
+import { chatMessageHook } from '@/ai/hooks/chat-message';
+
+export async function POST(req: Request) {
+  const { threadId, orderStatus } = await req.json();
+
+  // Inject order update into the conversation // [!code highlight]
+  await chatMessageHook.resume(`thread:${threadId}`, { // [!code highlight]
+    message: `[System] Order status updated: ${orderStatus}`, // [!code highlight]
+  }); // [!code highlight]
+
+  return Response.json({ success: true });
+}
+```
+
+## Related Documentation
+
+- [Building Durable AI Agents](/guides/ai-agents) - Foundation guide for durable agents
+- [Message Queueing](/guides/ai-agents/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
diff --git a/docs/content/guides/ai-agents/message-queueing.mdx b/docs/content/guides/ai-agents/message-queueing.mdx
index 9385be044..1ac8cbfb0 100644
--- a/docs/content/guides/ai-agents/message-queueing.mdx
+++ b/docs/content/guides/ai-agents/message-queueing.mdx
@@ -2,293 +2,132 @@
 title: Queueing User Messages
 ---
 
-import { AgentTraces } from '@/components/guides/agent-traces';
+When using [multi-turn workflows](/guides/ai-agents/chat-session-modeling#multi-turn-workflows), messages typically arrive between agent turns—the workflow waits at a hook, receives a message, then starts a new turn. But sometimes you need to inject messages *during* an agent's turn, before tool calls complete or while the model is reasoning.
 
-In some scenarios, you want to queue new messages into an ongoing AI agent conversation. For example, when a user sends follow-up messages while the agent is still processing, or when external events need to influence the conversation mid-stream.
+`DurableAgent`'s `prepareStep` callback enables this by running before each step in the agent loop, giving you a chance to inject queued messages into the conversation.
 
-Workflow DevKit's [`defineHook()`](/docs/api-reference/workflow/define-hook) enables this pattern: defining a typed hook that can be resumed programmatically via an API endpoint, allowing both users and backend systems to enqueue messages for an existing workflow run.
+## When to Use This
 
-Messages get queued until the next tool call gets executed, and then get flushed to the AI call with the tool call results.
+Message queueing is useful when:
 
-<AgentTraces variant="message-queue" />
+- Users send follow-up messages while the agent is still processing tool calls
+- External systems need to inject context mid-turn (e.g., a webhook fires during processing)
+- You want messages to influence the agent's next step rather than waiting for the current turn to complete
 
-## How It Works
-
-<Steps>
-
-<Step>
-A hook is defined with a schema for incoming messages, and the workflow creates instances of this hook in a loop.
-</Step>
-
-<Step>
-The agent processes messages and returns the updated conversation history.
-</Step>
-
-<Step>
-The workflow waits for the hook to be resumed, then processes the new message.
-</Step>
-
-<Step>
-An API endpoint accepts a `runId` and `message`, resuming the hook programmatically.
-</Step>
+<Callout type="info">
+If you just need basic multi-turn conversations where messages arrive between turns, see [Chat Session Modeling](/guides/ai-agents/chat-session-modeling). This guide covers the more advanced case of injecting messages *during* turns.
+</Callout>
 
-<Step>
-A special command (like `/done`) signals the end of the conversation.
-</Step>
+## The `prepareStep` Callback
 
-</Steps>
+The `prepareStep` callback runs before each step in the agent loop. It receives the current state and can modify the messages sent to the model:
 
-## Implementation
+```typescript lineNumbers
+interface PrepareStepInfo {
+  model: string | (() => Promise<LanguageModelV2>);  // Current model
+  stepNumber: number;                                 // 0-indexed step count
+  steps: StepResult[];                               // Previous step results
+  messages: LanguageModelV2Prompt;                   // Messages to be sent
+}
 
-<Tabs items={['Workflow', 'API Routes', 'Hook Definition']}>
+interface PrepareStepResult {
+  model?: string | (() => Promise<LanguageModelV2>); // Override model
+  messages?: LanguageModelV2Prompt;                  // Override messages
+}
+```
 
-<Tab value="Workflow">
+## Injecting Queued Messages
 
-The workflow creates hook instances in a loop, waiting for each message:
+Combine a message queue with `prepareStep` to inject messages that arrive during processing:
 
 ```typescript title="app/api/chat/workflow.ts" lineNumbers
 import { DurableAgent } from '@workflow/ai/agent';
-import type { ModelMessage, UIMessageChunk } from 'ai';
+import type { UIMessageChunk } from 'ai';
 import { getWritable } from 'workflow';
 import { chatMessageHook } from '@/ai/hooks/chat-message';
 
-export async function chatWorkflow(initialMessage: string) {
+export async function chatWorkflow(threadId: string, initialMessage: string) {
   'use workflow';
 
   const writable = getWritable<UIMessageChunk>();
+  const messageQueue: Array<{ role: 'user'; content: string }> = []; // [!code highlight]
 
-  const agent = new DurableAgent({ /* ... agent setup */ })
-
-  const hook = chatMessageHook.create(); // [!code highlight]
-
-  while (true) { // [!code highlight]
-
-    // Do a stream step
-    const { messages: latest } = await agent.stream({
-      writable,
-      messages,
-      preventClose: true, // [!code highlight] keep agent open for follow-ups
-    });
-
-    // Then check if any messages have been queued, or wait for a new one to arrive
-    const { message, username } = await hook; // [!code highlight]
-    if (message === '/done') {
-      break;
-    }
-    const content = username ? `[${username}]: ${message}` : message;
-    messages.push({ role: 'user', content }); // [!code highlight] add to conversation
-  }
+  const agent = new DurableAgent({
+    model: 'anthropic/claude-haiku-4.5',
+    system: 'You are a helpful assistant.',
+    tools: { /* long-running tools */ },
+  });
 
-  // [... close stream]
+  // Listen for messages in background (non-blocking) // [!code highlight]
+  const hook = chatMessageHook.create({ token: `thread:${threadId}` }); // [!code highlight]
+  hook.then(({ message }) => { // [!code highlight]
+    messageQueue.push({ role: 'user', content: message }); // [!code highlight]
+  }); // [!code highlight]
 
-  return { messages };
+  await agent.stream({
+    messages: [{ role: 'user', content: initialMessage }],
+    writable,
+    prepareStep: ({ messages: currentMessages }) => { // [!code highlight]
+      // Inject any queued messages before the next LLM call // [!code highlight]
+      if (messageQueue.length > 0) { // [!code highlight]
+        const newMessages = messageQueue.splice(0); // Drain queue // [!code highlight]
+        return { // [!code highlight]
+          messages: [ // [!code highlight]
+            ...currentMessages, // [!code highlight]
+            ...newMessages.map(m => ({ // [!code highlight]
+              role: m.role, // [!code highlight]
+              content: [{ type: 'text' as const, text: m.content }], // [!code highlight]
+            })), // [!code highlight]
+          ], // [!code highlight]
+        }; // [!code highlight]
+      } // [!code highlight]
+      return {}; // [!code highlight]
+    }, // [!code highlight]
+  });
 }
 ```
 
+Messages sent via `chatMessageHook.resume()` accumulate in the queue and get injected before the next step—whether that's a tool call or another LLM request.
+
 <Callout type="info">
-Each `chatMessageHook.create()` generates a new hook instance. The workflow suspends at `await hook` until the hook is resumed via the API.
+The `prepareStep` callback receives messages in `LanguageModelV2Prompt` format (with content arrays), which is the internal format used by the AI SDK.
 </Callout>
 
-</Tab>
+## Other `prepareStep` Patterns
 
-<Tab value="API Routes">
+Beyond message injection, `prepareStep` supports other per-step modifications:
 
-Two endpoints: one to start the workflow, one to enqueue messages:
+**Context Management** — Trim old messages to stay within context limits:
 
-```typescript title="app/api/chat/route.ts" lineNumbers
-import { createUIMessageStreamResponse, convertToModelMessages } from 'ai';
-import { start } from 'workflow/api';
-import { chatWorkflow } from './workflow';
-
-export async function POST(req: Request) {
-  const { message } = await req.json();
-
-  const run = await start(chatWorkflow, [message]); // [!code highlight]
-
-  return createUIMessageStreamResponse({
-    stream: run.readable,
-    headers: {
-      'X-Run-Id': run.id, // Return runId to client // [!code highlight]
-    },
-  });
-}
-```
-
-```typescript title="app/api/chat/message/route.ts" lineNumbers
-import { chatMessageHook } from '@/ai/hooks/chat-message';
-
-export async function POST(req: Request) {
-  const { runId, message, username } = await req.json();
-
-  try {
-    await chatMessageHook.resume(runId, { message, username }); // [!code highlight]
-    return Response.json({ success: true });
-  } catch (error) {
-    return Response.json(
-      { error: 'Failed to enqueue message' },
-      { status: 400 }
-    );
+```typescript lineNumbers
+prepareStep: ({ messages }) => {
+  if (messages.length > 20) {
+    return {
+      messages: [
+        messages[0],            // Keep system message
+        ...messages.slice(-10), // Keep last 10 messages
+      ],
+    };
   }
+  return {};
 }
 ```
 
-This API can be called by:
-
-- **UI clients** sending follow-up messages
-- **Backend services** injecting system events
-- **External systems** via API integration
-
-</Tab>
-
-<Tab value="Hook Definition">
-
-Define a typed hook for incoming messages:
-
-```typescript title="ai/hooks/chat-message.ts" lineNumbers
-import { defineHook } from 'workflow';
-import { z } from 'zod';
-
-export const chatMessageHook = defineHook({
-  schema: z.object({
-    message: z.string(),
-    username: z.string().optional(),
-  }),
-});
-```
-
-</Tab>
-
-</Tabs>
-
-## Client Integration
-
-The client stores the `runId` from the initial response and uses it for follow-ups:
-
-```typescript title="hooks/use-chat-with-queue.ts" lineNumbers
-'use client';
-
-import { useState, useCallback } from 'react';
-
-export function useChatWithQueue() {
-  const [runId, setRunId] = useState<string | null>(null);
-
-  const startChat = useCallback(async (message: string) => {
-    const response = await fetch('/api/chat', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ message }),
-    });
-
-    // Store runId for follow-up messages // [!code highlight]
-    const id = response.headers.get('X-Run-Id'); // [!code highlight]
-    setRunId(id); // [!code highlight]
-
-    return response.body; // Stream for UI rendering
-  }, []);
-
-  const sendMessage = useCallback(async (message: string) => {
-    if (!runId) return;
-
-    await fetch('/api/chat/message', { // [!code highlight]
-      method: 'POST', // [!code highlight]
-      headers: { 'Content-Type': 'application/json' }, // [!code highlight]
-      body: JSON.stringify({ runId, message }), // [!code highlight]
-    }); // [!code highlight]
-  }, [runId]);
-
-  const endChat = useCallback(async () => {
-    if (!runId) return;
-    await fetch('/api/chat/message', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ runId, message: '/done' }),
-    });
-    setRunId(null);
-  }, [runId]);
-
-  return { runId, startChat, sendMessage, endChat };
-}
-```
-
-## Use Cases
-
-### System Event Injection
-
-Backend services can inject messages based on external events:
-
-```typescript title="app/api/webhooks/payment/route.ts" lineNumbers
-import { chatMessageHook } from '@/ai/hooks/chat-message';
-
-export async function POST(req: Request) {
-  const { runId, paymentStatus, amount } = await req.json();
-
-  // Inject payment notification into the conversation // [!code highlight]
-  await chatMessageHook.resume(runId, { // [!code highlight]
-    message: `Payment ${paymentStatus}: $${amount}`, // [!code highlight]
-    username: 'system', // [!code highlight]
-  }); // [!code highlight]
-
-  return Response.json({ success: true });
-}
-```
-
-### Collaborative Sessions
-
-Multiple users can send messages to the same conversation by sharing the `runId`:
+**Dynamic Model Selection** — Switch models based on conversation complexity:
 
 ```typescript lineNumbers
-// Any participant can enqueue messages using the shared runId
-await fetch('/api/chat/message', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    runId: sharedRunId,
-    message: 'I have a question about that',
-    username: 'Alice',
-  }),
-});
-```
-
-### Scheduled Follow-ups
-
-Use `sleep()` in combination with hooks for time-delayed messages:
-
-```typescript lineNumbers
-import { sleep } from 'workflow';
-
-export async function chatWithRemindersWorkflow(initialMessage: string) {
-  'use workflow';
-
-  // ... agent setup (see "Building Durable AI Agents" guide)
-
-  while (true) {
-    const hook = chatMessageHook.create();
-
-    // Race between user message and reminder timeout // [!code highlight]
-    const result = await Promise.race([ // [!code highlight]
-      hook.then((data) => ({ type: 'message' as const, data })), // [!code highlight]
-      sleep('5m').then(() => ({ type: 'timeout' as const })), // [!code highlight]
-    ]); // [!code highlight]
-
-    if (result.type === 'timeout') {
-      messages.push({
-        role: 'user',
-        content: '[System: User has been idle for 5 minutes]',
-      });
-    } else if (result.data.message === '/done') {
-      break;
-    } else {
-      messages.push({ role: 'user', content: result.data.message });
-    }
-
-    // Continue conversation...
+prepareStep: ({ stepNumber, messages }) => {
+  // Use a stronger model for later steps
+  if (stepNumber > 2 && messages.length > 10) {
+    return { model: 'anthropic/claude-sonnet-4.5' };
   }
+  return {};
 }
 ```
 
 ## Related Documentation
 
+- [Chat Session Modeling](/guides/ai-agents/chat-session-modeling) - Single-turn vs multi-turn patterns
 - [Building Durable AI Agents](/guides/ai-agents) - Complete guide to creating durable agents
-- [Human-in-the-Loop](/guides/ai-agents/human-in-the-loop) - Using hooks for approval workflows
-- [Sleep and Delays](/guides/ai-agents/sleep-and-delays) - Time-based workflow patterns
+- [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Full API documentation
 - [`defineHook()` API Reference](/docs/api-reference/workflow/define-hook) - Hook configuration options
diff --git a/docs/content/guides/ai-agents/meta.json b/docs/content/guides/ai-agents/meta.json
index e588f4657..0b1f32110 100644
--- a/docs/content/guides/ai-agents/meta.json
+++ b/docs/content/guides/ai-agents/meta.json
@@ -5,6 +5,7 @@
     "resumable-streams",
     "sleep-and-delays",
     "human-in-the-loop",
+    "chat-session-modeling",
     "message-queueing"
   ],
   "defaultOpen": true

From bbe7df9d48a601f3821b42bb1eadddc47c274a23 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 18:37:13 -0800
Subject: [PATCH 25/38] Small polish

---
 docs/content/docs/ai-agents/defining-tools.mdx          | 7 +++----
 docs/content/guides/ai-agents/chat-session-modeling.mdx | 2 +-
 docs/content/guides/ai-agents/message-queueing.mdx      | 8 ++++----
 3 files changed, 8 insertions(+), 9 deletions(-)

diff --git a/docs/content/docs/ai-agents/defining-tools.mdx b/docs/content/docs/ai-agents/defining-tools.mdx
index 036843041..193699204 100644
--- a/docs/content/docs/ai-agents/defining-tools.mdx
+++ b/docs/content/docs/ai-agents/defining-tools.mdx
@@ -4,7 +4,7 @@ title: Defining Tools
 
 Tools in Workflow DevKit follow the same structure as [AI SDK tools](https://ai-sdk.dev/docs/foundations/tools), but with additional context provided by `DurableAgent`. This page covers the key concepts for defining tools in durable agents.
 
-<Callout>
+<Callout type="info">
 For a complete walkthrough with examples, see the **[Building Durable AI Agents](/guides/ai-agents)** guide.
 </Callout>
 
@@ -15,10 +15,10 @@ When `DurableAgent` invokes a tool, the execute function receives additional con
 ```typescript lineNumbers
 execute: async (input, options) => {
   const { toolCallId, messages } = options;
-  
+
   // toolCallId: Unique identifier for correlating stream chunks
   // messages: Full conversation history (LanguageModelV2Prompt format)
-  
+
   return result;
 }
 ```
@@ -106,4 +106,3 @@ async function executeFetchWithDelay({ url }: { url: string }) {
 - [Streaming](/docs/foundations/streaming) - How streaming works
 - [Workflows and Steps](/docs/foundations/workflows-and-steps) - Understanding execution contexts
 - [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Full API documentation
-
diff --git a/docs/content/guides/ai-agents/chat-session-modeling.mdx b/docs/content/guides/ai-agents/chat-session-modeling.mdx
index 47b8ede25..7506b60d6 100644
--- a/docs/content/guides/ai-agents/chat-session-modeling.mdx
+++ b/docs/content/guides/ai-agents/chat-session-modeling.mdx
@@ -263,7 +263,7 @@ export function useMultiTurnChat() {
 | Workflow complexity | Lower | Higher |
 | Observability scope | Per-turn traces | Full session traces |
 
-**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. Server-owned state, native message injection, and full session observability become increasingly valuable as your agent matures.
+**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. Server-owned state, native message injection, and full session observability become increasingly valuable as your agent matures.
 
 **Single-turn works well when adapting existing architectures.** If you already have client-side message state management (e.g., via AI SDK's `useChat`), single-turn workflows slot in with minimal changes. Each turn maps cleanly to an independent workflow run.
 
diff --git a/docs/content/guides/ai-agents/message-queueing.mdx b/docs/content/guides/ai-agents/message-queueing.mdx
index 1ac8cbfb0..ef10c7881 100644
--- a/docs/content/guides/ai-agents/message-queueing.mdx
+++ b/docs/content/guides/ai-agents/message-queueing.mdx
@@ -2,7 +2,7 @@
 title: Queueing User Messages
 ---
 
-When using [multi-turn workflows](/guides/ai-agents/chat-session-modeling#multi-turn-workflows), messages typically arrive between agent turns—the workflow waits at a hook, receives a message, then starts a new turn. But sometimes you need to inject messages *during* an agent's turn, before tool calls complete or while the model is reasoning.
+When using [multi-turn workflows](/guides/ai-agents/chat-session-modeling#multi-turn-workflows), messages typically arrive between agent turns. The workflow waits at a hook, receives a message, then starts a new turn. But sometimes you need to inject messages *during* an agent's turn, before tool calls complete or while the model is reasoning.
 
 `DurableAgent`'s `prepareStep` callback enables this by running before each step in the agent loop, giving you a chance to inject queued messages into the conversation.
 
@@ -87,7 +87,7 @@ export async function chatWorkflow(threadId: string, initialMessage: string) {
 }
 ```
 
-Messages sent via `chatMessageHook.resume()` accumulate in the queue and get injected before the next step—whether that's a tool call or another LLM request.
+Messages sent via `chatMessageHook.resume()` accumulate in the queue and get injected before the next step, whether that's a tool call or another LLM request.
 
 <Callout type="info">
 The `prepareStep` callback receives messages in `LanguageModelV2Prompt` format (with content arrays), which is the internal format used by the AI SDK.
@@ -97,7 +97,7 @@ The `prepareStep` callback receives messages in `LanguageModelV2Prompt` format (
 
 Beyond message injection, `prepareStep` supports other per-step modifications:
 
-**Context Management** — Trim old messages to stay within context limits:
+**Context Management**: Trim old messages to stay within context limits:
 
 ```typescript lineNumbers
 prepareStep: ({ messages }) => {
@@ -113,7 +113,7 @@ prepareStep: ({ messages }) => {
 }
 ```
 
-**Dynamic Model Selection** — Switch models based on conversation complexity:
+**Dynamic Model Selection**: Switch models based on conversation complexity:
 
 ```typescript lineNumbers
 prepareStep: ({ stepNumber, messages }) => {

From 7e50e2ef7abfab753b141d5726e851afd3491e09 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 18:43:34 -0800
Subject: [PATCH 26/38] remove unneeded file

---
 packages/ai/docs.md                         | 213 --------------------
 packages/ai/src/agent/durable-agent.test.ts |   4 +-
 2 files changed, 2 insertions(+), 215 deletions(-)
 delete mode 100644 packages/ai/docs.md

diff --git a/packages/ai/docs.md b/packages/ai/docs.md
deleted file mode 100644
index 887bae54a..000000000
--- a/packages/ai/docs.md
+++ /dev/null
@@ -1,213 +0,0 @@
-# DurableAgent Architecture and State Propagation
-
-This document explains how `DurableAgent` integrates with Workflow DevKit, how state is stored and propagated between workflow and tool call steps.
-
-## Overview
-
-`DurableAgent` is a class for building AI-powered agents within workflows. It enables AI agents to:
-
-- Maintain state across workflow steps
-- Call tools with automatic retries
-- Handle interruptions and resumptions gracefully
-
-## Core Components
-
-### 1. DurableAgent (`durable-agent.ts`)
-
-The main orchestrator that:
-
-- Accepts a model, tools, and system prompt
-- Manages the conversation loop via `stream()` method
-- Delegates LLM streaming to `streamTextIterator`
-- Executes tools when the model makes tool calls
-
-### 2. StreamTextIterator (`stream-text-iterator.ts`)
-
-An async generator that:
-
-- Maintains the `conversationPrompt` (message history as `LanguageModelV2Prompt`)
-- Calls `doStreamStep` to stream LLM responses
-- Yields tool calls when the model requests them
-- Receives tool results and adds them to the conversation
-- Returns the final conversation when done
-
-### 3. DoStreamStep (`do-stream-step.ts`)
-
-A workflow step function (marked with `"use step"`) that:
-
-- Initializes the language model
-- Calls `model.doStream()` with the conversation prompt
-- Transforms LLM stream chunks to `UIMessageChunk` format
-- Writes chunks to the writable stream
-- Returns tool calls and finish reason
-
-## State Flow Diagram
-
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                          DurableAgent.stream()                          │
-│                         (Workflow Context)                              │
-└─────────────────────────────────────────────────────────────────────────┘
-                                    │
-                                    ▼
-┌─────────────────────────────────────────────────────────────────────────┐
-│                         streamTextIterator()                            │
-│                         (Workflow Context)                              │
-│                                                                         │
-│   ┌─────────────────────────────────────────────────────────────────┐   │
-│   │  conversationPrompt: LanguageModelV2Prompt                      │   │
-│   │  - Mutable copy of the initial prompt                           │   │
-│   │  - Grows as assistant/tool messages are added                   │   │
-│   └─────────────────────────────────────────────────────────────────┘   │
-│                                    │                                    │
-│                                    ▼                                    │
-│   ┌───────────────────────────────────────────────────────────────┐     │
-│   │              while (!done) loop                                │     │
-│   │                                                                │     │
-│   │   1. Call doStreamStep() with conversationPrompt              │     │
-│   │      (This is a "use step" function - runs in step runtime)   │     │
-│   │                                                                │     │
-│   │   2. If finish reason is "tool-calls":                        │     │
-│   │      - Add assistant message with tool calls to prompt        │     │
-│   │      - yield toolCalls (pause, wait for tool results)         │     │
-│   │      - Receive toolResults from DurableAgent                  │     │
-│   │      - Add tool message with results to prompt                │     │
-│   │      - Check stop conditions                                  │     │
-│   │                                                                │     │
-│   │   3. If finish reason is "stop":                              │     │
-│   │      - Add final assistant message to prompt                  │     │
-│   │      - Set done = true                                        │     │
-│   └───────────────────────────────────────────────────────────────┘     │
-│                                    │                                    │
-│                                    ▼                                    │
-│   return conversationPrompt (final message history)                     │
-└─────────────────────────────────────────────────────────────────────────┘
-                                    │
-         ┌──────────────────────────┼──────────────────────────┐
-         │                          │                          │
-         ▼                          ▼                          ▼
-┌─────────────────┐    ┌─────────────────────┐    ┌─────────────────┐
-│   executeTool   │    │    executeTool      │    │   executeTool   │
-│   (tool #1)     │    │    (tool #2)        │    │   (tool #n)     │
-│                 │    │                     │    │                 │
-│ tool.execute(   │    │ tool.execute(       │    │ tool.execute(   │
-│   input,        │    │   input,            │    │   input,        │
-│   {             │    │   {                 │    │   {             │
-│     toolCallId, │    │     toolCallId,     │    │     toolCallId, │
-│     messages,   │◄───│     messages,       │◄───│     messages,   │
-│   }             │    │   }                 │    │   }             │
-│ )               │    │ )                   │    │ )               │
-└─────────────────┘    └─────────────────────┘    └─────────────────┘
-         │                          │                          │
-         └──────────────────────────┼──────────────────────────┘
-                                    │
-                                    ▼
-                          Tool Results returned
-                          to streamTextIterator
-```
-
-## State Propagation
-
-### Message History Flow
-
-1. **Initial Messages**: User provides `messages` to `agent.stream()`
-2. **Prompt Standardization**: Messages are converted to `LanguageModelV2Prompt` format
-3. **Iterator Maintains State**: `streamTextIterator` keeps a mutable `conversationPrompt`
-4. **LLM Responses Added**: After each LLM call, assistant messages are appended
-5. **Tool Results Added**: After tool execution, tool messages with results are appended
-6. **Final Return**: The complete conversation history is returned from `stream()`
-
-### Message Format
-
-The internal format is `LanguageModelV2Prompt`, an array of messages with roles:
-
-- `system`: System prompt (if provided)
-- `user`: User messages with text/image content
-- `assistant`: Model responses, including tool call requests
-- `tool`: Tool execution results
-
-### The Messages Problem (This TODO)
-
-When a tool's `execute` function is called, the AI SDK expects to receive the conversation history so tools can have context about what led to the tool call:
-
-```typescript
-tool.execute(input, {
-  toolCallId: string,
-  messages: ModelMessage[],  // <-- The conversation history
-  abortSignal?: AbortSignal,
-})
-```
-
-**Current State**: `messages` is passed as an empty array `[]`
-**Desired State**: `messages` should contain the conversation history up to the point of the tool call
-
-## Implementation Details
-
-### Why Messages Matter for Tools
-
-Tools may need conversation context to:
-
-1. Understand the full request context
-2. Make decisions based on prior tool results
-3. Provide more accurate responses
-4. Implement conversation-aware functionality
-
-### Current Implementation Gap
-
-In `executeTool()`:
-
-```typescript
-const toolResult = await tool.execute(input.value, {
-  toolCallId: toolCall.toolCallId,
-  // TODO: pass the proper messages to the tool
-  messages: [],  // <-- Currently empty
-});
-```
-
-The challenge: `executeTool` doesn't have access to `conversationPrompt` because it's maintained inside `streamTextIterator`.
-
-### Solution Approach
-
-To fix this, we need to:
-
-1. Modify `streamTextIterator` to yield both tool calls AND the current messages
-2. Update `DurableAgent.stream()` to extract messages from the yield value
-3. Pass messages through to `executeTool()`
-
-## Workflow DevKit Integration
-
-### Step Functions
-
-`doStreamStep` is marked with `"use step"`, meaning:
-
-- It runs in the step runtime (full Node.js access)
-- Results are automatically persisted to the event log
-- Automatic retry on failures
-- Workflow suspends while step executes
-
-### Stream Handling
-
-- Streams (`WritableStream<UIMessageChunk>`) are serializable across workflow boundaries
-- The writable stream receives LLM response chunks in real-time
-- Tool outputs are also written to the stream for UI updates
-
-### Durability
-
-The workflow's event log stores:
-
-- Step function results (including LLM responses)
-- Tool execution results
-- Conversation state between invocations
-
-This enables:
-
-- Resume after failures
-- Replay for debugging
-- Long-running conversations that survive serverless timeouts
-
-## Related Files
-
-- `packages/ai/src/agent/durable-agent.ts` - Main DurableAgent class
-- `packages/ai/src/agent/stream-text-iterator.ts` - Async generator for LLM streaming
-- `packages/ai/src/agent/do-stream-step.ts` - Step function for LLM calls
-- `packages/ai/src/agent/tools-to-model-tools.ts` - Tool schema conversion
diff --git a/packages/ai/src/agent/durable-agent.test.ts b/packages/ai/src/agent/durable-agent.test.ts
index ce43b9591..ab8694a64 100644
--- a/packages/ai/src/agent/durable-agent.test.ts
+++ b/packages/ai/src/agent/durable-agent.test.ts
@@ -8,9 +8,9 @@ import type {
   LanguageModelV2,
   LanguageModelV2ToolCall,
 } from '@ai-sdk/provider';
-import { FatalError } from 'workflow';
-import { describe, expect, it, vi } from 'vitest';
 import type { ToolSet } from 'ai';
+import { describe, expect, it, vi } from 'vitest';
+import { FatalError } from 'workflow';
 import { z } from 'zod';
 
 // Mock the streamTextIterator

From e97a2b3c9c421feb8d7aa77713fdcd2c29a57b09 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 19:40:08 -0800
Subject: [PATCH 27/38] Polish pass

---
 .../content/docs/ai-agents/defining-tools.mdx |  15 +-
 .../ai-agents/chat-session-modeling.mdx       | 196 +++++++++++++-----
 .../guides/ai-agents/human-in-the-loop.mdx    |  85 +-------
 docs/content/guides/ai-agents/index.mdx       |  16 +-
 .../guides/ai-agents/resumable-streams.mdx    | 188 +----------------
 .../guides/ai-agents/sleep-and-delays.mdx     |  18 +-
 6 files changed, 180 insertions(+), 338 deletions(-)

diff --git a/docs/content/docs/ai-agents/defining-tools.mdx b/docs/content/docs/ai-agents/defining-tools.mdx
index 193699204..6d07d9074 100644
--- a/docs/content/docs/ai-agents/defining-tools.mdx
+++ b/docs/content/docs/ai-agents/defining-tools.mdx
@@ -51,10 +51,10 @@ Tools can emit real-time updates by writing to the workflow's output stream. Sin
 async function emitProgress(status: string, toolCallId: string) {
   'use step'; // [!code highlight]
 
-  const writable = getWritable<UIMessageChunk>();
-  const writer = writable.getWriter();
+  const writable = getWritable<UIMessageChunk>(); // [!code highlight]
+  const writer = writable.getWriter(); // [!code highlight]
 
-  await writer.write({
+  await writer.write({ // [!code highlight]
     id: toolCallId,
     type: 'data-status',
     data: { status },
@@ -64,9 +64,10 @@ async function emitProgress(status: string, toolCallId: string) {
 }
 
 async function executeSearch({ query }: { query: string }, { toolCallId }: { toolCallId: string }) {
-  await emitProgress('searching', toolCallId);
+  'use step';
+  await emitProgress('searching', toolCallId); // [!code highlight]
   const results = await performSearch(query);
-  await emitProgress('complete', toolCallId);
+  await emitProgress('complete', toolCallId); // [!code highlight]
   return results;
 }
 ```
@@ -75,14 +76,14 @@ async function executeSearch({ query }: { query: string }, { toolCallId }: { too
 
 Tools can run at two levels with different capabilities:
 
-| Capability | Step-Level (`"use step"`) | Workflow-Level |
+| Capability | Step-Level (`"use step"`) | Workflow-Level (`"use workflow"`) |
 |------------|---------------------------|----------------|
 | `getWritable()` | ✅ | ❌ |
 | Automatic retries | ✅ | ❌ |
 | `sleep()` | ❌ | ✅ |
 | `createWebhook()` | ❌ | ✅ |
 
-Most tools combine both: use step functions for I/O operations, and keep the execute function at the workflow level for orchestration:
+Tools can combine both: use a step function for I/O operations, and keep the execute function at the workflow level for orchestration:
 
 ```typescript lineNumbers
 // Step: handles I/O with retries
diff --git a/docs/content/guides/ai-agents/chat-session-modeling.mdx b/docs/content/guides/ai-agents/chat-session-modeling.mdx
index 7506b60d6..3d739d8ed 100644
--- a/docs/content/guides/ai-agents/chat-session-modeling.mdx
+++ b/docs/content/guides/ai-agents/chat-session-modeling.mdx
@@ -2,11 +2,13 @@
 title: Chat Session Modeling
 ---
 
-Chat sessions in AI agents can be modeled at different layers of your architecture. The choice affects state ownership, latency characteristics, and how you handle interruptions and reconnections. Workflow DevKit supports two primary patterns.
+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.
+
+While there are many ways to model chat sessions, the two most common categories are single-turn and multi-turn.
 
 ## Single-Turn Workflows
 
-Each user message triggers a new workflow run. The client owns the conversation history and sends the full message array with each request.
+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.
 
 <Tabs items={['Workflow', 'API Route', 'Client']}>
 
@@ -62,14 +64,44 @@ export async function POST(req: Request) {
 
 <Tab value="Client">
 
-```typescript title="app/chat.tsx" lineNumbers
+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.
+
+```typescript title="app/chats/[id]/page.tsx" lineNumbers
 'use client';
 
 import { useChat } from '@ai-sdk/react';
+import { WorkflowChatTransport } from '@workflow/ai'; // [!code highlight]
+import { useParams } from 'next/navigation';
+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]
 
-export function Chat() {
   const { messages, input, handleInputChange, handleSubmit } = useChat({
-    api: '/api/chat', // [!code highlight] AI SDK manages message history
+    initialMessages, // [!code highlight] Loaded via getMessages(sessionId)
+    transport, // [!code highlight]
   });
 
   return (
@@ -85,18 +117,13 @@ export function Chat() {
 
 </Tabs>
 
-**Characteristics:**
+In this pattern, the client owns conversation state, with the latest turn managed by the AI SDK's `useChat`, and past turns persisted to the backend. The current turn is either managed through the workflow by a resumable stream (see [Resumable Streams](/guides/ai-agents/resumable-streams)), or a hook into `useChat` persists every new message to the backend, as messages come in.
 
-- Client owns conversation state (via AI SDK's `useChat`)
-- Each turn is independently retryable
-- Simpler server-side logic; no cross-turn state management
-- Workflow results are self-contained
-
-This is the pattern shown at the start of [Building Durable AI Agents](/guides/ai-agents).
+This is the pattern used in the [Building Durable AI Agents](/guides/ai-agents) guide.
 
 ## Multi-Turn Workflows
 
-A single workflow handles the entire conversation session. The server owns conversation state, and clients inject new messages via hooks.
+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.
 
 <Tabs items={['Workflow', 'API Routes', 'Hook Definition', 'Client']}>
 
@@ -161,16 +188,16 @@ export async function POST(req: Request) {
 
   return createUIMessageStreamResponse({
     stream: run.readable,
-    headers: { 'X-Thread-Id': threadId },
   });
 }
 ```
 
-```typescript title="app/api/chat/message/route.ts" lineNumbers
+```typescript title="app/api/chat/[id]/route.ts" lineNumbers
 import { chatMessageHook } from '@/ai/hooks/chat-message';
 
 export async function POST(req: Request) {
-  const { threadId, message } = await req.json();
+  const { message } = await req.json();
+  const { id: threadId } = await params; // [!code highlight]
 
   await chatMessageHook.resume(`thread:${threadId}`, { message }); // [!code highlight]
 
@@ -200,45 +227,61 @@ export const chatMessageHook = defineHook({
 ```typescript title="hooks/use-multi-turn-chat.ts" lineNumbers
 'use client';
 
-import { useState, useCallback } from 'react';
+import { useChat } from '@ai-sdk/react'; // [!code highlight]
+import { WorkflowChatTransport } from '@workflow/ai'; // [!code highlight]
+import { useState, useCallback, useMemo } from 'react';
 
 export function useMultiTurnChat() {
   const [threadId, setThreadId] = useState<string | null>(null);
 
-  const startSession = useCallback(async (message: string) => {
-    const newThreadId = crypto.randomUUID();
-    setThreadId(newThreadId);
-
-    const response = await fetch('/api/chat', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ threadId: newThreadId, message }),
-    });
-
-    return response.body; // Stream for UI rendering
-  }, []);
-
-  const sendMessage = useCallback(async (message: string) => {
-    if (!threadId) return;
+  const transport = useMemo( // [!code highlight]
+    () => // [!code highlight]
+      new WorkflowChatTransport({ // [!code highlight]
+        api: '/api/chat', // [!code highlight]
+      }), // [!code highlight]
+    [] // [!code highlight]
+  ); // [!code highlight]
+
+  const {
+    messages,
+    sendMessage: sendInitialMessage, // [!code highlight] Renamed from sendMessage
+    ...chatProps
+  } = useChat({ transport }); // [!code highlight]
+
+  const startSession = useCallback(
+    async (message: string) => {
+      const newThreadId = crypto.randomUUID();
+      setThreadId(newThreadId);
+
+      // Send initial message with threadId in body // [!code highlight]
+      await sendInitialMessage(message, { // [!code highlight]
+        body: { threadId: newThreadId }, // [!code highlight]
+      }); // [!code highlight]
+    },
+    [sendInitialMessage]
+  );
 
-    await fetch('/api/chat/message', { // [!code highlight]
-      method: 'POST', // [!code highlight]
-      headers: { 'Content-Type': 'application/json' }, // [!code highlight]
-      body: JSON.stringify({ threadId, message }), // [!code highlight]
-    }); // [!code highlight]
-  }, [threadId]);
+  // Follow-up messages go through the hook resumption endpoint // [!code highlight]
+  const sendMessage = useCallback(
+    async (message: string) => {
+      if (!threadId) return;
+
+      await fetch(`/api/chat/${threadId}`, { // [!code highlight]
+        method: 'POST', // [!code highlight]
+        headers: { 'Content-Type': 'application/json' }, // [!code highlight]
+        body: JSON.stringify({ message }), // [!code highlight]
+      }); // [!code highlight]
+    },
+    [threadId]
+  );
 
   const endSession = useCallback(async () => {
     if (!threadId) return;
-    await fetch('/api/chat/message', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ threadId, message: '/done' }),
-    });
+    await sendMessage('/done');
     setThreadId(null);
-  }, [threadId]);
+  }, [threadId, sendMessage]);
 
-  return { threadId, startSession, sendMessage, endSession };
+  return { messages, threadId, startSession, sendMessage, endSession, ...chatProps };
 }
 ```
 
@@ -246,30 +289,48 @@ export function useMultiTurnChat() {
 
 </Tabs>
 
-**Characteristics:**
-
-- Server owns conversation state
-- Single workflow spans the entire session
-- Enables multi-party injection (webhooks, system events, other users)
-- Workflow can coordinate cross-turn behavior (reminders, timeouts)
+In this pattern, the workflow owns the entire conversation session. All messages are persisted in the workflow, and messages are injected into the workflow via hooks. The current **and** past turns are available in the UI by reconnecting to the main workflow stream. Alternatively to a stream, this could also use a step on the workflow side to persists (and possibly load) messages from an external store. Using an external database is more flexible, but less performant and harder to resume neatly than the built-in stream.
 
 ## Choosing a Pattern
 
 | Consideration | Single-Turn | Multi-Turn |
 |--------------|-------------|------------|
-| State ownership | Client | Server |
-| Message injection from backend | Requires external coordination | Native via hooks |
-| Session continuity after client disconnect | Lost (new run per turn) | Preserved |
+| State ownership | Client or API route | Workflow |
+| Message injection from backend | Requires stitching together runs | Native via hooks |
 | Workflow complexity | Lower | Higher |
+| Workflow time horizon | Minutes | Hours to indefinitely |
 | Observability scope | Per-turn traces | Full session traces |
 
 **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. Server-owned state, native message injection, and full session observability become increasingly valuable as your agent matures.
 
-**Single-turn works well when adapting existing architectures.** If you already have client-side message state management (e.g., via AI SDK's `useChat`), single-turn workflows slot in with minimal changes. Each turn maps cleanly to an independent workflow run.
+**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.
 
 ## Multi-Party Injection
 
-The multi-turn pattern enables backend systems to inject messages into active conversations:
+The multi-turn pattern also easily enables multi-party chat sessions. Parties can be system events, external services, and multiple 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-party chat sessions:
+
+<Tabs items={['System Event', 'External Service', 'Multiple Users']}>
+
+<Tab value="System Event">
+
+```typescript title="app/api/webhooks/order-update/route.ts" lineNumbers
+import { chatMessageHook } from '@/ai/hooks/chat-message';
+
+export async function POST(req: Request) {
+  const { threadId, orderStatus } = await req.json();
+
+  // Inject order update into the conversation // [!code highlight]
+  await chatMessageHook.resume(`thread:${threadId}`, { // [!code highlight]
+    message: `[System] Order status updated: ${orderStatus}`, // [!code highlight]
+  }); // [!code highlight]
+
+  return Response.json({ success: true });
+}
+```
+
+</Tab>
+
+<Tab value="External Service">
 
 ```typescript title="app/api/webhooks/order-update/route.ts" lineNumbers
 import { chatMessageHook } from '@/ai/hooks/chat-message';
@@ -286,6 +347,29 @@ export async function POST(req: Request) {
 }
 ```
 
+</Tab>
+
+<Tab value="Multiple Users">
+
+```typescript title="app/api/webhooks/order-update/route.ts" lineNumbers
+import { chatMessageHook } from '@/ai/hooks/chat-message';
+
+export async function POST(req: Request) {
+  const { threadId, orderStatus } = await req.json();
+
+  // Inject order update into the conversation // [!code highlight]
+  await chatMessageHook.resume(`thread:${threadId}`, { // [!code highlight]
+    message: `[System] Order status updated: ${orderStatus}`, // [!code highlight]
+  }); // [!code highlight]
+
+  return Response.json({ success: true });
+}
+```
+
+</Tab>
+
+</Tabs>
+j
 ## Related Documentation
 
 - [Building Durable AI Agents](/guides/ai-agents) - Foundation guide for durable agents
diff --git a/docs/content/guides/ai-agents/human-in-the-loop.mdx b/docs/content/guides/ai-agents/human-in-the-loop.mdx
index ae7c76a3d..3c7d54b27 100644
--- a/docs/content/guides/ai-agents/human-in-the-loop.mdx
+++ b/docs/content/guides/ai-agents/human-in-the-loop.mdx
@@ -2,46 +2,48 @@
 title: Human-in-the-Loop
 ---
 
-An extremely common feature necessary for running AI agents in production is the ability to wait for human input or external events before proceeding.
+A common pre-requisite for running AI agents in production is the ability to wait for human input or external events before proceeding.
 
 Workflow DevKit's [webhook](/docs/api-reference/workflow/create-webhook) and [hook](/docs/api-reference/workflow/define-hook) primitives enable "human-in-the-loop" patterns where workflows pause until a human takes action, allowing smooth resumption of workflows even after days of inactivity, and provides stability across code deployments.
 
+If you need to react to external events programmatically, see the [hooks](/docs/foundations/hooks) documentation for more information. This part of the guide will focus on the human-in-the-loop pattern, which is a subset of the more general hook pattern.
+
 ## How It Works
 
 <Steps>
 
 <Step>
-`createWebhook()` or `createHook()` generates a unique URL (or token) that can resume a workflow. This can be packaged as a tool for the Agent to call, or used directly in your backend code.
+`createWebhook()` generates a unique URL that can be used to resume a workflow. This can be packaged as a tool for the Agent to call, or used directly in your backend code.
 </Step>
 
 <Step>
-The workflow emits a data chunk containing the webhook URL, sending it to the consumer of the workflow, such as a chat UI, or an external service.
+The workflow emits a data chunk containing the webhook URL, sending it to the consumer of the workflow, such as a chat UI.
 </Step>
 
 <Step>
-The workflow pauses at `await webhook` - no compute resources are consumed.
+The workflow pauses at `await webhook` - no compute resources are consumed while waiting for the human to take action.
 </Step>
 
 <Step>
-The consumer of the workflow calls the webhook URL, sending data back to the workflow.
+The user of the workflow (e.g. a human in a chat UI) calls the webhook URL, optionally sending data back to the workflow.
 </Step>
 
 <Step>
-The workflow receives any data sent with the webhook (approval status, comments) and resumes execution.
+The workflow receives any data sent with the webhook (e.g. approval status, comments) and resumes execution.
 </Step>
 
 </Steps>
 
 ## Creating an Approval Tool
 
-Add a tool that pauses the agent until a human approves or rejects:
+Add a tool that allows the agent to deliberately pauses execution until a human approves or rejects:
 
 <Steps>
 
 <Step>
 ### Implement the tool
 
-The execute function creates a webhook and waits for approval:
+Create a tool with an execute function that creates a webhook and emits a data chunk containing the webhook URL.
 
 ```typescript title="ai/tools/human-approval.ts" lineNumbers
 import { tool, type UIMessageChunk } from 'ai';
@@ -102,7 +104,7 @@ async function emitApprovalRequest(
 ```
 
 <Callout type="info">
-The `createWebhook()` function must be called from within a workflow context, not from a step. This is why `executeHumanApproval` does not have `"use step"`.
+The `createWebhook()` function must be called from within a workflow context, not from a step. This is why `executeHumanApproval` does not have `"use step"`, but the stream write operation requires a step context, which is why `emitApprovalRequest` is a separate function with `"use step"`.
 </Callout>
 </Step>
 
@@ -330,71 +332,6 @@ This API can be called by:
 
 </Tabs>
 
-## Use Cases
-
-### Email Approval
-
-Wait for approval before sending an email to customers:
-
-```typescript lineNumbers
-async function executeSendEmail(
-  { recipients, subject, body }: EmailParams,
-  { toolCallId }: { toolCallId: string }
-) {
-  const webhook = createWebhook();
-
-  await emitEmailApproval({
-    url: webhook.url,
-    recipients,
-    subject,
-    preview: body.substring(0, 200),
-  }, toolCallId);
-
-  const request = await webhook;
-  const { approved } = await request.json();
-
-  if (!approved) {
-    return 'Email cancelled by user';
-  }
-
-  await sendEmail({ recipients, subject, body });
-  return `Email sent to ${recipients.length} recipients`;
-}
-```
-
-### Multi-Step Approval
-
-Chain multiple approvals for high-risk actions:
-
-```typescript lineNumbers
-export async function criticalActionWorkflow(action: string) {
-  'use workflow';
-
-  // First approval: Team lead
-  const leadApproval = await requestApproval({
-    role: 'team-lead',
-    action,
-  });
-
-  if (!leadApproval.approved) {
-    return { status: 'rejected', stage: 'team-lead' };
-  }
-
-  // Second approval: Manager
-  const managerApproval = await requestApproval({
-    role: 'manager',
-    action,
-  });
-
-  if (!managerApproval.approved) {
-    return { status: 'rejected', stage: 'manager' };
-  }
-
-  await executeCriticalAction(action);
-  return { status: 'completed' };
-}
-```
-
 ## Related Documentation
 
 - [Hooks & Webhooks](/docs/foundations/hooks) - Complete guide to hooks and webhooks
diff --git a/docs/content/guides/ai-agents/index.mdx b/docs/content/guides/ai-agents/index.mdx
index c17020371..a8116a6be 100644
--- a/docs/content/guides/ai-agents/index.mdx
+++ b/docs/content/guides/ai-agents/index.mdx
@@ -2,11 +2,13 @@
 title: Building Durable AI Agents
 ---
 
-AI agents are built on the primitive of LLM and tool-call loops, often with additional processes for data fetching, resource provisioning, or reacting to external events. Workflow DevKit makes your agents production-ready, by turning your agents into durable, resumable workflows, and managing your LLM calls, tool executions, and other async operations as retryable and observable steps.
+AI agents are built on the primitive of LLM and tool-call loops, often with additional processes for data fetching, resource provisioning, or reacting to external events.
+
+Workflow DevKit makes your agents production-ready, by turning them into durable, resumable workflows, and managing your LLM calls, tool executions, and other async operations as retryable and observable steps.
 
 <AgentTraces />
 
-This guide walks through converting a basic AI SDK agent into a durable agent using Workflow DevKit.
+This guide walks you through converting a basic AI SDK agent into a durable agent using Workflow DevKit.
 
 ## Why Durable Agents?
 
@@ -364,16 +366,11 @@ Run your development server, then open the observability dashboard to see your w
 npx workflow web
 ```
 
-This opens a local dashboard showing:
-
-- All workflow runs and their status
-- Individual step executions with timing
-- Errors and retry attempts
-- Stream data flowing through the workflow
+This opens a local dashboard showing all workflow runs and their status, as well as a trace viewer to inspect the workflow in detail, including retry attempts, and the data being passed between steps.
 
 ## Next Steps
 
-Now that you have a basic durable agent, explore these additional capabilities:
+Now that you have a basic durable agent, explore these additional features:
 
 <Cards>
   <Card title="Resumable Streams" href="/guides/ai-agents/resumable-streams">
@@ -555,7 +552,6 @@ export function Chat() {
 
 ## Related Documentation
 
-- [AI & Agents Overview](/docs/ai-agents) - Documentation hub for AI agent features
 - [Defining Tools](/docs/ai-agents/defining-tools) - Tool patterns and execute context
 - [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Full API documentation
 - [Workflows and Steps](/docs/foundations/workflows-and-steps) - Core concepts
diff --git a/docs/content/guides/ai-agents/resumable-streams.mdx b/docs/content/guides/ai-agents/resumable-streams.mdx
index 59aa79482..7230e828c 100644
--- a/docs/content/guides/ai-agents/resumable-streams.mdx
+++ b/docs/content/guides/ai-agents/resumable-streams.mdx
@@ -2,27 +2,13 @@
 title: Resumable Streams
 ---
 
-When building chat interfaces, network interruptions or page refreshes can break the connection to an in-progress agent. Workflow DevKit provides [`WorkflowChatTransport`](/docs/api-reference/workflow-ai/workflow-chat-transport), a drop-in transport for the AI SDK that enables automatic stream reconnection.
+When building chat interfaces, network interruptions, page refreshes, or serverless function timeouts can break the connection to an in-progress agent.
 
-## The Problem
+Where a standard chat implementation would require the user to resend their message and wait for the entire response again, Workflow DevKit provides [`WorkflowChatTransport`](/docs/api-reference/workflow-ai/workflow-chat-transport), a drop-in transport for the AI SDK that enables automatic stream reconnection.
 
-A typical chat application loses state when:
+## Implementing stream resumption
 
-- The user refreshes the page during a response
-- Network connectivity drops temporarily
-- Serverless function timeouts occur mid-stream
-
-With a standard chat implementation, users must resend their message and wait for the entire response again.
-
-## The Solution
-
-`WorkflowChatTransport` solves this by:
-
-1. Tracking the workflow run ID returned from your API
-2. Automatically reconnecting to the stream from the last received chunk
-3. Storing the run ID for session resumption across page loads
-
-## Implementation
+Getting stream resumption requires both adding `WorkflowChatTransport` (to allow the client to reconnect to the stream) and some client-side state management, in order to know when and where to reconnect to the stream.
 
 <Steps>
 
@@ -56,7 +42,7 @@ export async function POST(req: Request) {
 <Step>
 ### Add a Stream Reconnection Endpoint
 
-Create an endpoint that returns the stream for an existing run:
+Create a new API route that returns the stream for an existing run:
 
 ```typescript title="app/api/chat/[id]/stream/route.ts" lineNumbers
 import { createUIMessageStreamResponse } from 'ai';
@@ -89,7 +75,7 @@ The `startIndex` parameter ensures the client only receives chunks it missed, av
 <Step>
 ### Use `WorkflowChatTransport` in the Client
 
-Replace the default transport in `useChat` with `WorkflowChatTransport`:
+Replace the default transport in `useChat` with `WorkflowChatTransport`, and store the latest run ID.
 
 ```typescript title="app/chat.tsx" lineNumbers
 'use client';
@@ -178,167 +164,7 @@ export function Chat() {
 6. The reconnection endpoint returns the stream from where the client left off
 7. When the stream completes, `onChatEnd` clears the stored run ID
 
-## Handling Page Refreshes
-
-The `resume` option tells `useChat` to attempt reconnection on mount. Combined with localStorage persistence, this enables seamless recovery:
-
-```typescript lineNumbers
-const activeRunId = useMemo(() => {
-  if (typeof window === 'undefined') return;
-  return localStorage.getItem('active-workflow-run-id') ?? undefined;
-}, []);
-
-const { messages, sendMessage } = useChat({
-  resume: Boolean(activeRunId), // Attempt to resume if a run ID exists // [!code highlight]
-  transport: new WorkflowChatTransport({ /* ... */ }),
-});
-```
-
-When the user refreshes the page:
-
-1. The component checks localStorage for an active run ID
-2. If found, `resume: true` triggers a reconnection attempt
-3. The transport fetches the stream from the last known position
-4. Messages continue appearing where they left off
-
-## Error Handling
-
-Configure retry behavior with `maxConsecutiveErrors`:
-
-```typescript lineNumbers
-new WorkflowChatTransport({
-  maxConsecutiveErrors: 5, // Give up after 5 consecutive failures // [!code highlight]
-  // ...
-})
-```
-
-The transport automatically retries reconnection on network errors. After reaching the limit, it stops attempting and surfaces the error.
-
-## Complete Example
-
-<Tabs items={['Chat Endpoint', 'Reconnect Endpoint', 'Client']}>
-
-<Tab value="Chat Endpoint">
-
-```typescript title="app/api/chat/route.ts" lineNumbers
-import { createUIMessageStreamResponse, convertToModelMessages } from 'ai';
-import { start } from 'workflow/api';
-import { chatWorkflow } from './workflow';
-
-export async function POST(req: Request) {
-  const { messages, modelId } = await req.json();
-  const modelMessages = convertToModelMessages(messages);
-
-  const run = await start(chatWorkflow, [{ messages: modelMessages, modelId }]);
-
-  return createUIMessageStreamResponse({
-    stream: run.readable,
-    headers: {
-      'x-workflow-run-id': run.runId,
-    },
-  });
-}
-```
-
-</Tab>
-
-<Tab value="Reconnect Endpoint">
-
-```typescript title="app/api/chat/[id]/stream/route.ts" lineNumbers
-import { createUIMessageStreamResponse } from 'ai';
-import { getRun } from 'workflow/api';
-
-export async function GET(
-  request: Request,
-  { params }: { params: Promise<{ id: string }> }
-) {
-  const { id } = await params;
-  const { searchParams } = new URL(request.url);
-
-  const startIndexParam = searchParams.get('startIndex');
-  const startIndex = startIndexParam
-    ? parseInt(startIndexParam, 10)
-    : undefined;
-
-  const run = getRun(id);
-  const stream = run.getReadable({ startIndex });
-
-  return createUIMessageStreamResponse({ stream });
-}
-```
-
-</Tab>
-
-<Tab value="Client">
-
-```typescript title="app/chat.tsx" lineNumbers
-'use client';
-
-import { useChat } from '@ai-sdk/react';
-import { WorkflowChatTransport } from '@workflow/ai';
-import { useMemo, useState } from 'react';
-
-export function Chat() {
-  const [input, setInput] = useState('');
-
-  const activeRunId = useMemo(() => {
-    if (typeof window === 'undefined') return;
-    return localStorage.getItem('active-workflow-run-id') ?? undefined;
-  }, []);
-
-  const { messages, sendMessage, status } = useChat({
-    resume: Boolean(activeRunId),
-    transport: new WorkflowChatTransport({
-      api: '/api/chat',
-      onChatSendMessage: (response) => {
-        const workflowRunId = response.headers.get('x-workflow-run-id');
-        if (workflowRunId) {
-          localStorage.setItem('active-workflow-run-id', workflowRunId);
-        }
-      },
-      onChatEnd: () => {
-        localStorage.removeItem('active-workflow-run-id');
-      },
-      prepareReconnectToStreamRequest: ({ api, ...rest }) => {
-        const runId = localStorage.getItem('active-workflow-run-id');
-        if (!runId) throw new Error('No active workflow run ID found');
-        return {
-          ...rest,
-          api: `/api/chat/${encodeURIComponent(runId)}/stream`,
-        };
-      },
-      maxConsecutiveErrors: 5,
-    }),
-  });
-
-  return (
-    <div>
-      {messages.map((m) => (
-        <div key={m.id}>
-          <strong>{m.role}:</strong> {m.content}
-        </div>
-      ))}
-      <form
-        onSubmit={(e) => {
-          e.preventDefault();
-          sendMessage({ text: input });
-          setInput('');
-        }}
-      >
-        <input
-          value={input}
-          onChange={(e) => setInput(e.target.value)}
-          placeholder="Type a message..."
-        />
-      </form>
-    </div>
-  );
-}
-```
-
-</Tab>
-
-</Tabs>
+This approach also handles page refreshes, as the client will automatically reconnect to the stream from the last known position when the UI loads with a stored run ID.
 
 ## Related Documentation
 
diff --git a/docs/content/guides/ai-agents/sleep-and-delays.mdx b/docs/content/guides/ai-agents/sleep-and-delays.mdx
index b02a8d58f..66b45fbd4 100644
--- a/docs/content/guides/ai-agents/sleep-and-delays.mdx
+++ b/docs/content/guides/ai-agents/sleep-and-delays.mdx
@@ -2,26 +2,23 @@
 title: Sleep, Suspense, and Scheduling
 ---
 
-AI agents sometimes need to pause execution in order to schedule recurring or future actions, wait before retrying an operation (e.g. for rate limiting), or wait for external state to be available. Workflow DevKit's [`sleep()`](/docs/api-reference/workflow/sleep) function enables Agents to pause execution without consuming compute resources, and resume at specified times.
-This sleep operation survives restarts, deploys, and infrastructure changes, and the duration can span seconds, hours, days, or months.
+AI agents sometimes need to pause execution in order to schedule recurring or future actions, wait before retrying an operation (e.g. for rate limiting), or wait for external state to be available.
+
+Workflow DevKit's `sleep` function enables Agents to pause execution without consuming resources, and resume at a specified time, after a specified duration, or in response to an external event. Workflow operation that suspend will survive restarts, new deploys, and infrastructure changes, independent of whether the suspense takes seconds or months.
 
 <Callout type="info">
-See the [`sleep()` API Reference](/docs/api-reference/workflow/sleep) for the full list of supported duration formats and detailed API documentation.
+See the [`sleep()` API Reference](/docs/api-reference/workflow/sleep) for the full list of supported duration formats and detailed API documentation, and see the [hooks](/docs/foundations/hooks) documentation for more information on how to resume in response to external events.
 </Callout>
 
 ## Adding a Sleep Tool
 
-Create a tool that allows the agent to pause for a specified duration:
+We can expose the sleep tool directly to the Agent by wrapping it in a tool.
 
 <Steps>
 
 <Step>
 ### Define the Tool
 
-First, we make the `sleep()` function available to the AI Agent by packaging it as a tool.
-
-Note that the `sleep()` function must be called from within a workflow context, not from within a step. This is why `executeSleep` does not have `"use step"` - it runs in the workflow context where `sleep()` is available.
-
 ```typescript title="ai/tools/sleep.ts" lineNumbers
 import { tool } from 'ai';
 import { getWritable, sleep } from 'workflow'; // [!code highlight]
@@ -50,12 +47,13 @@ export const sleepTool = tool({
 });
 ```
 
-</Step>
+Note that the `sleep()` function must be called from within a workflow context, not from within a step. This is why `executeSleep` does not have `"use step"` - it runs in the workflow context where `sleep()` is available.
 
+</Step>
 <Step>
 ### Emitting status updates
 
-We want the UI to display the waiting state, so we emit a new chunk type `data-wait`, that the UI can then consume.
+We want the UI to react to the tool call status, so we emit a new chunk type `data-wait`, that the UI can then consume.
 
 ```typescript lineNumbers
 // This is just a helper function to emit the sleep status to the UI

From 9a1a2b5f642e7c2276f03875f5330d52d1a59fb9 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 19:44:07 -0800
Subject: [PATCH 28/38] Update multi-turn example

---
 .../ai-agents/chat-session-modeling.mdx       | 44 ++++++++++++-------
 1 file changed, 29 insertions(+), 15 deletions(-)

diff --git a/docs/content/guides/ai-agents/chat-session-modeling.mdx b/docs/content/guides/ai-agents/chat-session-modeling.mdx
index 3d739d8ed..41d01d8e7 100644
--- a/docs/content/guides/ai-agents/chat-session-modeling.mdx
+++ b/docs/content/guides/ai-agents/chat-session-modeling.mdx
@@ -313,13 +313,15 @@ The multi-turn pattern also easily enables multi-party chat sessions. Parties ca
 
 <Tab value="System Event">
 
-```typescript title="app/api/webhooks/order-update/route.ts" lineNumbers
+Internal system events like scheduled tasks, background jobs, or database triggers can inject updates into an active conversation.
+
+```typescript title="app/api/internal/order-update/route.ts" lineNumbers
 import { chatMessageHook } from '@/ai/hooks/chat-message';
 
+// Called by your order processing system when status changes
 export async function POST(req: Request) {
   const { threadId, orderStatus } = await req.json();
 
-  // Inject order update into the conversation // [!code highlight]
   await chatMessageHook.resume(`thread:${threadId}`, { // [!code highlight]
     message: `[System] Order status updated: ${orderStatus}`, // [!code highlight]
   }); // [!code highlight]
@@ -332,18 +334,25 @@ export async function POST(req: Request) {
 
 <Tab value="External Service">
 
-```typescript title="app/api/webhooks/order-update/route.ts" lineNumbers
+External webhooks from third-party services (Stripe, Twilio, etc.) can notify the conversation of events.
+
+```typescript title="app/api/webhooks/stripe/route.ts" lineNumbers
 import { chatMessageHook } from '@/ai/hooks/chat-message';
+import Stripe from 'stripe';
 
 export async function POST(req: Request) {
-  const { threadId, orderStatus } = await req.json();
+  const event = await req.json() as Stripe.Event;
 
-  // Inject order update into the conversation // [!code highlight]
-  await chatMessageHook.resume(`thread:${threadId}`, { // [!code highlight]
-    message: `[System] Order status updated: ${orderStatus}`, // [!code highlight]
-  }); // [!code highlight]
+  if (event.type === 'payment_intent.succeeded') {
+    const paymentIntent = event.data.object as Stripe.PaymentIntent;
+    const threadId = paymentIntent.metadata.threadId; // [!code highlight]
 
-  return Response.json({ success: true });
+    await chatMessageHook.resume(`thread:${threadId}`, { // [!code highlight]
+      message: `[Stripe] Payment of $${(paymentIntent.amount / 100).toFixed(2)} received.`, // [!code highlight]
+    }); // [!code highlight]
+  }
+
+  return Response.json({ received: true });
 }
 ```
 
@@ -351,15 +360,20 @@ export async function POST(req: Request) {
 
 <Tab value="Multiple Users">
 
-```typescript title="app/api/webhooks/order-update/route.ts" lineNumbers
+Multiple human users can participate in the same conversation. Each user's client connects to the same workflow stream.
+
+```typescript title="app/api/chat/[id]/route.ts" lineNumbers
 import { chatMessageHook } from '@/ai/hooks/chat-message';
+import { getUser } from '@/lib/auth';
 
-export async function POST(req: Request) {
-  const { threadId, orderStatus } = await req.json();
+export async function POST(req: Request, { params }) {
+  const { id: threadId } = await params;
+  const { message } = await req.json();
+  const user = await getUser(req); // [!code highlight]
 
-  // Inject order update into the conversation // [!code highlight]
+  // Inject message with user attribution // [!code highlight]
   await chatMessageHook.resume(`thread:${threadId}`, { // [!code highlight]
-    message: `[System] Order status updated: ${orderStatus}`, // [!code highlight]
+    message: `[${user.name}] ${message}`, // [!code highlight]
   }); // [!code highlight]
 
   return Response.json({ success: true });
@@ -369,7 +383,7 @@ export async function POST(req: Request) {
 </Tab>
 
 </Tabs>
-j
+
 ## Related Documentation
 
 - [Building Durable AI Agents](/guides/ai-agents) - Foundation guide for durable agents

From 87aa49f3f3c5d8a82c59c197a4d6e097f78d4478 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Wed, 26 Nov 2025 19:53:50 -0800
Subject: [PATCH 29/38] Empty commit


From e7da6512e94cd13a327656798ed22ed1897bd291 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Sat, 29 Nov 2025 15:37:11 -0800
Subject: [PATCH 30/38] Polish

---
 docs/content/docs/ai-agents/index.mdx   |  1 +
 docs/content/guides/ai-agents/index.mdx | 34 +++++++++++++++----------
 2 files changed, 22 insertions(+), 13 deletions(-)

diff --git a/docs/content/docs/ai-agents/index.mdx b/docs/content/docs/ai-agents/index.mdx
index 8282f365c..af8a46b84 100644
--- a/docs/content/docs/ai-agents/index.mdx
+++ b/docs/content/docs/ai-agents/index.mdx
@@ -39,3 +39,4 @@ The `@workflow/ai` package exports the following:
 - [Streaming](/docs/foundations/streaming) - How streaming works in Workflow DevKit
 - [Workflows and Steps](/docs/foundations/workflows-and-steps) - Understanding the execution model
 - [Hooks & Webhooks](/docs/foundations/hooks) - Pausing workflows for external events
+
diff --git a/docs/content/guides/ai-agents/index.mdx b/docs/content/guides/ai-agents/index.mdx
index a8116a6be..4e2254aac 100644
--- a/docs/content/guides/ai-agents/index.mdx
+++ b/docs/content/guides/ai-agents/index.mdx
@@ -12,19 +12,19 @@ This guide walks you through converting a basic AI SDK agent into a durable agen
 
 ## Why Durable Agents?
 
-Aside from the usual challenges of getting your long-running tasks to be production-ready, building mature AI agents typically requires solving several additional **challenges**:
+Aside from the usual challenges of getting your long-running tasks to be production-ready, building mature AI agents typically requires solving several **additional challenges**:
 
-- **Durability**: Persisting chat sessions and turning all LLM and tool calls into separate async jobs, with workers, queues, and state management, which repeatedly save and re-load state from a database.
-- **Observability**: Using services to collect traces and metrics, separately storing your messages and user history, and then combining them to get a complete picture of your agent's behavior.
-- **Resumability**: Separately from storing messages for replayability, most LLM calls are streams, and recovering from a call failure without re-doing the entire call requires piping and storing streams separately from your messages, usually in a separate service.
-- **Human-in-the-loop**: Your client, API, and async job orchestration need to work together to create, track, route to, and display human approval requests, or similar webhook operations. If your stack is disjointed, this simple feature becomes a major orchestration challenge.
+- **Statefulness**: Persisting chat sessions and turning LLM and tool calls into async jobs with workers and queues.
+- **Observability**: Using services to collect traces and metrics, and managing them separately from your messages and user history.
+- **Resumability**: Resuming streams requires not just storing your messages, but also storing streams, and piping them across services.
+- **Human-in-the-loop**: Your client, API, and async job orchestration need to work together to create, track, route to, and display human approval requests, or similar webhook operations.
 
 Workflow DevKit provides all of these capabilities out of the box. Your agent becomes a workflow, your tools become steps, and the framework handles interplay with your existing infrastructure.
 
 ## Getting Started
 
-We start out with a basic Next.js application using the AI SDK's `Agent` class,
-which is a simple wrapper around AI SDK's `streamText` function. It comes with a simple tool for reading web pages.
+We start out with a basic Next.js application using the [AI SDK's `Agent` class](https://ai-sdk.dev/docs/agents/overview),
+which is a simple wrapper around [AI SDK's `streamText` function](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text#streamtext). It comes with a simple tool for reading web pages.
 
 <Tabs items={['API Route', 'Tools', 'Client']}>
 
@@ -128,7 +128,7 @@ Add the Workflow DevKit packages to your project:
 npm i workflow @workflow/ai
 ```
 
-and extend the NextJS compiler to transform the code:
+and extend the NextJS config to transform the your workflow code:
 
 ```typescript title="next.config.ts" lineNumbers
 import { withWorkflow } from 'workflow/next';
@@ -358,9 +358,11 @@ export function Chat() {
 
 </Steps>
 
-## Running the Workflow
+That's all you need to do to convert your basic AI SDK agent into a durable agent. If you run your development server, and send a chat message, you should see your agent respond just as before, but now with added durability and observability.
 
-Run your development server, then open the observability dashboard to see your workflow in action:
+## Observability
+
+In your app directory, you can open up the observability dashboard to see your workflow in action, using the CLI:
 
 ```bash
 npx workflow web
@@ -368,19 +370,25 @@ npx workflow web
 
 This opens a local dashboard showing all workflow runs and their status, as well as a trace viewer to inspect the workflow in detail, including retry attempts, and the data being passed between steps.
 
+If you'd like to have terminal interface instead, you can use the CLI directly:
+
+```bash
+npx workflow inspect runs
+```
+
 ## Next Steps
 
-Now that you have a basic durable agent, explore these additional features:
+Now that you have a basic durable agent, it's a only a short step to add these additional features:
 
 <Cards>
   <Card title="Resumable Streams" href="/guides/ai-agents/resumable-streams">
     Enable clients to reconnect to interrupted streams without losing data.
   </Card>
   <Card title="Sleep and Delays" href="/guides/ai-agents/sleep-and-delays">
-    Add native sleep functionality for time-based workflows.
+    Add native sleep and scheduling functionality to your Agent and workflow.
   </Card>
   <Card title="Human-in-the-Loop" href="/guides/ai-agents/human-in-the-loop">
-    Implement approval workflows that wait for human input.
+    Implement approval steps to wait for human input or external events.
   </Card>
 </Cards>
 

From 6a083cb093e6af1d4e46e87e828dca661d3ef25a Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Sat, 29 Nov 2025 15:38:25 -0800
Subject: [PATCH 31/38] Rename and link

---
 docs/content/docs/observability/index.mdx | 2 +-
 docs/content/guides/ai-agents/index.mdx   | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/content/docs/observability/index.mdx b/docs/content/docs/observability/index.mdx
index e25c538c7..4daf9b867 100644
--- a/docs/content/docs/observability/index.mdx
+++ b/docs/content/docs/observability/index.mdx
@@ -36,7 +36,7 @@ npx workflow inspect runs --web
 
 ## Backends
 
-The Workflow DevKit CLI can inspect data from any [World](/docs/deploying#what-are-worlds). By default, it inspects data in your local development environment. For example, if you are using NextJS to develop workflows locally, the
+The Workflow DevKit CLI can inspect data from any [World](/docs/deploying#what-are-worlds). By default, it inspects data in your local development environment. For example, if you are using Next.js to develop workflows locally, the
 CLI will find the data in your `.next/workflow-data/` directory.
 
 If you're deploying workflows to a production environment, but want to inspect the data by using the CLI, you can specify the world you are using by setting the `--backend` flag to your world's name or package name, e.g. `vercel`.
diff --git a/docs/content/guides/ai-agents/index.mdx b/docs/content/guides/ai-agents/index.mdx
index 4e2254aac..ca3c628b2 100644
--- a/docs/content/guides/ai-agents/index.mdx
+++ b/docs/content/guides/ai-agents/index.mdx
@@ -8,7 +8,7 @@ Workflow DevKit makes your agents production-ready, by turning them into durable
 
 <AgentTraces />
 
-This guide walks you through converting a basic AI SDK agent into a durable agent using Workflow DevKit.
+This guide walks you through converting a basic [AI SDK agent](https://ai-sdk.dev/docs/agents/overview) into a durable agent using Workflow DevKit.
 
 ## Why Durable Agents?
 
@@ -128,7 +128,7 @@ Add the Workflow DevKit packages to your project:
 npm i workflow @workflow/ai
 ```
 
-and extend the NextJS config to transform the your workflow code:
+and extend the Next.js config to transform your workflow code (see Next.js [Getting Started guide](/docs/getting-started/next) for more details):
 
 ```typescript title="next.config.ts" lineNumbers
 import { withWorkflow } from 'workflow/next';

From a07664d069abf8f2e13432dcfb988844b16aadcf Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Sat, 29 Nov 2025 16:00:37 -0800
Subject: [PATCH 32/38] Make web the default viewer for observability in
 getting-started guide

---
 docs/content/docs/getting-started/express.mdx   | 5 ++++-
 docs/content/docs/getting-started/hono.mdx      | 5 ++++-
 docs/content/docs/getting-started/next.mdx      | 4 +++-
 docs/content/docs/getting-started/nitro.mdx     | 5 ++++-
 docs/content/docs/getting-started/nuxt.mdx      | 6 ++++--
 docs/content/docs/getting-started/sveltekit.mdx | 4 +++-
 docs/content/docs/getting-started/vite.mdx      | 4 +++-
 7 files changed, 25 insertions(+), 8 deletions(-)

diff --git a/docs/content/docs/getting-started/express.mdx b/docs/content/docs/getting-started/express.mdx
index ce6176e6c..cb98e6e7d 100644
--- a/docs/content/docs/getting-started/express.mdx
+++ b/docs/content/docs/getting-started/express.mdx
@@ -234,7 +234,10 @@ Check the Express development server logs to see your workflow execute as well a
 Additionally, you can use the [Workflow DevKit CLI or Web UI](/docs/observability) to inspect your workflow runs and steps in detail.
 
 ```bash
-npx workflow inspect runs # add '--web' for an interactive Web based UI
+# Open the observability Web UI
+npx workflow web
+# or if you prefer a terminal interface, use the CLI inspect command
+npx workflow inspect runs
 ```
 
 <img src="/o11y-ui.png" alt="Workflow DevKit Web UI" />
diff --git a/docs/content/docs/getting-started/hono.mdx b/docs/content/docs/getting-started/hono.mdx
index ef12960e3..df7cb3ded 100644
--- a/docs/content/docs/getting-started/hono.mdx
+++ b/docs/content/docs/getting-started/hono.mdx
@@ -218,7 +218,10 @@ Check the Hono development server logs to see your workflow execute as well as t
 Additionally, you can use the [Workflow DevKit CLI or Web UI](/docs/observability) to inspect your workflow runs and steps in detail.
 
 ```bash
-npx workflow inspect runs # add '--web' for an interactive Web based UI
+# Open the observability Web UI
+npx workflow web
+# or if you prefer a terminal interface, use the CLI inspect command
+npx workflow inspect runs
 ```
 
 <img src="/o11y-ui.png" alt="Workflow DevKit Web UI" />
diff --git a/docs/content/docs/getting-started/next.mdx b/docs/content/docs/getting-started/next.mdx
index b822f170e..b4e09535e 100644
--- a/docs/content/docs/getting-started/next.mdx
+++ b/docs/content/docs/getting-started/next.mdx
@@ -241,8 +241,10 @@ Check the Next.js development server logs to see your workflow execute, as well
 Additionally, you can use the [Workflow DevKit CLI or Web UI](/docs/observability) to inspect your workflow runs and steps in detail.
 
 ```bash
+# Open the observability Web UI
+npx workflow web
+# or if you prefer a terminal interface, use the CLI inspect command
 npx workflow inspect runs
-# or add '--web' for an interactive Web based UI
 ```
 
 <img src="/o11y-ui.png" alt="Workflow DevKit Web UI" />
diff --git a/docs/content/docs/getting-started/nitro.mdx b/docs/content/docs/getting-started/nitro.mdx
index 94ec98748..ae622c789 100644
--- a/docs/content/docs/getting-started/nitro.mdx
+++ b/docs/content/docs/getting-started/nitro.mdx
@@ -202,7 +202,10 @@ Check the Nitro development server logs to see your workflow execute as well as
 Additionally, you can use the [Workflow DevKit CLI or Web UI](/docs/observability) to inspect your workflow runs and steps in detail.
 
 ```bash
-npx workflow inspect runs # add '--web' for an interactive Web based UI
+# Open the observability Web UI
+npx workflow web
+# or if you prefer a terminal interface, use the CLI inspect command
+npx workflow inspect runs
 ```
 
 <img src="/o11y-ui.png" alt="Workflow DevKit Web UI" />
diff --git a/docs/content/docs/getting-started/nuxt.mdx b/docs/content/docs/getting-started/nuxt.mdx
index d89bd7803..a23954703 100644
--- a/docs/content/docs/getting-started/nuxt.mdx
+++ b/docs/content/docs/getting-started/nuxt.mdx
@@ -202,7 +202,10 @@ Check the Nuxt development server logs to see your workflow execute as well as t
 Additionally, you can use the [Workflow DevKit CLI or Web UI](/docs/observability) to inspect your workflow runs and steps in detail.
 
 ```bash
-npx workflow inspect runs # add '--web' for an interactive Web based UI
+# Open the observability Web UI
+npx workflow web
+# or if you prefer a terminal interface, use the CLI inspect command
+npx workflow inspect runs
 ```
 
 <img src="/o11y-ui.png" alt="Workflow DevKit Web UI" />
@@ -222,4 +225,3 @@ Check the [Deploying](/docs/deploying) section to learn how your workflows can b
 - Learn more about the [Foundations](/docs/foundations).
 - Check [Errors](/docs/errors) if you encounter issues.
 - Explore the [API Reference](/docs/api-reference).
-
diff --git a/docs/content/docs/getting-started/sveltekit.mdx b/docs/content/docs/getting-started/sveltekit.mdx
index 451e67523..0cd85534e 100644
--- a/docs/content/docs/getting-started/sveltekit.mdx
+++ b/docs/content/docs/getting-started/sveltekit.mdx
@@ -206,8 +206,10 @@ Check the SvelteKit development server logs to see your workflow execute as well
 Additionally, you can use the [Workflow DevKit CLI or Web UI](/docs/observability) to inspect your workflow runs and steps in detail.
 
 ```bash
+# Open the observability Web UI
+npx workflow web
+# or if you prefer a terminal interface, use the CLI inspect command
 npx workflow inspect runs
-# or add '--web' for an interactive Web based UI
 ```
 
 <img src="/o11y-ui.png" alt="Workflow DevKit Web UI" />
diff --git a/docs/content/docs/getting-started/vite.mdx b/docs/content/docs/getting-started/vite.mdx
index 62eced9d3..cf01afdeb 100644
--- a/docs/content/docs/getting-started/vite.mdx
+++ b/docs/content/docs/getting-started/vite.mdx
@@ -209,8 +209,10 @@ Check the Vite development server logs to see your workflow execute as well as t
 Additionally, you can use the [Workflow DevKit CLI or Web UI](/docs/observability) to inspect your workflow runs and steps in detail.
 
 ```bash
+# Open the observability Web UI
+npx workflow web
+# or if you prefer a terminal interface, use the CLI inspect command
 npx workflow inspect runs
-# or add '--web' for an interactive Web based UI
 ```
 
 <img src="/o11y-ui.png" alt="Workflow DevKit Web UI" />

From 5d7907e1df114b873ac4d2f74a05ee8ec167b768 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Sat, 29 Nov 2025 16:24:41 -0800
Subject: [PATCH 33/38] Remove "defining tools" page in favor of adding a small
 section to the "sleep and delays" page

---
 .../content/docs/ai-agents/defining-tools.mdx | 109 ------------------
 docs/content/docs/ai-agents/index.mdx         |  42 -------
 docs/content/docs/ai-agents/meta.json         |   5 -
 docs/content/docs/meta.json                   |   1 -
 .../guides/ai-agents/sleep-and-delays.mdx     |  30 +++++
 5 files changed, 30 insertions(+), 157 deletions(-)
 delete mode 100644 docs/content/docs/ai-agents/defining-tools.mdx
 delete mode 100644 docs/content/docs/ai-agents/index.mdx
 delete mode 100644 docs/content/docs/ai-agents/meta.json

diff --git a/docs/content/docs/ai-agents/defining-tools.mdx b/docs/content/docs/ai-agents/defining-tools.mdx
deleted file mode 100644
index 6d07d9074..000000000
--- a/docs/content/docs/ai-agents/defining-tools.mdx
+++ /dev/null
@@ -1,109 +0,0 @@
----
-title: Defining Tools
----
-
-Tools in Workflow DevKit follow the same structure as [AI SDK tools](https://ai-sdk.dev/docs/foundations/tools), but with additional context provided by `DurableAgent`. This page covers the key concepts for defining tools in durable agents.
-
-<Callout type="info">
-For a complete walkthrough with examples, see the **[Building Durable AI Agents](/guides/ai-agents)** guide.
-</Callout>
-
-## Tool Execute Context
-
-When `DurableAgent` invokes a tool, the execute function receives additional context:
-
-```typescript lineNumbers
-execute: async (input, options) => {
-  const { toolCallId, messages } = options;
-
-  // toolCallId: Unique identifier for correlating stream chunks
-  // messages: Full conversation history (LanguageModelV2Prompt format)
-
-  return result;
-}
-```
-
-### Accessing Conversation Messages
-
-Tools can access the full conversation history through the `messages` option:
-
-```typescript lineNumbers
-export const summarizeConversation = tool({
-  description: 'Summarize the conversation so far',
-  inputSchema: z.object({
-    focus: z.string().optional(),
-  }),
-  execute: async ({ focus }, { messages }) => { // [!code highlight]
-    const userMessages = messages
-      .filter(m => m.role === 'user')
-      .map(m => m.content.filter(p => p.type === 'text').map(p => p.text).join(' '));
-
-    return { summary: userMessages.slice(-3).join(', ') };
-  },
-});
-```
-
-## Streaming from Tools
-
-Tools can emit real-time updates by writing to the workflow's output stream. Since `getWritable()` requires the step context, streaming must be done in a step function:
-
-```typescript lineNumbers
-async function emitProgress(status: string, toolCallId: string) {
-  'use step'; // [!code highlight]
-
-  const writable = getWritable<UIMessageChunk>(); // [!code highlight]
-  const writer = writable.getWriter(); // [!code highlight]
-
-  await writer.write({ // [!code highlight]
-    id: toolCallId,
-    type: 'data-status',
-    data: { status },
-  });
-
-  writer.releaseLock();
-}
-
-async function executeSearch({ query }: { query: string }, { toolCallId }: { toolCallId: string }) {
-  'use step';
-  await emitProgress('searching', toolCallId); // [!code highlight]
-  const results = await performSearch(query);
-  await emitProgress('complete', toolCallId); // [!code highlight]
-  return results;
-}
-```
-
-## Step-Level vs Workflow-Level
-
-Tools can run at two levels with different capabilities:
-
-| Capability | Step-Level (`"use step"`) | Workflow-Level (`"use workflow"`) |
-|------------|---------------------------|----------------|
-| `getWritable()` | ✅ | ❌ |
-| Automatic retries | ✅ | ❌ |
-| `sleep()` | ❌ | ✅ |
-| `createWebhook()` | ❌ | ✅ |
-
-Tools can combine both: use a step function for I/O operations, and keep the execute function at the workflow level for orchestration:
-
-```typescript lineNumbers
-// Step: handles I/O with retries
-async function performFetch(url: string) {
-  'use step';
-  const response = await fetch(url);
-  return response.json();
-}
-
-// Workflow-level: orchestrates steps and can use sleep()
-async function executeFetchWithDelay({ url }: { url: string }) {
-  const result = await performFetch(url);
-  await sleep('5s'); // Only available at workflow level
-  return result;
-}
-```
-
-## Related
-
-- [Building Durable AI Agents](/guides/ai-agents) - Complete guide with examples
-- [Streaming](/docs/foundations/streaming) - How streaming works
-- [Workflows and Steps](/docs/foundations/workflows-and-steps) - Understanding execution contexts
-- [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Full API documentation
diff --git a/docs/content/docs/ai-agents/index.mdx b/docs/content/docs/ai-agents/index.mdx
deleted file mode 100644
index af8a46b84..000000000
--- a/docs/content/docs/ai-agents/index.mdx
+++ /dev/null
@@ -1,42 +0,0 @@
----
-title: AI & Agents
----
-
-Workflow DevKit provides first-class support for building durable AI agents through the `@workflow/ai` package. This package integrates with the [AI SDK](https://ai-sdk.dev) to provide production-ready agent primitives.
-
-## Guide
-
-For a complete walkthrough of building AI agents with Workflow DevKit, see the **[Building Durable AI Agents](/guides/ai-agents)** guide, which covers:
-
-- Converting AI SDK agents to durable agents
-- Implementing resumable streams
-- Adding sleep and scheduling capabilities
-- Human-in-the-loop approval patterns
-
-## Core Concepts
-
-<Cards>
-  <Card title="Defining Tools" href="/docs/ai-agents/defining-tools">
-    Learn how to define tools for durable agents, including streaming from tools and accessing conversation context.
-  </Card>
-</Cards>
-
-## API Reference
-
-The `@workflow/ai` package exports the following:
-
-<Cards>
-  <Card title="DurableAgent" href="/docs/api-reference/workflow-ai/durable-agent">
-    The main class for creating AI agents that maintain state across workflow steps, call tools, and handle interruptions.
-  </Card>
-  <Card title="WorkflowChatTransport" href="/docs/api-reference/workflow-ai/workflow-chat-transport">
-    AI SDK transport for reliable message streaming with automatic reconnection and resumption.
-  </Card>
-</Cards>
-
-## Related
-
-- [Streaming](/docs/foundations/streaming) - How streaming works in Workflow DevKit
-- [Workflows and Steps](/docs/foundations/workflows-and-steps) - Understanding the execution model
-- [Hooks & Webhooks](/docs/foundations/hooks) - Pausing workflows for external events
-
diff --git a/docs/content/docs/ai-agents/meta.json b/docs/content/docs/ai-agents/meta.json
deleted file mode 100644
index 14aa95e51..000000000
--- a/docs/content/docs/ai-agents/meta.json
+++ /dev/null
@@ -1,5 +0,0 @@
-{
-  "title": "AI & Agents",
-  "pages": ["defining-tools"],
-  "defaultOpen": true
-}
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index 89a95d728..b527dc11f 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -6,7 +6,6 @@
     "foundations",
     "how-it-works",
     "observability",
-    "ai-agents",
     "deploying",
     "errors",
     "api-reference"
diff --git a/docs/content/guides/ai-agents/sleep-and-delays.mdx b/docs/content/guides/ai-agents/sleep-and-delays.mdx
index 66b45fbd4..a963cd815 100644
--- a/docs/content/guides/ai-agents/sleep-and-delays.mdx
+++ b/docs/content/guides/ai-agents/sleep-and-delays.mdx
@@ -112,6 +112,36 @@ async function executeSleep(
 
 </Steps>
 
+## Step-Level vs Workflow-Level Tools
+
+Tools can be implemented either at the step level or the workflow level, with different capabilities and constraints.
+
+| Capability | Step-Level (`"use step"`) | Workflow-Level (`"use workflow"`) |
+|------------|---------------------------|----------------|
+| `getWritable()` | ✅ | ❌ |
+| Automatic retries | ✅ | ❌ |
+| Side-effects (e.g. API calls) allowed | ✅ | ❌ |
+| `sleep()` | ❌ | ✅ |
+| `createWebhook()` | ❌ | ✅ |
+
+Tools can also combine both by starting out on the workflow level, and calling into steps for I/O operations, like so:
+
+```typescript lineNumbers
+// Step: handles I/O with retries
+async function performFetch(url: string) {
+  'use step';
+  const response = await fetch(url);
+  return response.json();
+}
+
+// Workflow-level: orchestrates steps and can use sleep()
+async function executeFetchWithDelay({ url }: { url: string }) {
+  const result = await performFetch(url);
+  await sleep('5s'); // Only available at workflow level
+  return result;
+}
+```
+
 ## Use Cases
 
 Aside from providing `sleep()` as a tool, there are other use cases for Agents that commonly call for suspension and resumption.

From 7656c9c35da039d05f6986354e29b3783dbd9723 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Sat, 29 Nov 2025 17:44:30 -0800
Subject: [PATCH 34/38] Highlight selected header items

---
 docs/components/geistdocs/desktop-menu.tsx | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/docs/components/geistdocs/desktop-menu.tsx b/docs/components/geistdocs/desktop-menu.tsx
index a74abd4b5..022c37a27 100644
--- a/docs/components/geistdocs/desktop-menu.tsx
+++ b/docs/components/geistdocs/desktop-menu.tsx
@@ -1,6 +1,7 @@
 'use client';
 
 import Link from 'next/link';
+import { usePathname } from 'next/navigation';
 import {
   NavigationMenu,
   NavigationMenuItem,
@@ -8,6 +9,7 @@ import {
   NavigationMenuList,
 } from '@/components/ui/navigation-menu';
 import { useIsMobile } from '@/hooks/use-mobile';
+import { cn } from '@/lib/utils';
 
 type DesktopMenuProps = {
   items: { label: string; href: string }[];
@@ -15,6 +17,12 @@ type DesktopMenuProps = {
 
 export const DesktopMenu = ({ items }: DesktopMenuProps) => {
   const isMobile = useIsMobile();
+  const pathname = usePathname();
+
+  const isActive = (href: string) => {
+    if (href.startsWith('http')) return false;
+    return pathname === href || pathname.startsWith(`${href}/`);
+  };
 
   return (
     <NavigationMenu viewport={isMobile}>
@@ -23,7 +31,10 @@ export const DesktopMenu = ({ items }: DesktopMenuProps) => {
           <NavigationMenuItem key={item.href}>
             <NavigationMenuLink
               asChild
-              className="rounded-md px-3 font-medium text-sm"
+              className={cn(
+                'rounded-md px-3 font-medium text-sm text-gray-400',
+                isActive(item.href) && 'text-white'
+              )}
             >
               <Link href={item.href}>{item.label}</Link>
             </NavigationMenuLink>

From 239c671569ae88685591f5b11fe733915abd60b1 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Sat, 29 Nov 2025 17:52:11 -0800
Subject: [PATCH 35/38] New example query for docs search

---
 docs/app/layout.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/app/layout.tsx b/docs/app/layout.tsx
index a25ff356d..0cc98f57a 100644
--- a/docs/app/layout.tsx
+++ b/docs/app/layout.tsx
@@ -43,6 +43,7 @@ const suggestions = [
   'How does retrying work?',
   'What control flow patterns are there?',
   'How do directives work?',
+  'How do I build an AI agent?',
 ];
 
 const Layout = ({ children }: LayoutProps<'/'>) => (

From ee0ed68e4a9d6370d561d1ec371add9eb1ba1544 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Sat, 29 Nov 2025 19:29:29 -0800
Subject: [PATCH 36/38] Add all of the example and setup code

---
 docs/content/guides/ai-agents/index.mdx | 147 +++++++++++++++++++-----
 1 file changed, 119 insertions(+), 28 deletions(-)

diff --git a/docs/content/guides/ai-agents/index.mdx b/docs/content/guides/ai-agents/index.mdx
index ca3c628b2..225028ab6 100644
--- a/docs/content/guides/ai-agents/index.mdx
+++ b/docs/content/guides/ai-agents/index.mdx
@@ -8,7 +8,7 @@ Workflow DevKit makes your agents production-ready, by turning them into durable
 
 <AgentTraces />
 
-This guide walks you through converting a basic [AI SDK agent](https://ai-sdk.dev/docs/agents/overview) into a durable agent using Workflow DevKit.
+This guide walks you through converting a basic AI chat app into a durable AI agent using Workflow DevKit.
 
 ## Why Durable Agents?
 
@@ -23,28 +23,105 @@ Workflow DevKit provides all of these capabilities out of the box. Your agent be
 
 ## Getting Started
 
-We start out with a basic Next.js application using the [AI SDK's `Agent` class](https://ai-sdk.dev/docs/agents/overview),
-which is a simple wrapper around [AI SDK's `streamText` function](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text#streamtext). It comes with a simple tool for reading web pages.
+To make an Agent durable, we first need an Agent, which we'll be setting up here. If you already have an app you'd like to follow along with, you can skip this section.
 
-<Tabs items={['API Route', 'Tools', 'Client']}>
+For our example, we'll need an app with a simple chat interface and an API route calling an LLM, so that we can add Workflow DevKit to it. We'll use the [Flight Booking Agent](https://github.com/vercel/workflow-examples/tree/main/flight-booking-app) example as a starting point, which comes with a chat interface built using Next.js, AI SDK, and Shadcn UI.
 
-<Tab value="API Route">
+<Steps>
+
+<Step>
+### Clone example app
+
+We'll need an app with a simple chat interface and an API route calling an LLM, so that we can add Workflow DevKit to it. For the follow-along steps, we'll use the [Flight Booking Agent](https://github.com/vercel/workflow-examples/tree/main/flight-booking-app) example as a starting point, which comes with a chat interface built using Next.js, AI SDK, and Shadcn UI.
+
+If you have your own project, you can skip this step, and simply apply the changes of the following steps to your own project.
+
+```bash
+git clone https://github.com/vercel/workflow-examples -b plain-ai-sdk
+cd workflow-examples/flight-booking-app
+```
+
+</Step>
+
+<Step>
+
+### Set up API keys
+
+In order to connect to an LLM, we'll need to set up an API key. The easiest way to do this is to use a Vercel Gateway (works with all providers at zero markup), or you can configure a custom provider.
+<Tabs items={['Gateway', 'Custom Provider']}>
+
+<Tab value="Gateway">
+
+Get a Gateway API key from the [Vercel Gateway](https://vercel.com/docs/gateway/api-reference/overview) page.
+
+Then add it to your `.env.local` file:
+
+```bash title=".env.local" lineNumbers
+GATEWAY_API_KEY=...
+```
+
+</Tab>
+
+<Tab value="Custom Provider">
+
+This is an example of how to use the OpenAI provider for AI SDK. For details on other providers and more details, see the [AI SDK provider guide](https://ai-sdk.dev/providers/ai-sdk-providers).
+
+```package-install
+npm i @ai-sdk/openai
+```
+
+Set your OpenAI API key in your environment variables:
+
+```bash title=".env.local" lineNumbers
+OPENAI_API_KEY=...
+```
+
+Then modify your API endpoint to use the OpenAI provider:
 
 ```typescript title="app/api/chat/route.ts" lineNumbers
-import { createUIMessageStreamResponse, Experimental_Agent as Agent, stepCountIs } from 'ai';
-import { tools } from '@/ai/tools';
+// ...
+import { openai } from '@ai-sdk/openai'; // [!code highlight]
 
-export async function POST(req: Request) {
-  const { messages, modelId } = await req.json();
+// This uses the OPENAI_API_KEY environment variable by default, but you
+// can also pass { apiKey: string } to the createOpenAI function.
+const openai = createOpenAI();
 
+export async function POST(req: Request) {
+  // ...
   const agent = new Agent({
-    model: modelId,
-    system: 'You are a helpful assistant.',
-    tools,
+    model: openai('gpt-5.1'), // [!code highlight]
+    // ...
   });
+```
+
+</Tab>
+</Tabs>
+</Step>
 
-  const stream = agent.stream({ messages });
+<Step>
+
+### Get familiar with the code
+
+Let's take a moment to see what we're working with. Run the app with `npm run dev` and open [http://localhost:3000](http://localhost:3000) in your browser. You should see a simple chat interface to play with. Go ahead and give it a try.
 
+The core code that makes all of this happen is quite simple. Here's a breakdown of the main parts:
+
+<Tabs items={['API Route', 'Tools', 'Client']}>
+
+<Tab value="API Route">
+
+Our API route makes a simple call to [AI SDK's `Agent` class](https://ai-sdk.dev/docs/agents/overview), which is a simple wrapper around [AI SDK's `streamText` function](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text#streamtext). This is also where we pass tools to the agent.
+
+```typescript title="app/api/chat/route.ts" lineNumbers
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+  const agent = new Agent({ // [!code highlight]
+    model: gateway('bedrock/claude-4-5-haiku-20251001-v1'),
+    system: FLIGHT_ASSISTANT_PROMPT,
+    tools: flightBookingTools,
+  });
+  const modelMessages = convertToModelMessages(messages);
+  const stream = agent.stream({ messages: modelMessages }); // [!code highlight]
   return createUIMessageStreamResponse({
     stream: stream.toUIMessageStream(),
   });
@@ -55,47 +132,55 @@ export async function POST(req: Request) {
 
 <Tab value="Tools">
 
-```typescript title="ai/tools/index.ts" lineNumbers
+Our tools are mostly mocked out for the sake of the example. We use AI SDK's `tool` function to define the tool, and pass it to the agent. In your own app, this might be any kind of tool call, like database queries, calls to external services, etc.
+
+```typescript title="workflows/chat/steps/tools.ts" lineNumbers
 import { tool } from 'ai';
 import { z } from 'zod';
 
 export const tools = {
-  searchWeb: tool({
-    description: 'Read a web page and return the content',
-    inputSchema: z.object({ url: z.string() }),
-    execute: async ({ url }: { url: string }) => {
-      const response = await fetch(url);
-      return response.text();
-    },
+  searchFlights: tool({
+    description: 'Search for flights',
+    inputSchema: z.object({ query: z.string() }),
+    execute: searchFlights,
   }),
 };
+
+async function searchFlights({ from, to, date }: { from: string; to: string; date: string }) {
+  // ... generate some fake flights
+}
 ```
 
 </Tab>
 
 <Tab value="Client">
 
+Our `ChatPage` component has a lot of logic for nicely displaying the chat messages, but at it's core, it's simply managing input/output for the [`useChat` hook](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) from AI SDK.
+
 ```typescript title="app/chat.tsx" lineNumbers
 'use client';
 
 import { useChat } from '@ai-sdk/react';
 
-export function Chat() {
-  const { messages, input, handleInputChange, handleSubmit } = useChat({
+export default function ChatPage() {
+  const { messages, input, handleInputChange, handleSubmit } = useChat({ // [!code highlight]
     api: '/api/chat',
   });
 
+  // ... more UI logic
+
   return (
     <div>
+      // This is a simplified example of the rendering logic
       {messages.map((m) => (
         <div key={m.id}>
           <strong>{m.role}:</strong>
           {m.parts.map((part, i) => {
-            if (part.type === 'text') {
+            if (part.type === 'text') { // [!code highlight]
               return <span key={i}>{part.text}</span>;
             }
-            if (part.type === 'tool-invocation') {
-              return <div key={i}>Calling {part.toolInvocation.toolName}...</div>;
+            if (part.type === 'tool-searchFlights') { // [!code highlight]
+              // ... some special rendering for our tool results
             }
             return null;
           })}
@@ -117,9 +202,15 @@ export function Chat() {
 
 </Tabs>
 
-<Steps>
+</Step>
 
+</Steps>
+
+## Integrating Workflow DevKit
+
+<Steps>
 <Step>
+
 ### Install Dependencies
 
 Add the Workflow DevKit packages to your project:
@@ -128,7 +219,7 @@ Add the Workflow DevKit packages to your project:
 npm i workflow @workflow/ai
 ```
 
-and extend the Next.js config to transform your workflow code (see Next.js [Getting Started guide](/docs/getting-started/next) for more details):
+and extend the Next.js config to transform your workflow code (see [Getting Started](/docs/getting-started/next) for more details).
 
 ```typescript title="next.config.ts" lineNumbers
 import { withWorkflow } from 'workflow/next';

From 1db89f92e6eb435c022205d7a224f0cef1507e3a Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Sat, 29 Nov 2025 19:59:33 -0800
Subject: [PATCH 37/38] Split out section about streaming updates from tools

---
 docs/content/guides/ai-agents/index.mdx       | 184 +++++-------------
 docs/content/guides/ai-agents/meta.json       |   1 +
 .../streaming-updates-from-tools.mdx          | 111 +++++++++++
 3 files changed, 164 insertions(+), 132 deletions(-)
 create mode 100644 docs/content/guides/ai-agents/streaming-updates-from-tools.mdx

diff --git a/docs/content/guides/ai-agents/index.mdx b/docs/content/guides/ai-agents/index.mdx
index 225028ab6..d239149ca 100644
--- a/docs/content/guides/ai-agents/index.mdx
+++ b/docs/content/guides/ai-agents/index.mdx
@@ -104,7 +104,7 @@ export async function POST(req: Request) {
 
 Let's take a moment to see what we're working with. Run the app with `npm run dev` and open [http://localhost:3000](http://localhost:3000) in your browser. You should see a simple chat interface to play with. Go ahead and give it a try.
 
-The core code that makes all of this happen is quite simple. Here's a breakdown of the main parts:
+The core code that makes all of this happen is quite simple. Here's a breakdown of the main parts. Note that there's no changes needed here, we're simply taking a look at the code to understand what's happening.
 
 <Tabs items={['API Route', 'Tools', 'Client']}>
 
@@ -208,6 +208,8 @@ export default function ChatPage() {
 
 ## Integrating Workflow DevKit
 
+Now that we have a basic agent using AI SDK, we can modify it to make it durable.
+
 <Steps>
 <Step>
 
@@ -237,9 +239,9 @@ export default withWorkflow(nextConfig);
 <Step>
 ### Create a Workflow Function
 
-Move the agent logic into a separate workflow function:
+Move the agent logic into a separate function, which will serve as our workflow definition.
 
-```typescript title="app/api/chat/workflow.ts" lineNumbers
+```typescript title="workflows/chat/workflow.ts" lineNumbers
 import { DurableAgent } from '@workflow/ai/agent'; // [!code highlight]
 import { getWritable } from 'workflow'; // [!code highlight]
 import { stepCountIs } from 'ai';
@@ -273,27 +275,27 @@ export async function chatWorkflow({
 
 Key changes:
 
-- Replace `Agent` with [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) from `@workflow/ai/agent`
-- Add the `"use workflow"` directive to mark this as a workflow function
-- Use [`getWritable()`](/docs/api-reference/workflow/get-writable) to get a stream for agent output
-- Pass the `writable` to `agent.stream()` instead of returning a stream directly
+- Add the `"use workflow"` directive to mark our Agent as a workflow function
+- Replaced `Agent` with [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) from `@workflow/ai/agent`. This ensures that all calls to the LLM are executed as "steps", and results are aggregated within the workflow context (see [Workflows and Steps](/docs/foundations/workflows-and-steps) for more details on how workflows/steps are defined).
+- Use [`getWritable()`](/docs/api-reference/workflow/get-writable) to get a stream for agent output. This stream is persistent, and API endpoints can read from a run's stream at any time.
 </Step>
 
 <Step>
 ### Update the API Route
 
-Replace the agent call with [`start()`](/docs/api-reference/workflow-api/start) to run the workflow:
+Remove the agent call that we just extracted, and replace it with a call to `start()` to run the workflow:
 
 ```typescript title="app/api/chat/route.ts" lineNumbers
-import { createUIMessageStreamResponse, convertToModelMessages } from 'ai';
-import { start } from 'workflow/api'; // [!code highlight]
-import { chatWorkflow } from './workflow'; // [!code highlight]
+import type { UIMessage } from 'ai';
+import { convertToModelMessages, createUIMessageStreamResponse } from 'ai';
+import { start } from 'workflow/api';
+import { chatWorkflow } from '@/workflows/chat/workflow';
 
 export async function POST(req: Request) {
-  const { messages, modelId } = await req.json();
+  const { messages }: { messages: UIMessage[] } = await req.json();
   const modelMessages = convertToModelMessages(messages);
 
-  const run = await start(chatWorkflow, [{ messages: modelMessages, modelId }]); // [!code highlight]
+  const run = await start(chatWorkflow, [modelMessages]); // [!code highlight]
 
   return createUIMessageStreamResponse({
     stream: run.readable, // [!code highlight]
@@ -301,150 +303,68 @@ export async function POST(req: Request) {
 }
 ```
 
+Key changes:
+
+- Call `start()` to run the workflow function. This returns a `Run` object, which contains the run ID and the readable stream (see [Starting Workflows](/docs/foundations/starting-workflows) for more details on the `Run` object).
+- Pass the `writable` to `agent.stream()` instead of returning a stream directly, ensuring all the Agent output is written to to the run's stream.
+
 </Step>
 
 <Step>
 ### Convert Tools to Steps
 
-Mark tool execution functions with `"use step"` to make them durable. This enables automatic retries and observability:
+Mark all tool definitions with `"use step"` to make them durable. This enables automatic retries and observability for each tool call:
 
 ```typescript title="ai/tools/search-web.ts" lineNumbers
-import { tool } from 'ai';
-import { z } from 'zod';
+// ...
 
-async function executeSearch({ query }: { query: string }) {
+export async function searchFlights(
+  // ... arguments
+) {
   'use step'; // [!code highlight]
 
-  const response = await fetch(`https://api.search.com?q=${query}`);
-  return response.json();
+  // ... rest of the tool code
 }
 
-export const searchWeb = tool({
-  description: 'Search the web for information',
-  inputSchema: z.object({ query: z.string() }),
-  execute: executeSearch,
-});
-```
-
-With `"use step"`:
-
-- The tool execution runs in a separate step with full Node.js access
-- Failed tool calls are automatically retried (up to 3 times by default)
-- Each tool execution appears as a discrete step in observability tools
-- Results are persisted, so replays skip already-completed tools
-</Step>
-
-<Step>
-### Stream Progress Updates from Tools
-
-Tools can emit progress updates to the same stream the agent uses. This allows the UI to display tool status.
-
-<Tabs items={['Tool', 'Client']}>
-
-<Tab value="Tool">
-
-```typescript title="ai/tools/search-web.ts" lineNumbers
-import { tool } from 'ai';
-import { getWritable } from 'workflow';
-import { z } from 'zod';
-import type { UIMessageChunk } from 'ai';
-
-async function executeSearch(
-  { url }: { url: string },
-  { toolCallId }: { toolCallId: string }
+export async function checkFlightStatus(
+  // ... arguments
 ) {
-  'use step';
-
-  const writable = getWritable<UIMessageChunk>(); // [!code highlight]
-  const writer = writable.getWriter(); // [!code highlight]
-
-  // Emit a progress update // [!code highlight]
-  await writer.write({ // [!code highlight]
-    id: toolCallId, // [!code highlight]
-    type: 'data-search-web', // [!code highlight]
-    data: { url, status: 'fetching' }, // [!code highlight]
-  }); // [!code highlight]
-
-  const response = await fetch(url);
-  const content = await response.text();
-
-  await writer.write({ // [!code highlight]
-    id: toolCallId, // [!code highlight]
-    type: 'data-search-web', // [!code highlight]
-    data: { url, status: 'done' }, // [!code highlight]
-  }); // [!code highlight]
-
-  writer.releaseLock(); // [!code highlight]
+  'use step'; // [!code highlight]
 
-  return content;
+  // ... rest of the tool code
 }
 
-export const searchWeb = tool({
-  description: 'Read a web page and return the content',
-  inputSchema: z.object({ url: z.string() }),
-  execute: executeSearch,
-});
-```
-
-</Tab>
-
-<Tab value="Client">
+export async function getAirportInfo(
+  // ... arguments
+) {
+  'use step'; // [!code highlight]
 
-Handle the `data-search-web` chunks in your client to display progress. Data parts are stored in the message, so you can find the latest status directly:
+  // ... rest of the tool code
+}
 
-```typescript title="app/chat.tsx" lineNumbers
-'use client';
+export async function bookFlight({
+  // ... arguments
+}) {
+  'use step'; // [!code highlight]
 
-import { useChat } from '@ai-sdk/react';
+  // ... rest of the tool code
+}
 
-export function Chat() {
-  const { messages, input, handleInputChange, handleSubmit } = useChat({
-    api: '/api/chat',
-  });
+export async function checkBaggageAllowance(
+  // ... arguments
+) {
+    'use step'; // [!code highlight]
 
-  return (
-    <div>
-      {messages.map((m) => (
-        <div key={m.id}>
-          <strong>{m.role}:</strong>
-          {m.parts.map((part, i) => {
-            if (part.type === 'text') {
-              return <span key={i}>{part.text}</span>;
-            }
-            if (part.type === 'tool-invocation') {
-              // Find the latest data part for this tool call // [!code highlight]
-              const dataPart = m.parts.findLast( // [!code highlight]
-                (p) => p.type === 'data' && p.id === part.toolInvocation.toolCallId // [!code highlight]
-              ); // [!code highlight]
-              const status = dataPart?.type === 'data' ? dataPart.data : null; // [!code highlight]
-              return (
-                <div key={i}>
-                  {status?.status === 'fetching' // [!code highlight]
-                    ? `Fetching ${status.url}...` // [!code highlight]
-                    : `Called ${part.toolInvocation.toolName}`} // [!code highlight]
-                </div>
-              );
-            }
-            return null;
-          })}
-        </div>
-      ))}
-      <form onSubmit={handleSubmit}>
-        <input
-          value={input}
-          onChange={handleInputChange}
-          placeholder="Type a message..."
-        />
-      </form>
-    </div>
-  );
+    // ... rest of the tool code
+  }
 }
 ```
 
-</Tab>
-
-</Tabs>
+With `"use step"`:
 
+- The tool execution runs in a separate step with full Node.js access. In production, each step is executed in a separate worker process, which scales automatically with your workload.
+- Failed tool calls are automatically retried (up to 3 times by default). See [Errors and Retries](/docs/foundations/errors-and-retries) for more details.
+- Each tool execution appears as a discrete step in observability tools. See [Observability](/docs/observability) for more details.
 </Step>
 
 </Steps>
diff --git a/docs/content/guides/ai-agents/meta.json b/docs/content/guides/ai-agents/meta.json
index 0b1f32110..902c3ec41 100644
--- a/docs/content/guides/ai-agents/meta.json
+++ b/docs/content/guides/ai-agents/meta.json
@@ -2,6 +2,7 @@
   "title": "AI Agents",
   "pages": [
     "index",
+    "streaming-updates-from-tools",
     "resumable-streams",
     "sleep-and-delays",
     "human-in-the-loop",
diff --git a/docs/content/guides/ai-agents/streaming-updates-from-tools.mdx b/docs/content/guides/ai-agents/streaming-updates-from-tools.mdx
new file mode 100644
index 000000000..d34d94fa7
--- /dev/null
+++ b/docs/content/guides/ai-agents/streaming-updates-from-tools.mdx
@@ -0,0 +1,111 @@
+---
+title: Streaming Updates from Tools
+---
+
+Tools can emit progress updates to the same stream the agent uses. This allows the UI to display tool status.
+
+<Tabs items={['Tool', 'Client']}>
+
+<Tab value="Tool">
+
+```typescript title="ai/tools/search-web.ts" lineNumbers
+import { tool } from 'ai';
+import { getWritable } from 'workflow';
+import { z } from 'zod';
+import type { UIMessageChunk } from 'ai';
+
+async function executeSearch(
+  { url }: { url: string },
+  { toolCallId }: { toolCallId: string }
+) {
+  'use step';
+
+  const writable = getWritable<UIMessageChunk>(); // [!code highlight]
+  const writer = writable.getWriter(); // [!code highlight]
+
+  // Emit a progress update // [!code highlight]
+  await writer.write({ // [!code highlight]
+    id: toolCallId, // [!code highlight]
+    type: 'data-search-web', // [!code highlight]
+    data: { url, status: 'fetching' }, // [!code highlight]
+  }); // [!code highlight]
+
+  const response = await fetch(url);
+  const content = await response.text();
+
+  await writer.write({ // [!code highlight]
+    id: toolCallId, // [!code highlight]
+    type: 'data-search-web', // [!code highlight]
+    data: { url, status: 'done' }, // [!code highlight]
+  }); // [!code highlight]
+
+  writer.releaseLock(); // [!code highlight]
+
+  return content;
+}
+
+export const searchWeb = tool({
+  description: 'Read a web page and return the content',
+  inputSchema: z.object({ url: z.string() }),
+  execute: executeSearch,
+});
+```
+
+</Tab>
+
+<Tab value="Client">
+
+Handle the `data-search-web` chunks in your client to display progress. Data parts are stored in the message, so you can find the latest status directly:
+
+```typescript title="app/chat.tsx" lineNumbers
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+
+export function Chat() {
+  const { messages, input, handleInputChange, handleSubmit } = useChat({
+    api: '/api/chat',
+  });
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong>
+          {m.parts.map((part, i) => {
+            if (part.type === 'text') {
+              return <span key={i}>{part.text}</span>;
+            }
+            if (part.type === 'tool-invocation') {
+              // Find the latest data part for this tool call // [!code highlight]
+              const dataPart = m.parts.findLast( // [!code highlight]
+                (p) => p.type === 'data' && p.id === part.toolInvocation.toolCallId // [!code highlight]
+              ); // [!code highlight]
+              const status = dataPart?.type === 'data' ? dataPart.data : null; // [!code highlight]
+              return (
+                <div key={i}>
+                  {status?.status === 'fetching' // [!code highlight]
+                    ? `Fetching ${status.url}...` // [!code highlight]
+                    : `Called ${part.toolInvocation.toolName}`} // [!code highlight]
+                </div>
+              );
+            }
+            return null;
+          })}
+        </div>
+      ))}
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Type a message..."
+        />
+      </form>
+    </div>
+  );
+}
+```
+
+</Tab>
+
+</Tabs>

From 36229c7707d853cbc8f2e511b83f4a6418fa1933 Mon Sep 17 00:00:00 2001
From: Peter Wielander <mittgfu@gmail.com>
Date: Sat, 29 Nov 2025 20:35:30 -0800
Subject: [PATCH 38/38] Updates

---
 docs/content/guides/ai-agents/index.mdx       | 177 +-----------------
 .../guides/ai-agents/resumable-streams.mdx    |   4 +-
 .../streaming-updates-from-tools.mdx          | 173 ++++++++++-------
 3 files changed, 118 insertions(+), 236 deletions(-)

diff --git a/docs/content/guides/ai-agents/index.mdx b/docs/content/guides/ai-agents/index.mdx
index d239149ca..7d8ccdce2 100644
--- a/docs/content/guides/ai-agents/index.mdx
+++ b/docs/content/guides/ai-agents/index.mdx
@@ -381,22 +381,19 @@ npx workflow web
 
 This opens a local dashboard showing all workflow runs and their status, as well as a trace viewer to inspect the workflow in detail, including retry attempts, and the data being passed between steps.
 
-If you'd like to have terminal interface instead, you can use the CLI directly:
-
-```bash
-npx workflow inspect runs
-```
-
 ## Next Steps
 
 Now that you have a basic durable agent, it's a only a short step to add these additional features:
 
 <Cards>
+  <Card title="Streaming Updates from Tools" href="/guides/ai-agents/streaming-updates-from-tools">
+    Stream progress updates from tools to the UI while they're executing.
+  </Card>
   <Card title="Resumable Streams" href="/guides/ai-agents/resumable-streams">
     Enable clients to reconnect to interrupted streams without losing data.
   </Card>
-  <Card title="Sleep and Delays" href="/guides/ai-agents/sleep-and-delays">
-    Add native sleep and scheduling functionality to your Agent and workflow.
+  <Card title="Sleep, Suspense, and Scheduling" href="/guides/ai-agents/sleep-and-delays">
+    Add native sleep, suspense, and scheduling functionality to your Agent and workflow.
   </Card>
   <Card title="Human-in-the-Loop" href="/guides/ai-agents/human-in-the-loop">
     Implement approval steps to wait for human input or external events.
@@ -405,169 +402,7 @@ Now that you have a basic durable agent, it's a only a short step to add these a
 
 ## Complete Example
 
-Here is the complete code for the durable agent after all the steps above:
-
-<Tabs items={['API Route', 'Workflow', 'Tools', 'Client']}>
-
-<Tab value="API Route">
-
-```typescript title="app/api/chat/route.ts" lineNumbers
-import { createUIMessageStreamResponse, convertToModelMessages } from 'ai';
-import { start } from 'workflow/api';
-import { chatWorkflow } from './workflow';
-
-export async function POST(req: Request) {
-  const { messages, modelId } = await req.json();
-  const modelMessages = convertToModelMessages(messages);
-
-  const run = await start(chatWorkflow, [{ messages: modelMessages, modelId }]);
-
-  return createUIMessageStreamResponse({
-    stream: run.readable,
-  });
-}
-```
-
-</Tab>
-
-<Tab value="Workflow">
-
-```typescript title="app/api/chat/workflow.ts" lineNumbers
-import { DurableAgent } from '@workflow/ai/agent';
-import { getWritable } from 'workflow';
-import { stepCountIs } from 'ai';
-import { tools } from '@/ai/tools';
-import type { ModelMessage, UIMessageChunk } from 'ai';
-
-export async function chatWorkflow({
-  messages,
-  modelId,
-}: {
-  messages: ModelMessage[];
-  modelId: string;
-}) {
-  'use workflow';
-
-  const writable = getWritable<UIMessageChunk>();
-
-  const agent = new DurableAgent({
-    model: modelId,
-    system: 'You are a helpful assistant.',
-    tools,
-  });
-
-  await agent.stream({
-    messages,
-    writable,
-    stopWhen: stepCountIs(20),
-  });
-}
-```
-
-</Tab>
-
-<Tab value="Tools">
-
-```typescript title="ai/tools/index.ts" lineNumbers
-import { tool } from 'ai';
-import { getWritable } from 'workflow';
-import { z } from 'zod';
-import type { UIMessageChunk } from 'ai';
-
-async function executeSearch(
-  { url }: { url: string },
-  { toolCallId }: { toolCallId: string }
-) {
-  'use step';
-
-  const writable = getWritable<UIMessageChunk>();
-  const writer = writable.getWriter();
-
-  await writer.write({
-    id: toolCallId,
-    type: 'data-search-web',
-    data: { url, status: 'fetching' },
-  });
-
-  const response = await fetch(url);
-  const content = await response.text();
-
-  await writer.write({
-    id: toolCallId,
-    type: 'data-search-web',
-    data: { url, status: 'done' },
-  });
-
-  writer.releaseLock();
-
-  return content;
-}
-
-export const tools = {
-  searchWeb: tool({
-    description: 'Read a web page and return the content',
-    inputSchema: z.object({ url: z.string() }),
-    execute: executeSearch,
-  }),
-};
-```
-
-</Tab>
-
-<Tab value="Client">
-
-```typescript title="app/chat.tsx" lineNumbers
-'use client';
-
-import { useChat } from '@ai-sdk/react';
-
-export function Chat() {
-  const { messages, input, handleInputChange, handleSubmit } = useChat({
-    api: '/api/chat',
-  });
-
-  return (
-    <div>
-      {messages.map((m) => (
-        <div key={m.id}>
-          <strong>{m.role}:</strong>
-          {m.parts.map((part, i) => {
-            if (part.type === 'text') {
-              return <span key={i}>{part.text}</span>;
-            }
-            if (part.type === 'tool-invocation') {
-              // Find the latest data part for this tool call
-              const dataPart = m.parts.findLast(
-                (p) => p.type === 'data' && p.id === part.toolInvocation.toolCallId
-              );
-              const status = dataPart?.type === 'data' ? dataPart.data : null;
-              return (
-                <div key={i}>
-                  {status?.status === 'fetching'
-                    ? `Fetching ${status.url}...`
-                    : `Called ${part.toolInvocation.toolName}`}
-                </div>
-              );
-            }
-            return null;
-          })}
-        </div>
-      ))}
-      <form onSubmit={handleSubmit}>
-        <input
-          value={input}
-          onChange={handleInputChange}
-          placeholder="Type a message..."
-        />
-      </form>
-    </div>
-  );
-}
-```
-
-</Tab>
-
-</Tabs>
+A complete example that includes all of the above, plus all of the "next steps" features, is available on the main branch of the [Flight Booking Agent](https://github.com/vercel/workflow-examples/tree/main/flight-booking-app) example.
 
 ## Related Documentation
 
diff --git a/docs/content/guides/ai-agents/resumable-streams.mdx b/docs/content/guides/ai-agents/resumable-streams.mdx
index 7230e828c..fffcfdb1c 100644
--- a/docs/content/guides/ai-agents/resumable-streams.mdx
+++ b/docs/content/guides/ai-agents/resumable-streams.mdx
@@ -8,7 +8,9 @@ Where a standard chat implementation would require the user to resend their mess
 
 ## Implementing stream resumption
 
-Getting stream resumption requires both adding `WorkflowChatTransport` (to allow the client to reconnect to the stream) and some client-side state management, in order to know when and where to reconnect to the stream.
+We can enable stream resumption by adding the `WorkflowChatTransport` middleware to our `useChat` hook (to allow the client to reconnect to the stream), and then adding some client-side state management, in order to know when and where to reconnect to the stream.
+
+The examples below assume you have a basic Agent that compatible with one we built in the [Building Durable AI Agents](/guides/ai-agents) guide.
 
 <Steps>
 
diff --git a/docs/content/guides/ai-agents/streaming-updates-from-tools.mdx b/docs/content/guides/ai-agents/streaming-updates-from-tools.mdx
index d34d94fa7..59770aa98 100644
--- a/docs/content/guides/ai-agents/streaming-updates-from-tools.mdx
+++ b/docs/content/guides/ai-agents/streaming-updates-from-tools.mdx
@@ -2,11 +2,36 @@
 title: Streaming Updates from Tools
 ---
 
-Tools can emit progress updates to the same stream the agent uses. This allows the UI to display tool status.
+After [building a durable AI agent](/guides/ai-agents), we already get UI message chunks for displaying tool invocations and return values. However, for long-running steps, we may want to show progress updates, or stream step output to the user while it's being generated.
 
-<Tabs items={['Tool', 'Client']}>
+Workflow DevKit enables this by letting step functions write custom chunks to the same stream the agent uses. These chunks appear as data parts in your messages, which you can render however you like.
 
-<Tab value="Tool">
+<Steps>
+
+<Step>
+### Define Your Data Part Type
+
+First, define a TypeScript type for your custom data part. This ensures type safety across your tool and client code:
+
+```typescript title="types/chat.ts" lineNumbers
+export interface SearchWebDataPart {
+  type: 'data-search-web'; // [!code highlight]
+  id: string;
+  data: {
+    url: string;
+    status: 'fetching' | 'done';
+  };
+}
+```
+
+The `type` field must be a string starting with `data-` followed by your custom identifier. The `id` field should match the `toolCallId` so the client can associate the data with the correct tool invocation.
+
+</Step>
+
+<Step>
+### Emit Updates from Your Tool
+
+Use [`getWritable()`](/docs/api-reference/workflow/get-writable) inside a step function to get a handle to the stream. Write your custom chunks as the tool progresses:
 
 ```typescript title="ai/tools/search-web.ts" lineNumbers
 import { tool } from 'ai';
@@ -21,25 +46,25 @@ async function executeSearch(
   'use step';
 
   const writable = getWritable<UIMessageChunk>(); // [!code highlight]
-  const writer = writable.getWriter(); // [!code highlight]
+  const writer = writable.getWriter();
 
-  // Emit a progress update // [!code highlight]
-  await writer.write({ // [!code highlight]
-    id: toolCallId, // [!code highlight]
+  // Emit a progress update
+  await writer.write({
     type: 'data-search-web', // [!code highlight]
-    data: { url, status: 'fetching' }, // [!code highlight]
-  }); // [!code highlight]
+    id: toolCallId, // [!code highlight]
+    data: { url, status: 'fetching' },
+  });
 
   const response = await fetch(url);
   const content = await response.text();
 
-  await writer.write({ // [!code highlight]
-    id: toolCallId, // [!code highlight]
-    type: 'data-search-web', // [!code highlight]
-    data: { url, status: 'done' }, // [!code highlight]
-  }); // [!code highlight]
+  await writer.write({
+    type: 'data-search-web',
+    id: toolCallId,
+    data: { url, status: 'done' },
+  });
 
-  writer.releaseLock(); // [!code highlight]
+  writer.releaseLock();
 
   return content;
 }
@@ -51,61 +76,81 @@ export const searchWeb = tool({
 });
 ```
 
-</Tab>
+Key points:
+
+- Call `getWritable<UIMessageChunk>()` to get the stream
+- Use `getWriter()` to acquire a writer
+- Write objects with `type`, `id`, and `data` fields
+- Always call `releaseLock()` when done writing
+
+</Step>
 
-<Tab value="Client">
+<Step>
+### Handle Data Parts in the Client
 
-Handle the `data-search-web` chunks in your client to display progress. Data parts are stored in the message, so you can find the latest status directly:
+Update your chat component to detect and render the custom data parts. Data parts are stored in the message's `parts` array alongside text and tool invocation parts:
 
 ```typescript title="app/chat.tsx" lineNumbers
-'use client';
+{message.parts.map((part, partIndex) => {
+  // Render text parts
+  if (part.type === 'text') {
+    return (
+      <Response key={`${message.id}-text-${partIndex}`}>
+        {part.text}
+      </Response>
+    );
+  }
+
+  // Render tool parts with progress status // [!code highlight]
+  if (part.type === 'tool-searchWeb') { // [!code highlight]
+    if (!('toolCallId' in part) || !('state' in part)) {
+      return null;
+    }
+
+    // Find the latest data part for this tool call // [!code highlight]
+    const dataPart = message.parts.findLast( // [!code highlight]
+      (p) => p.type === 'data-search-web' && p.id === part.toolCallId // [!code highlight]
+    ); // [!code highlight]
+
+    // Extract status from the data part // [!code highlight]
+    const status = // [!code highlight]
+      dataPart && 'data' in dataPart // [!code highlight]
+        ? (dataPart.data as { status: string; url: string }) // [!code highlight]
+        : null; // [!code highlight]
+
+    return (
+      <Tool key={part.toolCallId}>
+        <ToolHeader type={part.type} state={part.state} />
+        <ToolContent>
+          {status?.status === 'fetching' && ( // [!code highlight]
+            <div className="text-muted-foreground text-sm"> // [!code highlight]
+              Fetching {status.url}... // [!code highlight]
+            </div> // [!code highlight]
+          )} // [!code highlight]
+          {part.state === 'output-available' && (
+            <ToolOutput output={renderToolOutput(part)} />
+          )}
+        </ToolContent>
+      </Tool>
+    );
+  }
+
+  return null;
+})}
+```
 
-import { useChat } from '@ai-sdk/react';
+The pattern is:
 
-export function Chat() {
-  const { messages, input, handleInputChange, handleSubmit } = useChat({
-    api: '/api/chat',
-  });
+1. When rendering a tool invocation part, search for matching data parts using `findLast()`
+2. Match by comparing the data part's `id` to the tool's `toolCallId`
+3. Use the data part's payload to display progress or intermediate results
 
-  return (
-    <div>
-      {messages.map((m) => (
-        <div key={m.id}>
-          <strong>{m.role}:</strong>
-          {m.parts.map((part, i) => {
-            if (part.type === 'text') {
-              return <span key={i}>{part.text}</span>;
-            }
-            if (part.type === 'tool-invocation') {
-              // Find the latest data part for this tool call // [!code highlight]
-              const dataPart = m.parts.findLast( // [!code highlight]
-                (p) => p.type === 'data' && p.id === part.toolInvocation.toolCallId // [!code highlight]
-              ); // [!code highlight]
-              const status = dataPart?.type === 'data' ? dataPart.data : null; // [!code highlight]
-              return (
-                <div key={i}>
-                  {status?.status === 'fetching' // [!code highlight]
-                    ? `Fetching ${status.url}...` // [!code highlight]
-                    : `Called ${part.toolInvocation.toolName}`} // [!code highlight]
-                </div>
-              );
-            }
-            return null;
-          })}
-        </div>
-      ))}
-      <form onSubmit={handleSubmit}>
-        <input
-          value={input}
-          onChange={handleInputChange}
-          placeholder="Type a message..."
-        />
-      </form>
-    </div>
-  );
-}
-```
+</Step>
+
+</Steps>
 
-</Tab>
+## Related Documentation
 
-</Tabs>
+- [Building Durable AI Agents](/guides/ai-agents) - Complete guide to durable agents
+- [`getWritable()` API Reference](/docs/api-reference/workflow/get-writable) - Stream API details
+- [Streaming](/docs/foundations/streaming) - Understanding workflow streams