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

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

@@ -2,16 +2,20 @@
 title: Publishing Libraries
 description: Structure and publish npm packages that export workflow functions for consumers to use with Workflow SDK.
 type: guide
-summary: Learn how to build, export, and test npm packages that ship workflow and step functions — including package.json exports, re-exporting for stable workflow IDs, keeping step I/O clean, and integration testing.
+summary: Learn how to build, export, and test npm packages that ship workflow and step functions, including package.json exports, re-exporting so the consumer's compiler discovers your workflows, keeping step I/O clean, and integration testing.
 ---
 
+<CopyPrompt
+  text="Package these workflow functions as a publishable npm library. Give the package a dedicated workflows entry point (for example `exports[&quot;./workflows&quot;]`) that ships the workflow and step source for the consumer's compiler to process. Keep every workflow and step input and output serializable, and read credentials from environment variables inside steps instead of accepting client instances. Document the consumer re-export requirement: consumers create a file in their `workflows/` directory containing `export * from &quot;<pkg>/workflows&quot;` so their build discovers and compiles the library's workflow and step files and replay can resolve them after cold starts. Add an integration test that runs a library workflow end to end from a consumer-style setup. Verify the build, that the library's workflows and steps show up as compiled entries, and replay safety."
+/>
+
 import { File, Folder, Files } from "fumadocs-ui/components/files";
 
 <Callout>
 This is an advanced guide for library authors who want to publish reusable workflow functions as npm packages. It assumes familiarity with `"use workflow"`, `"use step"`, and the workflow execution model.
 </Callout>
 
-## Package Structure
+## Package structure
 
 A workflow library follows a standard TypeScript package layout with a dedicated `workflows/` directory. Each workflow file exports one or more workflow functions that consumers can import and pass to `start()`.
 
@@ -40,14 +44,14 @@ A workflow library follows a standard TypeScript package layout with a dedicated
 
 Key files:
 
