workflow 5.0.0-beta.4 → 5.0.0-beta.40

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

@@ -1,150 +1,22 @@
 ---
-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.
+<CopyPrompt
+  text="Convert this stateless AI SDK agent to a durable agent with AI SDK v7's `WorkflowAgent`. Install/use `@ai-sdk/workflow` and `workflow`. Replace the manual `streamText` loop with `new WorkflowAgent(...)` from `@ai-sdk/workflow`, run inside an exported function with `&quot;use workflow&quot;`. Mark side-effectful tool `execute` functions with `&quot;use step&quot;` so they run as durable workflow steps with retries and observability. Stream `ModelCallStreamPart` chunks with `getWritable()` from `workflow`, convert the run stream to UI message chunks with `createModelCallToUIChunkTransform()` in the API route, and expose a route that starts or reconnects to the run. If migrating from the deprecated `DurableAgent`, follow the migration guide at https://ai-sdk.dev/v7/docs/agents/workflow-agent#migrating-from-durableagent. Verify tool retries, stream output, and resume/reconnect behavior."
+/>
 
-## When to use this
+## WorkflowAgent from AI SDK v7
 
-- Any AI agent with tool calls that should survive crashes and restarts
-- Agents where tool calls hit external APIs that need automatic retries
-- Long-running agent sessions where losing progress is unacceptable
-- Agents that need per-step observability in the workflow event log
+Use AI SDK v7's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) for new durable agent work. It replaces `DurableAgent` and keeps the current agent pattern in the AI SDK package.
 
-## Pattern
+- 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.
 
