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

package/docs/cookbook/advanced/meta.json

@@ -1,10 +1,9 @@
 {
   "title": "Advanced",
   "pages": [
+    "child-workflows",
+    "upgrading-workflows",
     "serializable-steps",
-    "durable-objects",
-    "isomorphic-packages",
-    "custom-serialization",
     "publishing-libraries"
   ]
 }

package/docs/cookbook/advanced/publishing-libraries.mdx

@@ -5,6 +5,8 @@ type: guide
 summary: Learn how to build, export, and test npm packages that ship workflow and step functions — including package.json exports, re-exporting for stable workflow IDs, keeping step I/O clean, and integration testing.
 ---
 
+import { File, Folder, Files } from "fumadocs-ui/components/files";
+
 <Callout>
 This is an advanced guide for library authors who want to publish reusable workflow functions as npm packages. It assumes familiarity with `"use workflow"`, `"use step"`, and the workflow execution model.
 </Callout>
@@ -13,23 +15,37 @@ This is an advanced guide for library authors who want to publish reusable workf
 
 A workflow library follows a standard TypeScript package layout with a dedicated `workflows/` directory. Each workflow file exports one or more workflow functions that consumers can import and pass to `start()`.
 
-```
-my-media-lib/
-├── src/
-│   ├── index.ts              # Package entry point
-│   ├── types.ts              # Shared types
-│   ├── workflows/
-│   │   ├── index.ts          # Re-exports all workflows
-│   │   ├── transcode.ts      # Workflow: transcode a video
-│   │   └── generate-thumbnails.ts
-│   └── lib/
-│       └── api-client.ts     # Internal helpers (NOT steps)
-├── test-server/
-│   └── workflows.ts          # Re-export for integration tests
-├── tsup.config.ts
-├── package.json
-└── tsconfig.json
-```
+<Files>
+  <Folder name="my-media-lib" defaultOpen>
+    <Folder name="src" defaultOpen>
+      <File name="index.ts" />
+      <File name="types.ts" />
+      <Folder name="workflows" defaultOpen>
+        <File name="index.ts" />
+        <File name="transcode.ts" />
+        <File name="generate-thumbnails.ts" />
+      </Folder>
+      <Folder name="lib" defaultOpen>
+        <File name="api-client.ts" />
+      </Folder>
+    </Folder>
+    <Folder name="test-server" defaultOpen>
+      <File name="workflows.ts" />
+    </Folder>
+    <File name="tsup.config.ts" />
+    <File name="package.json" />
+    <File name="tsconfig.json" />
+  </Folder>
+</Files>
+
+Key files:
+
+- **`src/index.ts`** — Package entry point. Exports the public API.
+- **`src/types.ts`** — Shared TypeScript types.
+- **`src/workflows/index.ts`** — Re-exports every workflow so consumers can pull them in under one specifier (see [Entry Points and Exports](#entry-points-and-exports)).
+- **`src/workflows/*.ts`** — One file per workflow function (e.g. `transcode.ts`, `generate-thumbnails.ts`).
+- **`src/lib/`** — Internal helpers. Plain async code, *not* marked with `"use workflow"` or `"use step"`.
+- **`test-server/workflows.ts`** — Re-export file used by integration tests (see [Testing Workflow Libraries](#testing-workflow-libraries)).
 
 ### Entry Points and Exports
 
@@ -126,7 +142,7 @@ When you publish a workflow library, every step function's inputs and outputs ar
 
 ### 1. Everything Must Be Serializable
 
-Step inputs and outputs must be serializable. The workflow runtime supports a rich set of types beyond plain JSON — including `Date`, `RegExp`, `Map`, `Set`, `BigInt`, `Uint8Array`, `URL`, `Error`, and class instances that implement [custom class serialization](/docs/cookbook/advanced/custom-serialization). See the [serialization reference](/docs/foundations/serialization) for the full list of supported types. Do not pass or return:
+Step inputs and outputs must be serializable. The workflow runtime supports a rich set of types beyond plain JSON — including `Date`, `RegExp`, `Map`, `Set`, `BigInt`, `Uint8Array`, `URL`, `Error`, and class instances that implement [custom class serialization](/docs/foundations/serialization#custom-class-serialization). See the [serialization reference](/docs/foundations/serialization) for the full list of supported types. Do not pass or return:
 
 - Functions or closures
 - `WeakRef`, `WeakMap`, or `WeakSet`
@@ -226,7 +242,18 @@ pnpm vitest run --config vitest.workflowsdk.config.ts
 
 ## Working With and Without Workflow Installed
 
-If your library should work both as a standalone package and inside Workflow SDK, declare `workflow` as an optional peer dependency:
+Some libraries want to be useful to consumers who *aren't* using Workflow SDK at all — the library picks up durable behavior when a workflow runtime is present and falls back to plain async execution otherwise.
+
+<Callout type="info">
+Two rules for isomorphic packages:
+
+1. **Any runtime reference to the `workflow` package must be loaded via dynamic `import("workflow")` inside a try/catch.** A static top-level import makes the module fail to load for consumers who haven't installed workflow.
+2. **The `"use workflow"` and `"use step"` directives are safe to keep in your library source.** When a consumer compiles your code with the Workflow SDK toolchain (via the [re-export pattern](#re-exporting-for-workflow-id-stability) above), the SWC plugin transforms them into durable-execution glue. When they're not compiled — plain Node, plain tests, a consumer without the runtime — they are just string expression statements and run as no-ops.
+</Callout>
+
+### Optional peer dependency
+
+Declare `workflow` as an **optional** peer so consumers without the runtime aren't forced to install it:
 
 ```json
 {
@@ -241,22 +268,53 @@ If your library should work both as a standalone package and inside Workflow SDK
 }
 ```
 
-Use dynamic imports and runtime detection so your library gracefully degrades when workflow is not installed:
+### Runtime detection
+
+Wrap a dynamic `import("workflow")` in try/catch. If either the module isn't installed *or* `getStepMetadata()` throws (call site isn't inside a workflow step), fall through to the standalone path.
 
 ```typescript lineNumbers
-async function isWorkflowRuntime(): Promise<boolean> {
+async function getWorkflowStepId(): Promise<string | null> { // [!code highlight]
   try {
     const wf = await import("workflow");
-    if (typeof wf.getWorkflowMetadata !== "function") return false;
-    wf.getWorkflowMetadata(); // [!code highlight]
-    return true;
+    const { stepId } = wf.getStepMetadata();
+    return stepId;
   } catch {
-    return false;
+    return null;
   }
 }
 ```
 
-See [Isomorphic Packages](/docs/cookbook/advanced/isomorphic-packages) for the full pattern including feature detection, dynamic imports, and dual-path execution.
+### A concrete use case: replay-safe idempotency keys
+
+A payments utility that uses the current workflow step ID as a Stripe idempotency key when available, and a fresh UUID otherwise:
+
+```typescript lineNumbers
+declare function getWorkflowStepId(): Promise<string | null>; // @setup (defined in the previous block)
+
+export async function processPayment(amount: number, currency: string) {
+  const stepId = await getWorkflowStepId();
+  const idempotencyKey = stepId ? `payment:${stepId}` : crypto.randomUUID(); // [!code highlight]
+
+  const res = await fetch("https://api.stripe.com/v1/charges", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`,
+      "Idempotency-Key": idempotencyKey, // [!code highlight]
+    },
+    body: new URLSearchParams({ amount: String(amount), currency }),
+  });
+  return res.json();
+}
+```
+
+When called from inside a workflow step, the utility gets a stable idempotency key for that step across retries — Stripe dedupes retries for free. When called from a plain Node.js process, it behaves like any other function and a fresh UUID is generated. For more patterns, see [Idempotency](/docs/foundations/idempotency).
+
+### In production
+
+Packages in the wild built on Workflow SDK:
+
+- **[`@mux/ai`](https://github.com/muxinc/ai)** — Reusable video AI workflows (summaries, chapters, content moderation, translation, embeddings) exported with `"use workflow"` / `"use step"` directives. In a standard Node environment the directives are no-ops and the SDK runs as a plain async library; in a Workflow SDK environment the consumer's compiler transforms them into durable, resumable steps with automatic retries and observability. Written up in detail in [*How Mux shipped durable video workflows with their @mux/ai SDK*](https://vercel.com/blog/how-mux-shipped-durable-video-workflows-with-their-mux-ai-sdk) on the Vercel blog.
+- **World ID** — Human-in-the-loop "proof of human" primitive for agent workflows. Developers drop a World ID step into any workflow to require a zero-knowledge cryptographic proof that a real, unique human authorized a specific action (deploy approvals, large payments, sensitive data access, etc.). Because it runs as a workflow step, every verification is durable, replay-safe, and viewable inside the run's execution timeline — giving you a provable audit record of which human approved what. Available on npm and announced in [*World ID for agents: Browserbase, Exa, Okta, and Vercel*](https://world.org/blog/announcements/browserbase-exa-okta-world-id-for-agentic-web) on the World blog.
 
 ## Checklist
 
@@ -273,7 +331,7 @@ Before publishing a workflow library:
 
 ## Key APIs
 
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
-- [`"use step"`](/docs/api-reference/workflow/use-step) — marks functions for durable execution
-- [`start`](/docs/api-reference/workflow/start) — starts a workflow run
+- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions) — declares the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions) — marks functions for durable execution
+- [`start`](/docs/api-reference/workflow-api/start) — starts a workflow run
 - [`getWorkflowMetadata`](/docs/api-reference/workflow/get-workflow-metadata) — runtime detection and run ID access

package/docs/cookbook/advanced/serializable-steps.mdx

@@ -1,17 +1,28 @@
 ---
 title: Serializable Steps
-description: Wrap non-serializable objects (like AI model providers) inside step functions so they can cross the workflow boundary.
+description: Wrap non-serializable third-party objects (like AI model providers) inside step factory functions so they can cross the workflow boundary.
 type: guide
-summary: Return a callback from a step to defer provider initialization, making non-serializable AI SDK models work inside durable workflows.
+summary: Return a callback from a step to defer construction of a non-owned class (AI SDK models, cloud SDK clients) until execution time, making them usable inside durable workflows.
+related:
+  - /docs/foundations/serialization
+  - /docs/foundations/serialization#custom-class-serialization
+  - /docs/foundations/workflows-and-steps#step-functions
 ---
 
 <Callout>
 This is an advanced guide. It dives into workflow internals and is not required reading to use workflow.
 </Callout>
 
+## When to use this pattern
+
+Workflow functions run inside a sandboxed VM where every value that crosses a function boundary must be serializable. There are two ways to get a non-serializable object across that boundary, depending on whether you own the class:
+
+- **You own the class** — implement the [`WORKFLOW_SERIALIZE` / `WORKFLOW_DESERIALIZE` protocol](/docs/foundations/serialization#custom-class-serialization). The instance becomes a first-class serializable value: you can pass it as a workflow input, return it from a step, and call `"use step"` instance methods on it directly. This is the right tool when the class is yours to modify.
+- **You don't own the class** — you can't add methods to `openai("gpt-4o")` from `@ai-sdk/openai` or `new S3Client({...})` from `@aws-sdk/client-s3`. Instead, wrap construction in a `"use step"` factory function and pass the factory across the boundary. That's what this page covers.
+
 ## The Problem
 
-Workflow functions run inside a sandboxed VM where every value that crosses a function boundary must be serializable (JSON-safe). AI SDK model providers — `openai("gpt-4o")`, `anthropic("claude-sonnet-4-20250514")`, etc. — return complex objects with methods, closures, and internal state. Passing one directly into a step causes a serialization error.
+AI SDK model providers — `openai("gpt-4o")`, `anthropic("claude-sonnet-4-20250514")`, etc. — return complex objects with methods, closures, and internal state. Passing one directly into a step causes a serialization error, and you can't bolt `WORKFLOW_SERIALIZE` onto a third-party class.
 
 ```typescript lineNumbers
 import { openai } from "@ai-sdk/openai";
@@ -130,6 +141,7 @@ async function uploadFile(
 
 ## Key APIs
 
-- [`"use step"`](/docs/api-reference/workflow/use-step) — marks a function for extraction and serialization
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions) — marks a function for extraction and serialization
+- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions) — declares the orchestrator function
 - [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — accepts a model factory for durable AI agent streaming
+- [Custom class serialization](/docs/foundations/serialization#custom-class-serialization) — the companion pattern for classes you own (`WORKFLOW_SERIALIZE` / `WORKFLOW_DESERIALIZE`)

package/docs/cookbook/advanced/upgrading-workflows.mdx

@@ -0,0 +1,195 @@
+---
+title: Upgrading Workflows
+description: Identify a clean upgrade point in a long-running workflow and spawn a fresh run on the latest deployment carrying state forward.
+type: guide
+summary: 'Identify a clean upgrade point and hand off to a fresh run via `start(self, [state], { deploymentId: "latest" })` — either automatically on every iteration, or on demand via a dedicated upgrade hook.'
+related:
+  - /docs/foundations/versioning
+  - /cookbook/common-patterns/workflow-composition
+  - /docs/api-reference/workflow-api/start
+  - /docs/foundations/hooks
+---
+
+Workflows that block on external events for days, weeks, or months can outlive many deployments. **The key is to identify a clean upgrade point in the workflow** — a moment where it's safe to checkpoint state and start fresh — and then call [`start()`](/docs/api-reference/workflow-api/start) with `deploymentId: "latest"` to spawn a new run carrying that state forward. The current run ends; the next run begins on whatever deployment is live at that moment, so shipped fixes apply immediately without ever migrating an in-flight run.
+
+<Callout type="info">
+For the underlying model — why runs pin to a deployment by default, how cancel-and-rerun works, and how state crosses the version boundary — see [Versioning](/docs/foundations/versioning). This recipe focuses on event-driven workflows that need to keep advancing across deployments.
+</Callout>
+
+A clean upgrade point is any spot in the workflow where:
+
+- All in-progress side effects have completed (or aren't needed by the next iteration)
+- The relevant state can be serialized into the workflow's input arguments
+- It's natural for the workflow to "checkpoint" — typically right after handling an external event, completing a batch, or finishing a logical phase
+
+There are two ways to apply this:
+
+1. **Upgrade on every iteration** ([Method 1](#method-1-upgrade-on-every-iteration)). Each run handles a single event and unconditionally hands off to a fresh run on the latest deployment before exiting. Simple — no extra triggers — but every event pays the respawn cost.
+2. **Upgrade on demand via a dedicated hook** ([Method 2](#method-2-upgrade-on-demand-via-a-dedicated-hook)). A single long-lived run handles many events in a loop and only respawns when an `upgradeHook` fires. A separate endpoint resumes that hook from your control plane (e.g. after a deploy). More control and fewer respawns, at the cost of an explicit trigger.
+
+### When to use each
+
+- **Method 1** when iterations are short and frequent, the work is cheap to checkpoint, and you want shipped fixes to apply on the very next event. Long-lived "session" workflows (subscriptions, queues, FSMs) that already process events one at a time fit this naturally.
+- **Method 2** when iterations are infrequent or expensive (you don't want to respawn on every event), or when you need to roll out a fix to a fleet of in-flight runs after a deploy by fanning out to a control-plane endpoint. Also fits when "upgrade" should be an explicit operation rather than a side effect of handling each event.
+
+## Method 1: Upgrade on every iteration
+
+Each run inherits state via its argument, blocks on a hook, processes the resume, then unconditionally hands off to its successor by calling `start()` directly from the workflow body with `deploymentId: "latest"`.
+
+```typescript lineNumbers
+import { defineHook, getWorkflowMetadata } from "workflow";
+import { start } from "workflow/api";
+
+declare function processItem(itemId: string): Promise<void>; // @setup
+
+interface QueueState {
+  processed: number;
+  cursor: string | null;
+}
+
+export const nextItemHook = defineHook<{ itemId: string }>();
+
+export async function longRunningQueue(
+  state: QueueState = { processed: 0, cursor: null },
+): Promise<void> {
+  "use workflow";
+
+  const { workflowRunId } = getWorkflowMetadata();
+
+  // Block until something fires the hook — could be hours, days, or longer.
+  // Per-run hook tokens (workflowRunId) keep concurrent chains isolated.
+  const { itemId } = await nextItemHook.create({ token: workflowRunId }); // [!code highlight]
+
+  await processItem(itemId);
+
+  // Hand off to a fresh run on the latest deployment. THIS run ends here.
+  // `deploymentId: "latest"` resolves to whichever deployment is current
+  // when this spawn lands — NOT the deployment running this code.
+  await start( // [!code highlight]
+    longRunningQueue, // [!code highlight]
+    [{ processed: state.processed + 1, cursor: itemId }], // [!code highlight]
+    { deploymentId: "latest" }, // [!code highlight]
+  );
+}
+```
+
+### Resuming the hook
+
+Any server-side code can resume the currently-active iteration by calling `.resume()` with the run ID:
+
+```typescript
+import { nextItemHook } from "@/workflows/long-running-queue";
+
+export async function POST(req: Request) {
+  const { runId, itemId } = await req.json();
+
+  await nextItemHook.resume(runId, { itemId }); // [!code highlight]
+
+  return Response.json({ success: true });
+}
+```
+
+The caller tracks the active `runId` (e.g. in a database, KV, or returned from the previous iteration) and updates it whenever the chain advances.
+
+## Method 2: Upgrade on demand via a dedicated hook
+
+Use a single long-running workflow that handles events in a loop. Define a second hook — `upgradeHook` — alongside the work hook, and race them. While only the work hook fires, the run keeps handling events on its current deployment. When `upgradeHook` resumes, the workflow captures current state and respawns on the latest deployment, then exits.
+
+```typescript lineNumbers
+import { defineHook, getWorkflowMetadata } from "workflow";
+import { start } from "workflow/api";
+
+declare function processItem(itemId: string): Promise<void>; // @setup
+
+interface QueueState {
+  processed: number;
+  cursor: string | null;
+}
+
+export const nextItemHook = defineHook<{ itemId: string }>();
+export const upgradeHook = defineHook<{ reason?: string }>(); // [!code highlight]
+
+export async function longRunningQueue(
+  state: QueueState = { processed: 0, cursor: null },
+): Promise<void> {
+  "use workflow";
+
+  const { workflowRunId } = getWorkflowMetadata();
+
+  while (true) {
+    // Race a normal work event against the upgrade signal.
+    const event = await Promise.race([ // [!code highlight]
+      nextItemHook
+        .create({ token: workflowRunId })
+        .then((payload) => ({ kind: "work" as const, payload })),
+      upgradeHook // [!code highlight]
+        .create({ token: workflowRunId }) // [!code highlight]
+        .then(() => ({ kind: "upgrade" as const })), // [!code highlight]
+    ]);
+
+    if (event.kind === "upgrade") { // [!code highlight]
+      // Checkpoint current state and hand off to a fresh run
+      // on whatever deployment is live now. THIS run ends here.
+      await start(longRunningQueue, [state], { // [!code highlight]
+        deploymentId: "latest", // [!code highlight]
+      }); // [!code highlight]
+      return; // [!code highlight]
+    }
+
+    await processItem(event.payload.itemId);
+    state = {
+      processed: state.processed + 1,
+      cursor: event.payload.itemId,
+    };
+  }
+}
+```
+
+### Triggering the upgrade
+
+Expose a separate endpoint that resumes `upgradeHook` for a given run. Call it from your deploy pipeline, an admin UI, or a fan-out script that iterates over every active run after shipping a fix.
+
+```typescript
+import { upgradeHook } from "@/workflows/long-running-queue";
+
+export async function POST(req: Request) {
+  const { runId, reason } = await req.json();
+
+  // The workflow exits its loop, captures state, and respawns
+  // on the latest deployment.
+  await upgradeHook.resume(runId, { reason }); // [!code highlight]
+
+  return Response.json({ success: true });
+}
+```
+
+To upgrade a fleet of runs after a deploy, list active runs (e.g. from a tracking store) and call this endpoint for each.
+
+## How it works
+
+1. **`deploymentId: "latest"` is the upgrade knob.** Without it, the spawn pins to the current deployment. With it, the new run resolves to whatever deployment is current when the runtime picks it up — so any shipped fix applies starting from that respawn. Both methods rely on this.
+2. **`start()` runs directly from the workflow body.** In v5, [`start()`](/docs/api-reference/workflow-api/start) is step-backed, so it can be called from a workflow function and still records a deterministic step boundary in the event log — no manual `"use step"` wrapper is required.
+3. **State carries through the function argument.** The accumulating context flows from run N to run N+1 as a serialized argument. No external store is required for the state itself.
+4. **Per-run hook tokens.** Using `workflowRunId` as the hook token scopes each iteration's wait to its own run, so multiple chains can run concurrently without interfering.
+5. **Method 1 vs Method 2 is just where the spawn happens.** In Method 1 every run spawns its successor unconditionally before exiting — there is no long-lived process to migrate. In Method 2 the spawn happens only when the upgrade hook fires; otherwise the loop keeps handling events on the same run.
+
+## Adapting to your use case
+
+- **Combine with a sleep.** Race the hook against `sleep()` so iterations also tick on a timer: `Promise.race([hook, sleep("1d")])` lets the workflow advance even if no external event arrives.
+- **Stateless successors.** If the next iteration doesn't need the previous state (e.g. a pure event router), call `start(longRunningQueue, [], { deploymentId: "latest" })` and skip the argument plumbing.
+- **Persist state externally.** If state needs to be readable from outside the workflow (dashboards, debugging, recovery), write it to a database in a step before spawning the next run.
+- **Track the active runId externally.** Whatever resumes the hook needs to know the current run. Capture the `runId` returned by `start()` and write it to a KV/database keyed by a stable session identifier (in a step) so resumers always look up the latest one.
+
+## Caveats
+
+- **Backward compatibility matters.** Because the next run executes on a different deployment, the workflow's input arguments and return type must remain compatible across deployments. Adding required fields, removing fields, or changing types can cause serialization failures. See the [`deploymentId: "latest"` callout](/docs/api-reference/workflow-api/start#using-deploymentid-latest).
+- **Workflow identity is the function name + file path.** Renaming the function or moving the file across a deployment changes the workflow ID — the next iteration will fail to resolve. Treat the workflow's name and location as stable interfaces.
+- **There is a tiny gap between iterations.** The current run ends as soon as `start()` returns; the next run starts asynchronously. A resume that arrives in that window can fail with "hook not found." Make resumers retry, or have the API persist pending payloads and apply them once the next iteration is ready.
+- **Method 2: track active runs externally.** Because Method 2's runs are long-lived, the set of in-flight runs only changes when one starts, completes, or upgrades. Persist run IDs (and clean them up on completion or upgrade) so a rollout script can fan out reliably. After resuming `upgradeHook`, also update the tracked run ID once the new run reports back, the same way you would in Method 1.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/foundations/workflows-and-steps) — marks the orchestrator function
+- [`start()`](/docs/api-reference/workflow-api/start) with [`deploymentId: "latest"`](/docs/api-reference/workflow-api/start#using-deploymentid-latest) — spawn the successor on the newest deployment
+- [`defineHook()`](/docs/api-reference/workflow/define-hook) — suspend the workflow until an external event resumes it
+- [`getWorkflowMetadata()`](/docs/api-reference/workflow/get-workflow-metadata) — exposes `workflowRunId` for per-run hook tokens

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

@@ -0,0 +1,156 @@
+---
+title: Agent Cancellation
+description: Cancel a running agent from the outside using AbortSignal — a hook fires the abort, the agent step bails out of the model stream, and the client gets a clean stop notification.
+type: guide
+summary: Cancel a running agent cooperatively with AbortController. A stop hook fires controller.abort(), the signal propagates into the agent step to cancel the model stream, and a data-stopped part is emitted to streaming clients before the workflow returns.
+---
+
+Cancel a running agent from the outside — for example, a "Stop" button in a chat UI, an admin cancellation endpoint, or a timeout fallback.
+
+## Pattern
+
+Create an `AbortController` in the workflow and race the agent (passing its signal) against a stop hook. When the hook fires, `controller.abort()` is called — the signal propagates into the agent step and cancels the underlying model stream. Before returning, a `data-stopped` part is written to the stream so any streaming clients can render a clean end state.
+
+```typescript lineNumbers
+import { DurableAgent } from "@workflow/ai/agent";
+import { defineHook, getWritable, getWorkflowMetadata } from "workflow";
+import { z } from "zod";
+import type { ModelMessage, UIMessageChunk } from "ai";
+
+export const stopHook = defineHook({
+  schema: z.object({ reason: z.string().optional() }),
+});
+
+async function searchWeb({ query }: { query: string }) {
+  "use step";
+  await new Promise((r) => setTimeout(r, 1500));
+  return { results: [{ title: `${query} - Wikipedia`, snippet: `Overview of ${query}...` }] };
+}
+
+async function analyzeData({ topic }: { topic: string }) {
+  "use step";
+  await new Promise((r) => setTimeout(r, 1200));
+  return { summary: `Analysis of ${topic}: significant developments found.`, confidence: 0.85 };
+}
+
+async function emitStopSignal(details: { reason?: string }) {
+  "use step";
+  const writer = getWritable<UIMessageChunk>().getWriter();
+  try {
+    await writer.write({ type: "data-stopped", id: "stop-signal", data: details } as UIMessageChunk);
+  } finally {
+    writer.releaseLock();
+  }
+}
+
+export async function stoppableAgent(messages: ModelMessage[]) {
+  "use workflow";
+
+  const { workflowRunId } = getWorkflowMetadata();
+  const controller = new AbortController(); // [!code highlight]
+  const hook = stopHook.create({ token: `stop:${workflowRunId}` });
+
+  const agent = new DurableAgent({
+    model: "anthropic/claude-haiku-4.5",
+    instructions: "You are a research assistant. Search and analyze data as needed.",
+    tools: {
+      searchWeb: {
+        description: "Search the web for information",
+        inputSchema: z.object({ query: z.string() }),
+        execute: searchWeb,
+      },
+      analyzeData: {
+        description: "Analyze a piece of data",
+        inputSchema: z.object({ topic: z.string() }),
+        execute: analyzeData,
+      },
+    },
+  });
+
+  const result = await Promise.race([
+    agent
+      .stream({
+        messages,
+        writable: getWritable<UIMessageChunk>(),
+        abortSignal: controller.signal, // [!code highlight]
+        maxSteps: 15,
+      })
+      .then((r) => ({ type: "complete" as const, messages: r.messages })),
+    hook.then(({ reason }) => {
+      controller.abort(reason); // [!code highlight]
+      return { type: "stopped" as const, reason };
+    }),
+  ]);
+
+  if (result.type === "stopped") {
+    await emitStopSignal({ reason: result.reason });
+  }
+
+  return result;
+}
+```
+
+### API Route to Trigger Stop
+
+```typescript lineNumbers
+import { stopHook } from "@/workflows/stoppable-agent";
+
+export async function POST(
+  request: Request,
+  { params }: { params: Promise<{ runId: string }> }
+) {
+  const { runId } = await params;
+  const { reason } = await request.json();
+
+  await stopHook.resume(`stop:${runId}`, {
+    reason: reason || "User requested stop",
+  });
+
+  return Response.json({ success: true });
+}
+```
+
+### Client Stop Button
+
+```tsx lineNumbers
+"use client";
+
+export function StopButton({ runId }: { runId: string }) {
+  const handleStop = async () => {
+    await fetch(`/api/chat/${runId}/stop`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ reason: "User clicked stop" }),
+    });
+  };
+
+  return (
+    <button type="button" onClick={handleStop}>
+      Stop Agent
+    </button>
+  );
+}
+```
+
+## How it works
+
+1. An `AbortController` is created at the start of the workflow
+2. A hook is created with token `stop:${workflowRunId}`
+3. `Promise.race` runs the agent stream and the stop hook concurrently
+4. The agent receives `controller.signal` — when aborted, the underlying model stream is cancelled
+5. When the stop API resumes the hook, `controller.abort()` is called — the race resolves and the workflow exits
+6. `emitStopSignal` writes a `data-stopped` part to the stream so the client renders a clean stop state
+
+## Adapting this
+
+* **Add a timeout** — race a third `sleep()` promise to auto-stop after a deadline
+* **Audit logging** — include a `reason` field in the stop schema to record who stopped and why
+* **Cross-process** — the hook token is deterministic, so any process can call `stopHook.resume()` with the run ID
+* **Step limits** — combine with `maxSteps` on the agent to cap execution even without manual stop
+
+## Key APIs
+
+* [`defineHook()`](/docs/api-reference/workflow/define-hook) — type-safe hook for the stop signal
+* [`getWorkflowMetadata()`](/docs/api-reference/workflow/get-workflow-metadata) — access the run ID for deterministic hook tokens
+* [`getWritable()`](/docs/api-reference/workflow/get-writable) — stream output and the stop notification to the client
+* [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — the agent that respects the abort signal via its `signal` option