workflow 5.0.0-beta.50 → 5.0.0-beta.52

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

@@ -1,8 +1,8 @@
 ---
 title: Serializable Steps
-description: Wrap non-serializable third-party objects (like AI model providers) inside step factory functions so they can cross the workflow boundary.
+description: Wrap non-serializable third-party objects, including AI provider models and cloud clients, inside step factory functions.
 type: guide
-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.
+summary: Defer construction of non-owned AI provider models and cloud SDK clients until step execution so they remain usable in durable workflows.
 related:
   - /docs/foundations/serialization
   - /docs/foundations/serialization#custom-class-serialization
@@ -10,7 +10,7 @@ related:
 ---
 
 <CopyPrompt
-  text="Make this non-serializable dependency usable inside a durable workflow with the step-as-factory pattern. Instead of passing the object (AI SDK model, cloud SDK client) into the workflow, export a factory that returns an async callback marked with &quot;use step&quot; which constructs and returns the object at execution time, for example `export function openai(...args) { return async () => { &quot;use step&quot;; return openaiProvider(...args); }; }`. Pass the factory across the workflow boundary (the compiler serializes the function reference, not the instance) and invoke it inside steps where full Node.js access is available. Keep the factory's constructor arguments serializable. Verify the workflow builds, replays deterministically, and the dependency is only instantiated during step execution."
+  text="Make this non-serializable dependency usable inside a durable workflow with the step-as-factory pattern. Instead of passing an AI provider model, cloud SDK client, or other class instance into the workflow, export a factory that returns an async callback marked with &quot;use step&quot;. Capture only serializable constructor options, construct the provider or client inside the step, and keep the instance inside that step's execution. Verify the workflow builds, replays deterministically, and never serializes the live dependency."
 />
 
 <Callout>
@@ -22,97 +22,68 @@ This is an advanced guide. It dives into workflow internals and is not required
 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.
+- **You don't own the class**: you can't add serialization methods to `openai("gpt-5.6-sol")` from `@ai-sdk/openai` or `new S3Client({...})` from `@aws-sdk/client-s3`. Instead, wrap construction and use in a `"use step"` factory function. That's what this page covers.
 
 ## The problem
 
-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.
+AI SDK provider models and cloud SDK clients often contain methods, closures, sockets, and internal state. Passing one across a workflow boundary causes a serialization error, and you can't add `WORKFLOW_SERIALIZE` to a class you don't own.
 
 ```typescript lineNumbers
-import { openai } from "@ai-sdk/openai";
-import { DurableAgent } from "@workflow/ai/agent";
-import { getWritable } from "workflow";
-import type { UIMessageChunk } from "ai";
-
-export async function brokenAgent(prompt: string) {
-  "use workflow";
+import { S3Client } from "@aws-sdk/client-s3";
 
-  const writable = getWritable<UIMessageChunk>();
-  const agent = new DurableAgent({
-    // This fails: the model object is not serializable
-    model: openai("gpt-4o"),
-  });
-
-  await agent.stream({ messages: [{ role: "user", content: prompt }], writable });
+async function uploadFile(client: S3Client, key: string) {
+  "use step";
+  // ... upload with client ...
 }
-```
 
-## The solution: step-as-factory
-
-Instead of passing the model object, pass a **callback function** that returns the model. Marking that callback with `"use step"` tells the compiler to serialize the *function reference* (which is a string identifier) rather than its return value. The provider is only instantiated at execution time, inside the step's full Node.js runtime.
-
-```typescript lineNumbers
-import { openai as openaiProvider } from "@ai-sdk/openai";
+export async function brokenUpload(region: string, key: string) {
+  "use workflow";
 
-// Returns a step function, not a model object
-export function openai(...args: Parameters<typeof openaiProvider>) {
-  return async () => {
-    "use step";
-    return openaiProvider(...args); // [!code highlight]
-  };
+  const client = new S3Client({ region });
+  await uploadFile(client, key); // Fails: S3Client is not serializable
 }
 ```
 
-The `DurableAgent` receives a function (`() => Promise<LanguageModel>`) instead of a model object. When the agent needs to call the large language model (LLM), it invokes the factory inside a step where the real provider can be constructed with full Node.js access.
+## The solution: step-as-factory
 
-## How `@workflow/ai` uses this
+Apply the same pattern to any non-serializable dependency. The key rule: **the outer function captures serializable arguments, and the inner `"use step"` function constructs the real object at runtime**.
 
-<Callout type="warn">
-`@workflow/ai`'s pre-wrapped providers and `DurableAgent` are deprecated. AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) resolves models from AI Gateway model strings (for example, `"openai/gpt-4o"`), which usually removes the need for a model factory; see the [migration guide](https://ai-sdk.dev/v7/docs/agents/workflow-agent#migrating-from-durableagent). The serialization pattern on this page still applies to any non-serializable dependency you own (for example, cloud SDK clients).
+<Callout type="info">
+A plain Vercel AI Gateway model string such as `"spacexai/grok-4.6"` is already serializable and does not need a factory.
 </Callout>
 
