Cloudflare changelogs | Agents

Agents - Agents SDK 包支持 AI SDK v6 和 v7

Thu, 23 Jul 2026 00:00:00 GMT

agents、@cloudflare/ai-chat、@cloudflare/codemode 和 @cloudflare/think 包现在支持 AI SDK v6 和 v7。现有应用程序在更新这些包时可以保留在 v6 版本。应用程序也可以采用 v7，而无需更改它们使用的 Cloudflare Agents API。

支持的同级依赖范围是 ai@^6 || ^7 和 @ai-sdk/react@^3 || ^4。请使用相匹配的主版本：将 AI SDK v6 与 @ai-sdk/react v3 配对，或将 AI SDK v7 与 @ai-sdk/react v4 配对。

要安装包含 AI SDK v7 的最新包：

npm i agents@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/think@latest ai@^7 @ai-sdk/react@^4

yarn add agents@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/think@latest ai@^7 @ai-sdk/react@^4

pnpm add agents@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/think@latest ai@^7 @ai-sdk/react@^4

bun add agents@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/think@latest ai@^7 @ai-sdk/react@^4

Think 会规范化两个 AI SDK 版本的流式传输、工具完成事件和遥测数据。现有的 v6 应用程序在更新 Think 之前无需迁移这些集成。

有关设置和使用的详细信息，请参阅 Think 文档。

Agents, Workers - Agents SDK 减少了 MCP Schema 转换，为 Think 中的 MCP 添加了暴露控制，并且 Code Mode SDK 添加了直接的主机 API

Wed, 22 Jul 2026 00:00:00 GMT

此版本减少了重复的 MCP schema 转换，并为 Think 的自动 MCP 工具暴露添加了选择停用（opt-out）机制。它还允许非 AI-SDK 主机直接调用持久的 Code Mode 运行时。

控制 Think 中直接的 MCP 工具暴露

现在，当实时连接保持相同的工具目录时，Agents SDK MCP 客户端会重用已转换的输入和输出 schema。这避免了在每个模型轮次中再次将每个 MCP JSON Schema 转换为 Zod。

@cloudflare/think 还添加了 includeMcpTools。当您通过 Code Mode 或 Think 自动工具集之外的其他机制暴露 MCP 工具时，可将其设置为 false：

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

export class MyAgent extends Think {
	includeMcpTools = false;
	waitForMcpConnections = true;
}

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

export class MyAgent extends Think<Env> {
	includeMcpTools = false;
	waitForMcpConnections = true;
}

此设置将跳过 Think 的自动 getAITools() 调用。MCP 注册、恢复、发现、原始目录访问、直接调用和 Code Mode 连接器仍然正常工作。

当您只需要原始 MCP 目录时，请使用 listTools()。对于连接器设置，请参阅在 Code Mode 中使用 MCP 工具。

无需 AI SDK 即可调用 Code Mode 运行时

@cloudflare/codemode@latest 在持久的运行时句柄中添加了 execute()、search() 和 describe()。MCP 服务器和其他主机现在可以执行代码并发现连接器方法，而无需将运行时适配到 AI SDK 工具。

const matches = await runtime.search("create issue");
const docs = await runtime.describe(matches.results[0].path);
const outcome = await runtime.execute({
	code: `async () => github.create_issue({ title: "Bug" })`,
});

const matches = await runtime.search("create issue");
const docs = await runtime.describe(matches.results[0].path);
const outcome = await runtime.execute({
	code: `async () => github.create_issue({ title: "Bug" })`,
});

搜索和描述结果为受保护的连接器方法包含 requiresApproval: true。使用现有的 approve() 和 reject() 方法可以恢复处于暂停状态的执行。

有关设置和确切的方法类型，请参阅创建持久 Code Mode 运行时和 Code Mode API 参考。

升级

npm i agents@latest @cloudflare/think@latest @cloudflare/codemode@latest

yarn add agents@latest @cloudflare/think@latest @cloudflare/codemode@latest

pnpm add agents@latest @cloudflare/think@latest @cloudflare/codemode@latest

