workflow 5.0.0-beta.1 → 5.0.0-beta.2

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

@@ -0,0 +1,135 @@
+---
+title: Serializable Steps
+description: Wrap non-serializable objects (like AI model providers) inside step functions so they can cross the workflow boundary.
+type: guide
+summary: Return a callback from a step to defer provider initialization, making non-serializable AI SDK models work inside durable workflows.
+---
+
+<Callout>
+This is an advanced guide. It dives into workflow internals and is not required reading to use workflow.
+</Callout>
+
+## The Problem
+
+Workflow functions run inside a sandboxed VM where every value that crosses a function boundary must be serializable (JSON-safe). 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.
+
+```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";
+
+  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 });
+}
+```
+
+## 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]
+  };
+}
+```
+
+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.
+
+## How `@workflow/ai` Uses This
+
+The `@workflow/ai` package ships pre-wrapped providers for all major AI SDK backends. Each one follows the same pattern:
+
+```typescript lineNumbers
+// packages/ai/src/providers/anthropic.ts
+import { anthropic as anthropicProvider } from "@ai-sdk/anthropic";
+
+export function anthropic(...args: Parameters<typeof anthropicProvider>) {
+  return async () => {
+    "use step";
+    return anthropicProvider(...args); // [!code highlight]
+  };
+}
+```
+
+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) {
+  "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 });
+}
+```
+
+## Writing Your Own Serializable Wrapper
+
+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**.
+
+```typescript lineNumbers
+import type { S3Client as S3ClientType } from "@aws-sdk/client-s3";
+
+// The arguments (region, bucket) are plain strings — serializable
+export function createS3Client(region: string) {
+  return async (): Promise<S3ClientType> => {
+    "use step";
+    const { S3Client } = await import("@aws-sdk/client-s3");
+    return new S3Client({ region });
+  };
+}
+
+// Usage in a workflow
+export async function processUpload(region: string, key: string) {
+  "use workflow";
+
+  const getClient = createS3Client(region); // [!code highlight]
+  // getClient is a serializable step reference, not an S3Client
+  await uploadFile(getClient, key);
+}
+
+async function uploadFile(
+  getClient: () => Promise<S3ClientType>,
+  key: string
+) {
+  "use step";
+  const client = await getClient(); // [!code highlight]
+  // Now you have a real S3Client with full Node.js access
+  await client.send(/* ... */);
+}
+```
+
+## 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.
+
+## 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

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

