workflow 5.0.0-beta.2 → 5.0.0-beta.4

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

@@ -1,255 +0,0 @@
----
-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

@@ -1,181 +0,0 @@
----
-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/content-router.mdx

@@ -1,207 +0,0 @@
----
-title: Conditional Routing
-description: Inspect a payload and route it to different step handlers based on its content.
-type: guide
-summary: Classify incoming messages and branch to specialized handlers using standard if/else logic in the workflow function.
----
-
-Use conditional routing when incoming messages need different processing paths depending on their content. A support ticket about billing goes to the billing handler; a bug report goes to engineering. The workflow inspects the payload and branches with standard JavaScript control flow.
-
-## When to use this
-
-- Support ticket routing by category
-- Order processing with different flows per product type
-- Event handling where different event types need different logic
-- Any message-driven system where the handler depends on the content
-
-## Pattern: Content-based router
-
-The workflow classifies the input, then branches with `if`/`else` to call the appropriate step:
-
-```typescript
-declare function classifyTicket(ticketId: string, subject: string): Promise<{ ticketType: string }>; // @setup
-declare function handleBilling(ticketId: string): Promise<void>; // @setup
-declare function handleTechnical(ticketId: string): Promise<void>; // @setup
-declare function handleAccount(ticketId: string): Promise<void>; // @setup
-declare function handleFeedback(ticketId: string): Promise<void>; // @setup
-
-export async function routeTicket(ticketId: string, subject: string) {
-  "use workflow";
-
-  const { ticketType } = await classifyTicket(ticketId, subject); // [!code highlight]
-
-  if (ticketType === "billing") { // [!code highlight]
-    await handleBilling(ticketId);
-  } else if (ticketType === "technical") {
-    await handleTechnical(ticketId);
-  } else if (ticketType === "account") {
-    await handleAccount(ticketId);
-  } else {
-    await handleFeedback(ticketId);
-  }
-
-  return { ticketId, routedTo: ticketType };
-}
-```
-
-### Step functions
-
-Each handler is a separate `"use step"` function. The classification step can use an LLM, keyword matching, or any logic you need:
-
-```typescript
-async function classifyTicket(
-  ticketId: string,
-  subject: string
-): Promise<{ ticketType: string }> {
-  "use step";
-
-  // Example: simple keyword classification
-  // In production, this could call an LLM or ML model
-  const lower = subject.toLowerCase();
-  if (lower.includes("invoice") || lower.includes("charge") || lower.includes("refund")) {
-    return { ticketType: "billing" };
-  }
-  if (lower.includes("error") || lower.includes("bug") || lower.includes("crash")) {
-    return { ticketType: "technical" };
-  }
-  if (lower.includes("password") || lower.includes("login") || lower.includes("access")) {
-    return { ticketType: "account" };
-  }
-  return { ticketType: "feedback" };
-}
-
-async function handleBilling(ticketId: string): Promise<void> {
-  "use step";
-  // Look up billing records, process refund, etc.
-}
-
-async function handleTechnical(ticketId: string): Promise<void> {
-  "use step";
-  // Create bug report, notify engineering, etc.
-}
-
-async function handleAccount(ticketId: string): Promise<void> {
-  "use step";
-  // Reset password, update permissions, etc.
-}
-
-async function handleFeedback(ticketId: string): Promise<void> {
-  "use step";
-  // Log feedback, notify product team, etc.
-}
-```
-
-## Pattern: Enrichment before routing
-
-When downstream handlers need more context than the raw input provides, enrich the message in parallel before routing:
-
-```typescript
-export async function enrichAndRoute(email: string) {
-  "use workflow";
-
-  // Step 1: Look up base data
-  const contact = await lookupContact(email);
-
-  // Step 2: Enrich from multiple sources in parallel
-  const [crm, social] = await Promise.allSettled([ // [!code highlight]
-    fetchCrmData(contact),
-    fetchSocialData(contact),
-  ]);
-
-  const enriched = {
-    ...contact,
-    crm: crm.status === "fulfilled" ? crm.value : null,
-    social: social.status === "fulfilled" ? social.value : null,
-  };
-
-  // Step 3: Route based on enriched data
-  if (enriched.crm?.segment === "enterprise") { // [!code highlight]
-    await routeToEnterpriseSales(enriched);
-  } else {
-    await routeToSelfServe(enriched);
-  }
-
-  return { email, segment: enriched.crm?.segment ?? "self-serve" };
-}
-
-async function lookupContact(email: string): Promise<{ email: string; domain: string }> {
-  "use step";
-  return { email, domain: email.split("@")[1] ?? "unknown" };
-}
-
-async function fetchCrmData(contact: { email: string }): Promise<{ segment: string }> {
-  "use step";
-  const res = await fetch(`https://crm.example.com/lookup?email=${contact.email}`);
-  return res.json();
-}
-
-async function fetchSocialData(contact: { email: string }): Promise<{ followers: number }> {
-  "use step";
-  const res = await fetch(`https://social.example.com/lookup?email=${contact.email}`);
-  return res.json();
-}
-
-async function routeToEnterpriseSales(enriched: unknown): Promise<void> {
-  "use step";
-  // Assign to enterprise sales team
-}
-
-async function routeToSelfServe(enriched: unknown): Promise<void> {
-  "use step";
-  // Add to self-serve onboarding flow
-}
-```
-
-## Pattern: Multiple event sources
-
-When a workflow must wait for signals from different systems before proceeding, create one hook per source and use `Promise.all` with a deadline:
-
-```typescript
-import { defineHook, sleep } from "workflow";
-
-export const orderSignal = defineHook<{ ok: true }>();
-
-const SIGNALS = ["payment", "inventory", "fraud"] as const;
-
-export async function waitForAllSignals(orderId: string) {
-  "use workflow";
-
-  const hooks = SIGNALS.map((kind) =>
-    orderSignal.create({ token: `${kind}:${orderId}` }) // [!code highlight]
-  );
-
-  const outcome = await Promise.race([ // [!code highlight]
-    Promise.all(hooks).then(() => ({ type: "ready" as const })), // [!code highlight]
-    sleep("5m").then(() => ({ type: "timeout" as const })), // [!code highlight]
-  ]);
-
-  if (outcome.type === "timeout") {
-    return { orderId, status: "timeout" };
-  }
-
-  await shipOrder(orderId);
-  return { orderId, status: "shipped" };
-}
-
-async function shipOrder(orderId: string): Promise<void> {
-  "use step";
-  await fetch(`https://shipping.example.com/ship`, {
-    method: "POST",
-    body: JSON.stringify({ orderId }),
-  });
-}
-```
-
-## Tips
-
-- **Workflow functions use standard JavaScript.** `if`/`else`, `switch`, ternaries -- any branching logic works. No special routing DSL needed.
-- **Each handler is an independent step.** This means each gets its own retries, its own error handling, and its own entry in the event log.
-- **Combine with enrichment** when downstream handlers need data from multiple sources. Fan out enrichment with `Promise.allSettled`, then route on the merged result.
-- **Use `defineHook` for event gateways** when the routing decision depends on external signals arriving asynchronously.
-
-## Key APIs
-
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) -- marks the orchestrator function
-- [`"use step"`](/docs/api-reference/workflow/use-step) -- marks each handler as a durable step
-- [`defineHook()`](/docs/api-reference/workflow/define-hook) -- creates hooks for event gateway patterns
-- [`sleep()`](/docs/api-reference/workflow/sleep) -- durable deadline for event gateways