bun add agents@latest @cloudflare/think@latest @cloudflare/codemode@latest

Agents, Workers - Agent 可以响应 MCP 引导式输入（elicitation）请求

Mon, 13 Jul 2026 00:00:00 GMT

现在，使用 addMcpServer 连接到 Model Context Protocol (MCP) 服务器的 Agent 可以处理引导式输入（elicitation） ↗请求。

引导式输入允许 MCP 服务器在处理工具调用时请求用户输入。表单（Form）模式收集结构化、非敏感的数据。URL 模式在打开带外（out-of-band）流（如第三方授权或支付）之前会征得同意。

sequenceDiagram
    participant 用户
    participant Agent as Agent (MCP 客户端)
    participant 服务器 as MCP 服务器
    participant 浏览器

    服务器->>Agent: elicitation/create
    Agent->>用户: 显示服务器、原因以及输入或 URL
    用户->>Agent: 提交、打开、拒绝或取消
    Agent->>浏览器: 征得同意后打开 URL（URL 模式）
    Agent->>服务器: accept, decline, or cancel
    服务器-->>Agent: 可选的 URL 完成通知

在 onStart() 中为您 Agent 支持的每种模式注册一个处理器：

import { Agent } from "agents";

export class MyAgent extends Agent {
	onStart() {
		this.mcp.configureElicitationHandlers({
			form: (request, serverId) => this.forwardToUser(request, serverId),
			url: (request, serverId) => this.forwardToUser(request, serverId),
		});
	}

	forwardToUser(request, serverId) {
		// Show the request in your UI and resolve after the user responds.
		throw new Error(
			`Implement elicitation for ${serverId}: ${request.params.message}`,
		);
	}
}

import { Agent } from "agents";
import type { ElicitRequest, ElicitResult } from "agents/mcp";

export class MyAgent extends Agent<Env> {
	onStart() {
		this.mcp.configureElicitationHandlers({
			form: (request, serverId) => this.forwardToUser(request, serverId),
			url: (request, serverId) => this.forwardToUser(request, serverId),
		});
	}

	private forwardToUser(
		request: ElicitRequest,
		serverId: string,
	): Promise<ElicitResult> {
		// Show the request in your UI and resolve after the user responds.
		throw new Error(
			`Implement elicitation for ${serverId}: ${request.params.message}`,
		);
	}
}

连接仅通告配置了处理器的模式。没有处理器的 Agent 不通告任何引导式输入能力，这允许服务器使用其回退方案。SDK 会在每次 MCP 服务器注册时存储通告的模式，以便它们在 Durable Object 休眠后仍能存活。回调函数将保留在内存中，并在 onStart() 运行时重新附着。

有关实现细节和浏览器转发模式，请参阅 MCP 客户端引导式输入。mcp-client ↗ 和 mcp-elicitation ↗ 示例实现双端对接。

升级

要更新到此版本：

npm i agents@latest

yarn add agents@latest

pnpm add agents@latest

bun add agents@latest

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

Fri, 26 Jun 2026 00:00:00 GMT

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

yarn add agents@latest @cloudflare/think@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/voice@latest

pnpm add agents@latest @cloudflare/think@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/voice@latest

bun add agents@latest @cloudflare/think@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/voice@latest

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

Agents, Workers - Agents SDK 改进了浏览器自动化、代码执行和恢复功能

Tue, 16 Jun 2026 00:00:00 GMT

Agents SDK ↗ 的最新版本使得构建能够安全地与真实系统交互且在中断时能够继续工作的 agent 变得更加容易。

Agent 现在可以通过 Browser Run 浏览网站、通过 Code Mode 针对外部工具编写代码、在委托给 Think 子 agent 时使用客户端提供的工具，并在从部署、Durable Object 驱逐以及连接流失中恢复时更加可靠。

更安全的浏览器自动化

Agent 现在可以通过单个持久化的 browser_execute 工具来使用 Browser Run。模型无需从固定的操作列表中进行选择，而是可以针对 Chrome DevTools Protocol (CDP) 编写代码，并可以检查页面、捕获屏幕截图、读取渲染的内容、调试前端行为以及与实时浏览器会话进行交互。

