Workflow

Related packages also include bundled docs:

• @workflow/ai: node_modules/@workflow/ai/docs/ - DurableAgent and AI integration
• @workflow/core: node_modules/@workflow/core/docs/ - Core runtime (foundations, how-it-works)
• @workflow/next: node_modules/@workflow/next/docs/ - Next.js integration

When in doubt, update to the latest version of the Workflow DevKit.

Official Resources

• Website: https://useworkflow.dev
• GitHub: https://github.com/vercel/workflow

Quick Reference

Directives:

"use workflow";  // First line - makes async function durable
"use step";      // First line - makes function a cached, retryable unit

Essential imports:

// Workflow primitives
import { sleep, fetch, createHook, createWebhook, getWritable } from "workflow";
import { FatalError, RetryableError } from "workflow";
import { getWorkflowMetadata, getStepMetadata } from "workflow";

// API operations
import { start, getRun, resumeHook, resumeWebhook } from "workflow/api";

// Framework integrations
import { withWorkflow } from "workflow/next";
import { workflow } from "workflow/vite";
import { workflow } from "workflow/astro";
// Or use modules: ["workflow/nitro"] for Nitro/Nuxt

Prefer Step Functions to Avoid Sandbox Errors

"use workflow" functions run in a sandboxed VM. "use step" functions have full Node.js access. Put your logic in steps and use the workflow function purely for orchestration.

// Steps have full Node.js and npm access
async function fetchUserData(userId: string) {
  "use step";
  const response = await fetch(`https://api.example.com/users/${userId}`);
  return response.json();
}

async function processWithAI(data: any) {
  "use step";
  // AI SDK works in steps without workarounds
  return await generateText({
    model: openai("gpt-4"),
    prompt: `Process: ${JSON.stringify(data)}`,
  });
}

// Workflow orchestrates steps - no sandbox issues
export async function dataProcessingWorkflow(userId: string) {
  "use workflow";
  const data = await fetchUserData(userId);
  const processed = await processWithAI(data);
  return { success: true, processed };
}

Benefits: Steps have automatic retry, results are persisted for replay, and no sandbox restrictions.

Workflow Sandbox Limitations

When you need logic directly in a workflow function (not in a step), these restrictions apply:

Example - Using fetch in workflow context:

import { fetch } from "workflow";

export async function myWorkflow() {
  "use workflow";
  globalThis.fetch = fetch;  // Required for AI SDK and HTTP libraries
  // Now generateText() and other libraries work
}

Note: DurableAgent from @workflow/ai handles the fetch assignment automatically.

Error Handling

Use FatalError for permanent failures (no retry), RetryableError for transient failures:

import { FatalError, RetryableError } from "workflow";

if (res.status >= 400 && res.status < 500) {
  throw new FatalError(`Client error: ${res.status}`);
}
if (res.status === 429) {
  throw new RetryableError("Rate limited", { retryAfter: "5m" });
}

Serialization

All data passed to/from workflows and steps must be serializable.

Supported types: string, number, boolean, null, undefined, bigint, plain objects, arrays, Date, RegExp, URL, URLSearchParams, Map, Set, Headers, ArrayBuffer, typed arrays, Request, Response, ReadableStream, WritableStream.

Not supported: Functions, class instances, Symbols, WeakMap/WeakSet. Pass data, not callbacks.

Streaming

Use getWritable() in step functions to stream data:

async function streamData() {
  "use step";  // Required - streaming only works in steps
  const writer = getWritable();
  await writer.write(data);
  writer.releaseLock();  // Always release the lock
}

// Close when done
await getWritable().close();

Debugging

# Check workflow endpoints are reachable
npx workflow health
npx workflow health --port 3001  # Non-default port

# Visual dashboard for runs
npx workflow web
npx workflow web --app-url http://localhost:3001

# CLI inspection (for agents)
npx workflow inspect runs
npx workflow inspect run <run_id>

Tip: Only import workflow APIs you actually use. Unused imports can cause 500 errors.