workflow-devkit

johnlindquist's avatarfrom johnlindquist

Build durable, resumable TypeScript workflows with Vercel Workflow DevKit. Use when creating long-running processes, AI agents, background jobs, multi-step pipelines, webhooks, or event-driven systems. Triggers on "workflow", "durable", "resumable", "use workflow", "use step".

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 19, 2025⬇️1downloads
[Tool Routing and Orchestration]

When & Why to Use This Skill

The Vercel Workflow DevKit is a specialized Claude skill designed for building durable, resumable TypeScript workflows. It enables developers to create reliable, long-running processes with built-in state persistence, automatic retries, and observability. By leveraging 'use workflow' and 'use step' directives, it simplifies the orchestration of complex AI agents, multi-step pipelines, and event-driven systems, ensuring high availability and fault tolerance in production environments.

Use Cases

  • AI Agent Orchestration: Developing complex, multi-turn AI agents that require state persistence and reliable execution across long-running sessions.
  • Durable Background Jobs: Managing asynchronous tasks such as user onboarding sequences, scheduled reports, or data synchronization with automatic error handling.
  • Event-Driven State Machines: Implementing robust actor models and webhooks for real-time applications that need to maintain state across distributed systems.
  • Resumable Multi-step Pipelines: Building CI/CD-style workflows or data processing pipelines where individual steps can be retried independently without restarting the entire process.
nameworkflow-devkit
descriptionBuild durable, resumable TypeScript workflows with Vercel Workflow DevKit. Use when creating long-running processes, AI agents, background jobs, multi-step pipelines, webhooks, or event-driven systems. Triggers on "workflow", "durable", "resumable", "use workflow", "use step".

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

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