const browserTools = createBrowserTools({
	ctx: this.ctx,
	browser: this.env.BROWSER,
	loader: this.env.LOADER,
	session: { mode: "dynamic" },
});

const browserTools = createBrowserTools({
	ctx: this.ctx,
	browser: this.env.BROWSER,
	loader: this.env.LOADER,
	session: { mode: "dynamic" },
});

浏览器会话可以是一次性的、重用的，或者在运行期间从一次性提升为持久化的。当 agent 需要人工登录、完成多因素身份验证（MFA）或批准敏感操作时，这非常有用。运行可以暂停，保持相同的标签页和 Cookie，并在批准后恢复。

浏览器工具还为单次浏览任务添加了 Live View URL、可选的会话记录以及 browser_markdown、browser_extract、browser_links 和 browser_scrape 等快速操作。

具有批准的可恢复代码执行

Code Mode 现在使用 createCodemodeRuntime、连接器和持久化的执行日志。这让您只需为模型提供一个 codemode 工具，而不是满是工具定义的庞大 Prompt。模型可以发现它需要的功能、针对类型化的全局变量编写代码并重用保存的代码片段。

const runtime = createCodemodeRuntime({
	ctx: this.ctx,
	executor: new DynamicWorkerExecutor({ loader: this.env.LOADER }),
	connectors: [new GithubConnector(this.ctx, this.env, connection)],
});

const result = streamText({
	model,
	messages,
	tools: { codemode: runtime.tool() },
});

const runtime = createCodemodeRuntime({
	ctx: this.ctx,
	executor: new DynamicWorkerExecutor({ loader: this.env.LOADER }),
	connectors: [new GithubConnector(this.ctx, this.env, connection)],
});

const result = streamText({
	model,
	messages,
	tools: { codemode: runtime.tool() },
});

当代码执行到受批准限制的操作时，运行时会暂停执行并返回一个待处理的批准。批准后，已完成的调用将从持久化日志中回放，运行获得批准的操作，然后继续执行相同的代码。这使得构建创建议题（issues）、更新外部系统或执行其他副作用的 agent 变得非常实用，而无需为每个工具都编写自定义的暂停和恢复逻辑。

更好的 Think 委托

Think 子 agent 现在可以通过 RPC chat() 路径使用客户端定义的工具。父 agent 可以通过 clientTools 传递工具 schema，并通过 onClientToolCall 解析工具调用。这使得被委托的 agent 能够使用调用者提供的功能，而无需浏览器 WebSocket。

await child.chat(message, callback, {
	signal,
	clientTools: [
		{
			name: "get_user_timezone",
			description: "Get the caller's timezone",
			parameters: { type: "object" },
		},
	],
	onClientToolCall: async ({ toolName, input }) => {
		return runClientTool(toolName, input);
	},
});

await child.chat(message, callback, {
	signal,
	clientTools: [
		{
			name: "get_user_timezone",
			description: "Get the caller's timezone",
			parameters: { type: "object" },
		},
	],
	onClientToolCall: async ({ toolName, input }) => {
		return runClientTool(toolName, input);
	},
});

Think Workflows 还改进了 step.prompt()。Prompt 步骤现在会在返回结构化输出之前运行一个完整的 agent 轮次，因此 agent 可以在产生类型化结果之前调用工具。这使得 Workflow 步骤在持久的分流、研究和审批流中更加有用。

在绑定 Browser Run 时，统一的 Think 执行工具还可以包含 cdp.* 浏览器功能，以及 state.* 和 tools.*。

Voice 输出设备选择

Voice 客户端可以将助手音频路由到特定的输出设备。在 useVoiceAgent 中使用 outputDeviceId，或者从与框架无关的客户端调用 client.setOutputDevice()。

const voice = useVoiceAgent({
	agent: "MyVoiceAgent",
	outputDeviceId: selectedSpeakerId,
});

const voice = useVoiceAgent({
	agent: "MyVoiceAgent",
	outputDeviceId: selectedSpeakerId,
});