@@ -0,0 +1,191 @@
+---
+title: Durable Agent
+description: Replace a stateless AI agent with a durable one that survives crashes, retries tool calls, and streams output.
+type: guide
+summary: Convert an AI SDK Agent into a DurableAgent backed by a workflow, with tools as retryable steps.
+---
+
+Use this pattern to make any AI SDK agent durable. The agent becomes a workflow, tools become steps, and the framework handles retries, streaming, and state persistence automatically.
+
+## Pattern
+
+Replace `Agent` with `DurableAgent`, wrap the function in `"use workflow"`, mark each tool with `"use step"`, and stream output through `getWritable()`.
+
+### Simplified
+
+```typescript lineNumbers
+import { DurableAgent } from "@workflow/ai/agent";
+import { getWritable } from "workflow";
+import { z } from "zod";
+import type { ModelMessage, UIMessageChunk } from "ai";
+
+declare function searchFlights(args: { from: string; to: string; date: string }): Promise<{ flights: { id: string; price: number }[] }>; // @setup
+declare function bookFlight(args: { flightId: string; passenger: string }): Promise<{ confirmationId: string }>; // @setup
+
+export async function flightAgent(messages: ModelMessage[]) {
+  "use workflow";
+
+  const agent = new DurableAgent({ // [!code highlight]
+    model: "anthropic/claude-haiku-4.5",
+    instructions: "You are a helpful flight booking assistant.",
+    tools: {
+      searchFlights: {
+        description: "Search for available flights",
+        inputSchema: z.object({
+          from: z.string(),
+          to: z.string(),
+          date: z.string(),
+        }),
+        execute: searchFlights,
+      },
+      bookFlight: {
+        description: "Book a specific flight",
+        inputSchema: z.object({
+          flightId: z.string(),
+          passenger: z.string(),
+        }),
+        execute: bookFlight,
+      },
+    },
+  });
+
+  await agent.stream({ // [!code highlight]
+    messages,
+    writable: getWritable<UIMessageChunk>(),
+  });
+}
+```
+
+### Full Implementation
+
+```typescript lineNumbers
+import { DurableAgent } from "@workflow/ai/agent";
+import { getWritable } from "workflow";
+import { z } from "zod";
+import type { ModelMessage, UIMessageChunk } from "ai";
+
+// Step: Search flights with full Node.js access and automatic retries
+async function searchFlights({
+  from,
+  to,
+  date,
+}: {
+  from: string;
+  to: string;
+  date: string;
+}) {
+  "use step";
+
+  const response = await fetch(
+    `https://api.example.com/flights?from=${from}&to=${to}&date=${date}`
+  );
+  if (!response.ok) throw new Error(`Search failed: ${response.status}`);
+  return response.json();
+}
+
+// Step: Book a flight — retries on transient failures
+async function bookFlight({
+  flightId,
+  passenger,
+}: {
+  flightId: string;
+  passenger: string;
+}) {
+  "use step";
+
+  const response = await fetch("https://api.example.com/bookings", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ flightId, passenger }),
+  });
+  if (!response.ok) throw new Error(`Booking failed: ${response.status}`);
+  return response.json();
+}
+
+// Step: Check flight status
+async function checkStatus({ flightId }: { flightId: string }) {
+  "use step";
+
+  const response = await fetch(
+    `https://api.example.com/flights/${flightId}/status`
+  );
+  return response.json();
+}
+
+export async function flightAgent(messages: ModelMessage[]) {
+  "use workflow";
+
+  const writable = getWritable<UIMessageChunk>(); // [!code highlight]
+
+  const agent = new DurableAgent({ // [!code highlight]
+    model: "anthropic/claude-haiku-4.5",
+    instructions: "You are a helpful flight booking assistant.",
+    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,
+      },
+      checkStatus: {
+        description: "Check the current status of a flight",
+        inputSchema: z.object({
+          flightId: z.string().describe("Flight ID to check"),
+        }),
+        execute: checkStatus,
+      },
+    },
+  });
+
+  const result = await agent.stream({ // [!code highlight]
+    messages,
+    writable,
+    maxSteps: 10,
+  });
+
+  return { messages: result.messages };
+}
+```
+
+### API Route
+
+```typescript lineNumbers
+import { createUIMessageStreamResponse } from "ai";
+import { start } from "workflow/api";
+import { flightAgent } from "@/workflows/flight-agent";
+import type { UIMessage } from "ai";
+import { convertToModelMessages } from "ai";
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+  const modelMessages = await convertToModelMessages(messages);
+
+  const run = await start(flightAgent, [modelMessages]); // [!code highlight]
+
+  return createUIMessageStreamResponse({
+    stream: run.readable,
+    headers: {
+      "x-workflow-run-id": run.runId,
+    },
+  });
+}
+```
+
+## 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

package/docs/cookbook/agent-patterns/human-in-the-loop.mdx

@@ -0,0 +1,278 @@
+---
+title: Human-in-the-Loop
+description: Pause an AI agent to wait for human approval, then resume based on the decision.
+type: guide
+summary: Use defineHook with the tool call ID to suspend an agent for human approval, with an optional timeout.
+---
+
+Use this pattern when an AI agent needs human confirmation before performing a consequential action like booking, purchasing, or publishing. The workflow suspends without consuming resources until the human responds.
+
+## Pattern
+
+Create a typed hook using `defineHook()`. When the agent calls the approval tool, the tool creates a hook instance using the tool call ID as the token, then awaits it. The UI renders approval controls, and an API route resumes the hook with the decision.
+
+### Simplified
+
+```typescript lineNumbers
+import { DurableAgent } from "@workflow/ai/agent";
+import { defineHook, sleep, getWritable } from "workflow";
+import { z } from "zod";
+import type { ModelMessage, UIMessageChunk } from "ai";
+
+export const bookingApprovalHook = defineHook({
+  schema: z.object({
+    approved: z.boolean(),
+    comment: z.string().optional(),
+  }),
+});
+
+declare function confirmBooking(args: { flightId: string; passenger: string }): Promise<{ confirmationId: string }>; // @setup
+
+// This tool runs at the workflow level (no "use step") because hooks are workflow primitives
+async function requestBookingApproval(
+  { flightId, passenger, price }: { flightId: string; passenger: string; price: number },
+  { toolCallId }: { toolCallId: string }
+) {
+  const hook = bookingApprovalHook.create({ token: toolCallId }); // [!code highlight]
+
+  const result = await Promise.race([ // [!code highlight]
+    hook.then((payload) => ({ type: "decision" as const, ...payload })),
+    sleep("24h").then(() => ({ type: "timeout" as const, approved: false })),
+  ]);
+
+  if (result.type === "timeout") return "Booking request expired after 24 hours.";
+  if (!result.approved) return `Booking rejected: ${result.comment || "No reason given"}`;
+
+  const booking = await confirmBooking({ flightId, passenger });
+  return `Booked! Confirmation: ${booking.confirmationId}`;
+}
+
+export async function bookingAgent(messages: ModelMessage[]) {
+  "use workflow";
+
+  const agent = new DurableAgent({
+    model: "anthropic/claude-haiku-4.5",
+    instructions: "You help book flights. Always request approval before booking.",
+    tools: {
+      requestBookingApproval: {
+        description: "Request human approval before booking a flight",
+        inputSchema: z.object({
+          flightId: z.string(),
+          passenger: z.string(),
+          price: z.number(),
+        }),
+        execute: requestBookingApproval,
+      },
+    },
+  });
+
+  await agent.stream({ // [!code highlight]
+    messages,
+    writable: getWritable<UIMessageChunk>(),
+  });
+}
+```
+
+### Full Implementation
+
+```typescript lineNumbers
+import { DurableAgent } from "@workflow/ai/agent";
+import { defineHook, sleep, getWritable } from "workflow";
+import { z } from "zod";
+import type { ModelMessage, UIMessageChunk } from "ai";
+
+// Define the approval hook with schema validation
+export const bookingApprovalHook = defineHook({
+  schema: z.object({
+    approved: z.boolean(),
+    comment: z.string().optional(),
+  }),
+});
+
+// Step: Search for flights (full Node.js access, automatic retries)
+async function searchFlights({
+  from,
+  to,
+  date,
+}: {
+  from: string;
+  to: string;
+  date: string;
+}) {
+  "use step";
+
+  // Your real flight search API call here
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  return {
+    flights: [
+      { id: "FL-100", airline: "Example Air", price: 299, from, to, date },
+      { id: "FL-200", airline: "Demo Airlines", price: 349, from, to, date },
+    ],
+  };
+}
+
+// Step: Confirm the booking after approval
+async function confirmBooking({
+  flightId,
+  passenger,
+}: {
+  flightId: string;
+  passenger: string;
+}) {
+  "use step";
+
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  return { confirmationId: `CONF-${flightId}-${Date.now().toString(36)}` };
+}
+
+// Workflow-level tool: hooks must be created in workflow context, not inside steps
+async function requestBookingApproval(
+  {
+    flightId,
+    passenger,
+    price,
+  }: { flightId: string; passenger: string; price: number },
+  { toolCallId }: { toolCallId: string }
+) {
+  // No "use step" — hooks are workflow-level primitives
+
+  const hook = bookingApprovalHook.create({ token: toolCallId }); // [!code highlight]
+
+  // Race: human approval vs. 24-hour timeout
+  const result = await Promise.race([ // [!code highlight]
+    hook.then((payload) => ({ type: "decision" as const, ...payload })),
+    sleep("24h").then(() => ({ type: "timeout" as const, approved: false })),
+  ]);
+
+  if (result.type === "timeout") {
+    return "Booking request expired after 24 hours.";
+  }
+
+  if (!result.approved) {
+    return `Booking rejected: ${result.comment || "No reason given"}`;
+  }
+
+  // Approved — proceed with booking
+  const booking = await confirmBooking({ flightId, passenger });
+  return `Flight ${flightId} booked for ${passenger}. Confirmation: ${booking.confirmationId}`;
+}
+
+export async function bookingAgent(messages: ModelMessage[]) {
+  "use workflow";
+
+  const writable = getWritable<UIMessageChunk>();
+
+  const agent = new DurableAgent({
+    model: "anthropic/claude-haiku-4.5",
+    instructions:
+      "You are a flight booking assistant. Search for flights, then request approval before booking.",
+    tools: {
+      searchFlights: {
+        description: "Search for available flights",
+        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,
+      },
+      requestBookingApproval: {
+        description: "Request human approval before booking a flight",
+        inputSchema: z.object({
+          flightId: z.string().describe("Flight ID to book"),
+          passenger: z.string().describe("Passenger name"),
+          price: z.number().describe("Total price"),
+        }),
+        execute: requestBookingApproval,
+      },
+    },
+  });
+
+  await agent.stream({ messages, writable }); // [!code highlight]
+}
+```
+
+### API Route for Approvals
+
+```typescript lineNumbers
+import { bookingApprovalHook } from "@/workflows/booking-agent";
+
+export async function POST(request: Request) {
+  const { toolCallId, approved, comment } = await request.json();
+
+  // Schema validation happens automatically via defineHook
+  await bookingApprovalHook.resume(toolCallId, { approved, comment }); // [!code highlight]
+
+  return Response.json({ success: true });
+}
+```
+
+### Approval Component
+
+```tsx lineNumbers
+"use client";
+
+import { useState } from "react";
+
+export function BookingApproval({
+  toolCallId,
+  input,
+  output,
+}: {
+  toolCallId: string;
+  input?: { flightId: string; passenger: string; price: number };
+  output?: string;
+}) {
+  const [comment, setComment] = useState("");
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  if (output) {
+    return <p className="text-sm text-muted-foreground">{output}</p>;
+  }
+
+  const handleSubmit = async (approved: boolean) => {
+    setIsSubmitting(true);
+    await fetch("/api/hooks/approval", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ toolCallId, approved, comment }),
+    });
+    setIsSubmitting(false);
+  };
+
+  return (
+    <div className="border rounded-lg p-4 space-y-3">
+      {input && (
+        <div className="text-sm space-y-1">
+          <div>Flight: {input.flightId}</div>
+          <div>Passenger: {input.passenger}</div>
+          <div>Price: ${input.price}</div>
+        </div>
+      )}
+      <textarea
+        value={comment}
+        onChange={(e) => setComment(e.target.value)}
+        placeholder="Add a comment (optional)..."
+        className="w-full border rounded p-2 text-sm"
+        rows={2}
+      />
+      <div className="flex gap-2">
+        <button type="button" onClick={() => handleSubmit(true)} disabled={isSubmitting}>
+          Approve
+        </button>
+        <button type="button" onClick={() => handleSubmit(false)} disabled={isSubmitting}>
+          Reject
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+## 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
+- [`defineHook()`](/docs/api-reference/workflow/define-hook) — type-safe hook with schema validation
+- [`sleep()`](/docs/api-reference/workflow/sleep) — durable timeout for approval expiry
+- [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — durable agent with tool definitions

package/docs/cookbook/agent-patterns/meta.json

@@ -0,0 +1,10 @@
+{
+  "title": "Agent Patterns",
+  "pages": [
+    "durable-agent",
+    "tool-streaming",
+    "human-in-the-loop",
+    "tool-orchestration",
+    "stop-workflow"
+  ]
+}