workflow 5.0.0-beta.2 → 5.0.0-beta.20

package/docs/cookbook/agent-patterns/stop-workflow.mdx

@@ -1,216 +0,0 @@
----
-title: Stop Workflow
-description: Gracefully cancel a running agent workflow using a hook signal.
-type: guide
-summary: Use a hook as a stop signal to break out of an agent loop and close the stream cleanly.
----
-
-Use this pattern when you need to gracefully stop a running agent from the outside — for example, a "Stop" button in a chat UI or an admin cancellation endpoint. The workflow listens for a stop signal via a hook while the agent runs, and breaks out of the loop when the signal arrives.
-
-## Pattern
-
-Create a hook with a known token (the run ID). Listen for a stop signal in a non-blocking `.then()`. In the `prepareStep` callback, check the flag and return `{ toolChoice: "none" }` to prevent further tool calls, causing the agent to generate a final response and exit the loop cleanly.
-
-### Simplified
-
-```typescript lineNumbers
-import { DurableAgent } from "@workflow/ai/agent";
-import { defineHook, getWritable, getWorkflowMetadata } from "workflow";
-import { z } from "zod";
-import type { ModelMessage, UIMessageChunk } from "ai";
-
-export const stopHook = defineHook({
-  schema: z.object({ reason: z.string().optional() }),
-});
-
-declare function processQuery(args: { query: string }): Promise<string>; // @setup
-
-export async function stoppableAgent(messages: ModelMessage[]) {
-  "use workflow";
-
-  const { workflowRunId } = getWorkflowMetadata();
-  let stopRequested = false;
-
-  const hook = stopHook.create({ token: `stop:${workflowRunId}` }); // [!code highlight]
-  hook.then(() => { stopRequested = true; }); // [!code highlight]
-
-  const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
-    tools: {
-      processQuery: {
-        description: "Process a query",
-        inputSchema: z.object({ query: z.string() }),
-        execute: processQuery,
-      },
-    },
-  });
-
-  const result = await agent.stream({
-    messages,
-    writable: getWritable<UIMessageChunk>(),
-    prepareStep: () => { // [!code highlight]
-      if (stopRequested) return { toolChoice: "none" }; // [!code highlight]
-      return {};
-    },
-  });
-
-  return { messages: result.messages, stopped: stopRequested };
-}
-```
-
-### Full Implementation
-
-```typescript lineNumbers
-import { DurableAgent } from "@workflow/ai/agent";
-import { defineHook, getWritable, getWorkflowMetadata } from "workflow";
-import { z } from "zod";
-import type { ModelMessage, UIMessageChunk } from "ai";
-
-// Hook to signal the workflow to stop
-export const stopHook = defineHook({
-  schema: z.object({
-    reason: z.string().optional(),
-  }),
-});
-
-// Step: Search the web
-async function searchWeb({ query }: { query: string }) {
-  "use step";
-
-  await new Promise((resolve) => setTimeout(resolve, 1000));
-  return { results: [`Result for "${query}"`] };
-}
-
-// Step: Analyze data
-async function analyzeData({ data }: { data: string }) {
-  "use step";
-
-  await new Promise((resolve) => setTimeout(resolve, 800));
-  return { analysis: `Analysis of: ${data}` };
-}
-
-// Step: Write the final close marker to the stream
-async function closeStream() {
-  "use step";
-
-  const writable = getWritable<UIMessageChunk>();
-  const writer = writable.getWriter();
-  try {
-    await writer.write({ type: "finish" } as UIMessageChunk);
-  } finally {
-    writer.releaseLock();
-  }
-  await writable.close();
-}
-
-export async function stoppableAgent(messages: ModelMessage[]) {
-  "use workflow";
-
-  const { workflowRunId } = getWorkflowMetadata();
-  const writable = getWritable<UIMessageChunk>();
-
-  // Listen for stop signal using a non-blocking hook
-  let stopRequested = false;
-  let stopReason: string | undefined;
-
-  const hook = stopHook.create({ token: `stop:${workflowRunId}` }); // [!code highlight]
-  hook.then(({ reason }) => { // [!code highlight]
-    stopRequested = true;
-    stopReason = reason;
-  });
-
-  const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
-    instructions: "You are a research assistant. Search and analyze data as needed.",
-    tools: {
-      searchWeb: {
-        description: "Search the web for information",
-        inputSchema: z.object({ query: z.string() }),
-        execute: searchWeb,
-      },
-      analyzeData: {
-        description: "Analyze a piece of data",
-        inputSchema: z.object({ data: z.string() }),
-        execute: analyzeData,
-      },
-    },
-  });
-
-  const result = await agent.stream({
-    messages,
-    writable,
-    preventClose: true,
-    maxSteps: 20,
-    prepareStep: ({ stepNumber }) => { // [!code highlight]
-      // Check stop flag before each agent step.
-      // Setting toolChoice to "none" prevents tool calls,
-      // causing the agent to generate a final response and exit.
-      if (stopRequested) {
-        return { toolChoice: "none" }; // [!code highlight]
-      }
-      return {};
-    },
-  });
-
-  // Clean up: close the stream
-  await closeStream();
-
-  return {
-    messages: result.messages,
-    stopped: stopRequested,
-    stopReason,
-    stepsCompleted: result.steps.length,
-  };
-}
-```
-
-### API Route to Trigger Stop
-
-```typescript lineNumbers
-import { stopHook } from "@/workflows/stoppable-agent";
-
-export async function POST(
-  request: Request,
-  { params }: { params: Promise<{ runId: string }> }
-) {
-  const { runId } = await params;
-  const { reason } = await request.json();
-
-  await stopHook.resume(`stop:${runId}`, { // [!code highlight]
-    reason: reason || "User requested stop",
-  });
-
-  return Response.json({ success: true });
-}
-```
-
-### Client Stop Button
-
-```tsx lineNumbers
-"use client";
-
-export function StopButton({ runId }: { runId: string }) {
-  const handleStop = async () => {
-    await fetch(`/api/chat/${runId}/stop`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ reason: "User clicked stop" }),
-    });
-  };
-
-  return (
-    <button type="button" onClick={handleStop}>
-      Stop Agent
-    </button>
-  );
-}
-```
-
-## 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 for the stop signal
-- [`getWorkflowMetadata()`](/docs/api-reference/workflow/get-workflow-metadata) — access the run ID for deterministic hook tokens
-- [`getWritable()`](/docs/api-reference/workflow/get-writable) — stream output and close cleanly on stop
-- [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — `prepareStep` callback to check stop flag before each step

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