workflow 5.0.0-beta.8 → 5.0.0

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

@@ -1,46 +1,59 @@
 ---
 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.
+description: Cancel a running WorkflowAgent from the outside using AbortSignal and a durable stop hook.
 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.
+summary: Cancel a running WorkflowAgent cooperatively with AbortController so the model stream stops and the workflow can return a clean status.
 ---
 
-Cancel a running agent from the outside — for example, a "Stop" button in a chat UI, an admin cancellation endpoint, or a timeout fallback.
+<CopyPrompt
+  text="Add cancellation to this AI SDK WorkflowAgent. For hard cancellation, expose a server route that receives `runId` and calls `getRun(runId).cancel()` from `workflow/api`. For graceful cancellation, define `stopHook` with `defineHook()` from `workflow`, create it with a stable token such as the workflow run ID, and race `WorkflowAgent.stream()` against the stop hook using `Promise.race`. Pass an `AbortController` signal to the agent, forward the tool execution signal to cancellable I/O, and wait for the agent branch to settle after aborting before returning a stopped status. Wire the UI Stop button to the route that resumes the hook or falls back to `getRun(runId).cancel()`, and verify stale run IDs are handled."
+/>
+
+Cancel a running agent from the outside through a **Stop** button in a chat user interface (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.
+Create an `AbortController` in the workflow and race the agent (passing its signal) against a stop hook. When the hook fires, call `controller.abort()`, then wait for the agent branch to observe the signal and settle before the workflow returns. The signal cancels the underlying model stream and is passed to tool execution; each tool must forward it to cancellable I/O. The workflow return value records whether it completed or stopped; read that value through the run API or persist it in application state.
 
+{/* @skip-typecheck: requires AI SDK 7 and @ai-sdk/workflow */}
 ```typescript lineNumbers
-import { DurableAgent } from "@workflow/ai/agent";
+import { WorkflowAgent, type ModelCallStreamPart } from "@ai-sdk/workflow";
+import {
+  isStepCount,
+  tool,
+  type ModelMessage,
+  type ToolExecutionOptions,
+} from "ai";
 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 }) {
+async function searchWeb(
+  { query }: { query: string },
+  { abortSignal }: ToolExecutionOptions<unknown>,
+) {
   "use step";
-  await new Promise((r) => setTimeout(r, 1200));
-  return { summary: `Analysis of ${topic}: significant developments found.`, confidence: 0.85 };
+  const response = await fetch(
+    `https://api.example.com/search?q=${encodeURIComponent(query)}`,
+    { signal: abortSignal }, // [!code highlight]
+  );
+  return response.json();
 }
 
