cloudflare-workflows

Cloudflare Workflows

ステータス：本番環境対応済み ✅ | 最終確認日：2025-12-27 | バージョン：3.0.0

依存関係：cloudflare-worker-base（Worker のセットアップ用）

目次：クイックスタート • コマンド • エージェント • 主要な概念 • 重要なルール • よくあるエラー • 一般的なパターン • 参照資料を読み込むタイミング • 制限

---

クイックスタート（10 分）

1. Workflow を作成する

Cloudflare Workflows のスターターテンプレートを使用します。

npm create cloudflare@latest my-workflow -- --template cloudflare/workflows-starter --git --deploy false
cd my-workflow

作成されるもの：

• WorkflowEntrypoint クラスのテンプレート
• Workflow を起動する Worker
• 完全な wrangler.jsonc 設定

2. Workflow の基本構造

src/index.ts：

import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';

type Env = {
  MY_WORKFLOW: Workflow;
};

type Params = {
  userId: string;
  email: string;
};

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    const { userId, email } = event.payload;

    // Step 1: Do work with automatic retries
    const result = await step.do('process user', async () => {
      return { processed: true, userId };
    });

    // Step 2: Wait before next step
    await step.sleep('wait 1 hour', '1 hour');

    // Step 3: Continue workflow
    await step.do('send email', async () => {
      return { sent: true, email };
    });

    return { completed: true, userId };
  }
}

// Worker to trigger workflow
export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const instance = await env.MY_WORKFLOW.create({
      params: { userId: '123', email: '[email protected]' }
    });

    return Response.json({
      id: instance.id,
      status: await instance.status()
    });
  }
};

テンプレート：完全な例については templates/basic-workflow.ts を参照してください。

3. wrangler.jsonc を設定する

{
  "name": "my-workflow",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-22",
  "workflows": [
    {
      "binding": "MY_WORKFLOW",
      "name": "my-workflow",
      "class_name": "MyWorkflow"
    }
  ]
}

テンプレート：templates/wrangler-workflows-config.jsonc を参照してください。

4. デプロイする

npm run deploy

---

コマンド

Workflow 開発用の対話型スラッシュコマンド：

コマンド	説明	使用する場面
/workflow-setup	新しい Workflow プロジェクト用の完全なウィザード	新しいプロジェクトを開始するとき、完全なセットアップが必要なとき
/workflow-create	Workflow クラスをすばやくスキャフォールディング	既存のプロジェクトに Workflow を追加するとき
/workflow-debug	エラーパターンに基づく対話型デバッグ	Workflow の問題をトラブルシューティングするとき
/workflow-test	Workflow をローカルおよびリモートでテスト	Workflow の動作を検証するとき

使用例：

/workflow-setup   # Full guided setup wizard
/workflow-create  # Quick workflow scaffolding
/workflow-debug   # Debug workflow issues
/workflow-test    # Test workflow execution

---

エージェント

複雑な Workflow タスクに対応する自律型エージェント：

エージェント	説明	起動条件
workflow-debugger	設定や実行時のエラーを自動検出して修正します	「workflow をデバッグ」「workflow のエラーを修正」
workflow-optimizer	パフォーマンス、コスト、信頼性を分析します	「workflow を最適化」「パフォーマンスを改善」
workflow-setup-assistant	プロジェクトのスキャフォールディングを自動化します	「workflow をセットアップ」「最初の workflow を作成」

主な機能：

• Debugger：6 段階の分析、I/O コンテキスト、シリアライゼーション、エクスポートの問題を自動修正
• Optimizer：コスト分析、信頼性のスコアリング、実行可能な推奨事項
• Setup Assistant：プロジェクトの検出、自動スキャフォールディング、検証

---

スクリプト

scripts/ ディレクトリにある自動化スクリプト：

スクリプト	用途
validate-workflow-config.sh	wrangler.jsonc の設定を検証します
test-workflow.sh	Workflow インスタンスを作成してテストします
benchmark-workflow.sh	パフォーマンスとコストを測定します
generate-workflow.sh	テンプレートから新しい Workflow をスキャフォールディングします
check-workflow-limits.sh	Cloudflare の制限に照らして検証します