-Replace `Agent` with `DurableAgent`, wrap the function in `"use workflow"`, mark each tool with `"use step"`, and stream output through `getWritable()`.
-
-### Workflow
-
-```typescript
-import { DurableAgent } from "@workflow/ai/agent";
-import { getWritable } from "workflow";
-import { z } from "zod";
-import type { ModelMessage, UIMessageChunk } from "ai";
-
-async function searchFlights({ from, to, date }: {
-  from: string;
-  to: string;
-  date: string;
-}) {
-  "use step"; // [!code highlight]
-  const res = await fetch(
-    `https://api.example.com/flights?from=${from}&to=${to}&date=${date}`
-  );
-  if (!res.ok) throw new Error(`Search failed: ${res.status}`);
-  return res.json();
-}
-
-async function bookFlight({ flightId, passenger }: {
-  flightId: string;
-  passenger: string;
-}) {
-  "use step"; // [!code highlight]
-  const res = await fetch("https://api.example.com/bookings", {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ flightId, passenger }),
-  });
-  if (!res.ok) throw new Error(`Booking failed: ${res.status}`);
-  return res.json();
-}
-
-async function checkWeather({ city }: { city: string }) {
-  "use step"; // [!code highlight]
-  const res = await fetch(`https://api.weather.com/forecast?city=${city}`);
-  return res.json();
-}
-
-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 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,
-      },
-      checkWeather: {
-        description: "Check the weather forecast for a city",
-        inputSchema: z.object({
-          city: z.string().describe("City name"),
-        }),
-        execute: checkWeather,
-      },
-    },
-  });
-
-  const result = await agent.stream({ // [!code highlight]
-    messages,
-    writable: getWritable<UIMessageChunk>(), // [!code highlight]
-    maxSteps: 10,
-  });
-
-  return { messages: result.messages };
-}
-```
-
-### API route
-
-```typescript
-import type { UIMessage } from "ai";
-import { convertToModelMessages, createUIMessageStreamResponse } from "ai";
-import { start } from "workflow/api";
-import { flightAgent } from "@/app/workflows/flight-agent";
-
-export async function POST(req: Request) {
-  const { messages }: { messages: UIMessage[] } = await req.json();
-  const modelMessages = await convertToModelMessages(messages); // [!code highlight]
-
-  const run = await start(flightAgent, [modelMessages]); // [!code highlight]
-
-  return createUIMessageStreamResponse({ // [!code highlight]
-    stream: run.readable,
-    headers: {
-      "x-workflow-run-id": run.runId,
-    },
-  });
-}
-```
-
-## How it works
-
-1. **DurableAgent wraps Agent** — same API as AI SDK's `Agent`, but backed by a workflow. If the process crashes, the agent resumes from the last completed step on replay.
-2. **Tools as steps** — each tool's `execute` function uses `"use step"`, giving it automatic retries, full Node.js access, and an entry in the workflow event log.
-3. **Streaming** — `getWritable<UIMessageChunk>()` streams the agent's output (text chunks, tool calls, tool results) to the client in real time via `createUIMessageStreamResponse`.
-4. **maxSteps** — limits the total number of LLM calls the agent can make, preventing runaway tool loops.
-
-## Adapting to your use case
-
-- **Change the model** — replace `"anthropic/claude-haiku-4.5"` with any AI Gateway model string (e.g. `"openai/gpt-4o"`, `"anthropic/claude-sonnet-4-5"`).
-- **Add tools** — define a new `"use step"` function with a Zod schema. Each tool automatically gets retries and persistence.
-- **Workflow-level tools** — if a tool needs workflow primitives like `sleep()` or `createHook()`, omit `"use step"` so it runs in the workflow context instead.
-- **Multi-turn** — pass `result.messages` plus new user messages to subsequent `agent.stream()` calls for multi-turn conversations.
-- **Client integration** — use `useChat()` from `@ai-sdk/react` with `WorkflowChatTransport` from `@workflow/ai` for a full chat UI with reconnection support.
-
-## 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 and remains documented for existing code only. See the [migration guide](https://ai-sdk.dev/v7/docs/agents/workflow-agent#migrating-from-durableagent), or the [`DurableAgent` API reference](/docs/api-reference/workflow-ai/durable-agent) while migrating.
+</Callout>

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

@@ -5,6 +5,14 @@ type: guide
 summary: Use defineHook with the tool call ID to suspend an agent for human approval, with an optional timeout.
 ---
 
+<CopyPrompt
+  text="Add a human approval gate to this AI workflow. Define a typed hook with `defineHook()` from `workflow` for approval payloads. At the approval point, create the hook once with a stable token, await it inside the `&quot;use workflow&quot;` function, and branch on approved/rejected input. Add a server route that receives the human decision and calls `resumeHook(token, payload)` from `workflow/api`. If the approval should expire, race the hook against `sleep()` from `workflow`. Update the UI to show the pending approval and call the resume route. Verify approve, reject, timeout, and duplicate resume behavior."
+/>
+
+<Callout type="warn">
+This recipe uses the deprecated `DurableAgent` API. For new agents, use AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) and follow the [migration guide](https://ai-sdk.dev/v7/docs/agents/workflow-agent#migrating-from-durableagent). The human-in-the-loop pattern here (hooks, `Promise.race`, approval gating) applies to either API.
+</Callout>
+
 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.
 
 ## When to use this
@@ -247,9 +255,9 @@ const approvalResult = messages
 
 ## 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
+- [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) — AI SDK's durable agent (replaces `DurableAgent`)

package/docs/cookbook/common-patterns/batching.mdx

@@ -5,6 +5,10 @@ type: guide
 summary: Split items into fixed-size batches, process each batch concurrently with Promise.allSettled, and pace batches with sleep to avoid overloading downstream services.
 ---
 
+<CopyPrompt
+  text="Implement durable batch processing. Import `sleep` from `workflow`. In an exported &quot;use workflow&quot; function, split the input records into chunks of a fixed `batchSize`. For each batch, call a &quot;use step&quot; helper such as `processRecord(record)` for every record using `Promise.allSettled` so one record failure does not hide the rest. Record successes and failures in a serializable result object. Between batches, `await sleep(&quot;1s&quot;)` or another configured delay to respect downstream rate limits. Make the step idempotent using record IDs or external idempotency keys. Verify all-success, partial-failure, and rate-paced execution paths."
+/>
+
 Use batching when you need to process a large list of items in parallel while controlling concurrency. Items are split into fixed-size batches, each batch runs concurrently, and failures in one batch don't affect others.
 
 ## When to use this

package/docs/cookbook/common-patterns/idempotency.mdx

@@ -1,45 +1,29 @@
 ---
 title: Idempotency
-description: Ensure external side effects happen exactly once, even when steps are retried or workflows are replayed.
+description: Make step retries safe and coordinate duplicate workflow starts with hook tokens.
 type: guide
-summary: Use step IDs as idempotency keys for external APIs like Stripe so that retries and replays don't create duplicate charges.
+summary: Use step IDs for retry-safe external calls, and use deterministic hook tokens when duplicate requests must route to one active workflow.
 ---
 
-Workflow steps can be retried (on failure) and replayed (on cold start). If a step calls an external API that isn't idempotent, retries could create duplicate charges, send duplicate emails, or double-process records. Use idempotency keys to make these operations safe.
+<CopyPrompt
+  text="Make this workflow's side effects idempotent. For retry-safe external calls, read the deterministic step ID inside the &quot;use step&quot; function with `getStepMetadata()` from `workflow` and pass `stepId` as the idempotency key to the external API (for example Stripe's `Idempotency-Key` header) so step retries deduplicate. For duplicate workflow starts, derive a deterministic hook token from the domain key (for example `order:${orderId}`): in the API route, look up the active hook with `getHookByToken(token)` from `workflow/api` — catching `HookNotFoundError` from `workflow/errors` — and reuse its `runId`, otherwise call `start(...)`; inside the workflow, create the hook with the same token and check `await hook.getConflict()` before duplicate-sensitive work. Verify retried steps deduplicate, duplicate starts reuse the active run, and conflicts are handled."
+/>
+
+Use idempotency when a retry or duplicate request should not repeat the underlying work. In Workflow, there are two common patterns: use the step ID for retry-safe external calls, and use hook tokens to coordinate duplicate workflow starts.
 
 ## When to use this
 
-- Charging a payment (Stripe, PayPal)
-- Sending transactional emails or SMS
-- Creating records in external systems where duplicates are harmful
-- Any step that has side effects in systems you don't control
+- A step charges a payment, sends an email, enqueues work, or creates an external record.
+- A route may receive duplicate requests that should map to one active workflow run.
 
-## Pattern: Step ID as idempotency key
+## Step idempotency
 
 Every step has a unique, deterministic `stepId` available via `getStepMetadata()`. Pass this as the idempotency key to external APIs:
 
 ```typescript
 import { getStepMetadata } from "workflow";
 
