workflow 5.0.0-beta.2 → 5.0.0-beta.20

package/docs/cookbook/agent-patterns/durable-agent.mdx

@@ -1,191 +1,18 @@
 ---
-title: Durable Agent
-description: Replace a stateless AI agent with a durable one that survives crashes, retries tool calls, and streams output.
+title: DurableAgent is now WorkflowAgent
+description: Use AI SDK v7's WorkflowAgent for durable, resumable AI agents.
 type: guide
-summary: Convert an AI SDK Agent into a DurableAgent backed by a workflow, with tools as retryable steps.
+summary: Build durable, resumable AI agents with AI SDK v7's WorkflowAgent.
 ---
 
-Use this pattern to make any AI SDK agent durable. The agent becomes a workflow, tools become steps, and the framework handles retries, streaming, and state persistence automatically.
+## WorkflowAgent from AI SDK v7
 
-## Pattern
+Use AI SDK v7's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) for new durable agent work. It replaces `DurableAgent` in v5 and keeps the current agent pattern in the AI SDK package.
 
-Replace `Agent` with `DurableAgent`, wrap the function in `"use workflow"`, mark each tool with `"use step"`, and stream output through `getWritable()`.
+- Import `WorkflowAgent` from `@ai-sdk/workflow` and run it inside a `"use workflow"` function.
+- Stream `ModelCallStreamPart` chunks with `getWritable()`, then convert the run stream to UI message chunks with `createModelCallToUIChunkTransform()` in your route.
+- Mark tool `execute` functions with `"use step"` when they should run as durable workflow steps with retry and observability behavior.
 