使用方法：

./scripts/validate-workflow-config.sh           # Check config
./scripts/test-workflow.sh my-workflow          # Test workflow
./scripts/benchmark-workflow.sh my-workflow 10  # Benchmark 10 runs
./scripts/generate-workflow.sh MyWorkflow       # Generate scaffold
./scripts/check-workflow-limits.sh src/workflows/my-workflow.ts

---

主要な概念

WorkflowEntrypoint

すべての Workflow は WorkflowEntrypoint を継承する必要があります。

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    // Workflow logic here
  }
}

主なポイント：

• Env：環境バインディング（KV、D1 など）
• Params：Workflow インスタンスの作成時に渡される型付きペイロード
• event：id、payload、timestamp を含みます
• step：永続的な実行のためのメソッド

Step メソッド

Workflow のすべての処理は、永続性を確保するためにステップ内で実行する必要があります。

// step.do - Execute work with automatic retries
await step.do('step name', async () => {
  return { result: 'data' };
});

// step.sleep - Wait for duration
await step.sleep('wait', '1 hour');

// step.sleepUntil - Wait until timestamp
await step.sleepUntil('wait until', Date.now() + 3600000);

// step.waitForEvent - Wait for external event
const event = await step.waitForEvent('payment received', 'payment.completed', {
  timeout: '30 minutes'
});

重要：すべての I/O（fetch、KV、D1、R2）は step.do() コールバック内で実行する必要があります。

参照：すべてのパターンについては references/workflow-patterns.md を参照してください。

---

重要なルール

必ず行うこと ✅

✅ すべての I/O を step.do() 内で実行する - 永続性の確保に必須です
✅ 名前付きステップを使用する - デバッグが容易になります
✅ ステップから JSON シリアライズ可能なデータを返す - 状態の永続化に必須です
✅ 遅延には step.sleep() を使用する - setTimeout() は使用しないでください
✅ エラーを明示的に処理する - ステップのコールバック内で try/catch を使用します
✅ 恒久的な失敗には NonRetryableError を使用する - リトライを停止します

Workflow のパターン：以下については references/workflow-patterns.md を参照してください。

• 順次実行の Workflow
• 並列実行
• イベント駆動型 Workflow
• スケジュール型 Workflow
• ヒューマン・イン・ザ・ループ型 Workflow

絶対にしないこと ❌

❌ step.do() の外で I/O を行わないでください。「I/O context」エラーが発生します ❌ setTimeout() や setInterval() を使用しないでください。代わりに step.sleep() を使用してください ❌ シリアライズできないデータを返さないでください。関数や Promise などはエラーになります ❌ タイムアウトをハードコードしないでください。ワークフロー設定を使用してください ❌ NonRetryableError を無視しないでください。恒久的な失敗を示しています

---

重大なエラー上位 5 件

エラー #1：I/O コンテキストエラー ⚠️

エラー：

Cannot perform I/O on behalf of a different request

原因： step.do() コールバックの外で I/O を実行しています

解決方法：

// ❌ WRONG
const data = await fetch('https://api.example.com');
await step.do('use data', async () => {
  return data; // Error!
});

// ✅ CORRECT
const data = await step.do('fetch data', async () => {
  const response = await fetch('https://api.example.com');
  return await response.json();
});

エラー #2：シリアライゼーションエラー

エラー：

Cannot serialize workflow state

原因： ステップから JSON にシリアライズできないデータを返しています

解決方法：

// ❌ WRONG
await step.do('process', async () => {
  return { fn: () => {} }; // Functions not serializable
});

// ✅ CORRECT
await step.do('process', async () => {
  return { result: 'data' }; // JSON-serializable
});

エラー #3：NonRetryableError がスローされない

エラー： 恒久的な失敗でもワークフローが無限に再試行されます

解決方法：

import { NonRetryableError } from 'cloudflare:workers';

await step.do('validate', async () => {
  if (!isValid) {
    throw new NonRetryableError('Invalid input'); // Stop retries
  }
  return { valid: true };
});

エラー #4：WorkflowEvent が見つからない

エラー：

WorkflowEvent 'payment.completed' not found

原因： waitForEvent とトリガーのイベント名が一致していません