-async function emitStopSignal(details: { reason?: string }) {
+async function analyzeData(
+  { topic }: { topic: string },
+  { abortSignal }: ToolExecutionOptions<unknown>,
+) {
   "use step";
-  const writer = getWritable<UIMessageChunk>().getWriter();
-  try {
-    await writer.write({ type: "data-stopped", id: "stop-signal", data: details } as UIMessageChunk);
-  } finally {
-    writer.releaseLock();
-  }
+  const response = await fetch("https://api.example.com/analyze", {
+    method: "POST",
+    body: JSON.stringify({ topic }),
+    signal: abortSignal, // [!code highlight]
+  });
+  return response.json();
 }
 
 export async function stoppableAgent(messages: ModelMessage[]) {
@@ -50,47 +63,52 @@ export async function stoppableAgent(messages: ModelMessage[]) {
   const controller = new AbortController(); // [!code highlight]
   const hook = stopHook.create({ token: `stop:${workflowRunId}` });
 
-  const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+  const agent = new WorkflowAgent({
+    model: "spacexai/grok-4.6",
     instructions: "You are a research assistant. Search and analyze data as needed.",
     tools: {
-      searchWeb: {
+      searchWeb: tool({
         description: "Search the web for information",
         inputSchema: z.object({ query: z.string() }),
         execute: searchWeb,
-      },
-      analyzeData: {
+      }),
+      analyzeData: tool({
         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 };
-    }),
+  const agentPromise = agent.stream({
+    messages,
+    writable: getWritable<ModelCallStreamPart>(),
+    abortSignal: controller.signal, // [!code highlight]
+    stopWhen: isStepCount(15),
+  });
+
+  const outcome = await Promise.race([
+    agentPromise.then((result) => ({
+      type: "complete" as const,
+      messages: result.messages,
+    })),
+    hook.then(({ reason }) => ({
+      type: "stop-requested" as const,
+      reason,
+    })),
   ]);
 
-  if (result.type === "stopped") {
-    await emitStopSignal({ reason: result.reason });
+  if (outcome.type === "stop-requested") {
+    controller.abort(outcome.reason); // [!code highlight]
+    await agentPromise; // Wait until the losing branch has stopped. // [!code highlight]
+    return { type: "stopped" as const, reason: outcome.reason };
   }
 
-  return result;
+  return outcome;
 }
 ```
 
-### API Route to Trigger Stop
+### API route to trigger stop
 
 ```typescript lineNumbers
 import { stopHook } from "@/workflows/stoppable-agent";
@@ -110,7 +128,7 @@ export async function POST(
 }
 ```
 
-### Client Stop Button
+### Client stop button
 
 ```tsx lineNumbers
 "use client";
@@ -134,23 +152,23 @@ export function StopButton({ runId }: { runId: string }) {
 
 ## 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
+1. The workflow creates an `AbortController` when it starts.
+2. The workflow creates a hook with the token `stop:${workflowRunId}`.
+3. `Promise.race` runs the agent stream and the stop hook concurrently.
+4. The agent receives `controller.signal`. When aborted, the signal cancels the active model stream, propagates to tool execution, and prevents another model step from starting. Tool implementations must forward it to operations such as `fetch` that support cancellation.
+5. When the stop API resumes the hook, the race reports a stop request. The workflow aborts the controller and awaits `agentPromise`, so it does not return while that branch is still running.
+6. After the agent branch settles, the workflow returns a `stopped` result. That return value is not written to the model-call stream automatically; the application can read `run.returnValue` or persist the status separately.
 
 ## 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
+- **Add a timeout**: Race a third `sleep()` promise to stop automatically after a deadline.
+- **Audit logging**: Include a `reason` field in the stop schema to record who stopped the agent and why.
+- **Cross-process**: The hook token is deterministic, so any process can call `stopHook.resume()` with the run ID.
+- **Step limits**: Combine the pattern with `stopWhen: isStepCount(...)` to cap execution without a 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
+- [`defineHook()`](/docs/api-reference/workflow/define-hook): Defines a type-safe hook for the stop signal.
+- [`getWorkflowMetadata()`](/docs/api-reference/workflow/get-workflow-metadata): Provides the run ID for deterministic hook tokens.
+- [`getWritable()`](/docs/api-reference/workflow/get-writable): Stores durable model-call output from the agent.
+- [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent): AI SDK's durable agent that applies the abort signal to model calls and replaces `DurableAgent`.

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

@@ -1,154 +1,42 @@
 ---
-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 durable agents in Workflow 5. It replaces `DurableAgent` and keeps the current agent pattern in the AI SDK package.
 
-<Callout type="info">
-A durable agent run stays on the deployment that started it. For multi-turn agents that should pick up newer code between turns, see [Versioning](/docs/foundations/versioning) for patterns that start the next turn or next session run with `deploymentId: "latest"`.
-</Callout>
-
-## Pattern
-
-Replace `Agent` with `DurableAgent`, wrap the function in `"use workflow"`, mark each tool with `"use step"`, and stream output through `getWritable()`.
-
-### Workflow
+- Import `WorkflowAgent` from `@ai-sdk/workflow` and run it inside a `"use workflow"` function.
+- Pass `"spacexai/grok-4.6"` as a plain model string so AI SDK routes requests through Vercel AI Gateway.
+- 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.
 
 ```typescript
-import { DurableAgent } from "@workflow/ai/agent";
+import { WorkflowAgent, type ModelCallStreamPart } from "@ai-sdk/workflow";
 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[]) {
+export async function agentWorkflow(prompt: string) {
   "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 agent = new WorkflowAgent({
+    model: "spacexai/grok-4.6",
+    instructions: "You are a helpful assistant.",
   });
 
-  const result = await agent.stream({ // [!code highlight]
-    messages,
-    writable: getWritable<UIMessageChunk>(), // [!code highlight]
-    maxSteps: 10,
+  return agent.stream({
+    messages: [{ role: "user", content: prompt }],
+    writable: getWritable<ModelCallStreamPart>(),
   });
-
-  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>