workflow-devkit

Workflow DevKit

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

Quick Reference

Pattern	Use Case	Key API
Workflows	Orchestrate durable operations	"use workflow" directive
Steps	Atomic, retriable units	"use step" directive
Webhooks	Human-in-the-loop, callbacks	createWebhook()
Actors	Event-driven state machines	defineHook() + for await
Streaming	Real-time frontend updates	getWritable() / run.readable
AI Agents	Durable LLM workflows	DurableAgent + globalThis.fetch = fetch
AI Gateway	Multi-provider model switching	"provider/model" strings, @ai-sdk/gateway

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 - Workflow patterns (sequential, parallel, routing, actors)
• api-reference.md - Complete API reference
• 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/

Example	Pattern
nextjs/	Basic user signup workflow
kitchen-sink/	All patterns reference
actors/	Event-driven actor pattern
ai-sdk-workflow-patterns/	AI agent patterns
flight-booking-app/	DurableAgent with tools
rag-agent/	RAG with PostgreSQL + embeddings
birthday-card-generator/	Webhooks + scheduling