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

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"
+  ]
+}

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

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