-### Simplified
-
-```typescript lineNumbers
-import { DurableAgent } from "@workflow/ai/agent";
-import { getWritable } from "workflow";
-import { z } from "zod";
-import type { ModelMessage, UIMessageChunk } from "ai";
-
-declare function searchFlights(args: { from: string; to: string; date: string }): Promise<{ flights: { id: string; price: number }[] }>; // @setup
-declare function bookFlight(args: { flightId: string; passenger: string }): Promise<{ confirmationId: string }>; // @setup
-
-export async function flightAgent(messages: ModelMessage[]) {
-  "use workflow";
-
-  const agent = new DurableAgent({ // [!code highlight]
-    model: "anthropic/claude-haiku-4.5",
-    instructions: "You are a helpful flight booking assistant.",
-    tools: {
-      searchFlights: {
-        description: "Search for available flights",
-        inputSchema: z.object({
-          from: z.string(),
-          to: z.string(),
-          date: z.string(),
-        }),
-        execute: searchFlights,
-      },
-      bookFlight: {
-        description: "Book a specific flight",
-        inputSchema: z.object({
-          flightId: z.string(),
-          passenger: z.string(),
-        }),
-        execute: bookFlight,
-      },
-    },
-  });
-
-  await agent.stream({ // [!code highlight]
-    messages,
-    writable: getWritable<UIMessageChunk>(),
-  });
-}
-```
-
-### Full Implementation
-
-```typescript lineNumbers
-import { DurableAgent } from "@workflow/ai/agent";
-import { getWritable } from "workflow";
-import { z } from "zod";
-import type { ModelMessage, UIMessageChunk } from "ai";
-
-// Step: Search flights with full Node.js access and automatic retries
-async function searchFlights({
-  from,
-  to,
-  date,
-}: {
-  from: string;
-  to: string;
-  date: string;
-}) {
-  "use step";
-
-  const response = await fetch(
-    `https://api.example.com/flights?from=${from}&to=${to}&date=${date}`
-  );
-  if (!response.ok) throw new Error(`Search failed: ${response.status}`);
-  return response.json();
-}
-
-// Step: Book a flight — retries on transient failures
-async function bookFlight({
-  flightId,
-  passenger,
-}: {
-  flightId: string;
-  passenger: string;
-}) {
-  "use step";
-
-  const response = await fetch("https://api.example.com/bookings", {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ flightId, passenger }),
-  });
-  if (!response.ok) throw new Error(`Booking failed: ${response.status}`);
-  return response.json();
-}
-
-// Step: Check flight status
-async function checkStatus({ flightId }: { flightId: string }) {
-  "use step";
-
-  const response = await fetch(
-    `https://api.example.com/flights/${flightId}/status`
-  );
-  return response.json();
-}
-
-export async function flightAgent(messages: ModelMessage[]) {
-  "use workflow";
-
-  const writable = getWritable<UIMessageChunk>(); // [!code highlight]
-
-  const agent = new DurableAgent({ // [!code highlight]
-    model: "anthropic/claude-haiku-4.5",
-    instructions: "You are a helpful flight booking assistant.",
-    tools: {
-      searchFlights: {
-        description: "Search for available flights between two airports",
-        inputSchema: z.object({
-          from: z.string().describe("Departure airport code"),
-          to: z.string().describe("Arrival airport code"),
-          date: z.string().describe("Travel date (YYYY-MM-DD)"),
-        }),
-        execute: searchFlights,
-      },
-      bookFlight: {
-        description: "Book a specific flight for a passenger",
-        inputSchema: z.object({
-          flightId: z.string().describe("Flight ID from search results"),
-          passenger: z.string().describe("Passenger full name"),
-        }),
-        execute: bookFlight,
-      },
-      checkStatus: {
-        description: "Check the current status of a flight",
-        inputSchema: z.object({
-          flightId: z.string().describe("Flight ID to check"),
-        }),
-        execute: checkStatus,
-      },
-    },
-  });
-
-  const result = await agent.stream({ // [!code highlight]
-    messages,
-    writable,
-    maxSteps: 10,
-  });
-
-  return { messages: result.messages };
-}
-```
-
-### API Route
-
-```typescript lineNumbers
-import { createUIMessageStreamResponse } from "ai";
-import { start } from "workflow/api";
-import { flightAgent } from "@/workflows/flight-agent";
-import type { UIMessage } from "ai";
-import { convertToModelMessages } from "ai";
-
-export async function POST(req: Request) {
-  const { messages }: { messages: UIMessage[] } = await req.json();
-  const modelMessages = await convertToModelMessages(messages);
-
-  const run = await start(flightAgent, [modelMessages]); // [!code highlight]
-
-  return createUIMessageStreamResponse({
-    stream: run.readable,
-    headers: {
-      "x-workflow-run-id": run.runId,
-    },
-  });
-}
-```
-
-## Key APIs
-
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
-- [`"use step"`](/docs/api-reference/workflow/use-step) — declares step functions with retries and full Node.js access
-- [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — durable wrapper around AI SDK's Agent
-- [`getWritable()`](/docs/api-reference/workflow/get-writable) — streams agent output to the client
-- [`start()`](/docs/api-reference/workflow-api/start) — starts a workflow run from an API route
+<Callout type="warn">
+`DurableAgent` is deprecated in v5 and remains documented for existing code only. Existing `DurableAgent` users can refer to the [`DurableAgent` API reference](/docs/api-reference/workflow-ai/durable-agent) while migrating.
+</Callout>

package/docs/cookbook/agent-patterns/human-in-the-loop.mdx

@@ -7,165 +7,141 @@ summary: Use defineHook with the tool call ID to suspend an agent for human appr
 
 Use this pattern when an AI agent needs human confirmation before performing a consequential action like booking, purchasing, or publishing. The workflow suspends without consuming resources until the human responds.
 
-## Pattern
-
-Create a typed hook using `defineHook()`. When the agent calls the approval tool, the tool creates a hook instance using the tool call ID as the token, then awaits it. The UI renders approval controls, and an API route resumes the hook with the decision.
-
-### Simplified
+## When to use this
 
-```typescript lineNumbers
-import { DurableAgent } from "@workflow/ai/agent";
-import { defineHook, sleep, getWritable } from "workflow";
-import { z } from "zod";
-import type { ModelMessage, UIMessageChunk } from "ai";
-
-export const bookingApprovalHook = defineHook({
-  schema: z.object({
-    approved: z.boolean(),
-    comment: z.string().optional(),
-  }),
-});
-
-declare function confirmBooking(args: { flightId: string; passenger: string }): Promise<{ confirmationId: string }>; // @setup
-
-// This tool runs at the workflow level (no "use step") because hooks are workflow primitives
-async function requestBookingApproval(
-  { flightId, passenger, price }: { flightId: string; passenger: string; price: number },
-  { toolCallId }: { toolCallId: string }
-) {
-  const hook = bookingApprovalHook.create({ token: toolCallId }); // [!code highlight]
-
-  const result = await Promise.race([ // [!code highlight]
-    hook.then((payload) => ({ type: "decision" as const, ...payload })),
-    sleep("24h").then(() => ({ type: "timeout" as const, approved: false })),
-  ]);
+- Booking confirmations where users must approve before charges are made
+- Content publishing gates where an editor must sign off
+- Any agent action where the cost of getting it wrong justifies a human check
+- Actions with side effects that can't be easily undone
 
-  if (result.type === "timeout") return "Booking request expired after 24 hours.";
-  if (!result.approved) return `Booking rejected: ${result.comment || "No reason given"}`;
-
-  const booking = await confirmBooking({ flightId, passenger });
-  return `Booked! Confirmation: ${booking.confirmationId}`;
-}
-
-export async function bookingAgent(messages: ModelMessage[]) {
-  "use workflow";
-
-  const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
-    instructions: "You help book flights. Always request approval before booking.",
-    tools: {
-      requestBookingApproval: {
-        description: "Request human approval before booking a flight",
-        inputSchema: z.object({
-          flightId: z.string(),
-          passenger: z.string(),
-          price: z.number(),
-        }),
-        execute: requestBookingApproval,
-      },
-    },
-  });
+## Pattern
 
