workflow 5.0.0-beta.2 → 5.0.0-beta.4

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

@@ -0,0 +1,205 @@
+---
+title: Agent Cancellation
+description: Cancel a running agent from the outside — either immediately via run.cancel() or gracefully via a stop signal hook.
+type: guide
+summary: Two patterns for cancelling a running agent — Hard Cancellation via getRun(runId).cancel() for forced termination, or Stop Signal via a hook + Promise.race for a clean exit with cleanup and final stream notification.
+---
+
+Cancel a running agent from the outside — for example, a "Stop" button in a chat UI, an admin cancellation endpoint, or a timeout fallback. Two patterns are available depending on whether you need the agent to exit cleanly or just need the run to stop: **Hard Cancellation** via `getRun(runId).cancel()` for immediate forced termination, or **Stop Signal** via a hook + `Promise.race` for a graceful exit that runs cleanup and notifies streaming clients before returning.
+
+## When to use this
+
+* **Chat stop buttons** — let users cancel a long-running agent from the browser
+* **Admin cancellation** — stop an agent from a different process or API
+* **Timeout fallback** — combine with `sleep()` to auto-stop after a deadline
+
+## Choosing an approach
+
+Pick the option that matches what your endpoint needs to deliver to the caller:
+
+* **Hard Cancellation** — terminates the run immediately with no opportunity for cleanup or client notification. A single line of code, but the workflow throws `WorkflowRunCancelledError` and any streaming clients see an abrupt connection close.
+* **Stop Signal** — the workflow exits as soon as the hook fires, runs any pending cleanup, emits a final `data-stopped` part to the stream so the client can render cleanly, and returns a real result.
+
+The trade-offs at a glance:
+
+| | Hard Cancellation | Stop Signal |
+| --- | --- | --- |
+| Mechanism | `getRun(runId).cancel()` | Hook + `Promise.race` |
+| Speed to terminate | Immediate | At the next `await` boundary in the workflow |
+| Runs `finally` / cleanup | No | Yes |
+| Final stream notification | No (abrupt close) | Yes (`data-stopped` part) |
+| `run.returnValue` | Throws `WorkflowRunCancelledError` | Returns the workflow's result |
+| Code complexity | One line | Hook + race + signal step |
+| Best for | Stuck or unresponsive runs, forced termination | User-facing stop, admin cancel, timeouts |
+
+## Hard Cancellation
+
+Call `.cancel()` on a run to terminate it immediately:
+
+```typescript lineNumbers
+import { getRun } from "workflow/api";
+
+export async function POST(
+  _request: Request,
+  { params }: { params: Promise<{ runId: string }> }
+) {
+  const { runId } = await params;
+  await getRun(runId).cancel(); // [!code highlight]
+  return Response.json({ success: true });
+}
+```
+
+This is an abrupt termination — the run is stopped mid-step with no opportunity to exit cleanly:
+
+* **No cleanup runs** — `finally` blocks, defer-style step cleanup, and any logic after the current step are all skipped
+* **No final notification to the client** — the writable closes abruptly, so a streaming UI just sees the connection drop with no `data-stopped` part to render a clean ending
+* **`run.returnValue` throws** — anyone awaiting the result receives [`WorkflowRunCancelledError`](/docs/api-reference/workflow-errors/workflow-run-cancelled-error) instead of a meaningful payload
+* **Underlying step keeps running** — same caveat as the Stop Signal pattern below: the model stream or HTTP call inside the current step continues to completion in the background
+
+Hard Cancellation is the appropriate choice when the run is stuck or unresponsive, has exceeded its expected runtime, or you don't need a clean exit. For everything else — chat stop buttons, admin "stop" actions, timeout fallbacks — you typically want the Stop Signal pattern: the agent finishes its current step, emits a final stream part so the client renders a clean ending, and returns a real result.
+
+## Stop Signal
+
+<Callout type="warn">
+**Limitation:** This pattern does not cancel the underlying model stream. The agent step writing to the writable continues running in the background until it completes — tokens generated after the stop signal are still produced (and billed by your model provider). What this pattern *does* is exit the workflow function as soon as the hook fires and emit a `data-stopped` part so the client can stop rendering. For hard cross-process cancellation that signals the inner step to bail out, see [Distributed Abort Controller](/cookbook/advanced/distributed-abort-controller).
+</Callout>
+
+### Example
+
+```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 }) { // [!code highlight]
+  "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 hook = stopHook.create({ token: `stop:${workflowRunId}` }); // [!code highlight]
+
+  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([ // [!code highlight]
+    agent
+      .stream({ messages, writable: getWritable<UIMessageChunk>(), maxSteps: 15 })
+      .then((r) => ({ type: "complete" as const, messages: r.messages })),
+    hook.then(({ reason }) => ({ type: "stopped" as const, reason })), // [!code highlight]
+  ]);
+
+  if (result.type === "stopped") {
+    await emitStopSignal({ reason: result.reason }); // [!code highlight]
+  }
+
+  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}`, { // [!code highlight]
+    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. A hook is created with token `stop:${workflowRunId}` when the workflow starts
+2. `Promise.race` runs the agent stream and the stop hook concurrently
+3. When the stop API resumes the hook, the race resolves immediately — the workflow exits
+4. Before returning, `emitStopSignal` writes a `data-stopped` part to the stream so the client knows the agent was stopped (not just disconnected)
+5. The client detects `data-stopped` and updates the UI accordingly
+
+This is the same pattern used by the [Distributed Abort Controller](/cookbook/advanced/distributed-abort-controller) — race a long-running operation against a hook signal.
+
+## 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
+* **Hard Cancellation as a fallback** — wire your stop endpoint to fall back to `getRun(runId).cancel()` if the hook resume errors with `not found` / `expired` (for example, the hook was already consumed). This guarantees the run is terminated even when the Stop Signal path is unavailable.
+
+## 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 a stop notification to the client
+* [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — the agent that gets raced against the stop hook
+* [`getRun()`](/docs/api-reference/workflow-api/get-run) — entry point for Hard Cancellation: `getRun(runId).cancel()`

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

@@ -7,116 +7,61 @@ summary: Convert an AI SDK Agent into a DurableAgent backed by a workflow, with
 
 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.
 
-## Pattern
-
-Replace `Agent` with `DurableAgent`, wrap the function in `"use workflow"`, mark each tool with `"use step"`, and stream output through `getWritable()`.
-
-### Simplified
-
-```typescript lineNumbers
-import { DurableAgent } from "@workflow/ai/agent";
-import { getWritable } from "workflow";
-import { z } from "zod";
-import type { ModelMessage, UIMessageChunk } from "ai";
+## When to use this
 
-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";
+- 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
 
-  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,
-      },
-    },
-  });
+## Pattern
 
-  await agent.stream({ // [!code highlight]
-    messages,
-    writable: getWritable<UIMessageChunk>(),
-  });
-}
-```
+Replace `Agent` with `DurableAgent`, wrap the function in `"use workflow"`, mark each tool with `"use step"`, and stream output through `getWritable()`.
 
-### Full Implementation
+### Workflow
 
-```typescript lineNumbers
+```typescript
 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,
-}: {
+async function searchFlights({ from, to, date }: {
   from: string;
   to: string;
   date: string;
 }) {
-  "use step";
-
-  const response = await fetch(
+  "use step"; // [!code highlight]
+  const res = 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();
+  if (!res.ok) throw new Error(`Search failed: ${res.status}`);
+  return res.json();
 }
 
-// Step: Book a flight — retries on transient failures
-async function bookFlight({
-  flightId,
-  passenger,
-}: {
+async function bookFlight({ flightId, passenger }: {
   flightId: string;
   passenger: string;
 }) {
-  "use step";
-
-  const response = await fetch("https://api.example.com/bookings", {
+  "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 (!response.ok) throw new Error(`Booking failed: ${response.status}`);
-  return response.json();
+  if (!res.ok) throw new Error(`Booking failed: ${res.status}`);
+  return res.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();
+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 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.",
@@ -138,19 +83,19 @@ export async function flightAgent(messages: ModelMessage[]) {
         }),
         execute: bookFlight,
       },
-      checkStatus: {
-        description: "Check the current status of a flight",
+      checkWeather: {
+        description: "Check the weather forecast for a city",
         inputSchema: z.object({
-          flightId: z.string().describe("Flight ID to check"),
+          city: z.string().describe("City name"),
         }),
-        execute: checkStatus,
+        execute: checkWeather,
       },
     },
   });
 
   const result = await agent.stream({ // [!code highlight]
     messages,
-    writable,
+    writable: getWritable<UIMessageChunk>(), // [!code highlight]
     maxSteps: 10,
   });
 
@@ -158,22 +103,21 @@ export async function flightAgent(messages: ModelMessage[]) {
 }
 ```
 
-### API Route
+### API route
 
-```typescript lineNumbers
-import { createUIMessageStreamResponse } from "ai";
-import { start } from "workflow/api";
-import { flightAgent } from "@/workflows/flight-agent";
+```typescript
 import type { UIMessage } from "ai";
-import { convertToModelMessages } 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);
+  const modelMessages = await convertToModelMessages(messages); // [!code highlight]
 
   const run = await start(flightAgent, [modelMessages]); // [!code highlight]
 
-  return createUIMessageStreamResponse({
+  return createUIMessageStreamResponse({ // [!code highlight]
     stream: run.readable,
     headers: {
       "x-workflow-run-id": run.runId,
@@ -182,6 +126,21 @@ export async function POST(req: Request) {
 }
 ```
 
+## 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