跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

更新日志

Cloudflare 的最新更新与改进。

查看 RSS 订阅源订阅 RSS
Back to all posts

Agents SDK 添加了后台子 agent 和统一的轮次入口点

AgentsWorkers

Agents SDK ↗ 的最新版本使得在后台运行长时间工作、通过一个入口点驱动轮次以及让聊天 agent 在部署、驱逐和重新连接期间保持正常工作变得更加容易。

此版本添加了一等的独立（后台）子 agent 运行（具有实时进度和持久里程碑）、单个 runTurn 轮次准入入口点，以及大量的恢复和可靠性修复，这些修复继续将 @cloudflare/think 和 @cloudflare/ai-chat 收敛到同一个模型上。

具有进度和里程碑的后台子 agent

runAgentTool 现在可以派发一个子 agent，而不会阻塞调用轮次。独立的运行会立即返回一个句柄，并由一个持久的、在驱逐中存活的骨干（backbone）所拥有，而不是在派发轮次结束时被放弃。

class OrdersAgent extends Think {
	async startImport(input) {
		// Fire-and-forget, or wire a durable completion callback
		// (by method name, like schedule()):
		await this.runAgentTool(ImportAgent, {
			input,
			detached: { onFinish: "onImportDone", maxBudgetMs: 60 * 60 * 1000 },
		});
	}

	// result.status: "completed" | "error" | "aborted" | "interrupted"
	async onImportDone(run, result) {}
}
class OrdersAgent extends Think {
	async startImport(input) {
		// Fire-and-forget, or wire a durable completion callback
		// (by method name, like schedule()):
		await this.runAgentTool(ImportAgent, {
			input,
			detached: { onFinish: "onImportDone", maxBudgetMs: 60 * 60 * 1000 },
		});
	}

	// result.status: "completed" | "error" | "aborted" | "interrupted"
	async onImportDone(run, result) {}
}

亮点：

  • 持久的、在正常路径上仅执行一次的完成：通过热快速路径以及一个在驱逐和部署中存活的自调度对齐骨干。
  • 有边界。 绝对的 maxBudgetMs 上限（默认 24 小时）和 cancelAgentTool(runId) 可以防止被放弃的运行永远占用并发槽位。
  • detached: { notify: true } 允许已完成的后台运行将消息注入回聊天中，以便模型对结果做出反应 —— 无需手动连接 onFinish。

子 agent 还可以报告运行中进度，这些进度会通过它们自己的轮次流返回到父级连接的客户端：

// Inside the child sub-agent:
await this.reportProgress({
	fraction: 0.6,
	phase: "deploying",
	message: "Generating menu page…",
});
// Inside the child sub-agent:
await this.reportProgress({
	fraction: 0.6,
	phase: "deploying",
	message: "Generating menu page…",
});

进度通过 useAgentToolEvents 呈现在 AgentToolRunState.progress 上，因此后台运行托盘（tray）可以渲染实时进度条而无需深入查看，并且最新快照会被持久化以便在驱逐后进行检查。命名一个 milestone（里程碑）会将一个信号提升为持久的、可重放的行，并且 detached: { onMilestones } 可以将里程碑呈现为合成聊天消息（对于简单的状态行使用 "narrate"，或者使用 "react" 来驱动模型轮次）。

轮次的单一入口点：runTurn

@cloudflare/think 添加了一个公共 runTurn(options) 外观（facade），将轮次准入统一在单个 mode 后面：

await this.runTurn({ mode: "wait", messages }); // saveMessages / continueLastTurn
await this.runTurn({ mode: "submit", messages }); // durable submitMessages
await this.runTurn({ mode: "stream", messages }); // chat()
await this.runTurn({ mode: "wait", messages }); // saveMessages / continueLastTurn
await this.runTurn({ mode: "submit", messages }); // durable submitMessages
await this.runTurn({ mode: "stream", messages }); // chat()

