Agents, Workers - Agents SDK v0.12.4: chat recovery, routing retries, durable Think submissions, and Voice connection control

Cloudflare の Agents SDK ↗ の最新リリース（v0.12.4）は、チャット回復の信頼性向上、再接続時の Agent 状態同期の修正、Think の耐久的な提出の追加、ルーティング再試行設定の公開、Voice エージェントの接続制御を提供します。

チャット回復の改善

@cloudflare/ai-chat は、ブラウザやクライアントのストリームが中断された場合でもサーバー側のターンを継続して実行するようになりました。長時間実行される AI 応答（ユーザーがページを更新、タブを閉じる、または一時的に接続を失う場合）で有用です。stop() を呼ぶと依然としてサーバーターンはキャンセルされます。

ブラウザやクライアントの中断でもサーバーターンをキャンセルしたい場合は cancelOnClientAbort: true を設定してください。

例（JavaScript / TypeScript）

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

主なバグ修正

• リプレイが閉じた WebSocket と競合する場合にチャットストリームの再開交渉が例外を投げなくなりました。
• 回復したチャット継続が、元のソケット切断時に useAgentChat をストリーミング状態のままにしなくなりました。
• 承認の自動継続が推論部分を保持し、最終メッセージに継続推論を永続化します。
• 再開されたストリームがフォールバックのオブザーバーパスからトランスポートが所有するストリームに移行した場合でも、isServerStreaming が正しくリセットされます。

Agent 状態とルーティングの修正

• agents@0.12.4 は WebSocket 接続セットアップ中の重複する初期状態フレームの送出を防ぎます。これにより、クライアントが既に送信した状態更新を古い初期状態メッセージが上書きすることを回避します。
• ツール呼び出しが Durable Object の再起動にまたがる場合でも、Agent の回復がより堅牢になりました。回復時にはユーザーの finish フックを Agent の起動後まで遅延させ、フックの失敗を分離して、1 つの失敗したフックが他の回復済み実行の最終化を妨げないようにします。

getAgentByName() は一時的な Durable Object ルーティング障害に対する routingRetry をサポートするようになりました。例:

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

Durable Think 提出

@cloudflare/think はプログラム的な耐久的提出をサポートします。submitMessages() は、耐久的受け入れ、冪等な再試行、状態検査、キャンセル、および呼び出し後に継続すべきサーバー駆動ターンのクリーンアップを提供します。

• Think.chat() の RPC ターンはチャット回復ファイバー内で実行され、ストリームチャンクを永続化します。
• 中断されたサブエージェントのターンは部分出力を回復できるようになり、最初からやり直す必要がなくなります。
• ChatOptions.tools は TypeScript API から削除されました。耐久的なツールは子エージェント上で定義するか、オーケストレーションにはエージェントツールを使用してください。レガシー呼び出しで渡されたランタイムの options.tools の値は警告を出した上で無視されます。

Think のメッセージ剪定（pruning）挙動の変更

@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",
            }),
        };
    }
}

（TypeScript でも同様に定義可能です）

Voice エージェントの接続制御

@cloudflare/voice は useVoiceAgent に enabled オプションを追加しました。React アプリは、Capability トークンなどの前提条件が準備できるまで VoiceClient の作成と接続を遅延させることができます。

例（JavaScript / TypeScript）

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

このリリースでは、Workers AI の音声→テキストセッションのエッジケースと、AI SDK の textStream 応答からの withVoice テキストストリーミングの修正も含まれます。

その他の改善点

• Streamable HTTP routing — 単独の SSE ストリームが利用できない場合、サーバー→クライアント要求は発信元の POST ストリームを経由してルーティングされます。
• Structured tool output — メッセージの古い部分やサイズ超過で永続化された行を切り詰める際にも、ツール出力の形状が保持されます。
• Non-chat Think tool steps — Think の agent-tool 子はアシスタントのテキストを出力せずに完了でき、getAgentToolOutput 経由で構造化出力を返せます。
• Sub-agent schedules — 所有する facet registry エントリが存在しなくなった stale なサブエージェントのスケジュール行は剪定されます。
• @cloudflare/codemode — iframe サンドボックス実行器を使ったブラウザ安全なエクスポートを追加し、サンドボックス内で OpenAPI 仕様を解決して Worker Loader RPC のサイズ制限を回避します。

アップグレード

最新バージョンに更新するには：

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

詳細は Agents API リファレンスおよび Chat agents ドキュメントを参照してください。