-The `@workflow/ai` package ships pre-wrapped providers for all major AI SDK backends. Each one follows the same pattern:
+### AI provider example
+
+When using an AI SDK provider package, construct and use its model inside the step. The outer factory captures only the serializable model ID:
 
 ```typescript lineNumbers
-// packages/ai/src/providers/anthropic.ts
-import { anthropic as anthropicProvider } from "@ai-sdk/anthropic";
+import { openai } from "@ai-sdk/openai";
+import { generateText } from "ai";
 
-export function anthropic(...args: Parameters<typeof anthropicProvider>) {
-  return async () => {
+export function createOpenAIGenerator(modelId: string) {
+  return async (prompt: string) => {
     "use step";
-    return anthropicProvider(...args); // [!code highlight]
+    const { text } = await generateText({ model: openai(modelId), prompt });
+    return text;
   };
 }
-```
 
-This means you import from `@workflow/ai` instead of `@ai-sdk/*` directly:
-
-```typescript lineNumbers
-import { anthropic } from "@workflow/ai/anthropic";
-import { DurableAgent } from "@workflow/ai/agent";
-import { getWritable } from "workflow";
-import type { UIMessageChunk } from "ai";
-
-export async function chatAgent(prompt: string) {
+export async function summarize(prompt: string) {
   "use workflow";
 
-  const writable = getWritable<UIMessageChunk>();
-  const agent = new DurableAgent({
-    model: anthropic("claude-sonnet-4-20250514"), // [!code highlight]
-  });
-
-  await agent.stream({ messages: [{ role: "user", content: prompt }], writable });
+  const generate = createOpenAIGenerator("gpt-5.6-sol");
+  return generate(prompt);
 }
 ```
 
-## Writing your own serializable wrapper
+The same structure works with provider packages such as `@ai-sdk/anthropic` and `@ai-sdk/google`: capture serializable configuration in the outer function and keep the provider object inside the step. For durable agent loops, continue to use `WorkflowAgent`; the factory pattern is for lower-level AI SDK calls and other third-party dependencies.
 
-Apply the same pattern to any non-serializable dependency. The key rule: **the outer function captures serializable arguments, and the inner `"use step"` function constructs the real object at runtime**.
+### Cloud client example
 
 ```typescript lineNumbers
 import type { S3Client as S3ClientType } from "@aws-sdk/client-s3";
 
-// The arguments (region, bucket) are plain strings, which are serializable
+// The region is a plain string, which is serializable
 export function createS3Client(region: string) {
   return async (): Promise<S3ClientType> => {
     "use step";
@@ -152,4 +123,5 @@ async function uploadFile(
 - [`"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.
 - [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent): Provides AI SDK's durable agent, resolves models through AI Gateway strings, and replaces `DurableAgent`.
+- [AI SDK providers](https://ai-sdk.dev/providers/ai-sdk-providers): Lists direct provider packages and configuration.
 - [Custom class serialization](/docs/foundations/serialization#custom-class-serialization): Provides the companion pattern for classes you own (`WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE`).

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

@@ -1,54 +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.
 ---
 
 <CopyPrompt
-  text="Add cancellation to this durable AI agent. For hard cancellation, expose a server route that receives `runId` and calls `getRun(runId).cancel()` from `workflow/api`. For graceful stop, define `stopHook` with `defineHook()` from `workflow`, create it with a stable token such as the workflow run ID, and race the agent loop against the stop hook using `Promise.race`. Use `getWritable<UIMessageChunk>()` to emit a final stopped/canceled message before returning. Wire the UI Stop button to the route that resumes the hook or falls back to `getRun(runId).cancel()`. Verify active model/tool work stops, cleanup runs for graceful stop, and stale run IDs are handled."
+  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.
 
-<Callout type="warn">
-This recipe uses the deprecated `DurableAgent` API. For new agents, use AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) and follow the [migration guide](https://ai-sdk.dev/v7/docs/agents/workflow-agent#migrating-from-durableagent). The cancellation patterns here (`run.cancel()`, stop-signal hook + `Promise.race`, `AbortController`) apply to either API.
-</Callout>
-
 ## 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[]) {
@@ -58,43 +63,48 @@ 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;
 }
 ```
 
@@ -145,20 +155,20 @@ export function StopButton({ runId }: { runId: string }) {
 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 underlying model stream.
-5. When the stop API resumes the hook, the workflow calls `controller.abort()`, resolves the race, and exits.
-6. `emitStopSignal` writes a `data-stopped` part to the stream so the client renders a clean stop state.
+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 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 `maxSteps` on the agent to cap execution without a manual stop.
+- **Step limits**: Combine the pattern with `stopWhen: isStepCount(...)` to cap execution without a manual stop.
 
 ## Key APIs
 
 - [`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): Streams output and the stop notification to the client.
-- [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent): AI SDK's durable agent that respects the abort signal and replaces `DurableAgent`.
+- [`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

@@ -11,12 +11,32 @@ summary: Build durable, resumable AI agents with AI SDK v7's WorkflowAgent.
 
 ## WorkflowAgent from AI SDK v7
 
-Use AI SDK v7's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) for new durable agent work. It replaces `DurableAgent` and keeps the current agent pattern in the AI SDK package.
+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.
 
 - 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 { WorkflowAgent, type ModelCallStreamPart } from "@ai-sdk/workflow";
+import { getWritable } from "workflow";
+
+export async function agentWorkflow(prompt: string) {
+  "use workflow";
+
+  const agent = new WorkflowAgent({
+    model: "spacexai/grok-4.6",
+    instructions: "You are a helpful assistant.",
+  });
+
+  return agent.stream({
+    messages: [{ role: "user", content: prompt }],
+    writable: getWritable<ModelCallStreamPart>(),
+  });
+}
+```
+
 <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>