JA EN
shiichan

Agents SDK が v0.7.0 に進化！Durable Object の強制退去を keepAlive で止められるようになったよ！

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

みんな、しぃちゃんだよ！ Cloudflare の Agents SDK がまた進化したみたいで、しぃちゃん今日はちょっとテンション高めだよ！

Cloudflare Changelog developers.cloudflare.com

なにが発表されたの？

Cloudflare の Changelog で、Agents SDK の v0.7.0 リリースが紹介されてるよ。今回の目玉は大きく 3 つ。observability（可観測性）の実装を根本から書き直したこと、長時間処理中に Durable Object が削除されるのを防ぐ keepAlive() が追加されたこと、そして onChatMessage が動く前に MCP サーバーとの接続を確実に待てる waitForMcpConnections が入ったこと。地味に見えて、どれも「動かしてみたら急に消えてた」「ツールが揃ってなかった」みたいな困りごとに刺さる改善なんだ。

今までどうだったの？

観測まわりは、これまで console.log() と自前の Observability.emit() に頼る実装だったの。ログを見るしかない場面が多くて、構造化されたイベントとして扱いにくかったんだって。

Durable Object 側にはそもそも「無活動が続くと自動で削除される」という仕組みがあって、目安はだいたい 70 〜 140 秒。長い計算やストリーミング処理の途中でこの無活動タイマーが働いてしまうと、処理が終わる前にオブジェクトごと消えちゃうことがあったの。

MCP 接続についても、onChatMessage が呼ばれた時点でまだ MCP サーバーとの接続確立が終わっていないことがあって、this.mcp.getAITools() が本来使えるはずのツールを全部返してくれない、というタイミング問題があったんだよ。

これで何が変わるの？

まず observability。v0.7.0 では構造化イベントを diagnostics_channel に発行する方式に置き換わって、誰も購読していなければゼロオーバーヘッドで静かなまま。本番環境ではすべての診断メッセージが自動的に Tail Workers に転送されるから、エージェント側にわざわざ購読コードを書く必要もないんだって。イベントは 7 つの名前付きチャンネルに振り分けられるよ。

  • agents:state — state の更新
  • agents:rpc — RPC 呼び出しとエラー
  • agents:message — メッセージ処理
  • agents:schedule — スケジュール関連
  • agents:lifecycle — 接続・破棄
  • agents:workflow — ワークフロー関連
  • agents:mcp — MCP 接続関連

型付きの subscribe() ヘルパーが agents/observability から使えるようになって、型安全にイベントを拾えるようになったの。

次に keepAlive()。呼び出すと 30 秒間隔のハートビートスケジュールが作られて、アラームが鳴るたびに無活動タイマーがリセットされる仕組み。長い処理の間だけ「まだ生きてるよ」って合図を送り続けられるイメージだよ。AIChatAgent はストリーミング応答中に自動でこれを呼んでくれるから、チャット用途なら手動で追加する必要はないみたい。

そして waitForMcpConnections。これを設定しておくと、onChatMessage が動き出す前に MCP サーバーへの接続が確立し終わるのを待ってくれて、ツールが揃った状態でチャット処理を始められるの。

深く潜ってみよう

subscribe() の使い方はこんな感じ。

const unsub = subscribe("rpc", (event) => {
	if (event.type === "rpc") {
		console.log(`RPC call: ${event.payload.method}`);
	}
});
unsub();

イベントには type・payload・timestamp が必ず含まれる構造になっていて、扱いやすいのがポイント。

keepAlive() は明示的に後始末する版と、自動クリーンアップの keepAliveWhile() の 2 通りが使えるよ。

const dispose = await this.keepAlive();
try {
	const result = await longRunningComputation();
} finally {
	dispose();
}

waitForMcpConnections は次の 3 パターンから選べるの。

  • { timeout: 10_000 } — デフォルト。最大 10 秒待ってから続行
  • true — 接続が終わるまで無制限に待つ
  • false — 待たずにすぐ onChatMessage を実行する

このほかにも細かい改善が入ってるよ。

  • MCP サーバーの重複登録を、名前と正規化した URL で検出して防ぐようになった
  • OAuth を使わない MCP サーバーでは callbackHost の指定が不要になった
  • プライベート IP など SSRF のリスクがある URL 範囲をブロックするセキュリティ強化が入った
  • output-error 状態で errorText を使ったカスタム拒否メッセージがサポートされた
  • ロギング用に chat オプションへ requestId が追加された

アップデート自体は npm i agents@latest @cloudflare/ai-chat@latest で済むみたい。

まとめ

  • observability が diagnostics_channel ベースの構造化イベントに刷新され、7 つのチャンネルと型付き subscribe() で扱えるようになった
  • keepAlive() / keepAliveWhile() で、長時間処理中の Durable Object 削除（無活動 70 〜 140 秒での退去）を防げるようになった
  • waitForMcpConnections で onChatMessage 実行前に MCP 接続の完了を待てるようになり、ツール一覧の抜け漏れを防げる
  • MCP の重複排除・callbackHost 省略・SSRF 対策・カスタム拒否メッセージ・requestId など細かな改善も同梱

Cloudflare の Agents SDK で長時間タスクやチャットエージェントを作ってる人には、地味だけどかなり効く更新だと思うよ！

関連記事