-declare function createCharge(customerId: string, amount: number): Promise<{ id: string }>; // @setup
-declare function sendReceipt(customerId: string, chargeId: string): Promise<void>; // @setup
-
-export async function chargeCustomer(customerId: string, amount: number) {
-  "use workflow";
-
-  const charge = await createCharge(customerId, amount);
-  await sendReceipt(customerId, charge.id);
-
-  return { customerId, chargeId: charge.id, status: "completed" };
-}
-```
-
-### Step function with idempotency key
-
-```typescript
-import { getStepMetadata } from "workflow";
-
-async function createCharge(
+export async function createCharge(
   customerId: string,
   amount: number
 ): Promise<{ id: string }> {
@@ -69,39 +53,43 @@ async function createCharge(
 
   return charge.json();
 }
-
-async function sendReceipt(customerId: string, chargeId: string): Promise<void> {
-  "use step";
-
-  const { stepId } = getStepMetadata();
-
-  await fetch("https://api.example.com/receipts", {
-    method: "POST",
-    headers: { "Idempotency-Key": stepId },
-    body: JSON.stringify({ customerId, chargeId }),
-  });
-}
 ```
 
-## Race condition caveats
+See [Step Idempotency](/docs/foundations/idempotency#step-idempotency) for why `stepId` is stable across retries and how to think about external API conflicts.
 
-Workflow does not currently provide distributed locking or true exactly-once delivery across concurrent runs. If two workflow runs could process the same entity concurrently:
+## Run idempotency
 
-- **Rely on the external API's idempotency** (like Stripe's `Idempotency-Key`) rather than checking a local flag.
-- **Don't use check-then-act patterns** like "read a flag, then write if not set" -- another run could read the same flag between your read and write.
+For duplicate workflow-start requests, derive a hook token from your domain key. You can avoid obvious duplicate starts by checking whether an active hook already owns that token before calling `start()`:
 
-If your external API doesn't support idempotency keys natively, consider adding a deduplication layer (e.g., a database unique constraint on the operation ID).
+```typescript
+import { getHookByToken, start } from "workflow/api";
+import { HookNotFoundError } from "workflow/errors";
+import { processOrder } from "./workflows/process-order";
+
+export async function POST(request: Request) {
+  const { orderId } = await request.json();
+  const token = `order:${orderId}`;
+
+  try {
+    const hook = await getHookByToken(token); // [!code highlight]
+    return Response.json({ runId: hook.runId, reused: true });
+  } catch (error) {
+    if (!HookNotFoundError.is(error)) throw error;
+  }
 
-## Tips
+  const run = await start(processOrder, [orderId]); // [!code highlight]
+  return Response.json({ runId: run.runId, reused: false });
+}
+```
 
-- **`stepId` is deterministic.** It's the same value across retries and replays of the same step, making it a reliable idempotency key.
-- **Always provide idempotency keys for non-idempotent external calls.** Even if you think a step won't be retried, cold-start replay will re-execute it.
-- **Handle 409/conflict as success.** If an external API returns "already processed," treat that as a successful result, not an error.
-- **Make your own APIs idempotent** where possible. Accept an idempotency key and return the cached result on duplicate requests.
+The workflow should create the deterministic hook and check `await hook.getConflict()` before duplicate-sensitive work — awaiting `getConflict()` suspends the workflow to commit the hook registration and resolves with the conflicting run when another active run already owns the token (or `null` once the hook is registered). See [Run idempotency](/docs/foundations/idempotency#run-idempotency) for the full pattern, including how to steer an active run with `resumeHook()` and how to handle the current race between `start()` and hook registration.
 
 ## 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 full Node.js access
-- [`getStepMetadata()`](/docs/api-reference/step/get-step-metadata) -- provides the deterministic `stepId` for idempotency keys
+- [`"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 full Node.js access
+- [`getStepMetadata()`](/docs/api-reference/workflow/get-step-metadata) -- provides the deterministic `stepId` for idempotency keys
+- [`createHook()`](/docs/api-reference/workflow/create-hook) -- creates a hook with an optional deterministic token
+- [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) -- finds the Hook that owns a token
+- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) -- resumes the active hook when the duplicate request carries data
 - [`start()`](/docs/api-reference/workflow-api/start) -- starts a new workflow run

package/docs/cookbook/common-patterns/rate-limiting.mdx

@@ -5,6 +5,10 @@ type: guide
 summary: When an external API returns 429, throw RetryableError with the Retry-After value so the workflow runtime automatically reschedules the step after the specified delay.
 ---
 
+<CopyPrompt
+  text="Add durable rate-limit handling to external API steps. Import `RetryableError`, `FatalError`, `getStepMetadata`, and `sleep` from `workflow` as needed. In each HTTP-calling &quot;use step&quot; helper, if the response status is 429, read the `Retry-After` header and throw `new RetryableError(&quot;Rate limited&quot;, { retryAfter })`. For transient 5xx/network failures, throw `RetryableError` with an exponential delay based on `getStepMetadata().attempt`. For permanent 4xx failures, throw `FatalError`. If the dependency is completely down, add a workflow-level circuit breaker that `await sleep(&quot;30s&quot;)` before probing again. Make requests idempotent with stable keys, and verify 429, 5xx, fatal 4xx, and circuit-breaker behavior."
+/>
+
 Use this pattern when calling external APIs that enforce rate limits. Instead of writing manual retry loops, throw `RetryableError` with a `retryAfter` value and let the workflow runtime handle rescheduling.
 
 ## When to use this
@@ -224,5 +228,5 @@ export async function downloadWithRetry(url: string) {
 - [`"use step"`](/docs/foundations/workflows-and-steps) -- marks functions that run with full Node.js access
 - [`RetryableError`](/docs/api-reference/workflow/retryable-error) -- signals the runtime to retry after a delay
 - [`FatalError`](/docs/api-reference/workflow/fatal-error) -- signals a permanent failure, skipping retries
-- [`getStepMetadata()`](/docs/api-reference/step/get-step-metadata) -- provides the current attempt number and step ID
+- [`getStepMetadata()`](/docs/api-reference/workflow/get-step-metadata) -- provides the current attempt number and step ID
 - [`sleep()`](/docs/api-reference/workflow/sleep) -- durable pause for circuit breaker cooldowns

package/docs/cookbook/common-patterns/saga.mdx

@@ -5,6 +5,10 @@ type: guide
 summary: Run a sequence of steps where each registers a compensation. If any step throws a FatalError, compensations execute in reverse order to restore consistency.
 ---
 
+<CopyPrompt
+  text="Implement a saga-style workflow. Import `FatalError` from `workflow`. In the exported &quot;use workflow&quot; function, keep a compensation stack such as `const compensations: Array<() => Promise<void>> = []`. For each forward side effect, create a &quot;use step&quot; helper, await it, then push the matching compensation &quot;use step&quot; helper onto the stack. Throw `FatalError` for permanent business failures and normal errors for retryable failures. In the workflow catch block, run compensations in reverse order with `for (const compensate of compensations.reverse()) await compensate()`, then rethrow or return a failed status. Make each compensation idempotent. Verify successful completion, a fatal failure after multiple steps, and a replay/retry during rollback."
+/>
+
 Use the saga pattern when a business transaction spans multiple services and you need automatic rollback if any step fails. Each forward step registers a compensation, and on failure the workflow unwinds them in reverse order.
 
 ## When to use this
@@ -241,7 +245,7 @@ export async function subscriptionUpgradeSaga(accountId: string, seats: number)
 
 ## 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 full Node.js access
+- [`"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 full Node.js access
 - [`FatalError`](/docs/api-reference/workflow/fatal-error) -- non-retryable error that triggers compensation
 - [`getWritable()`](/docs/api-reference/workflow/get-writable) -- streams data from workflows for real-time UI updates

package/docs/cookbook/common-patterns/scheduling.mdx

@@ -5,8 +5,16 @@ type: guide
 summary: Schedule future actions with durable sleep that survives cold starts, and race sleeps against hooks to let external events cancel the workflow early.
 ---
 
+<CopyPrompt
+  text="Create an interruptible scheduled workflow. Import `defineHook` and `sleep` from `workflow`. Define a cancellation hook such as `export const cancelDrip = defineHook<{ reason?: string }>()`. In an exported workflow function with &quot;use workflow&quot;, create the hook once, send the first message in a &quot;use step&quot; helper, then `await Promise.race([sleep(&quot;2d&quot;).then(() => false), cancelHook.then(() => true)])` before each delayed action. If the hook wins, return a cancelled status; if sleep wins, continue to the next step. Add an API route that calls `cancelDrip.resume(runIdOrToken, { reason })` or `resumeHook()` from `workflow/api`. Verify scheduled delivery, cancellation before sleep completes, and resume after server restart."
+/>
+
 Workflow's `sleep()` is durable — it survives cold starts, restarts, and deployments. Combined with `defineHook()` and `Promise.race()`, it becomes the foundation for interruptible scheduled workflows like drip campaigns, reminders, and timed sequences.
 
+<Callout type="info">
+Scheduled workflows are still pinned to the deployment that started them. If you are building recurring or indefinitely running schedules that should adopt newer code over time, see [Versioning](/docs/foundations/versioning) for the explicit `deploymentId: "latest"` continuation pattern.
+</Callout>
+
 ## When to use this
 
 - Sending emails on a schedule (drip campaigns, onboarding sequences, reminders)
@@ -102,6 +110,10 @@ export async function POST(req: Request) {
 3. **Race** — `Promise.race([sleep(...), hook])` blocks until either the timer fires or the hook is resumed, whichever comes first.
 4. **Fresh hooks per window** — after a sleep completes normally, the previous hook instance is consumed. A new `.create()` call registers a fresh hook for the next sleep window, reusing the same token.
 
+<Callout type="info">
+Deterministic hook tokens can also serve as the idempotency point for scheduled runs. If duplicate schedule starts would send duplicate campaigns or reminders, create a hook with a token derived from the campaign key near the beginning of the workflow and route retries through that hook. If two scheduled starts race, the duplicate run can detect the conflict early with `await hook.getConflict()`, which resolves with the active owner so the duplicate can defer to it. See [Idempotency](/docs/foundations/idempotency).
+</Callout>
+
 ## Adapting to your use case
 
 - **Change durations** — replace `"2d"` with any duration string (`"1h"`, `"7d"`, `"30m"`) or a `Date` object for absolute times.

package/docs/cookbook/common-patterns/sequential-and-parallel.mdx

@@ -9,6 +9,10 @@ related:
   - /cookbook/common-patterns/scheduling
 ---
 
+<CopyPrompt
+  text="Compose these workflow steps with standard async/await patterns. In the exported &quot;use workflow&quot; function, chain dependent &quot;use step&quot; calls with sequential `await`; run independent steps concurrently by starting them without `await` and awaiting `Promise.all([...])`; and use `Promise.race([...])` to act on whichever promise settles first. These compose with durable primitives — race a step or a webhook from `createWebhook()` against `sleep()` from `workflow` for deadlines. Keep every step input and output serializable, and remember `Promise.race` does not cancel the losing branch — it keeps running — so side-effectful losers need idempotency keys. Verify sequential ordering, parallel execution, and both race outcomes."
+/>
+
 Workflows are written in plain async/await — there's no new control-flow API to learn. Sequential awaits chain steps that depend on each other, `Promise.all` runs independent steps in parallel, and `Promise.race` returns whichever finishes first. These compose with workflow primitives like [`sleep()`](/docs/api-reference/workflow/sleep) and [`createWebhook()`](/docs/api-reference/workflow/create-webhook) since those are also just promises.
 
 ## When to use this

package/docs/cookbook/common-patterns/timeouts.mdx

@@ -10,6 +10,10 @@ related:
   - /cookbook/common-patterns/webhooks
 ---
 
+<CopyPrompt
+  text="Add a deadline to this slow workflow operation. Import `sleep` from `workflow`. In the exported &quot;use workflow&quot; function, race the operation against a durable sleep: `await Promise.race([slowStep(...), deadline(&quot;10m&quot;)])`, where `deadline` is a helper that awaits `sleep(duration)` and returns a sentinel value or throws. Branch on the winner: continue normally on success, run the fallback or compensation path on timeout. Use the same pattern to bound hooks and webhooks. `Promise.race` does not cancel the loser — the underlying step keeps running — so pass an `AbortSignal` into the step for cooperative cancellation and make non-idempotent side effects retry-safe with idempotency keys. Verify the fast path, the timeout path, and side-effect safety when the loser completes late."
+/>
+
 A common requirement is bounding how long a workflow waits for something to finish — a slow step, an external webhook, a human approval. Race the operation against a durable `sleep()` with `Promise.race()` — whichever finishes first wins, and the loser keeps running but its result is ignored.
 
 ## When to use this
@@ -80,7 +84,7 @@ export async function waitForApproval(requestId: string) {
 4. **Throw to fail the workflow** — inside a workflow function, throwing an `Error` exits the run with that error. Use `FatalError` inside steps; throw plain errors inside workflows.
 
 <Callout type="warn">
-**The losing operation keeps running.** `Promise.race` doesn't cancel — when the sleep wins, the underlying step (or model call, or HTTP request) continues to completion in the background. This is fine for idempotent reads but matters when the operation has side effects or costs money. For hard cancellation across processes, see [Distributed Abort Controller](/cookbook/advanced/distributed-abort-controller).
+**The losing operation keeps running.** `Promise.race` doesn't cancel — when the sleep wins, the underlying step (or model call, or HTTP request) continues to completion in the background. This is fine for idempotent reads but matters when the operation has side effects or costs money. Pass an `AbortSignal` into the step to cancel it cooperatively, and use idempotency keys for non-idempotent side effects. See the [Cancellation Guide](/docs/foundations/cancellation) and [Idempotency](/docs/foundations/idempotency) for patterns.
 </Callout>
 
 ## Adapting to your use case
@@ -96,4 +100,5 @@ export async function waitForApproval(requestId: string) {
 - [`sleep()`](/docs/api-reference/workflow/sleep) — durable wait (survives restarts, zero compute cost)
 - [`createWebhook()`](/docs/api-reference/workflow/create-webhook) — create a webhook URL the workflow can race against
 - [`defineHook()`](/docs/api-reference/workflow/define-hook) — typed hook for in-process cancellation
+- [Idempotency](/docs/foundations/idempotency) — protect side effects that may keep running after a timeout
 - [`Promise.race()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race) — race operations against deadlines

package/docs/cookbook/common-patterns/webhooks.mdx

@@ -5,6 +5,10 @@ type: guide
 summary: Create webhook endpoints that your workflow can await, process incoming requests in steps, and respond to the caller — all within durable workflow context.
 ---
 
+<CopyPrompt
+  text="Implement durable webhook handling for this workflow. Use `createWebhook()` from `workflow` inside the &quot;use workflow&quot; function when the workflow needs a generated callback URL. Use `createWebhook({ respondWith: &quot;manual&quot; })` when the workflow must validate the request before sending an HTTP response. Await the webhook request, pass the `RequestWithResponse` into a &quot;use step&quot; function for validation and side effects, and call `request.respondWith(Response.json(...))` on every code path. Race the webhook against `sleep()` for deadlines and throw `FatalError` for permanent timeout/failure paths. For fixed public callbacks or large payloads, use `defineHook()` plus `resumeHook()` from `workflow/api` and pass only a token or blob reference into the hook payload. Verify success response, invalid response, timeout, duplicate callback, and large-payload behavior."
+/>
+
 Use webhooks when external services push events to your application via HTTP callbacks. The workflow creates a webhook URL, suspends with zero compute cost, and resumes when a request arrives.
 
 ## When to use this

package/docs/cookbook/common-patterns/workflow-composition.mdx

@@ -5,11 +5,16 @@ type: guide
 summary: Compose workflows two ways — direct await flattens the child into the parent's event log, while background spawn via start() runs the child as an independent run.
 related:
   - /cookbook/advanced/child-workflows
+  - /cookbook/common-patterns/idempotency
   - /docs/api-reference/workflow-api/start
   - /docs/api-reference/workflow-api/get-run
 ---
 
-Workflows can call other workflows. Choose between two composition modes depending on whether the parent needs the child's result inline (direct await) or wants to fire the child off as an independent run (background spawn). For massive fan-out with polling and partial-failure handling, see [Child Workflows](/cookbook/advanced/child-workflows).
+<CopyPrompt
+  text="Compose these workflows. For direct composition, `await` the child workflow function from the parent &quot;use workflow&quot; function — the child's steps flatten into the parent's event log and run as a single run sharing the parent's lifecycle. For independent background work, spawn the child with `start()` from `workflow/api` called directly in the workflow (in v5, `start()` is step-backed and records a deterministic step boundary) and return `run.runId` so callers can track it with `getRun()`. Choose flattening when the parent needs the child's result; choose background spawn when the child should have its own run, retries, and lifetime. Keep all inputs and outputs serializable. Verify flattened execution, background spawn with a separate runId, and replay determinism."
+/>
+
+Workflows can call other workflows. Choose between two composition modes depending on whether the parent needs the child's result inline (direct await) or wants to fire the child off as an independent run (background spawn). For massive fan-out with hook-based waiting and partial-failure handling, see [Child Workflows](/cookbook/advanced/child-workflows).
 
 ## When to use this
 
@@ -53,7 +58,7 @@ The parent waits for the child to finish before continuing. Both functions share
 
 ### Background spawn via `start()`
 
-To run a child workflow independently without blocking the parent, call [`start()`](/docs/api-reference/workflow-api/start) from a step. This launches the child as a separate workflow run with its own `runId`.
+To run a child workflow independently without blocking the parent, call [`start()`](/docs/api-reference/workflow-api/start) from the parent workflow. This launches the child as a separate workflow run with its own `runId`.
 
 ```typescript lineNumbers
 import { start } from "workflow/api";
@@ -62,37 +67,34 @@ declare function generateReport(reportId: string): Promise<void>; // @setup
 declare function fulfillOrder(orderId: string): Promise<{ id: string }>; // @setup
 declare function sendConfirmation(orderId: string): Promise<void>; // @setup
 
-async function triggerReportGeneration(reportId: string) {
-  "use step"; // [!code highlight]
-
-  const run = await start(generateReport, [reportId]); // [!code highlight]
-  return run.runId;
-}
-
 export async function processOrder(orderId: string) {
   "use workflow";
 
   const order = await fulfillOrder(orderId);
 
-  const reportRunId = await triggerReportGeneration(orderId); // [!code highlight]
+  const reportRun = await start(generateReport, [orderId]); // [!code highlight]
 
   await sendConfirmation(orderId);
 
-  return { orderId, reportRunId };
+  return { orderId, reportRunId: reportRun.runId };
 }
 ```
 
 The parent continues immediately after `start()` returns. The child runs independently and can be monitored separately using the returned `runId` (e.g., via [`getRun()`](/docs/api-reference/workflow-api/get-run)).
 
 <Callout type="info">
-If you want the child workflow to run on the latest deployment rather than the current one, pass [`deploymentId: "latest"`](/docs/api-reference/workflow-api/start#using-deploymentid-latest) in the `start()` options. This is currently a Vercel-specific feature. Be aware that the child workflow's function name, file path, argument types, and return type must remain compatible across deployments — renaming the function or changing its location will change the workflow ID, and modifying expected inputs or outputs can cause serialization failures.
+Each background spawn creates a separate run. If duplicate requests must route to one active child workflow, have the child create a deterministic hook token from the business key and use that hook as the idempotency point. If concurrent starts race, the losing child can detect the conflict early with `await hook.getConflict()`, which resolves with the active owner so the child can point callers at it. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
+<Callout type="info">
+If you want the child workflow to run on the latest deployment rather than the current one, pass [`deploymentId: "latest"`](/docs/api-reference/workflow-api/start#using-deploymentid-latest) in the `start()` options. See [Versioning](/docs/foundations/versioning) for the full model. This is currently a Vercel-specific feature, and other Worlds may map the concept to their own deployment runtimes. Be aware that the child workflow's function name, file path, argument types, and return type must remain compatible across deployments — renaming the function or changing its location will change the workflow ID, and modifying expected inputs or outputs can cause serialization failures.
 </Callout>
 
 ## How it works
 
 1. **Direct await flattens.** When a workflow function awaits another workflow function, the child's `"use workflow"` directive is treated as inline — the child's steps emit into the parent's event log and share the parent's run ID.
 2. **`start()` mints a new run.** The child gets its own `runId`, its own event log, and its own retry boundary. The parent only sees the `runId` returned by `start()`.
-3. **`start()` must be called from a step.** Calling `start()` directly from a workflow function is not allowed — wrap it in a `"use step"` function. This keeps the spawn deterministic across replays.
+3. **`start()` can run inside workflows.** In v5, `start()` is step-backed, so it can be called directly from a workflow function and still records a deterministic step boundary in the event log.
 
 ## Choosing between the two modes
 
@@ -106,9 +108,9 @@ If you want the child workflow to run on the latest deployment rather than the c
 
 ## Adapting to your use case
 
-- **Spawn many children at once** — call `start()` in a loop inside a step. For more advanced fan-out (chunking, polling, partial-failure handling), graduate to the [Child Workflows](/cookbook/advanced/child-workflows) recipe.
-- **Wait for a background child to finish** — combine `start()` with `getRun()` polling. The [Child Workflows](/cookbook/advanced/child-workflows) page covers the full polling loop.
-- **Pass results back from background children** — the spawn step returns the `runId`; later, a poll step uses `getRun(runId).returnValue` to fetch the final result.
+- **Spawn many children at once** — call `start()` in a loop from the workflow. For more advanced fan-out (chunking, hook-based waiting, partial-failure handling), graduate to the [Child Workflows](/cookbook/advanced/child-workflows) recipe.
+- **Wait for a background child to finish** — combine `start()` with a completion hook the child resumes when done. The [Child Workflows](/cookbook/advanced/child-workflows) page covers the recommended `startAndWait()` pattern.
+- **Pass results back from background children** — the wrapped child resumes the parent's hook in `finally` with `{ status, value | error }`; the parent awaits the hook instead of polling `getRun().status`.
 
 ## Key APIs
 
@@ -116,3 +118,4 @@ If you want the child workflow to run on the latest deployment rather than the c
 - [`"use step"`](/docs/foundations/workflows-and-steps) — marks functions with full Node.js access
 - [`start()`](/docs/api-reference/workflow-api/start) — spawn a child workflow as a separate run
 - [`getRun()`](/docs/api-reference/workflow-api/get-run) — retrieve a workflow run's status and return value
+- [Idempotency](/docs/foundations/idempotency) — deduplicate step side effects and workflow starts

package/docs/cookbook/index.mdx

@@ -8,7 +8,7 @@ A curated collection of workflow patterns with clean, copy-paste code examples f
 
 ## Agent Patterns
 
-- [**Durable Agent**](/cookbook/agent-patterns/durable-agent) — Replace a stateless AI agent with one that survives crashes and retries tool calls
+- [**WorkflowAgent**](/cookbook/agent-patterns/durable-agent) — Build durable, resumable AI agents with AI SDK's WorkflowAgent
 - [**Human-in-the-Loop**](/cookbook/agent-patterns/human-in-the-loop) — Pause an agent for human approval, then resume based on the decision
 - [**Agent Cancellation**](/cookbook/agent-patterns/agent-cancellation) — Stop a running agent immediately via `run.cancel()` or gracefully via a hook + `Promise.race`
 
@@ -21,7 +21,7 @@ A curated collection of workflow patterns with clean, copy-paste code examples f
 - [**Rate Limiting**](/cookbook/common-patterns/rate-limiting) — Handle 429 responses and transient failures with RetryableError and backoff
 - [**Scheduling**](/cookbook/common-patterns/scheduling) — Use durable sleep to schedule actions minutes, hours, or weeks ahead
 - [**Timeouts**](/cookbook/common-patterns/timeouts) — Add deadlines to slow steps, hooks, and webhooks by racing them against a durable sleep
-- [**Idempotency**](/cookbook/common-patterns/idempotency) — Ensure side effects happen exactly once, even when steps retry
+- [**Idempotency**](/cookbook/common-patterns/idempotency) — Ensure side effects and duplicate starts are safe to retry
 - [**Webhooks**](/cookbook/common-patterns/webhooks) — Receive HTTP callbacks from external services and process them durably
 
 ## Integrations
@@ -33,6 +33,6 @@ A curated collection of workflow patterns with clean, copy-paste code examples f
 ## Advanced
 
 - [**Child Workflows**](/cookbook/advanced/child-workflows) — Spawn and orchestrate child workflows from a parent
-- [**Distributed Abort Controller**](/cookbook/advanced/distributed-abort-controller) — Build a cross-process abort controller using workflow streams and hooks
+- [**Upgrading Workflows**](/cookbook/advanced/upgrading-workflows) — Identify a clean upgrade point in a long-running workflow and spawn a fresh run on the latest deployment carrying state forward
 - [**Serializable Steps**](/cookbook/advanced/serializable-steps) — Wrap non-serializable third-party objects so they cross the workflow boundary
 - [**Publishing Libraries**](/cookbook/advanced/publishing-libraries) — Ship npm packages that export reusable workflow functions