Workflow DevKit

Build reliable, long-running processes with automatic retries, state persistence, and observability.

Quick Reference

Prerequisites

pnpm add workflow @workflow/ai ai @ai-sdk/gateway zod

Core Concepts

Workflows ("use workflow")

import { sleep } from "workflow";

export async function myWorkflow(input: string) {
  "use workflow";
  const result = await step1(input);
  await sleep("5s");
  return result;
}

Steps ("use step") - MUST be in SAME FILE as workflow

async function step1(input: string) {
  "use step";
  return await fetch(`/api/data?q=${input}`).then(r => r.json());
}

Error Types

import { FatalError, RetryableError } from "workflow";

// Auto-retried
throw new Error("Transient failure");

// No retry - stops workflow
throw new FatalError("Invalid credentials");

// Custom retry timing
throw new RetryableError("Rate limited", { retryAfter: "60s" });

Detailed Documentation

• [patterns.md](patterns.md) - Workflow patterns (sequential, parallel, routing, actors)
• [api-reference.md](api-reference.md) - Complete API reference
• [ai-integration.md](ai-integration.md) - AI SDK and DurableAgent patterns

Imports Cheat Sheet

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

// API routes
import { start, getRun } from "workflow/api";

// AI integration
import { DurableAgent } from "@workflow/ai/agent";
import { generateText, generateObject } from "ai";
import { createUIMessageStreamResponse } from "ai";

Examples Directory

Reference implementations: ~/dev/workflow-examples/