workflow 5.0.0-beta.5 → 5.0.0-beta.51

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

@@ -0,0 +1,199 @@
+---
+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
+---
+
+<CopyPrompt
+  text="Add a safe self-upgrade point to this long-running workflow. Identify the loop boundary where no step is mid-side-effect. Define a serializable state object that contains all progress needed to continue. At the boundary, call `start(self, [state], { deploymentId: &quot;latest&quot; })` or the documented replacement workflow with the carried state, then return from the old run. If upgrades should be manual, add a `defineHook()` upgrade signal and resume it from an API route with `resumeHook()` from `workflow/api`. Make the handoff idempotent so retries do not start duplicate successor runs, and verify old-to-new handoff plus duplicate prevention."
+/>
+
+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.
+- The workflow can create a checkpoint 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. This method needs no extra triggers, but every event incurs the respawn cost.
+2. **Upgrade on demand through 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 respawns only when an `upgradeHook` fires. A separate endpoint resumes that hook from your control plane, for example, after a deployment. This method provides more control and fewer respawns at the cost of an explicit trigger.
+
+### When to use each
+
+- **Use Method 1** when iterations are short and frequent, the work is inexpensive to checkpoint, and you want shipped fixes to apply on the next event. Long-lived session workflows, such as subscriptions, queues, and finite-state machines (FSMs), that already process events one at a time fit this method.
+- **Use Method 2** when iterations are infrequent or expensive, or when you need to roll out a fix to a fleet of in-flight runs after a deployment by fanning out to a control-plane endpoint. This method also fits when an 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`, such as in a database 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 deployment 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 deployment, list active runs from a tracking store and call this endpoint for each run.
+
+## 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, so 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 only 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.
+- **Use stateless successors**: If the next iteration doesn't need the previous state, such as for 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 for dashboards, debugging, or recovery, write it to a database in a step before spawning the next run.
+- **Track the active `runId` externally**: The system that resumes the hook needs to know the current run. Capture the `runId` returned by `start()` and write it to a database keyed by a stable session identifier in a step, so resumers always look up the latest run.
+
+## Caveats
+
+- **Maintain backward compatibility**: 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).
+- **Keep the workflow identity stable**: The function name and file path form the workflow identity. Renaming the function or moving the file across a deployment changes the workflow ID, so the next iteration will fail to resolve.
+- **Account for the gap between iterations**: The current run ends as soon as `start()` returns, and 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.
+- **Track active Method 2 runs externally**: Because Method 2's runs are long-lived, the set of in-flight runs changes only 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`, update the tracked run ID once the new run reports back, as 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): Spawns the successor on the newest deployment.
+- [`defineHook()`](/docs/api-reference/workflow/define-hook): Suspends 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

@@ -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,150 +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.
 
-## 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 { 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,
-    },
+  return agent.stream({
+    messages: [{ role: "user", content: prompt }],
+    writable: getWritable<ModelCallStreamPart>(),
   });
 }
 ```
 
-## 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>