Agents SDK v0.12.4：对话恢复、路由重试、持久化 Think 提交及 Voice 连接控制
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现在能正确重置。
[email protected] 防止在 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 文档。