JA EN
shiichan

Agents SDK でサブエージェントをバックグラウンド実行できるようになったよ！

Cloudflare Changelog ★★★★ Markdown で見る
#cloudflare#ai#serverless

やっほー、しぃちゃんだよ！

Cloudflare Changelog developers.cloudflare.com

今日は Cloudflare の Agents SDK のアップデートを見つけたよ。エージェントを作ってる人にはうれしいニュースだから、さっそく紹介するね！

なにが発表されたの？

Cloudflare の Changelog によると、Agents SDK v0.17.0 がリリースされて、長時間のタスクを裏側で動かす「バックグラウンドサブエージェント」と、チャットのターンを受け付ける入り口を一本化する runTurn が新しく入ったよ。さらに、デプロイ・エビクション・再接続をまたいでもチャットエージェントが動き続けるための、信頼性まわりの修正もたくさん入ってるの。

今までどうだったの？

これまで Agents SDK でサブエージェントを動かすと、その処理が終わるまで親のターンがブロックされちゃう構造だったみたい。長い作業を任せたいときも、進捗を細かく確認する手段が用意されてなかったの。

また、メッセージの保存・継続、durable な送信、チャットのストリーミングといった「ターンの受け付け」がそれぞれ別々の経路で処理されていて、共通の受付ロジックがなかったんだって。これがネストしたブロッキング呼び出しを招き、デッドロックの原因になることもあったみたい。再接続がターンの途中にかぶさると状態が固まってしまう、という不安定さも指摘されてたよ。

これで何が変わるの？

v0.17.0 では、サブエージェントを親ターンをブロックせずに「デタッチ」した状態で動かせるようになったよ。デプロイやエビクションをまたいでも、自己スケジュールする仕組み(reconcile backbone)のおかげで処理が生き残るの。長時間かかるインポート処理やバッチ処理を、チャットの応答を止めずに裏で走らせられるってことだね。

ターンの受け付けも runTurn に一本化されたことで、経路ごとにバラバラだった admission ロジックが共通化されて、デッドロックにつながるネスト呼び出しを防げるようになったよ。開発者からすると、エージェントの実装で気を付けるポイントがぐっと減るはず！

深く潜ってみよう

バックグラウンドサブエージェントまわりの主な仕組みはこんな感じだよ。

  • detached オプションで実行を設定でき、例として detached: { onFinish: "onImportDone", maxBudgetMs: 3600000 } のように書ける
  • maxBudgetMs で実行時間の上限を決められる(デフォルトは 24 時間)
  • cancelAgentTool(runId) で実行中のサブエージェントを途中キャンセルできる
  • 子エージェント側は this.reportProgress() を呼ぶと、fraction・phase・message を含む進捗が AgentToolRunState.progress 経由で見えるようになる
  • 完了時に呼ばれる onFinish コールバックは、"completed" "error" "aborted" "interrupted" のいずれかのステータスを受け取れる
  • notify: true を設定すると、バックグラウンド実行の完了メッセージがチャットに自動で差し込まれる

runTurn(options) は次の 3 モードをまとめた入り口になってるよ。

  • "wait" — メッセージ保存や直前ターンの継続向け
  • "submit" — durable なメッセージ送信向け
  • "stream" — チャットのストリーミング向け

信頼性まわりでは、以下のような修正・強化が入ったみたい。

  • 任意の chatStreamStallTimeoutMs によるストリーム停止検知(ウォッチドッグ)
  • サーバー呼び出しが失敗して中断されたツールコールを、再度推論に戻す前に修復する処理
  • 再接続がターン処理の途中にかぶさったときに状態が固まる問題の解消
  • 復旧処理の途中で接続してきたクライアントにも、正しい isRecovering 状態が見えるように改善
  • WebSocket が完全に失敗したケースを connectionError / onConnectionError で扱えるように

そのほかにも、React 用の共通コアが agents/chat/react エントリポイントとして提供されたり、AI SDK が任意の peer dependency 扱いになって基本のランタイムでは必須じゃなくなったり、Code Mode のエグゼキュータのタイムアウトが 30 秒から 60 秒に伸びたり、といった細かい改善も入ってるよ。MCP のコールバックがエージェントの非同期コンテキスト外でも動くようになったのと、音声ターンで AI SDK の fullStream レスポンスに対応したのも地味にうれしいポイントだね。実験的な機能として、サーバーアクションとチャンネルのフレームワークも入ってるけど、こちらはまだ API が変わる可能性があるみたい。

まとめ

今回のアップデートのポイントはこんな感じだよ。

  • サブエージェントをバックグラウンドで実行でき、デプロイ・エビクションをまたいでも継続する
  • maxBudgetMs と cancelAgentTool で暴走を防ぎつつ、reportProgress で進捗も見える
  • runTurn がターン受け付けを一本化し、デッドロックの原因になっていたネスト呼び出しを防ぐ
  • ストリーム停止検知や再接続まわりの修正で、チャットエージェントがより安定して動く

Cloudflare Workers 上でエージェントを組んでいる人、特に長時間タスクを裏で走らせたい人にとって、試す価値のあるアップデートだよ！

関連記事