更新日志

Agents SDK ↗ 的最新版本带来了更可靠的对话恢复、修复了重连时的 Agent 状态同步、添加了 Think 的持久化提交、暴露了路由重试配置，并为 Voice agents 添加了连接控制。

@cloudflare/ai-chat 现在在浏览器或客户端流中断时保持服务端 turn 继续运行。这对于长时间运行的 AI 响应场景非常有用，例如用户刷新页面、关闭标签页或临时断线。调用 stop() 仍会取消服务端 turn。

如果浏览器或客户端中止也应取消服务端 turn，请设置 cancelOnClientAbort: true：

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

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

主要 bug 修复：

• 对话流恢复协商不再在 replay 与关闭的 WebSocket 连接竞争时抛出异常。
• 恢复的对话续传不再在原始 socket 在终端响应前断开时，导致 useAgentChat 卡在流式传输状态。
• 审批自动续传保留推理部分，并在最终消息中持久化续传推理。
• 当恢复的流从备用观察路径切换到传输拥有的流时，isServerStreaming 现在能正确重置。

agents@0.12.4 防止在 WebSocket 连接设置期间出现重复的初始状态帧。这避免了过时的初始状态消息覆盖客户端已发送的状态更新。

当工具调用跨越 Durable Object 重启时，Agent 恢复也更加可靠。恢复现在会将用户完成钩子推迟到 agent 启动后，并隔离钩子失败，因此一个失败的钩子不会阻止其他恢复的运行完成。

getAgentByName() 现在支持 routingRetry，用于处理瞬态 Durable Object 路由失败：

import { getAgentByName } from "agents";

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

import { getAgentByName } from "agents";

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

@cloudflare/think 现在支持持久化的程序化提交。submitMessages() 提供持久化接受、幂等重试、状态检查、取消和清理功能，适用于应在调用方返回后继续运行的服务器驱动 turn。

Think.chat() RPC turn 现在在对话恢复 fiber 内运行并持久化其流式数据块。中断的子 agent turn 可以恢复部分输出，而不必从头开始。

ChatOptions.tools 已从 TypeScript API 中移除。请在子 agent 上定义持久化工具，或使用 agent 工具进行编排。遗留调用者传入的运行时 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",
			}),
		};
	}
}

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

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

@cloudflare/voice 为 useVoiceAgent 添加了 enabled 选项。React 应用现在可以延迟创建和连接 VoiceClient，直到所需条件（如能力令牌）就绪。

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

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

此版本还修复了 Workers AI 语音转文字会话的边界情况，以及 AI SDK textStream 响应中 withVoice 文本流的问题。

• Streamable HTTP 路由 — 当没有独立 SSE 流可用时，服务器到客户端的请求现在通过原始 POST 流路由。
• 结构化工具输出 — 裁剪旧消息或超大持久化行时会保留工具输出的形状。
• 非对话 Think 工具步骤 — Think agent 工具子项可在不发出助手文本的情况下完成，并可通过 getAgentToolOutput 返回结构化输出。
• 子 agent 调度 — 当拥有 facet 注册条目不再存在时，过时的子 agent 调度行会被清理。
• @cloudflare/codemode — 添加了带有 iframe sandbox 执行器的浏览器安全导出，并在 sandbox 内解析 OpenAPI 规范以避免 Worker Loader RPC 大小限制。

升级到最新版本：

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

更多信息请参阅 Agents API 参考 和对话 agents 文档。