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

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

今日は 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 上でエージェントを組んでいる人、特に長時間タスクを裏で走らせたい人にとって、試す価値のあるアップデートだよ！