-- **`src/index.ts`** — Package entry point. Exports the public API.
-- **`src/types.ts`** — Shared TypeScript types.
-- **`src/workflows/index.ts`** — Re-exports every workflow so consumers can pull them in under one specifier (see [Entry Points and Exports](#entry-points-and-exports)).
-- **`src/workflows/*.ts`** — One file per workflow function (e.g. `transcode.ts`, `generate-thumbnails.ts`).
-- **`src/lib/`** — Internal helpers. Plain async code, *not* marked with `"use workflow"` or `"use step"`.
-- **`test-server/workflows.ts`** — Re-export file used by integration tests (see [Testing Workflow Libraries](#testing-workflow-libraries)).
+- **`src/index.ts`**: Package entry point that exports the public API.
+- **`src/types.ts`**: Shared TypeScript types.
+- **`src/workflows/index.ts`**: Re-exports every workflow so consumers can pull them in under one specifier (see [Entry points and exports](#entry-points-and-exports)).
+- **`src/workflows/*.ts`**: One file per workflow function (for example, `transcode.ts` or `generate-thumbnails.ts`).
+- **`src/lib/`**: Internal helpers with plain async code that is not marked with `"use workflow"` or `"use step"`.
+- **`test-server/workflows.ts`**: Re-export file used by integration tests (see [Test workflow libraries](#test-workflow-libraries)).
 
-### Entry Points and Exports
+### Entry points and exports
 
 Use the `exports` field in `package.json` to expose separate entry points for the main API and the raw workflow functions:
 
@@ -71,7 +75,7 @@ Use the `exports` field in `package.json` to expose separate entry points for th
 
 The main entry point (`@acme/media`) exports types, utilities, and convenience wrappers. The `./workflows` entry point (`@acme/media/workflows`) exports the raw workflow functions that consumers need for the build system.
 
-### Source Files
+### Source files
 
 The package entry re-exports workflows alongside any utilities:
 
@@ -89,7 +93,7 @@ export * from "./transcode";
 export * from "./generate-thumbnails";
 ```
 
-### Build Configuration
+### Build configuration
 
 Use a bundler like `tsup` with separate entry points for each export. Mark `workflow` as external so it's resolved from the consumer's project:
 
@@ -110,39 +114,43 @@ export default defineConfig({
 });
 ```
 
-## Re-Exporting for Workflow ID Stability
+## Re-exporting for compiler discovery
 
-Workflow SDK's compiler assigns each workflow function a stable ID based on its position in the source file that the build system processes. When a consumer imports a pre-built workflow from an npm package, the compiler never sees the original source — it only sees the compiled output. This means workflow IDs won't match between the library's development environment and the consumer's app.
+The workflow compiler only transforms files it discovers, and discovery starts from the consumer's `workflows/` directory and follows imports out from there. A library's workflow functions are not on that graph by default, so nothing compiles them and the runtime has no definition to run.
 
-The fix is a **re-export file**. The consumer creates a file in their `workflows/` directory that re-exports the library's workflows. The build system then processes this file and assigns stable IDs.
+The fix is a **re-export file**. The consumer creates a file in their `workflows/` directory that re-exports the library's workflows, which pulls the library's source onto the discovery graph and gives its entry point an address the runtime can resolve.
 
-### Consumer Setup
+### Consumer setup
 
 ```typescript lineNumbers
 // workflows/media.ts (in the consumer's project)
-// Re-export library workflows so the build system assigns stable IDs
+// Re-export library workflows so the compiler discovers and transforms them
 export * from "@acme/media/workflows"; // [!code highlight]
 ```
 
-This one-line file is all that's needed. The workflow compiler transforms this file, discovers the workflow and step functions from the library, and assigns IDs that are stable across deployments.
+This one-line file is all that's needed. The compiler follows the re-export into the package, transforms the workflow and step functions it finds, and registers them under IDs the runtime can resolve.
+
+### Why this is necessary
+
+Without re-exporting, the workflow runtime cannot match a running workflow to its function definition. When a run is replayed after a cold start, the runtime looks up functions by their compiler-assigned IDs. If those functions were never compiled, the IDs don't exist and replay fails.
 
-### Why This Is Necessary
+Point the re-export at the package's dedicated workflows entry point rather than a deep path into `dist/`. Files reachable through the package's `exports` map get an ID of the form `name/subpath@version`; a deep, non-exported file falls back to a path-based ID instead.
 
-Without re-exporting, the workflow runtime cannot match a running workflow to its function definition. When a workflow run is replayed after a cold start, the runtime looks up functions by their compiler-assigned IDs. If the IDs don't exist (because the compiler never processed the library's source), replay fails.
+<Callout type="info">
+**IDs for code you ship embed your package version.** A step in `@acme/media` version `1.4.0` gets the ID `step//@acme/media/workflows@1.4.0//transcode`, so publishing `1.5.0` renames every workflow and step the package ships.
 
-The re-export pattern ensures:
+That is safe on worlds with deployment pinning, such as Vercel, because runs are pinned to the deployment that started them. A run records its deployment ID and every resume targets that same deployment, so after a consumer upgrades, new runs execute the new version while runs already in flight keep replaying against the old one. Consumers do not need to drain anything before upgrading.
 
-1. **Stable IDs** — the compiler assigns IDs based on the consumer's source tree
-2. **Replay safety** — IDs persist across deployments and cold starts
-3. **Version upgrades** — re-exported IDs remain stable as long as the consumer's file doesn't change
+The re-export file does not change any of this. An ID is derived from where the file lives, not from how it was imported, so a package file keeps its `name@version` ID whether or not a consumer re-exports it.
+</Callout>
 
-## Keeping Step I/O Clean
+## Keeping step I/O clean
 
 When you publish a workflow library, every step function's inputs and outputs are recorded in the event log. This has two implications:
 
-### 1. Everything Must Be Serializable
+### 1. Everything must be serializable
 
-Step inputs and outputs must be serializable. The workflow runtime supports a rich set of types beyond plain JSON — including `Date`, `RegExp`, `Map`, `Set`, `BigInt`, `Uint8Array`, `URL`, `Error`, and class instances that implement [custom class serialization](/docs/foundations/serialization#custom-class-serialization). See the [serialization reference](/docs/foundations/serialization) for the full list of supported types. Do not pass or return:
+Step inputs and outputs must be serializable. The workflow runtime supports a rich set of types beyond plain JSON, including `Date`, `RegExp`, `Map`, `Set`, `BigInt`, `Uint8Array`, `URL`, `Error`, and class instances that implement [custom class serialization](/docs/foundations/serialization#custom-class-serialization). See the [serialization reference](/docs/foundations/serialization) for the full list of supported types. Do not pass or return:
 
 - Functions or closures
 - `WeakRef`, `WeakMap`, or `WeakSet`
@@ -161,7 +169,7 @@ async function callExternalApi(endpoint: string, params: Record<string, string>)
 // Bad: pass a pre-constructed client object
 async function callExternalApi(client: ApiClient, params: Record<string, string>) {
   "use step";
-  // ApiClient is not serializable — this will fail on replay
+  // ApiClient is not serializable, so this will fail on replay
   return await client.request(params);
 }
 ```
@@ -191,13 +199,13 @@ async function fetchData(apiKey: string, query: string) {
 
 The choice is a matter of library API design preference. Resolving from environment variables keeps the step signature simpler, while passing credentials explicitly makes dependencies visible and can be easier to test.
 
-## Testing Workflow Libraries
+## Testing workflow libraries
 
-Library authors need integration tests that exercise workflows through the full Workflow SDK runtime — not just unit tests of individual functions.
+Library authors need integration tests that exercise workflows through the full Workflow SDK runtime, rather than only unit tests of individual functions.
 
-### Test Server Pattern
+### Test server pattern
 
-Create a minimal test server that re-exports your library's workflows, just like a consumer would:
+Create a minimal test server that re-exports your library's workflows, like a consumer would:
 
 ```typescript lineNumbers
 // test-server/workflows.ts
@@ -206,7 +214,7 @@ export * from "@acme/media/workflows"; // [!code highlight]
 
 This test server acts as a stand-in consumer app. Point your test runner at it to exercise the full workflow lifecycle: start, replay, and completion.
 
-### Vitest Configuration
+### Vitest configuration
 
 Use a dedicated Vitest config for integration tests that run against the Workflow SDK runtime:
 
@@ -233,22 +241,22 @@ pnpm vitest run tests/unit
 pnpm vitest run --config vitest.workflowsdk.config.ts
 ```
 
-### What to Test
+### What to test
 
-- **Happy path**: workflow starts, all steps execute, and the final result is correct
-- **Serialization round-trip**: inputs and outputs survive the event log
-- **Replay**: kill and restart a workflow mid-execution to verify deterministic replay
-- **Error handling**: verify that step failures produce the expected errors
+- **Happy path**: The workflow starts, all steps execute, and the final result is correct.
+- **Serialization round-trip**: Inputs and outputs survive the event log.
+- **Replay**: Stop and restart a workflow during execution to verify deterministic replay.
+- **Error handling**: Step failures produce the expected errors.
 
-## Working With and Without Workflow Installed
+## Working with and without Workflow installed
 
-Some libraries want to be useful to consumers who *aren't* using Workflow SDK at all — the library picks up durable behavior when a workflow runtime is present and falls back to plain async execution otherwise.
+Some libraries need to support consumers who *aren't* using Workflow SDK. The library gains durable behavior when a workflow runtime is present and falls back to plain async execution otherwise.
 
 <Callout type="info">
 Two rules for isomorphic packages:
 
-1. **Any runtime reference to the `workflow` package must be loaded via dynamic `import("workflow")` inside a try/catch.** A static top-level import makes the module fail to load for consumers who haven't installed workflow.
-2. **The `"use workflow"` and `"use step"` directives are safe to keep in your library source.** When a consumer compiles your code with the Workflow SDK toolchain (via the [re-export pattern](#re-exporting-for-workflow-id-stability) above), the SWC plugin transforms them into durable-execution glue. When they're not compiled — plain Node, plain tests, a consumer without the runtime — they are just string expression statements and run as no-ops.
+1. **Load any runtime reference to the `workflow` package through dynamic `import("workflow")` inside a try/catch.** A static top-level import makes the module fail to load for consumers who haven't installed Workflow.
+2. **Keep the `"use workflow"` and `"use step"` directives in your library source.** When a consumer compiles your code with the Workflow SDK toolchain (via the [re-export pattern](#re-export-for-compiler-discovery) above), the SWC plugin transforms the directives into durable-execution glue. When the directives aren't compiled (plain Node.js, plain tests, or a consumer without the runtime), they are string expression statements and run as no-ops.
 </Callout>
 
 ### Optional peer dependency
@@ -270,14 +278,14 @@ Declare `workflow` as an **optional** peer so consumers without the runtime aren
 
 ### Runtime detection
 
-Wrap a dynamic `import("workflow")` in try/catch. If either the module isn't installed *or* `getWorkflowMetadata()` throws (call site isn't inside a workflow run), fall through to the standalone path.
+Wrap a dynamic `import("workflow")` in try/catch. If either the module isn't installed *or* `getStepMetadata()` throws (call site isn't inside a workflow step), fall through to the standalone path.
 
 ```typescript lineNumbers
-async function getWorkflowRunId(): Promise<string | null> { // [!code highlight]
+async function getWorkflowStepId(): Promise<string | null> { // [!code highlight]
   try {
     const wf = await import("workflow");
-    const { workflowRunId } = wf.getWorkflowMetadata();
-    return workflowRunId;
+    const { stepId } = wf.getStepMetadata();
+    return stepId;
   } catch {
     return null;
   }
@@ -286,13 +294,14 @@ async function getWorkflowRunId(): Promise<string | null> { // [!code highlight]
 
 ### A concrete use case: replay-safe idempotency keys
 
-A payments utility that uses the workflow run ID as a Stripe idempotency key when available, and a fresh UUID otherwise:
+A payments utility can use the current workflow step ID as a Stripe idempotency key when available and a fresh universally unique identifier (UUID) otherwise:
 
-{/* @skip-typecheck - depends on getWorkflowRunId defined in the previous block */}
 ```typescript lineNumbers
+declare function getWorkflowStepId(): Promise<string | null>; // @setup (defined in the previous block)
+
 export async function processPayment(amount: number, currency: string) {
-  const runId = await getWorkflowRunId();
-  const idempotencyKey = runId ?? crypto.randomUUID(); // [!code highlight]
+  const stepId = await getWorkflowStepId();
+  const idempotencyKey = stepId ? `payment:${stepId}` : crypto.randomUUID(); // [!code highlight]
 
   const res = await fetch("https://api.stripe.com/v1/charges", {
     method: "POST",
@@ -306,14 +315,14 @@ export async function processPayment(amount: number, currency: string) {
 }
 ```
 
-When called from inside a workflow run, the step wrapping this utility gets a stable idempotency key across replays — Stripe dedupes retries for free. When called from a plain Node.js process, it behaves like any other function and a fresh UUID is generated.
+When called from inside a workflow step, the utility gets a stable idempotency key for that step across retries, so Stripe deduplicates retries. When called from a plain Node.js process, it behaves like any other function and generates a fresh UUID. For more patterns, see [Idempotency](/docs/foundations/idempotency).
 
 ### In production
 
 Packages in the wild built on Workflow SDK:
 
-- **[`@mux/ai`](https://github.com/muxinc/ai)** — Reusable video AI workflows (summaries, chapters, content moderation, translation, embeddings) exported with `"use workflow"` / `"use step"` directives. In a standard Node environment the directives are no-ops and the SDK runs as a plain async library; in a Workflow SDK environment the consumer's compiler transforms them into durable, resumable steps with automatic retries and observability. Written up in detail in [*How Mux shipped durable video workflows with their @mux/ai SDK*](https://vercel.com/blog/how-mux-shipped-durable-video-workflows-with-their-mux-ai-sdk) on the Vercel blog.
-- **World ID** — Human-in-the-loop "proof of human" primitive for agent workflows. Developers drop a World ID step into any workflow to require a zero-knowledge cryptographic proof that a real, unique human authorized a specific action (deploy approvals, large payments, sensitive data access, etc.). Because it runs as a workflow step, every verification is durable, replay-safe, and viewable inside the run's execution timeline — giving you a provable audit record of which human approved what. Available on npm and announced in [*World ID for agents: Browserbase, Exa, Okta, and Vercel*](https://world.org/blog/announcements/browserbase-exa-okta-world-id-for-agentic-web) on the World blog.
+- **[`@mux/ai`](https://github.com/muxinc/ai)**: Reusable video AI workflows (summaries, chapters, content moderation, translation, embeddings) exported with `"use workflow"` / `"use step"` directives. In a standard Node environment the directives are no-ops and the SDK runs as a plain async library; in a Workflow SDK environment the consumer's compiler transforms them into durable, resumable steps with automatic retries and observability. Written up in detail in [*How Mux shipped durable video workflows with their @mux/ai SDK*](https://vercel.com/blog/how-mux-shipped-durable-video-workflows-with-their-mux-ai-sdk) on the Vercel blog.
+- **World ID**: Human-in-the-loop "proof of human" primitive for agent workflows. Developers drop a World ID step into any workflow to require a zero-knowledge cryptographic proof that a real, unique human authorized a specific action (deploy approvals, large payments, sensitive data access, etc.). Because it runs as a workflow step, every verification is durable, replay-safe, and viewable inside the run's execution timeline, giving you a provable audit record of which human approved what. Available on npm and announced in [*World ID for agents: Browserbase, Exa, Okta, and Vercel*](https://world.org/blog/announcements/browserbase-exa-okta-world-id-for-agentic-web) on the World blog.
 
 ## Checklist
 
@@ -330,7 +339,7 @@ Before publishing a workflow library:
 
 ## Key APIs
 
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
-- [`"use step"`](/docs/api-reference/workflow/use-step) — marks functions for durable execution
-- [`start`](/docs/api-reference/workflow/start) — starts a workflow run
-- [`getWorkflowMetadata`](/docs/api-reference/workflow/get-workflow-metadata) — runtime detection and run ID access
+- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions): Declares the orchestrator function.
+- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions): Marks functions for durable execution.
+- [`start`](/docs/api-reference/workflow-api/start): Starts a workflow run.
+- [`getWorkflowMetadata`](/docs/api-reference/workflow/get-workflow-metadata): Provides runtime detection and run ID access.

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

@@ -1,14 +1,18 @@
 ---
 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
-  - /docs/api-reference/workflow/use-step
+  - /docs/foundations/workflows-and-steps#step-functions
 ---
 
+<CopyPrompt
+  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>
 This is an advanced guide. It dives into workflow internals and is not required reading to use workflow.
 </Callout>
@@ -17,94 +21,69 @@ 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 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 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
+## 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";
+import { S3Client } from "@aws-sdk/client-s3";
 
-export async function brokenAgent(prompt: string) {
-  "use workflow";
+async function uploadFile(client: S3Client, key: string) {
+  "use step";
+  // ... upload with client ...
+}
 
-  const writable = getWritable<UIMessageChunk>();
-  const agent = new DurableAgent({
-    // This fails — the model object is not serializable
-    model: openai("gpt-4o"),
-  });
+export async function brokenUpload(region: string, key: string) {
+  "use workflow";
 
-  await agent.stream({ messages: [{ role: "user", content: prompt }], writable });
+  const client = new S3Client({ region });
+  await uploadFile(client, key); // Fails: S3Client is not serializable
 }
 ```
 
-## The Solution: Step-as-Factory
+## 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 just 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";
-
-// Returns a step function, not a model object
-export function openai(...args: Parameters<typeof openaiProvider>) {
-  return async () => {
-    "use step";
-    return openaiProvider(...args); // [!code highlight]
-  };
-}
-```
+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**.
 
-The `DurableAgent` receives a function (`() => Promise<LanguageModel>`) instead of a model object. When the agent needs to call the LLM, it invokes the factory inside a step where the real provider can be constructed with full Node.js access.
+<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>
 
-## How `@workflow/ai` Uses This
+### AI provider example
 
-The `@workflow/ai` package ships pre-wrapped providers for all major AI SDK backends. Each one follows the same pattern:
+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 — serializable
+// The region is a plain string, which is serializable
 export function createS3Client(region: string) {
   return async (): Promise<S3ClientType> => {
     "use step";
@@ -133,15 +112,16 @@ async function uploadFile(
 }
 ```
 
-## Why This Works
+## Why this works
 
-1. **Compiler transformation**: `"use step"` tells the SWC plugin to extract the function into a separate bundle. The workflow VM only sees a serializable reference (function ID + captured arguments).
-2. **Closure tracking**: The compiler tracks which variables the step function closes over. Only serializable values (strings, numbers, plain objects) can be captured.
-3. **Deferred construction**: The actual provider/client is only constructed when the step executes in the Node.js runtime — never in the sandboxed workflow VM.
+1. **Compiler transformation**: `"use step"` tells the SWC plugin to extract the function into a separate bundle. The workflow VM only sees a serializable reference (function ID and captured arguments).
+2. **Closure tracking**: The compiler tracks which variables the step function closes over. The function can capture only serializable values, such as strings, numbers, and plain objects.
+3. **Deferred construction**: The step constructs the provider or client only when it executes in the Node.js runtime, never in the sandboxed workflow VM.
 
 ## Key APIs
 
-- [`"use step"`](/docs/api-reference/workflow/use-step) — marks a function for extraction and serialization
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
-- [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — accepts a model factory for durable AI agent streaming
-- [Custom class serialization](/docs/foundations/serialization#custom-class-serialization) — the companion pattern for classes you own (`WORKFLOW_SERIALIZE` / `WORKFLOW_DESERIALIZE`)
+- [`"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`).