workflow-devkit

majiayu000 的头像作者 majiayu000

使用 Vercel Workflow DevKit 构建持久、可恢复的 TypeScript 工作流程。在创建长时间运行的流程、AI 代理、后台作业、多步骤管道、Webhooks 或事件驱动系统时使用。在“工作流程”、“持久”、“可恢复”、“使用工作流程”、“使用步骤”上触发。

📖 中文导读:使用 Vercel Workflow DevKit 构建持久、可恢复的 TypeScript 工作流程。在创建长时间运行的流程、AI 代理、后台作业、多步骤管道、Webhooks 或事件驱动系统时使用。在“工作流程”、“持久”、“可恢复”、“使用工作流程”、“使用步骤”上触发。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: workflow-devkit description: 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".

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