stream 模式接受数组和函数输入以匹配 wait 模式，所有入口点现在都通过共享的内部准入路径进行路由，该路径在之前可能导致死锁的嵌套阻塞准入上会抛出清晰的错误。

恢复和可靠性

此版本的很大一部分继续强化恢复，并将 @cloudflare/think 和 @cloudflare/ai-chat 收敛到同一个模型上：

  • 流停滞看门狗。 AIChatAgent 可以通过选择启用的 chatStreamStallTimeoutMs 看门狗检测并从挂起的模型/传输流中恢复。启用 chatRecovery 后，停滞将路由到部署或驱逐使用的相同有界恢复机制中；否则，它会作为终端流错误显现，以便清除加载指示器。
  • 中断的工具调用修复。 AIChatAgent 现在在重新进入推理之前会修复带有已死服务器工具调用的脚本（与 @cloudflare/think 保持一致），因此恢复的轮次不再因 AI_MissingToolResultsError 而失败。可重写的 repairInterruptedToolPart(part) Hook 允许应用程序自定义修复后的形状。
  • 重连后状态卡住。 修复了当重连与已接受但尚未开始流式传输的轮次发生竞态时，AI SDK status 卡住的问题，因此 UI 现在会渲染进行中的轮次，而不是卡在 ready。
  • 连接时的实时 “recovering…”。 AIChatAgent 现在会将恢复状态回放到在恢复途中连接的客户端，因此 useAgentChat 的 isRecovering 会立即反映进行中的恢复，而不是显得冻结。
  • 终端连接失败。 客户端在终端 WebSocket 关闭事件上停止重新连接，并通过 AgentClient、useAgent 和 useAgentChat 上的 connectionError / onConnectionError 暴露它们。
  • Agent-tool 子节点恢复。 在部署后，健康的长期运行子 agent 运行不再被作为 interrupted（中断）放弃（对于 @cloudflare/think 和 AIChatAgent 皆是如此）。
  • 来自子 agent 侧面（facets）的 Workflow。 Agent Workflows 现在可以从子 agent 侧面（facets）开始，回调和 Workflow RPC 会被路由回源侧面。
  • 此外还有前向进度信用收敛、广播优先放弃顺序、事件驱动的自动继续屏障，以及 AIChatAgent 中的结构化行大小压缩。

其他改进

  • 共享聊天 React 核心。 新的 agents/chat/react 入口暴露了 useAgentChat、传输辅助函数和共享线缆（wire）类型，具有用于服务器权威脚本存储的 syncMessagesToServer。@cloudflare/think/react and @cloudflare/ai-chat/react 现在只是它的薄包装器。
  • 可选的 ai 同级依赖。 根 agents and @cloudflare/codemode 运行时不再引用 AI SDK 类型，因此它们可以在不安装 ai / zod 的情况下打包；特定于 AI 的入口点在导入时仍然需要同级依赖。just-bash 同样移动到了仅由 skills bash 运行器使用的可选同级依赖中。
  • Code Mode。 默认的 DynamicWorkerExecutor 超时时间从 30 秒增加到 60 秒，每次运行后现在会销毁动态加载的 Worker 及其 RPC 存根（stub）（修复了不稳定的隔离区关闭断言），连接器导入已被清理，并且外部 MCP 工具调用上下文会被传递给 openApiMcpServer 请求回调。
  • Voice。 Voice 轮次现在支持 AI SDK fullStream 响应（并在使用 textStream 时发出警告）。
  • MCP。 McpAgent 服务器到客户端的请求现在可以从不继承 agent 异步上下文的回调中发送，包括通过 Worker Loader RPC 到达的回调。
  • 实验性：服务器操作和通道。 此版本为受保护的服务器操作（带有持久重放账本和批准的 action() / getActions()）和统一的通道表面（configureChannels()、deliverNotice()）奠定了基础。两者都是实验性的，它们的 API 可能会发生变化，因此我们目前不建议依赖它们。

升级

要更新到最新版本：

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

有关更多信息，请参阅 Think 文档、Code Mode 文档和 Agents 文档。