-  await agent.stream({ // [!code highlight]
-    messages,
-    writable: getWritable<UIMessageChunk>(),
-  });
-}
-```
+Create a typed hook using `defineHook()`. When the agent calls the approval tool, the tool emits a custom data part to the stream so the client can render approval controls, then creates a hook and suspends. An API route resumes the hook with the decision.
 
-### Full Implementation
+### Workflow
 
-```typescript lineNumbers
+```typescript
 import { DurableAgent } from "@workflow/ai/agent";
 import { defineHook, sleep, getWritable } from "workflow";
 import { z } from "zod";
 import type { ModelMessage, UIMessageChunk } from "ai";
 
-// Define the approval hook with schema validation
-export const bookingApprovalHook = defineHook({
+// Exported so the approval API route can call .resume()
+export const bookingApprovalHook = defineHook({ // [!code highlight]
   schema: z.object({
     approved: z.boolean(),
     comment: z.string().optional(),
   }),
 });
 
-// Step: Search for flights (full Node.js access, automatic retries)
-async function searchFlights({
-  from,
-  to,
-  date,
-}: {
+async function searchFlights({ from, to, date }: {
   from: string;
   to: string;
   date: string;
 }) {
   "use step";
+  const res = await fetch(
+    `https://api.example.com/flights?from=${from}&to=${to}&date=${date}`
+  );
+  return res.json();
+}
 
-  // Your real flight search API call here
-  await new Promise((resolve) => setTimeout(resolve, 500));
-  return {
-    flights: [
-      { id: "FL-100", airline: "Example Air", price: 299, from, to, date },
-      { id: "FL-200", airline: "Demo Airlines", price: 349, from, to, date },
-    ],
-  };
+async function confirmBooking({ flightId, passenger }: {
+  flightId: string;
+  passenger: string;
+}) {
+  "use step";
+  const res = await fetch("https://api.example.com/bookings", {
+    method: "POST",
+    body: JSON.stringify({ flightId, passenger }),
+  });
+  return res.json();
 }
 