解決方法：

// Workflow waits for event
const event = await step.waitForEvent('wait payment', 'payment.completed', {
  timeout: '30 minutes'
});

// Trigger event with EXACT same name
await instance.trigger('payment.completed', { amount: 100 });

エラー #5：ワークフローの実行に失敗

エラー：

Workflow execution failed: Step timeout exceeded

原因： ステップが CPU 時間の上限（30 秒）を超えています

解決方法：

// ❌ WRONG
await step.do('long task', async () => {
  for (let i = 0; i < 1000000; i++) {
    // Long computation
  }
});

// ✅ CORRECT - Break into smaller steps
for (let i = 0; i < 100; i++) {
  await step.do(`batch ${i}`, async () => {
    // Process batch
  });
}

---

すべての問題：詳しい説明は references/common-issues.md を参照してください

---

よく使われるパターン

順次ワークフロー

ステップを順番に実行する基本的なワークフローです。各ステップが完了してから、次のステップが開始されます。

ユースケース：注文処理、ユーザーのオンボーディング、データパイプライン

完全な例については templates/basic-workflow.ts を読み込んでください

スケジュールされたワークフロー

step.sleep() または step.sleepUntil() を使用して、ステップ間に時間の遅延を設けるワークフローです。

ユースケース：リマインダーの連続配信、スケジュールされたタスク、遅延通知

完全な例については templates/scheduled-workflow.ts を読み込んでください

イベント駆動型ワークフロー

step.waitForEvent() で外部イベントを待ちます。必ずタイムアウトを設定し、NonRetryableError で処理してください。

const payment = await step.waitForEvent('wait payment', 'payment.completed', {
  timeout: '30 minutes'
});
if (!payment) throw new NonRetryableError('Payment timeout');

完全な例については templates/workflow-with-events.ts を読み込んでください

再試行を伴うワークフロー

恒久的な失敗（404）には NonRetryableError を、一時的な失敗（5xx）には通常の Error を使用してください。

const data = await step.do('fetch', async () => {
  const response = await fetch(url);
  if (!response.ok) {
    if (response.status === 404) throw new NonRetryableError('Not found');
    throw new Error('Temporary failure'); // Will retry
  }
  return await response.json();
});

再試行設定を含む完全な例については templates/workflow-with-retries.ts を読み込んでください

---

ワークフローのトリガー

Worker から：env.MY_WORKFLOW.create() でインスタンスを作成し、instance.status() でステータスを取得し、instance.trigger() でイベントをトリガーします。

Cron から：scheduled() ハンドラーを使用して、スケジュールに従ってワークフローインスタンスを作成します。

Worker からトリガーする完全な例については templates/worker-trigger.ts を読み込んでください Cron からトリガーする完全な例については templates/scheduled-workflow.ts を読み込んでください

---

参照情報を読み込むタイミング

references/common-issues.md：I/O コンテキスト、シリアライズ、NonRetryableError、イベント名、タイムアウトのエラーが発生したときや、ワークフローの失敗をトラブルシューティングするときに読み込みます。

references/workflow-patterns.md：複雑なオーケストレーション、承認ワークフロー、冪等性パターン、サーキットブレーカーパターンを構築するときに読み込みます。

references/wrangler-commands.md：ワークフローインスタンスの管理、停止したワークフローのデバッグ、本番環境の監視に CLI コマンドが必要なときに読み込みます。

references/production-checklist.md：デプロイの準備、デプロイ前の確認、監視やエラーハンドリングの設定が必要なときに読み込みます。

references/limits-quotas.md：インスタンス数、ステップ数、ペイロードの上限に達したとき、コストを最適化するとき、大量のワークフローを設計するときに読み込みます。

references/2025-features.md：イベントシステム、強化されたリトライ、インスタンスのライフサイクル制御、最新の Workflows 機能を使用するときに読み込みます。

references/metrics-analytics.md：監視、カスタムメトリクス、外部ロギング連携、ワークフローダッシュボードを設定するときに読み込みます。

references/troubleshooting.md：複雑なデバッグシナリオ、停止したインスタンス、体系的な診断、パフォーマンスの問題に対応するときに読み込みます。