不支持扬声器选择的浏览器将继续通过默认的输出设备播放，并报告非致命的 outputDeviceError。

可靠性修复

此版本包括针对生产环境 agent 的多项修复：

useAgent 和 AgentClient 在重连和配置更改期间更可靠地处理 WebSocket 替换。
聊天流回放在重连、部署和提供商错误后更加可靠。
纤程（Fiber）恢复可以跨多通道扫描继续，并在恢复 Hook 持续失败时进行退避。
即使启动拆卸的请求被取消，Agent 拆卸仍会继续。
大型会话历史记录使用按字节预算的读取，以减少启动期间的内存压力。

升级

要更新到最新版本：

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

yarn add agents@latest @cloudflare/think@latest @cloudflare/codemode@latest @cloudflare/ai-chat@latest @cloudflare/voice@latest

pnpm add agents@latest @cloudflare/think@latest @cloudflare/codemode@latest @cloudflare/ai-chat@latest @cloudflare/voice@latest

bun add agents@latest @cloudflare/think@latest @cloudflare/codemode@latest @cloudflare/ai-chat@latest @cloudflare/voice@latest

有关更多信息，请参阅 Code Mode 文档、浏览器工具文档、Think 工具文档以及 Voice 文档。

Workers, Agents, Workers AI - 在 Workers AI 上推出 GLM-5.2

Tue, 16 Jun 2026 00:00:00 GMT

我们很高兴宣布在 Workers AI 上推出 GLM-5.2，这是 Z.ai 的旗舰代理（agentic）编码模型。

@cf/zai-org/glm-5.2 是一款专为代理型编码工作流构建的文本生成模型。凭借函数调用和推理支持，它可以处理长代码库、多步规划和工具增强型智能体。

关键特性和使用场景：

代理编码：专为自主编码任务、长周期规划和复杂的软件工程工作流而设计
大型上下文窗口：GLM-5.2 最多支持 1,048,576 个 token 的上下文窗口。Workers AI 推出该模型时提供 262,144 个 token 的上下文窗口，并计划在未来增加此限制
函数调用：构建可在多个对话轮次中调用工具和 API 的智能体
推理：解决复杂的问题求解和分步推理任务

通过 Workers AI 绑定（binding） (env.AI.run())、REST API /run 或 /v1/chat/completions，或 AI Gateway 来使用 GLM-5.2。

定价可在模型页面或定价页面上找到。

Agents, Workers - Agents SDK v0.14.0：Agent 技能、信使（messengers）、计划任务、Workflows 以及强化的聊天恢复

Tue, 02 Jun 2026 00:00:00 GMT

Agents SDK ↗ 的最新版本添加了四种使用 @cloudflare/think 进行构建的新方式：按需 Agent 技能（Agent Skills）、聊天信使（chat messengers，从 Telegram 开始）、声明式计划任务以及 Workflows 内部的持久推理步骤。此版本还显著强化了持久聊天恢复，因此轮次能够可靠地度过生产环境中的部署、驱逐和停滞的模型流。

Agent 技能（Agent Skills）（实验性）

给 agent 一个按需指令、资源和脚本的目录。技能源将目录添加到系统 Prompt 中，而模型仅在任务匹配时才激活技能 —— 因此庞大的功能库不会膨胀每个 Prompt。

import { Think, skills } from "@cloudflare/think";
import bundledSkills from "agents:skills";

export class SkillsAgent extends Think {
	getSkills() {
		return [
			bundledSkills,
			skills.r2(this.env.SKILLS_BUCKET, { prefix: "skills/" }),
		];
	}
}

import { Think, skills } from "@cloudflare/think";
import bundledSkills from "agents:skills";

export class SkillsAgent extends Think<Env> {
	getSkills() {
		return [
			bundledSkills,
			skills.r2(this.env.SKILLS_BUCKET, { prefix: "skills/" }),
		];
	}
}