-// Step: Confirm the booking after approval
-async function confirmBooking({
-  flightId,
-  passenger,
-}: {
+// Stream a custom data part so the client can render the approval UI.
+// This MUST run before the hook suspends the workflow — otherwise
+// the tool-invocation won't appear in the stream until the tool returns,
+// and the client would have no way to show approval buttons.
+async function emitApprovalRequest(details: {
   flightId: string;
   passenger: string;
+  price: number;
+  toolCallId: string;
 }) {
   "use step";
+  const writer = getWritable<UIMessageChunk>().getWriter();
+  try {
+    await writer.write({
+      type: "data-approval-needed", // [!code highlight]
+      id: details.toolCallId,
+      data: details,
+    } as UIMessageChunk);
+  } finally {
+    writer.releaseLock();
+  }
+}
 
-  await new Promise((resolve) => setTimeout(resolve, 500));
-  return { confirmationId: `CONF-${flightId}-${Date.now().toString(36)}` };
+// Stream the resolution so the client can update the approval card.
+async function emitApprovalResolved(details: {
+  toolCallId: string;
+  result: string;
+}) {
+  "use step";
+  const writer = getWritable<UIMessageChunk>().getWriter();
+  try {
+    await writer.write({
+      type: "data-approval-resolved", // [!code highlight]
+      id: details.toolCallId,
+      data: details,
+    } as UIMessageChunk);
+  } finally {
+    writer.releaseLock();
+  }
 }
 
-// Workflow-level tool: hooks must be created in workflow context, not inside steps
+// No "use step" — hooks are workflow-level primitives
 async function requestBookingApproval(
-  {
-    flightId,
-    passenger,
-    price,
-  }: { flightId: string; passenger: string; price: number },
+  { flightId, passenger, price }: {
+    flightId: string;
+    passenger: string;
+    price: number;
+  },
   { toolCallId }: { toolCallId: string }
 ) {
-  // No "use step" — hooks are workflow-level primitives
+  // Emit to the stream before suspending so the UI can show buttons
+  await emitApprovalRequest({ flightId, passenger, price, toolCallId }); // [!code highlight]
 
-  const hook = bookingApprovalHook.create({ token: toolCallId }); // [!code highlight]
+  const hook = bookingApprovalHook.create({ token: toolCallId });
 
-  // Race: human approval vs. 24-hour timeout
-  const result = await Promise.race([ // [!code highlight]
+  // Race: human decision vs. timeout
+  const result = await Promise.race([
     hook.then((payload) => ({ type: "decision" as const, ...payload })),
-    sleep("24h").then(() => ({ type: "timeout" as const, approved: false })),
+    sleep("24h").then(() => ({ type: "timeout" as const, approved: false as const })),
   ]);
 
   if (result.type === "timeout") {
-    return "Booking request expired after 24 hours.";
+    const msg = "Booking request expired.";
+    await emitApprovalResolved({ toolCallId, result: msg }); // [!code highlight]
+    return msg;
   }
-
   if (!result.approved) {
-    return `Booking rejected: ${result.comment || "No reason given"}`;
+    const msg = `Rejected: ${result.comment || "No reason given"}`;
+    await emitApprovalResolved({ toolCallId, result: msg }); // [!code highlight]
+    return msg;
   }
 
-  // Approved — proceed with booking
   const booking = await confirmBooking({ flightId, passenger });
-  return `Flight ${flightId} booked for ${passenger}. Confirmation: ${booking.confirmationId}`;
+  const msg = `Booked! Confirmation: ${booking.confirmationId}`;
+  await emitApprovalResolved({ toolCallId, result: msg }); // [!code highlight]
+  return msg;
 }
 
 export async function bookingAgent(messages: ModelMessage[]) {
   "use workflow";
 
-  const writable = getWritable<UIMessageChunk>();
-
   const agent = new DurableAgent({
     model: "anthropic/claude-haiku-4.5",
-    instructions:
-      "You are a flight booking assistant. Search for flights, then request approval before booking.",
+    instructions: "You help book flights. Always request approval before booking.",
     tools: {
       searchFlights: {
         description: "Search for available flights",
@@ -188,91 +164,92 @@ export async function bookingAgent(messages: ModelMessage[]) {
     },
   });
 
-  await agent.stream({ messages, writable }); // [!code highlight]
+  await agent.stream({
+    messages,
+    writable: getWritable<UIMessageChunk>(),
+  });
 }
 ```
 
-### API Route for Approvals
+### Approval API route
+
+The approval route imports the hook definition and calls `.resume()` with the tool call ID as the token:
 
-```typescript lineNumbers
-import { bookingApprovalHook } from "@/workflows/booking-agent";
+```typescript
+import { bookingApprovalHook } from "@/app/workflows/booking-agent";
 
-export async function POST(request: Request) {
-  const { toolCallId, approved, comment } = await request.json();
+export async function POST(req: Request) {
+  const { toolCallId, approved, comment } = await req.json();
 
-  // Schema validation happens automatically via defineHook
   await bookingApprovalHook.resume(toolCallId, { approved, comment }); // [!code highlight]
 
   return Response.json({ success: true });
 }
 ```
 
-### Approval Component
-
-```tsx lineNumbers
-"use client";
+### Client rendering
+
+Listen for `data-approval-needed` and `data-approval-resolved` custom data parts in the message stream. The approval tool invocation itself won't appear until the tool returns, so the custom data parts are the mechanism for showing and updating the approval UI.
+
+```tsx
+// Scan all messages for the resolution
+const approvalResult = messages
+  .flatMap((m) => m.parts)
+  .find((p) => p.type === "data-approval-resolved")
+  ?.data?.result;
+
+// In your message parts loop:
+{message.parts.map((part, i) => {
+  if (part.type === "data-approval-needed") { // [!code highlight]
+    const { flightId, passenger, price, toolCallId } = part.data;
+    if (approvalResult) {
+      return <div key={i}>Result: {approvalResult}</div>;
+    }
+    return (
+      <div key={i} className="rounded-lg border p-4 space-y-3">
+        <div className="text-sm">
+          <div>Flight: {flightId}</div>
+          <div>Passenger: {passenger}</div>
+          <div>Price: ${price}</div>
+        </div>
+        <div className="flex gap-2">
+          <button onClick={() => approve(toolCallId)}>Approve</button> {/* [!code highlight] */}
+          <button onClick={() => reject(toolCallId)}>Reject</button> {/* [!code highlight] */}
+        </div>
+      </div>
+    );
+  }
+  // Hide the requestBookingApproval tool-invocation part
+  if (part.type === "tool-invocation" &&
+      part.toolInvocation.toolName === "requestBookingApproval") {
+    return null;
+  }
+  // ... other part types
+})}
+```
 
-import { useState } from "react";
+## How it works
 
-export function BookingApproval({
-  toolCallId,
-  input,
-  output,
-}: {
-  toolCallId: string;
-  input?: { flightId: string; passenger: string; price: number };
-  output?: string;
-}) {
-  const [comment, setComment] = useState("");
-  const [isSubmitting, setIsSubmitting] = useState(false);
+1. **`defineHook()` with schema** — creates a typed hook with Zod validation. The approval payload is validated before the workflow receives it.
+2. **`toolCallId` as token** — the approval tool uses the tool call ID as the hook token, naturally linking the hook to the specific tool invocation.
+3. **`emitApprovalRequest` step** — writes a `data-approval-needed` custom data part to the stream *before* the hook suspends. Without this, the client would never see the approval controls because tool invocations don't stream until the tool returns.
+4. **No `"use step"` on the approval tool** — the tool runs at the workflow level because `defineHook().create()` is a workflow primitive. It calls step functions (`emitApprovalRequest`, `emitApprovalResolved`, `confirmBooking`) for I/O.
+5. **`Promise.race` with sleep** — the approval races against a durable timeout. If nobody responds, the workflow continues with an expiration message.
+6. **`emitApprovalResolved` step** — writes the outcome to the stream so the client can update the card immediately, without waiting for the tool-invocation result.
 
-  if (output) {
-    return <p className="text-sm text-muted-foreground">{output}</p>;
-  }
+## Adapting to your use case
 
-  const handleSubmit = async (approved: boolean) => {
-    setIsSubmitting(true);
-    await fetch("/api/hooks/approval", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ toolCallId, approved, comment }),
-    });
-    setIsSubmitting(false);
-  };
-
-  return (
-    <div className="border rounded-lg p-4 space-y-3">
-      {input && (
-        <div className="text-sm space-y-1">
-          <div>Flight: {input.flightId}</div>
-          <div>Passenger: {input.passenger}</div>
-          <div>Price: ${input.price}</div>
-        </div>
-      )}
-      <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 type="button" onClick={() => handleSubmit(true)} disabled={isSubmitting}>
-          Approve
-        </button>
-        <button type="button" onClick={() => handleSubmit(false)} disabled={isSubmitting}>
-          Reject
-        </button>
-      </div>
-    </div>
-  );
-}
-```
+- **Change the approval schema** — add fields like `reason`, `amount`, `reviewerEmail` to match your domain.
+- **Multiple approval gates** — the pattern works for any number of tools. Each tool creates its own hook with its own `toolCallId`.
+- **Escalation** — if the first approver doesn't respond, use `sleep()` + another hook to escalate to a backup reviewer.
+- **Adjust timeout** — use `"24h"` for production, shorter durations for demos.
+- **Workflow-level vs step tools** — tools that use `sleep()`, `defineHook()`, or other workflow primitives must NOT use `"use step"`. Tools with only I/O (API calls, DB queries) should use `"use step"` for retries.
 
 ## Key APIs
 
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
-- [`"use step"`](/docs/api-reference/workflow/use-step) — declares step functions with retries
+- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions) — declares the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions) — declares step functions with retries
 - [`defineHook()`](/docs/api-reference/workflow/define-hook) — type-safe hook with schema validation
 - [`sleep()`](/docs/api-reference/workflow/sleep) — durable timeout for approval expiry
+- [`getWritable()`](/docs/api-reference/workflow/get-writable) — stream custom data parts from steps
 - [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — durable agent with tool definitions

package/docs/cookbook/agent-patterns/meta.json

@@ -1,10 +1,4 @@
 {
   "title": "Agent Patterns",
-  "pages": [
-    "durable-agent",
-    "tool-streaming",
-    "human-in-the-loop",
-    "tool-orchestration",
-    "stop-workflow"
-  ]
+  "pages": ["durable-agent", "human-in-the-loop", "agent-cancellation"]
 }