Cloudflare Agents SDK v0.12.4！ページ更新してもチャットが止まらなくなったよ

こんにちは、しぃちゃんだよ！今日は Cloudflare の Agents SDK のアップデート情報を見つけたよ。地味に見えるけど、実はエージェントを本番運用するうえでかなり嬉しい修正が詰まってるの！

Cloudflare Changelog developers.cloudflare.com

なにが発表されたの？

Cloudflare の Changelog で、Agents SDK 関連パッケージ agents・@cloudflare/ai-chat・@cloudflare/think・@cloudflare/voice の v0.12.4 リリースが発表されたよ。今回の内容はこんな感じ！

• チャットリカバリーの信頼性向上
• 再接続時の Agent 状態同期の修正
• @cloudflare/think の耐久的なメッセージ提出(submitMessages)
• getAgentByName() のルーティング再試行設定
• @cloudflare/voice の接続制御(enabled オプション)

新機能というより「今まで細かく困ってた挙動」をまとめて直しにきたアップデートだよ。

今までどうだったの？

AI エージェントとチャットしてるとき、ユーザーがページを更新したりタブを閉じたり、通信が一瞬切れたりすることってよくあるよね。今までは、そういうクライアント側の切断が起きると、サーバー側で進んでいた応答生成まで巻き込まれて中断されがちだったの。長い応答を生成している途中でうっかりリロードしちゃったら、最初からやり直し……なんてこともあったんだよ。

そのほかにも、WebSocket の再接続時に初期状態フレームが重複して送られてきたり、Durable Object へのルーティングが一時的に失敗してもリトライする手段がなかったり、地味に開発者を悩ませるポイントがいくつもあったの。

これで何が変わるの？

• @cloudflare/ai-chat のチャットリカバリー改善 — ブラウザやクライアント側のストリームが中断されても、サーバー側のターンはそのまま実行を続けるようになったよ。ユーザーがページを更新したりタブを閉じたり、一時的に接続が切れたりしても、長時間かかる AI 応答が無駄にならないの
• agents@0.12.4 の状態同期修正 — WebSocket 接続のセットアップ中に初期状態フレームが重複して送られる問題がなくなって、クライアントが送った状態更新が古い初期状態で上書きされてしまう事故を防げるようになったよ
• getAgentByName() のルーティング再試行 — Durable Object への一時的なルーティング失敗に対応できるようになったよ
• @cloudflare/think の耐久的な提出(submitMessages()) — 呼び出し元が処理を返したあとも継続する、サーバー駆動のターンに対応したよ
• @cloudflare/voice の接続制御 — Voice エージェントの接続開始タイミングを自分でコントロールできるようになったよ

深く潜ってみよう

チャットリカバリー周りは、明示的に stop() を呼べば今まで通りサーバーターンもキャンセルされるよ。もしクライアント側の中断でサーバーターンも一緒にキャンセルしたい場合は、cancelOnClientAbort: true を設定すればいいの。

const chat = useAgentChat({
	agent: "assistant",
	name: "user-123",
	cancelOnClientAbort: true,
});

今回のリリースには、このほかにも細かいバグ修正がいろいろ入ってるよ。

• チャットストリームの再開交渉が、リプレイと WebSocket クローズが同時に起きてもエラーを出さなくなった
• 復旧されたチャット継続で、元のソケットが終端応答の前に切断しても useAgentChat がストリーミング状態のまま固まらなくなった
• 承認の自動継続が推論(reasoning)部分をきちんと保持して、最終メッセージにも継続の推論内容が残るようになった
• isServerStreaming が、フォールバックのオブザーバー経由からトランスポート専有のストリームに切り替わったときも正しくリセットされるようになった

Agent の状態同期については、ツール呼び出しが Durable Object の再起動をまたいでも復旧の信頼性が上がったよ。復旧処理はユーザーの finish フックの実行をエージェント起動後まで遅らせるようになっていて、1 つのフックが失敗しても他の復旧中のランがブロックされないよう分離されているの。

ルーティング再試行はこんな風に使えるよ。

import { getAgentByName } from "agents";

const agent = await getAgentByName(env.AssistantAgent, "user-123", {
	routingRetry: {
		maxAttempts: 3,
	},
});

@cloudflare/think では、submitMessages() が耐久的な受付・冪等なリトライ・状態確認・キャンセル・クリーンアップまで面倒を見てくれるようになったよ。さらに Think.chat() の RPC ターンがチャットリカバリーのファイバー内で動くようになって、ストリームのチャンクも永続化されるようになったの。中断されたサブエージェントのターンは、最初からやり直すんじゃなくて途中の出力を復旧できるようになったよ。

一方で、TypeScript API から ChatOptions.tools が削除されたよ。耐久的なツールは子エージェント側に定義するか、オーケストレーション用の agent tools を使う必要があるの。レガシーな呼び出し元が options.tools を渡した場合は、警告付きで無視される仕様になってるよ。

メッセージ剪定のデフォルト挙動も変わっていて、@cloudflare/think はデフォルトでは pruneMessages({ toolCalls: "before-last-2-messages" }) をモデルコンテキストに適用しなくなったの。従来のデフォルトだと、長いマルチターンのやり取りでクライアント側のツール結果が消えてしまうことがあったんだって。truncateOlderMessages は引き続き働くから、コンテキストのコストが際限なく膨らむ心配はないよ。もし従来の積極的な剪定を使いたい場合は、beforeTurn から自分で呼び出せばいいの。

import { Think } from "@cloudflare/think";
import { pruneMessages } from "ai";

export class MyAgent extends Think {
	beforeTurn(ctx) {
		return {
			messages: pruneMessages({
				messages: ctx.messages,
				toolCalls: "before-last-2-messages",
			}),
		};
	}
}

@cloudflare/voice には useVoiceAgent 向けの enabled オプションが追加されたよ。キャパビリティトークンなどの前提条件が揃うまで、VoiceClient の作成と接続を遅らせられるようになったの。

const voice = useVoiceAgent({
	agent: "MyVoiceAgent",
	enabled: Boolean(token),
});

このほかにも、Workers AI の音声認識(speech-to-text)のエッジケース修正や、AI SDK の textStream からの withVoice テキストストリーミング修正、サーバーからクライアントへのリクエストがスタンドアロン SSE ストリーム無しでも POST ストリーム経由でルーティングされる改善、構造化ツール出力の形状保持、非チャット系の Think ツールステップ対応、不要になったサブエージェントスケジュールの整理なども入っているよ。アップデートは次のコマンドで一気にできるよ。

npm i agents@latest @cloudflare/ai-chat@latest @cloudflare/think@latest @cloudflare/voice@latest

まとめ

今回の Agents SDK v0.12.4 のポイントをおさらいするね。

• チャットリカバリー改善: クライアントの切断があってもサーバーターンは続行(cancelOnClientAbort で挙動を選べる)
• Agent 状態同期の修正: WebSocket 再接続時の初期状態フレーム重複を解消
• getAgentByName() にルーティング再試行(routingRetry)を追加
• @cloudflare/think に耐久的な submitMessages() を追加、メッセージ剪定のデフォルトも変更
• @cloudflare/voice に接続タイミングを制御できる enabled オプションを追加

チャットや音声のエージェントを Cloudflare 上で運用していて、ネットワークの瞬断や再接続まわりの挙動に地味に悩んでた開発者さんには、まさに刺さるアップデートだと思うな！