agents:skills 导入通过 Agents Vite 插件打包本地的 ./skills 目录（每个技能一个目录，每个目录包含一个 SKILL.md）。技能也可以从 R2 或清单（manifest）中加载。当技能可用时，Think 会暴露 activate_skill、read_skill_resource 和一个可选的 run_skill_script 工具。技能加载是弹性的：重复或失败的源将被跳过并发出警告，而不会损坏 agent。

Agent 技能处于实验性阶段，尤其是脚本执行还处于早期阶段。API 可能会在未来的版本中发生变化。我们非常期待您的反馈 —— 请在 Agents 仓库 ↗中告诉我们您正在构建什么以及缺少了什么。

信使（Messengers）

将 Think agent 直接连接到聊天平台。Think 拥有 Webhook 路由、会话路由、持久回复纤程（durable reply fiber）以及流式传送回提供商。Telegram 作为第一个提供商发布。

import { Think } from "@cloudflare/think";
import {
	defineMessengers,
	ThinkMessengerStateAgent,
} from "@cloudflare/think/messengers";
import telegramMessenger from "@cloudflare/think/messengers/telegram";

export { ThinkMessengerStateAgent };

export class SupportAgent extends Think {
	getMessengers() {
		return defineMessengers({
			telegram: telegramMessenger({
				token: this.env.TELEGRAM_BOT_TOKEN,
				userName: "support_bot",
				secretToken: this.env.TELEGRAM_WEBHOOK_SECRET_TOKEN,
			}),
		});
	}
}

import { Think } from "@cloudflare/think";
import {
	defineMessengers,
	ThinkMessengerStateAgent,
} from "@cloudflare/think/messengers";
import telegramMessenger from "@cloudflare/think/messengers/telegram";

export { ThinkMessengerStateAgent };

export class SupportAgent extends Think<Env> {
	getMessengers() {
		return defineMessengers({
			telegram: telegramMessenger({
				token: this.env.TELEGRAM_BOT_TOKEN,
				userName: "support_bot",
				secretToken: this.env.TELEGRAM_WEBHOOK_SECRET_TOKEN,
			}),
		});
	}
}

默认情况下，每个 Chat SDK 线程都映射到其自己的 Think 子 agent，因此群聊和直接消息不会共享内存。支持多个机器人、自定义会话路由和自定义提供商。

计划任务

使用类型化的领域特定语言 (DSL) 声明循环的、具有时区感知的 Prompt 和处理器。Think 在启动时协调声明，并在每次运行后重新设定下一次发生，由持久幂等提交提供支持。

import { Think, defineScheduledTasks } from "@cloudflare/think";

export class DigestAgent extends Think {
	getScheduledTasks() {
		return defineScheduledTasks({
			weeklyCommitReport: {
				schedule: "every week on monday at 09:00",
				prompt:
					"Compile my GitHub commits for the last week and summarize them.",
			},
			workout: {
				schedule: "every day at 08:00 in Europe/London",
				prompt: "Start my workout.",
			},
		});
	}
}

import { Think, defineScheduledTasks } from "@cloudflare/think";

export class DigestAgent extends Think<Env> {
	getScheduledTasks() {
		return defineScheduledTasks({
			weeklyCommitReport: {
				schedule: "every week on monday at 09:00",
				prompt:
					"Compile my GitHub commits for the last week and summarize them.",
			},
			workout: {
				schedule: "every day at 08:00 in Europe/London",
				prompt: "Start my workout.",
			},
		});
	}
}

Think Workflows

使用 ThinkWorkflow 和 step.prompt() 在 Cloudflare Workflow 内部运行模型驱动的推理步骤，具有持久的类型化结构化输出、长时间等待和审批门槛。

import { z } from "zod";
import { ThinkWorkflow } from "@cloudflare/think/workflows";

const draftSchema = z.object({
	title: z.string(),
	summary: z.string(),
	labels: z.array(z.string()),
});

export class TriageWorkflow extends ThinkWorkflow {
	async run(event, step) {
		const draft = await step.prompt("triage-issue", {
			prompt: `Triage issue #${event.payload.issueNumber}`,
			output: draftSchema,
			timeout: "3 days",
		});

		await step.do("apply-labels", async () => {
			await this.agent.applyLabels(draft.labels);
		});
	}
}

