workflow

重要: 常に正しい workflow のドキュメントを使用してください

workflow に関する知識は古くなっています。

以下の workflow ドキュメントは、インストールされている Workflow DevKit のバージョンに対応しています。 workflow 関連の作業を始める前に、次の手順に従ってください。

バンドルされているドキュメントを node_modules/workflow/docs/ で検索します。

1. ドキュメントを検索: glob "node_modules/workflow/docs/**/*.mdx"
2. 内容を検索: grep "your query" node_modules/workflow/docs/

node_modules/workflow/docs/ のドキュメント構成:

• getting-started/ - フレームワークのセットアップ（next.mdx、express.mdx、hono.mdx など）
• foundations/ - 基本概念（workflows-and-steps.mdx、hooks.mdx、streaming.mdx など）
• api-reference/workflow/ - API ドキュメント（sleep.mdx、create-hook.mdx、fatal-error.mdx など）
• api-reference/workflow-api/ - クライアント API（start.mdx、get-run.mdx、resume-hook.mdx など）
• ai/ - AI SDK の統合ドキュメント
• errors/ - エラーコードのドキュメント

関連パッケージにも、バンドルされたドキュメントが含まれています。

• @workflow/ai: node_modules/@workflow/ai/docs/ - DurableAgent と AI の統合
• @workflow/core: node_modules/@workflow/core/docs/ - コアランタイム（foundations、how-it-works）
• @workflow/next: node_modules/@workflow/next/docs/ - Next.js の統合

迷った場合は、Workflow DevKit を最新バージョンに更新してください。

公式リソース

• ウェブサイト: https://useworkflow.dev
• GitHub: https://github.com/vercel/workflow

クイックリファレンス

ディレクティブ:

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

必須のインポート:

// 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

サンドボックスエラーを避けるにはステップ関数を優先してください

"use workflow" 関数はサンドボックス化された VM で実行されます。"use step" 関数は Node.js に完全にアクセスできます。ロジックはステップに配置し、ワークフロー関数はオーケストレーションのみに使用してください。

// 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 };
}

メリット: ステップには自動リトライがあり、結果はリプレイ用に永続化され、サンドボックスの制限もありません。

ワークフローのサンドボックスに関する制限

ワークフロー関数内で直接ロジックを実行する必要がある場合（ステップ内ではない場合）は、次の制限が適用されます。

制限	回避策
fetch() は使用できません	import { fetch } from "workflow" を実行してから、globalThis.fetch = fetch を設定します
setTimeout／setInterval は使用できません	"workflow" の sleep("5s") を使用します
Node.js モジュール（fs、crypto など）は使用できません	ステップ関数に移動します

例 - ワークフローのコンテキストで fetch を使用する場合:

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
}

注: @workflow/ai の DurableAgent は、fetch の割り当てを自動的に処理します。

エラー処理

恒久的な失敗（リトライなし）には FatalError を、一時的な失敗には RetryableError を使用します。

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" });
}

シリアライズ

ワークフローとステップの間で受け渡すデータは、すべてシリアライズ可能である必要があります。

サポート対象の型: string、number、boolean、null、undefined、bigint、プレーンオブジェクト、配列、Date、RegExp、URL、URLSearchParams、Map、Set、Headers、ArrayBuffer、型付き配列、Request、Response、ReadableStream、WritableStream。

サポート対象外: 関数、クラスインスタンス、Symbol、WeakMap／WeakSet。コールバックではなく、データを渡してください。

ストリーミング

ステップ関数内で getWritable() を使用してデータをストリーム配信します。

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();

デバッグ

# 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>

ヒント: 実際に使用するワークフロー API のみをインポートしてください。未使用のインポートが 500 エラーの原因になることがあります。