templates/：basic-workflow.ts（逐次処理）、scheduled-workflow.ts（遅延／スリープ）、workflow-with-events.ts（waitForEvent）、workflow-with-retries.ts（カスタムリトライ）、worker-trigger.ts（Worker トリガー）、wrangler-workflows-config.jsonc（Wrangler 設定）、parallel-execution-workflow.ts（バッチ並列処理）、circuit-breaker-workflow.ts（外部呼び出しの耐障害性）

---

Wrangler コマンド

主なコマンド：wrangler workflows create、wrangler workflows instances list/describe/terminate、wrangler deploy

すべてのワークフロー管理コマンド、ワークフローの監視、停止したインスタンスのデバッグを網羅した完全な CLI リファレンスについては、references/wrangler-commands.md を読み込んでください。

---

状態の永続化

ワークフローでは、ステップ間の状態が自動的に永続化されます。手動で状態を管理する必要はありません。

export class StatefulWorkflow extends WorkflowEntrypoint {
  async run(event, step) {
    // Step 1 result is automatically persisted
    const result1 = await step.do('step 1', async () => {
      return { data: 'value' };
    });

    // Even if workflow crashes here, step 1 won't re-run
    await step.sleep('wait', '1 hour');

    // Step 2 can use step 1's result (still available after sleep)
    await step.do('step 2', async () => {
      console.log(result1.data); // 'value' - persisted!
    });
  }
}

主なポイント：

• ステップの結果は自動的に永続化されます
• 完了したステップは再実行されません（クラッシュや再起動後も同様です）
• ワークフローのライフタイム全体で状態を利用できます

---

制限

リソース	上限
ステップの CPU 時間	30 秒
ワークフローの期間	30 日
ステップのペイロードサイズ	128 KB
ワークフローのペイロードサイズ	128 KB
ワークフローあたりのステップ数	1,000
同時実行インスタンス数	ワークフローあたり 1,000
イベントのペイロードサイズ	128 KB

回避策：

• 大きなデータ：KV/R2 に保存し、ステップにはキーを渡します
• 長時間の CPU 処理：小さなステップに分割します
• ステップ数が多い場合：サブワークフローを検討します

料金

• 実行時間：100 万 GB-s あたり $0.02（Workers と同じ）
• リクエスト：100 万回あたり $0.15（ワークフローの作成＋ステップの実行）
• 状態のストレージ：料金に含まれます（追加料金なし）
• スリープ：無料（スリープ中は CPU を使用しません）

料金の例（ワークフローを 100 万回実行）：

• 各 5 ステップ = 500 万リクエスト = $0.75
• 各ステップ 10ms = 50GB-s = $0.001
• 合計：ワークフロー 100 万回あたり約 $0.75

---

トラブルシューティング

「I/O context」エラー

解決策：すべての I/O を step.do() コールバック内に移動します → references/common-issues.md #1 を参照してください

「Serialization error」

解決策：ステップからは JSON にシリアライズ可能なデータのみを返します → references/common-issues.md #2 を参照してください

ワークフローが無限にリトライする

解決策：恒久的な失敗には NonRetryableError をスローします → references/common-issues.md #3 を参照してください

「WorkflowEvent not found」

解決策：イベント名が完全に一致していることを確認します → references/common-issues.md #4 を参照してください

「Step timeout exceeded」

解決策：長時間の計算を小さなステップに分割します → references/common-issues.md #5 を参照してください

---

本番環境向けチェックリスト

デプロイ前の10項目チェックリスト：I/O コンテキストの分離、JSON シリアライズ、NonRetryableError の使用、イベント名の一貫性、ステップの実行時間制限、エラー処理、再試行設定、タイムアウト、ワークフローの命名、モニタリング。

詳細な説明、コード例、検証手順、デプロイワークフローを含む完全なチェックリストについては、references/production-checklist.md を読み込んでください。

---

公式ドキュメント

ワークフロー：https://developers.cloudflare.com/workflows/ • API リファレンス：https://developers.cloudflare.com/workflows/reference/ • 例：https://developers.cloudflare.com/workflows/examples/ • ブログ：https://blog.cloudflare.com/cloudflare-workflows/