import { z } from "zod";
import { ThinkWorkflow } from "@cloudflare/think/workflows";
import type { ThinkWorkflowStep } from "@cloudflare/think/workflows";
import type { AgentWorkflowEvent } from "agents/workflows";

const draftSchema = z.object({
	title: z.string(),
	summary: z.string(),
	labels: z.array(z.string()),
});

export class TriageWorkflow extends ThinkWorkflow<TriageAgent, Params> {
	async run(event: AgentWorkflowEvent<Params>, step: ThinkWorkflowStep) {
		const draft = await step.prompt("triage-issue", {
			prompt: `Triage issue #${event.payload.issueNumber}`,
			output: draftSchema,
			timeout: "3 days",
		});

		await step.do("apply-labels", async () => {
			await this.agent.applyLabels(draft.labels);
		});
	}
}

针对持久聊天恢复的生产硬化

持久聊天轮次一直被设计为在轮次途中部署或 Durable Object 驱逐后存活。此版本是针对该机制进行生产硬化的重大更新。

在部署期间具有更好的恢复能力。 轮次现在可以度过持续部署和驱逐，而不会丢失已完成的工作，也不会重新运行已经运行过的工具。
实时的 “recovering…” 信号。 useAgentChat 暴露了一个新的 isRecovering 标志，因此恢复中的轮次会显示进度，而不是看起来像冻结了一样。大多数 UI 将 isStreaming || isRecovering 渲染为“忙碌（busy）”。
停滞的流恢复。 设置 chatStreamStallTimeoutMs 可以将挂起的提供商流路由到相同的恢复路径中，而不是留下一个无限旋转的加载指示器（spinner）。
子 agent 重新挂载。 在父节点恢复时，正在运行的 agentTool() 子节点会重新挂载到其结果上，而不是被放弃并重新运行，因此长期运行的子节点在部署下不再丢失工作。

MCP 传输改进

可恢复的流 — 基于服务器发送事件（SSE）的正在运行的工具调用可在连接中断时存活。客户端使用 Last-Event-ID 重新连接并回放它们遗漏的任何内容。
可读的服务器 ID — addMcpServer 接受一个可选的 id，因此工具会呈现为可读的键（例如 tool_github_create_pull_request），而不是不透明的连接 ID。
更好地处理并发请求 — 重叠的 JSON-RPC 请求现在可以跨 HTTP 和 RPC 传输正确关联到其响应。

其他改进

压缩 — Session 的 tokenCounter 现在还驱动压缩边界决策（“压缩什么”），而不仅仅是触发/不触发。
@cloudflare/worker-bundler — 为 createWorker 添加了 virtualModules 选项，以便在打包（bundling）期间提供内存中模块源。
客户端工具继续运行 — 并行工具结果现在合并为一个单一的继续，立即恢复请求会附加到挂起的继续上，并且服务器端 needsApproval 继续会在批准后可靠地恢复。

升级

要更新到最新版本：

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

yarn add agents@latest @cloudflare/think@latest @cloudflare/ai-chat@latest

pnpm add agents@latest @cloudflare/think@latest @cloudflare/ai-chat@latest

bun add agents@latest @cloudflare/think@latest @cloudflare/ai-chat@latest

有关更多信息，请参阅 Agents API 参考和聊天 Agent 文档。

Agents - 通过 Cloudflare Tunnel 分享 sandbox 预览

Fri, 29 May 2026 00:00:00 GMT

Sandboxes 可以通过 sandbox.tunnels 命名空间将容器内运行的服务暴露到公共预览 URL。SDK 在 sandbox 内部使用 cloudflared，因此你可以在不配置 exposePort() 或自定义域名的情况下共享正在运行的服务。

默认情况下，sandbox.tunnels.get(port) 会在零配置的 *.trycloudflare.com URL 上创建一个快速隧道 ↗——无需 Cloudflare 账户、DNS 记录或自定义域名。这非常适合快速开发以及 .workers.dev 部署。

