workflow 5.0.0-beta.0 → 5.0.0-beta.2

package/docs/cookbook/agent-patterns/tool-orchestration.mdx

@@ -0,0 +1,255 @@
+---
+title: Tool Orchestration
+description: Choose between step-level and workflow-level tools, or combine both for complex tool implementations.
+type: guide
+summary: Implement tools as steps for retries and I/O, at the workflow level for sleep and hooks, or combine both.
+---
+
+Use this pattern to understand when to implement a tool as a step, at the workflow level, or as a combination. The choice depends on whether the tool needs Node.js I/O (step), workflow primitives like `sleep()` and hooks (workflow level), or both.
+
+## Pattern
+
+Tools marked with `"use step"` get automatic retries and full Node.js access but cannot use `sleep()` or hooks. Tools without `"use step"` run in the workflow context and can use workflow primitives but cannot perform side effects directly. Combine both by having a workflow-level tool call into steps for I/O.
+
+### Step-Level vs Workflow-Level
+
+| Capability | Step (`"use step"`) | Workflow Level |
+|------------|---------------------|----------------|
+| `getWritable()` | Yes | Yes |
+| Automatic retries | Yes | No |
+| Side effects (fetch, DB) | Yes | No |
+| `sleep()` | No | Yes |
+| `createHook()` / `createWebhook()` | No | Yes |
+
+### Simplified
+
+```typescript lineNumbers
+import { DurableAgent } from "@workflow/ai/agent";
+import { sleep, getWritable } from "workflow";
+import { z } from "zod";
+import type { UIMessageChunk } from "ai";
+
+// Step-level tool: I/O with retries
+async function fetchWeather({ city }: { city: string }) {
+  "use step";
+  const res = await fetch(`https://api.weather.com?city=${city}`);
+  return res.json();
+}
+
+// Workflow-level tool: uses sleep()
+async function scheduleReminder({ delayMs }: { delayMs: number }) {
+  // No "use step" — sleep() requires workflow context
+  await sleep(delayMs); // [!code highlight]
+  return { message: `Reminder fired after ${delayMs}ms` };
+}
+
+// Combined: workflow-level orchestration calling into steps
+async function fetchWithDelay({ url, delayMs }: { url: string; delayMs: number }) {
+  const result = await doFetch(url);   // Step handles I/O // [!code highlight]
+  await sleep(delayMs);                // Workflow handles sleep // [!code highlight]
+  return result;
+}
+
+async function doFetch(url: string) {
+  "use step";
+  const res = await fetch(url);
+  return res.json();
+}
+
+export async function assistantAgent(userMessage: string) {
+  "use workflow";
+
+  const agent = new DurableAgent({
+    model: "anthropic/claude-haiku-4.5",
+    tools: {
+      fetchWeather: {
+        description: "Get weather for a city",
+        inputSchema: z.object({ city: z.string() }),
+        execute: fetchWeather,
+      },
+      scheduleReminder: {
+        description: "Set a reminder after a delay",
+        inputSchema: z.object({ delayMs: z.number() }),
+        execute: scheduleReminder,
+      },
+      fetchWithDelay: {
+        description: "Fetch a URL then wait before returning",
+        inputSchema: z.object({ url: z.string(), delayMs: z.number() }),
+        execute: fetchWithDelay,
+      },
+    },
+  });
+
+  await agent.stream({ // [!code highlight]
+    messages: [{ role: "user", content: userMessage }],
+    writable: getWritable<UIMessageChunk>(),
+  });
+}
+```
+
+### Full Implementation
+
+```typescript lineNumbers
+import { DurableAgent } from "@workflow/ai/agent";
+import { sleep, createWebhook, getWritable } from "workflow";
+import { z } from "zod";
+import type { UIMessageChunk } from "ai";
+
+// --- Step-level tools: I/O with retries ---
+
+async function searchDatabase({ query }: { query: string }) {
+  "use step";
+
+  const response = await fetch(`https://api.example.com/search?q=${query}`);
+  if (!response.ok) throw new Error(`Search failed: ${response.status}`);
+  return response.json();
+}
+
+async function sendNotification({
+  userId,
+  message,
+}: {
+  userId: string;
+  message: string;
+}) {
+  "use step";
+
+  await fetch("https://api.example.com/notifications", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ userId, message }),
+  });
+  return { sent: true };
+}
+
+// --- Workflow-level tool: uses sleep ---
+
+async function waitThenCheck({
+  delayMs,
+  endpoint,
+}: {
+  delayMs: number;
+  endpoint: string;
+}) {
+  // No "use step" — workflow context needed for sleep()
+  await sleep(delayMs); // [!code highlight]
+  // Delegate I/O to a step
+  return pollEndpoint(endpoint);
+}
+
+async function pollEndpoint(endpoint: string) {
+  "use step";
+  const res = await fetch(endpoint);
+  return res.json();
+}
+
+// --- Workflow-level tool: uses webhook ---
+
+async function waitForCallback({ description }: { description: string }) {
+  // No "use step" — webhooks are workflow primitives
+  const webhook = createWebhook(); // [!code highlight]
+  // Log the URL so external systems can call it
+  console.log(`Waiting for callback at: ${webhook.url}`);
+
+  const result = await Promise.race([ // [!code highlight]
+    webhook.then((req) => req.json()),
+    sleep("1h").then(() => ({ status: "timeout" })),
+  ]);
+
+  return result;
+}
+
+// --- Combined tool: step I/O + workflow sleep + step I/O ---
+
+async function retryWithCooldown({
+  url,
+  maxAttempts,
+}: {
+  url: string;
+  maxAttempts: number;
+}) {
+  for (let i = 0; i < maxAttempts; i++) {
+    const result = await attemptFetch(url);
+    if (result.success) return result;
+    if (i < maxAttempts - 1) {
+      await sleep(`${(i + 1) * 5}s`); // Increasing cooldown between attempts // [!code highlight]
+    }
+  }
+  return { success: false, error: "All attempts failed" };
+}
+
+async function attemptFetch(url: string) {
+  "use step";
+  try {
+    const res = await fetch(url);
+    if (!res.ok) return { success: false, status: res.status };
+    return { success: true, data: await res.json() };
+  } catch {
+    return { success: false, error: "Network error" };
+  }
+}
+
+export async function orchestrationAgent(userMessage: string) {
+  "use workflow";
+
+  const writable = getWritable<UIMessageChunk>();
+
+  const agent = new DurableAgent({
+    model: "anthropic/claude-haiku-4.5",
+    instructions:
+      "You are an assistant with access to search, notifications, polling, callbacks, and retry tools.",
+    tools: {
+      searchDatabase: {
+        description: "Search the database",
+        inputSchema: z.object({ query: z.string() }),
+        execute: searchDatabase,
+      },
+      sendNotification: {
+        description: "Send a notification to a user",
+        inputSchema: z.object({
+          userId: z.string(),
+          message: z.string(),
+        }),
+        execute: sendNotification,
+      },
+      waitThenCheck: {
+        description: "Wait for a duration then check an endpoint",
+        inputSchema: z.object({
+          delayMs: z.number().describe("Milliseconds to wait"),
+          endpoint: z.string().describe("URL to check after waiting"),
+        }),
+        execute: waitThenCheck,
+      },
+      waitForCallback: {
+        description: "Create a webhook and wait for an external system to call it",
+        inputSchema: z.object({
+          description: z.string().describe("What the callback is for"),
+        }),
+        execute: waitForCallback,
+      },
+      retryWithCooldown: {
+        description: "Fetch a URL with retries and increasing cooldown between attempts",
+        inputSchema: z.object({
+          url: z.string(),
+          maxAttempts: z.number().default(3),
+        }),
+        execute: retryWithCooldown,
+      },
+    },
+  });
+
+  await agent.stream({ // [!code highlight]
+    messages: [{ role: "user", content: userMessage }],
+    writable,
+  });
+}
+```
+
+## 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 Node.js access
+- [`sleep()`](/docs/api-reference/workflow/sleep) — durable pause (only in workflow context)
+- [`createWebhook()`](/docs/api-reference/workflow/create-webhook) — wait for external HTTP callbacks (only in workflow context)
+- [`getWritable()`](/docs/api-reference/workflow/get-writable) — stream data from steps
+- [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — agent with mixed step/workflow-level tools

package/docs/cookbook/agent-patterns/tool-streaming.mdx

@@ -0,0 +1,181 @@
+---
+title: Tool Streaming
+description: Stream real-time progress updates from tools to the UI while they execute.
+type: guide
+summary: Emit custom data parts from step functions to show incremental results during long-running tool calls.
+---
+
+Use this pattern when tools take a long time to execute and you want to show progress updates, intermediate results, or status messages in the UI while the tool is still running.
+
+## Pattern
+
+Inside a step function, call `getWritable<UIMessageChunk>()` to write custom data parts to the same stream the agent uses. These appear as typed data parts in the client's message parts array.
+
+### Simplified
+
+```typescript lineNumbers
+import { DurableAgent } from "@workflow/ai/agent";
+import { getWritable } from "workflow";
+import { z } from "zod";
+import type { UIMessageChunk } from "ai";
+
+declare function performSearch(query: string): Promise<{ id: string; title: string }[]>; // @setup
+declare function searchWithProgress(args: { query: string }): Promise<any>; // @setup
+
+export async function searchAgent(userMessage: string) {
+  "use workflow";
+
+  const agent = new DurableAgent({
+    model: "anthropic/claude-haiku-4.5",
+    tools: {
+      search: {
+        description: "Search for items",
+        inputSchema: z.object({ query: z.string() }),
+        execute: searchWithProgress,
+      },
+    },
+  });
+
+  await agent.stream({ // [!code highlight]
+    messages: [{ role: "user", content: userMessage }],
+    writable: getWritable<UIMessageChunk>(),
+  });
+}
+```
+
+### Full Implementation
+
+```typescript lineNumbers
+import { DurableAgent } from "@workflow/ai/agent";
+import { getWritable } from "workflow";
+import { z } from "zod";
+import type { UIMessageChunk } from "ai";
+
+// Custom data part type for the client to render
+interface FoundItemDataPart {
+  type: "data-found-item";
+  id: string;
+  data: {
+    title: string;
+    score: number;
+  };
+}
+
+// Step: Search with streaming progress updates
+async function searchWithProgress(
+  { query }: { query: string },
+  { toolCallId }: { toolCallId: string }
+) {
+  "use step";
+
+  const writable = getWritable<UIMessageChunk>(); // [!code highlight]
+  const writer = writable.getWriter();
+
+  try {
+    // Simulate finding items one at a time
+    const items = [
+      { title: "Result A", score: 95 },
+      { title: "Result B", score: 87 },
+      { title: "Result C", score: 72 },
+    ];
+
+    for (const item of items) {
+      // Simulate search latency
+      await new Promise((resolve) => setTimeout(resolve, 800));
+
+      // Stream each result to the UI as it's found
+      await writer.write({ // [!code highlight]
+        type: "data-found-item",
+        id: `${toolCallId}-${item.title}`,
+        data: item,
+      } as UIMessageChunk);
+    }
+
+    return {
+      message: `Found ${items.length} results for "${query}"`,
+      items,
+    };
+  } finally {
+    writer.releaseLock();
+  }
+}
+
+// Step: Fetch details for a specific item
+async function getItemDetails({ itemId }: { itemId: string }) {
+  "use step";
+
+  const writable = getWritable<UIMessageChunk>();
+  const writer = writable.getWriter();
+
+  try {
+    // Emit a transient progress message
+    await writer.write({ // [!code highlight]
+      type: "data-progress",
+      data: { message: `Loading details for ${itemId}...` },
+      transient: true,
+    } as UIMessageChunk);
+
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+
+    return { itemId, description: "Detailed information", available: true };
+  } finally {
+    writer.releaseLock();
+  }
+}
+
+export async function searchAgent(userMessage: string) {
+  "use workflow";
+
+  const writable = getWritable<UIMessageChunk>();
+
+  const agent = new DurableAgent({
+    model: "anthropic/claude-haiku-4.5",
+    instructions: "You help users search for items. Use the search tool first, then get details if asked.",
+    tools: {
+      search: {
+        description: "Search for items matching a query",
+        inputSchema: z.object({
+          query: z.string().describe("Search query"),
+        }),
+        execute: searchWithProgress,
+      },
+      getDetails: {
+        description: "Get detailed information about a specific item",
+        inputSchema: z.object({
+          itemId: z.string().describe("Item ID from search results"),
+        }),
+        execute: getItemDetails,
+      },
+    },
+  });
+
+  await agent.stream({ // [!code highlight]
+    messages: [{ role: "user", content: userMessage }],
+    writable,
+  });
+}
+```
+
+### Client Rendering
+
+```tsx lineNumbers
+// In your chat component's message rendering:
+{message.parts.map((part, i) => {
+  if (part.type === "data-found-item") {
+    const item = part.data as { title: string; score: number };
+    return (
+      <div key={part.id} className="p-3 bg-muted rounded-md">
+        <div className="font-medium">{item.title}</div>
+        <div className="text-muted-foreground">Score: {item.score}</div>
+      </div>
+    );
+  }
+  // ... other part types
+})}
+```
+
+## Key APIs
+
+- [`"use step"`](/docs/api-reference/workflow/use-step) — step functions can write to the stream
+- [`getWritable()`](/docs/api-reference/workflow/get-writable) — access the run's output stream from inside a step
+- [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — agent streams LLM output to the same writable

package/docs/cookbook/common-patterns/batching.mdx

@@ -0,0 +1,179 @@
+---
+title: Batching & Parallel Processing
+description: Process large collections in parallel batches with failure isolation between groups.
+type: guide
+summary: Split items into fixed-size batches, process each batch concurrently with Promise.allSettled, and pace batches with sleep to avoid overloading downstream services.
+---
+
+Use batching when you need to process a large list of items in parallel while controlling concurrency. Items are split into fixed-size batches, each batch runs concurrently, and failures in one batch don't affect others.
+
+## When to use this
+
+- Processing hundreds or thousands of items (orders, images, records)
+- Calling rate-limited APIs where you need to control concurrency
+- Any fan-out where you want failure isolation between groups
+
+## Pattern
+
+The workflow splits items into chunks and processes each chunk with `Promise.allSettled()`. A `sleep()` between chunks prevents overloading downstream services.
+
+```typescript
+import { sleep } from "workflow";
+
+declare function processItem(item: string): Promise<{ item: string; ok: boolean }>; // @setup
+
+export async function processBatch(items: string[], batchSize: number = 5) {
+  "use workflow";
+
+  const results = [];
+
+  for (let i = 0; i < items.length; i += batchSize) {
+    const batch = items.slice(i, i + batchSize);
+
+    // Run batch in parallel -- failures are isolated
+    const outcomes = await Promise.allSettled( // [!code highlight]
+      batch.map((item) => processItem(item))
+    );
+
+    for (let j = 0; j < outcomes.length; j++) {
+      const outcome = outcomes[j];
+      results.push(
+        outcome.status === "fulfilled"
+          ? outcome.value
+          : { item: batch[j], ok: false, error: String(outcome.reason) }
+      );
+    }
+
+    // Pace between batches to avoid overload
+    if (i + batchSize < items.length) {
+      await sleep("1s"); // [!code highlight]
+    }
+  }
+
+  const succeeded = results.filter((r) => r.ok).length;
+  return { total: results.length, succeeded, failed: results.length - succeeded };
+}
+```
+
+### Step function
+
+Each item is processed in its own step, giving it full Node.js access and automatic retries.
+
+```typescript
+async function processItem(item: string): Promise<{ item: string; ok: boolean }> {
+  "use step";
+  const res = await fetch(`https://api.example.com/process`, {
+    method: "POST",
+    body: JSON.stringify({ item }),
+  });
+  if (!res.ok) throw new Error(`Failed to process ${item}`);
+  return { item, ok: true };
+}
+```
+
+## Variations
+
+### Scatter-gather
+
+When you need results from multiple independent sources before continuing, fan out in parallel and collect all results:
+
+```typescript
+export async function scatterGather(query: string) {
+  "use workflow";
+
+  const [web, database, cache] = await Promise.allSettled([ // [!code highlight]
+    searchWeb(query),
+    searchDatabase(query),
+    searchCache(query),
+  ]);
+
+  return {
+    web: web.status === "fulfilled" ? web.value : null,
+    database: database.status === "fulfilled" ? database.value : null,
+    cache: cache.status === "fulfilled" ? cache.value : null,
+  };
+}
+
+async function searchWeb(query: string): Promise<string[]> {
+  "use step";
+  // Full Node.js access -- call external APIs
+  const res = await fetch(`https://search.example.com?q=${query}`);
+  return res.json();
+}
+
+async function searchDatabase(query: string): Promise<string[]> {
+  "use step";
+  // Query your database
+  return [`db-result-for-${query}`];
+}
+
+async function searchCache(query: string): Promise<string[]> {
+  "use step";
+  return [`cached-result-for-${query}`];
+}
+```
+
+## In-step concurrency control
+
+When you need to process many items against a rate-limited API but want the entire operation to be a single atomic step, batch the work inside the step itself. This keeps the event log clean (one step instead of hundreds) while still controlling concurrency.
+
+```typescript
+async function processConcurrently<T>(
+  items: string[],
+  processor: (item: string) => Promise<T>,
+  maxConcurrent: number = 5,
+): Promise<T[]> {
+  "use step";
+  const results: T[] = [];
+
+  for (let i = 0; i < items.length; i += maxConcurrent) {
+    const batch = items.slice(i, i + maxConcurrent);
+    const batchResults = await Promise.all(batch.map(processor)); // [!code highlight]
+    results.push(...batchResults);
+  }
+
+  return results;
+}
+```
+
+Usage in a workflow:
+
+```typescript
+declare function processConcurrently<T>(items: string[], processor: (item: string) => Promise<T>, maxConcurrent?: number): Promise<T[]>; // @setup
+
+export async function moderateImages(imageUrls: string[]) {
+  "use workflow";
+
+  const results = await processConcurrently(
+    imageUrls,
+    async (url) => {
+      const res = await fetch("https://api.example.com/moderate", {
+        method: "POST",
+        body: JSON.stringify({ url }),
+      });
+      return res.json();
+    },
+    3, // max 3 concurrent API calls
+  );
+
+  return { total: results.length, results };
+}
+```
+
+**When to use in-step batching vs workflow-level batching:**
+- **Workflow-level** (the pattern above): Each item is its own step with independent retries and failure isolation. Use when items are independent and individual failures should be retried.
+- **In-step**: All items are processed in one step. Use when the items are tightly coupled (e.g., moderating all thumbnails for a single video) or when you want to minimize step overhead for large item counts.
+
+## Tips
+
+- **Use `Promise.allSettled` over `Promise.all`** when you want to continue even if some items fail. `Promise.all` rejects on the first failure; `allSettled` waits for everything and tells you what failed.
+- **Tune batch size to your downstream API limits.** If the API allows 10 concurrent requests, use `batchSize: 10`.
+- **Add pacing with `sleep()`** between batches to respect rate limits. The sleep is durable -- it survives cold starts.
+- **Each `processItem` call is an independent step.** If one fails, it retries up to 3 times without affecting other items in the batch.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/foundations/workflows-and-steps) -- marks the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps) -- marks functions that run with full Node.js access
+- [`sleep()`](/docs/api-reference/workflow/sleep) -- pacing delay between batches
+- [`Promise.allSettled()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled) -- runs items in parallel, isolating failures