CurrentStack
#agents#cloud#edge#serverless#reliability#observability

Workers Agents SDK v0.8 実践: Idempotent Schedulingで作る壊れないエージェント運用

Cloudflareが2026年3月に公開したAgents SDK v0.8系の更新は、見た目のDX改善だけではありません。特に stateの直接参照 と idempotentなschedule制御 は、実運用で頻発する「二重実行」「再接続時の取りこぼし」「障害調査不能」をまとめて潰せる重要な土台です。

参照:

なぜこのアップデートが本番で効くのか

現場で起きる事故の多くは、モデルの回答品質ではなく制御プレーン側の設計不足です。例えば以下のような障害が典型です。

  • 同じ通知が2回送信される
  • 同じジョブが再起動後に重複登録される
  • UI上は処理中なのに、実際は失敗済みで止まっている
  • リトライが暴走してトークンコストだけ膨らむ

これらは「状態管理」と「再実行制御」を明示的に設計すると、再現率高く改善できます。v0.8の機能はその実装コストを一段下げる更新です。

推奨アーキテクチャ

以下の分割が、運用と監査の両方で扱いやすい構成です。

  • Ingress Worker: 認証・認可、入力検証、レート制御
  • Durable Object (Agent Core): 状態遷移の唯一の書き込み点
  • Workers AI: 推論実行
  • Workflows: 長時間処理、再開可能なジョブ管理
  • R2/KV: スナップショット、要約、検索用メタデータ

ポイントは、状態更新を「複数箇所で書く」のではなく、Durable Objectの遷移ハンドラに集中させることです。

状態モデルを先に決める

実装前に最低限これだけは定義してください。

  • phase（idle/planning/executing/waiting_approval/done/failed）
  • requestId（全ログで共通に追跡）
  • revision（単調増加）
  • deadline（soft/hard）
  • budget（token/cost）
  • pendingJobs（予約ジョブの一覧）

revisionを持たせることで、古いクライアントからの更新を弾けます。障害時にも「どの遷移で破綻したか」を追跡しやすくなります。

Idempotent Schedulingの実装ルール

schedule呼び出しを安全にする最低ルールは3つです。

  1. スケジュールキーを決定論的に作る
  2. リトライ時も同じキーを再利用する
  3. 外部副作用（通知、書き込み、API呼び出し）にも同じキー体系を持たせる

推奨キー形式:

  • {requestId}:{operation}:{target}

例:

  • req_0187:retry-tool:github-comment:issue-932

この規約だけで、再接続や再起動由来の重複実行をかなり減らせます。

よくある失敗と対策

1. 再起動後の重複通知

症状: 同じSlack通知が複数回飛ぶ

対策:

  • idempotent schedule必須化
  • 外部送信前にoutboxテーブルで重複キー検査
  • 送信成功時に確定ログを追記

2. stale state問題

症状: UIは進行中、実体は既にfailed

対策:

  • agent.stateを単一参照源として扱う
  • revision付き表示にする
  • 古いrevisionの更新要求をreject

3. リトライ暴走

症状: エラーが直らないのに課金だけ増える

対策:

  • エラー種別ごとに上限回数を分離
  • soft deadline超過で低優先度化
  • hard deadline超過で強制停止

4. 監査不能

症状: 誰の操作で何が起きたか追えない

対策:

  • immutableなイベントジャーナルを保持
  • actor/requestId/phase遷移/policy判定を記録
  • 監査ログを本番データと分離保管

30日導入プラン

Week 1: 現状可視化

  • 重複実行率、失敗率、平均処理時間を計測
  • requestIdの貫通を実装
  • phase図を文書化

Week 2: scheduling移行

  • schedule呼び出し箇所を棚卸し
  • 遷移ハンドラ経由に一本化
  • key生成関数を共通化

Week 3: リトライ制御

  • エラー分類別のポリシー導入
  • deadlineとbudgetを状態に統合
  • アラート閾値設定

Week 4: 検証と運用

  • 強制再起動カオステスト
  • 重複実行の再現テストをCI化
  • 運用Runbook（検知→切り分け→復旧）を整備

KPIの置き方

最低限、次の指標は日次で追ってください。

  • 重複抑止件数（suppress count）
  • 外部副作用の重複率
  • phase遷移のP95レイテンシ
  • 初回失敗後の復帰率
  • リトライ起因コスト

「壊れにくいエージェント」は、生成品質だけでなく制御品質で決まります。2026年の運用では、idempotencyを後付けにしないことが最短の近道です。

おすすめ記事

← 記事一覧へ戻る