import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, "my-sandbox");
await sandbox.startProcess("python -m http.server 8080");

const tunnel = await sandbox.tunnels.get(8080);
console.log(tunnel.url); // → https://random-words-here.trycloudflare.com

import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, "my-sandbox");
await sandbox.startProcess("python -m http.server 8080");

const tunnel = await sandbox.tunnels.get(8080);
console.log(tunnel.url); // → https://random-words-here.trycloudflare.com

命名隧道

如需更多控制，你可以通过 sandbox.tunnels.get(port, { name }) 创建命名隧道。命名隧道绑定一个由 Cloudflare Tunnel 支持的主机名（<name>.<your-zone>），并在你的区域上创建 CNAME 记录，最终生成类似 https://my-app-preview.example.com ↗ 的地址。

与每次都生成新随机 URL 的快速隧道不同，命名隧道生成的持久 URL 在容器重启后仍然有效。这使命名隧道适用于需要对隧道及其源站进行控制的生产用途。

const tunnel = await sandbox.tunnels.get(8080, { name: "my-app-preview" });
console.log(tunnel.url); // → https://my-app-preview.example.com

const tunnel = await sandbox.tunnels.get(8080, { name: "my-app-preview" });
console.log(tunnel.url); // → https://my-app-preview.example.com

调用 sandbox.destroy() 会在销毁容器的同时拆除 Cloudflare Tunnel 和关联的 DNS 记录，因此不会留下悬空的隧道或记录。

升级

升级到最新版本：

npm i @cloudflare/sandbox@latest

yarn add @cloudflare/sandbox@latest

pnpm add @cloudflare/sandbox@latest

bun add @cloudflare/sandbox@latest

有关完整的 API 详情，请参阅 Sandbox 隧道参考。

Agents, Workers - Agents SDK v0.12.4：对话恢复、路由重试、持久化 Think 提交及 Voice 连接控制

Wed, 13 May 2026 00:00:00 GMT

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 现在能正确重置。

Agent 状态和路由修复

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

持久化 Think 提交

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

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

ChatOptions.tools 已从 TypeScript API 中移除。请在子 agent 上定义持久化工具，或使用 agent 工具进行编排。遗留调用者传入的运行时 options.tools 值将被忽略并产生警告。

Think 消息裁剪行为变更

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

Voice agent 连接控制

@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 文档。

Cloudflare changelogs | Agents

Agents - Agents SDK 包支持 AI SDK v6 和 v7

Agents, Workers - Agents SDK 减少了 MCP Schema 转换，为 Think 中的 MCP 添加了暴露控制，并且 Code Mode SDK 添加了直接的主机 API

控制 Think 中直接的 MCP 工具暴露

无需 AI SDK 即可调用 Code Mode 运行时

升级

Agents, Workers - Agent 可以响应 MCP 引导式输入（elicitation）请求

升级

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

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

轮次的单一入口点：runTurn

恢复和可靠性

其他改进

升级

Agents, Workers - Agents SDK 改进了浏览器自动化、代码执行和恢复功能

更安全的浏览器自动化

具有批准的可恢复代码执行

更好的 Think 委托

Voice 输出设备选择

可靠性修复

升级

Workers, Agents, Workers AI - 在 Workers AI 上推出 GLM-5.2

Agents, Workers - Agents SDK v0.14.0：Agent 技能、信使（messengers）、计划任务、Workflows 以及强化的聊天恢复

Agent 技能（Agent Skills）（实验性）

信使（Messengers）

计划任务

Think Workflows

针对持久聊天恢复的生产硬化

MCP 传输改进

其他改进

升级

Agents - 通过 Cloudflare Tunnel 分享 sandbox 预览

命名隧道

升级

Agents, Workers - Agents SDK v0.12.4：对话恢复、路由重试、持久化 Think 提交及 Voice 连接控制

对话恢复改进

Agent 状态和路由修复

持久化 Think 提交

Think 消息裁剪行为变更

Voice agent 连接控制

其他改进

升级

轮次的单一入口点：`runTurn`