跳转到内容
搜索文档

更新日志

Cloudflare 的最新更新与改进。

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

此版本减少了重复的 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

预算提醒现在默认为按需付费账户开启

我们正在为符合条件的按需付费账户默认开启预算提醒。如果您的账户尚未设置预算提醒,Cloudflare 将为您创建一个账户级别阈值为 $10 的提醒。您的默认提醒将在下一个计费周期开始时启用,因此不会基于您已产生的使用量触发。

我们将在未来几周内分批推出,因此符合条件的账户可能会在不同时间看到其默认提醒出现。

默认提醒的行为与您自行创建的提醒完全相同。当您本计费周期的累计基于使用量的支出达到阈值时,您将收到一封电子邮件通知。该提醒仅供参考,不会限制您的使用量,也不会对您的账户产生任何影响。

使用量每天处理一次,计算前一天的活动,因此预算提醒会在达到阈值后的次日触发,而非实时触发。

预算提醒仅考虑基于使用量的产品支出。定期订阅费用(例如 Workers Paid 计划费用或其他月度计划费用)不包含在阈值计算中。

您可以从 Manage Account(管理账户) > Billing(计费) > **Billable Usage(计费使用量)**或通知设置中更改阈值、添加其他提醒或完全移除默认提醒。如果您已配置自己的预算提醒,则不会有任何变化。

企业合约账户不在此范围内。

如需更多信息,请参阅预算提醒文档

查看 Durable Object 命名空间的总 SQLite 存储指标

现在,您可以在 Cloudflare 仪表板中监控 Durable Object 命名空间随时间变化所使用的 SQLite 总存储量。全新的总存储图表显示了每小时报告的最大存储量。这有助于您识别存储增长、验证数据清理并调查异常使用情况。

总存储图表,显示了一个 Durable Object 命名空间随着时间的推移增长到 260.1 MB 的存储。Go to Durable Objects ↗

该图表仅适用于基于 SQLite 的 Durable Object 命名空间。对于使用旧版键值存储后端的命名空间,它不会显示。不支持按 ID 或名称查看单个 Durable Object 的存储量。

欲了解更多信息,请参阅指标和分析

平台现在可以通过 Cloudflare API 创建临时账户

平台现在可以通过 Cloudflare REST API 创建临时预览账户。这允许您的平台在用户登录 Cloudflare 之前部署一个在线的 Worker。

借助临时账户(Temporary Accounts)API,编码智能体、AI 应用构建器和其他平台可以为生成的 Workers 和支持的资源构建类似的流程。

您的平台可以在用户生成、部署和测试应用程序时,让他们保持在平台的引导流程中。用户不需要现有的 Cloudflare 账户,您的平台也不需要该账户的写入权限。

图表显示 AI 智能体在临时账户中部署、验证并重新部署 Worker,然后用户进行身份验证并认领该账户以保留其资源

API 返回一个认领 URL,允许用户将临时账户及其资源转为永久账户和资源。

Cloudflare Drop 展示了这种针对静态网站的“预览并认领”模式。用户可以上传网站,进行一小时的测试和分享,只有在想要保留它时才登录或创建账户。

该 API 扩展了最初通过 wrangler deploy --temporary 引入的流程。您的后端现在可以直接控制配置和部署体验:

  1. 在您的产品中向用户展示 Cloudflare 的服务条款和隐私政策,并要求用户接受它们。
  2. 请求并解决工作量证明(proof-of-work)挑战。
  3. 创建临时预览账户。
  4. 使用返回的临时账户 ID 和 API 令牌进行部署。
  5. 向用户显示已部署的 Worker URL 和认领 URL。
curl "https://api.cloudflare.com/client/v4/provisioning/previews/challenge" \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{}'

curl "https://api.cloudflare.com/client/v4/provisioning/previews" \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{
    "termsOfService": "https://www.cloudflare.com/terms/",
    "privacyPolicy": "https://www.cloudflare.com/privacypolicy/",
    "acceptTermsOfService": "yes",
    "challengeToken": "<CHALLENGE_TOKEN>",
    "solution": {
      "checkpoints": "<BASE64_CHECKPOINTS>"
    }
  }'

有关完整的 API 流程、工作量证明要求、支持的产品和限制,请参阅认领部署(临时账户)。有关此流程背后的背景和设计目标,请参阅 Temporary Cloudflare Accounts for AI agents

Agent 可以响应 MCP 引导式输入(elicitation)请求

现在,使用 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-clientmcp-elicitation 示例实现双端对接。

升级

要更新到此版本:

npm i agents@latest

新的 Durable Object 命名空间必须使用 SQLite 存储后端

如果您的账户中尚无基于键值 (KV) 后端的 Durable Object 命名空间,您将无法再创建新的此类命名空间。新的 Durable Object 命名空间必须使用 SQLite 存储后端。自 2024 年该后端正式商用 (GA) 以来,我们一直推荐所有新的 Durable Objects 使用该后端。

通过 new_sqlite_classes 迁移创建一个新类:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": [
        "MyDurableObject"
      ]
    }
  ]
}
[[migrations]]
tag = "v1"
new_sqlite_classes = ["MyDurableObject"]

基于 SQLite 的 Durable Objects 与键值后端具有同等的功能特性——包括键值存储 API——并且还支持关系型 SQL 查询以及 时间点恢复 (PITR),可将对象存储恢复到过去 30 天内的任意时间点。

如果您尝试在受影响的账户上创建新的基于键值的命名空间(使用 new_classes 迁移),部署将失败并显示以下错误:

Creating new key-value backed Durable Object namespaces is no longer supported on this account. Please create a namespace using a `new_sqlite_classes` migration instead.

此更改仅影响尚未开始使用键值存储后端的账户。拥有至少一个现有基于键值命名空间的账户目前仍可创建新的命名空间,而 Workers 免费计划一直以来仅支持基于 SQLite 的 Durable Objects。这是向将 SQLite 作为 Durable Objects 单一存储后端迈出的更广泛一步,为未来现有基于键值对象的迁移路径做准备。

欲了解更多信息,请参阅 Durable Objects 迁移

随 Worker 上传发送 npm 包依赖项元数据

Wrangler 现在在执行 wrangler deploywrangler versions upload 期间,从您项目的 package.json 中收集 npm 包依赖项信息,并将其包含在发送到 Cloudflare API 的上传元数据中。这些数据包括每个依赖项的名称、声明的版本范围以及实际安装的确切版本,有助于实现依赖项分析以及未来的供应链安全功能(如漏洞警报)。

要选择停用,请在您的 Wrangler 配置文件中将 dependencies_instrumentation.enabled 设置为 false

{
	"dependencies_instrumentation": {
		"enabled": false
	}
}
[dependencies_instrumentation]
enabled = false

有关更多详细信息,请参阅 Wrangler 配置

Cloudflare Drop

Cloudflare Drop 允许您向 Cloudflare 部署静态网站,而无需先拥有 Cloudflare 账户。

Cloudflare 拖放上传界面,用于浏览文件夹或 ZIP 文件

上传包含静态资产(静态 HTML、CSS、JavaScript、图像和字体)的文件夹或 ZIP 文件,即可获得保持在线 1 小时临时的实时预览。在此时间窗内,您可以测试网站、共享预览 URL 或认领该部署以保留它。

Cloudflare 拖放临时实时预览界面,带有认领和复制认领链接操作

当您准备好使部署永久生效时,请点击 Claim(认领) 以登录或创建 Cloudflare 账户。您可以将网站认领到现有的 Cloudflare 账户中,也可以为该部署创建一个新账户。

Cloudflare 拖放认领账户界面,显示认领链接过期前的倒计时

认领网站后,您可以:

  • 添加域名连接现有域名或为您的网站购买新域名。
  • 启用可观测性:监控您网站的性能和使用情况。
  • 启用 Markdown for Agents:允许 AI 智能体以 Markdown 格式访问您网站的内容。
  • 控制访问:将您的网站设为私有并选择谁可以查看它。
已认领的 Cloudflare 拖放网站设置界面,显示添加域名、控制访问、启用可观测性以及为智能体启用 Markdown 的选项

使用 `exports` 声明 Durable Object 类生命周期

Wrangler 配置文件中全新的声明式 exports 字段取代了用于管理 Durable Object 类生命周期的命令式 migrations 数组。您无需再编写带有唯一标签的有序迁移步骤列表,而是声明 Worker 导出的每个 Durable Object 类,Cloudflare 会将其与已部署的内容进行对比,以确定需要创建、重命名还是删除哪些 Durable Object 状态。

在使用旧版迁移时,将 ChatRoom 重命名为 Room 需要保留这两个标记的步骤:

Before — legacy migrationsjsonc
{
	"migrations": [
		{ "tag": "v1", "new_sqlite_classes": ["ChatRoom"] },
		{
			"tag": "v2",
			"renamed_classes": [{ "from": "ChatRoom", "to": "Room" }],
		},
	],
}

而使用 exports,您只需将 Room 声明为当前类,并将 ChatRoom 标记为已重命名:

After — declarative exportsjsonc
{
	"exports": {
		"ChatRoom": {
			"type": "durable-object",
			"state": "renamed",
			"renamed_to": "Room",
		},
		"Room": { "type": "durable-object", "storage": "sqlite" },
	},
}

每个条目都以类名作为键。state 字段承载生命周期(默认为 created——活动类——以及墓碑(tombstone)状态 deletedrenamedtransferred,和用于跨 Worker 传输的接收状态 expecting-transfer)。

与旧版 migrations 数组相比的关键改进:

  • 无需迁移标签。 当前的 exports 映射是唯一的真实数据源——无需维护 v1v2v3 条目的历史链。
  • 结构化的部署输出。 Wrangler 会在创建、更新、删除、重命名或传输 Durable Object 类时进行报告。它还会识别可安全删除的陈旧配置条目。没有更改或通知的部署不会打印此输出。
  • 零停机重命名和传输模式是一等公民。 墓碑(Tombstones)可以与代码中仍然存在的源类共存,从而实现 三次部署重命名四次部署跨 Worker 传输,在滚动部署期间不会出现运行时错误。
  • 跨 Worker 安全性。 当您删除或重命名类时,Cloudflare 会列出您账户中其绑定(binding)仍引用该命名空间的其他所有 Worker,以便您在更改生效前重新部署它们。

使用旧版 migrations 数组的现有 Workers 仍可照常工作,无需任何更改。要过渡到 exports,请参阅迁移指南。在单个 Worker 中,exportsmigrations 是互斥的。

欲了解完整的参考信息,请参阅 Durable Object 类导出

借助 @cloudflare/workers-types v5 实现更简单的运行时类型

我们已经发布了 @cloudflare/workers-types 的第 5 版。此版本简化了该包,使其仅公开最新的运行时类型。

我们仍然建议您使用 wrangler types 为您的 Worker 生成类型,但如果您想直接使用该包,您可以使用您选择的包管理器进行安装:

npm i -D @cloudflare/workers-types@latest

该包现在公开了两个入口点:

  • @cloudflare/workers-types 反映了最新的兼容性日期,使用最新的稳定兼容性标志。
  • @cloudflare/workers-types/experimental 反映了处于实验性兼容性标志之下的 API。

删除了带有日期的入口点,例如 @cloudflare/workers-types/2022-11-30@cloudflare/workers-types/2023-03-01。借助 Wrangler v4 中的运行时类型生成功能,您可以使用 wrangler types 命令来生成这些类型,以创建锁定到您的 Worker 兼容日期的类型。

有关更多信息,请参阅 TypeScript 语言支持

使用 Wrangler 身份验证配置文件(auth profiles)跨多个账户工作

Wrangler CLI 现在支持身份验证配置文件(auth profiles):命名登录,您可以将其范围限制为特定的 Cloudflare 账户,并根据您正在工作的目录自动在它们之间进行切换。

配置文件(profile)是绑定到目录的命名 OAuth 登录。在该目录及其子目录中运行的命令将使用匹配的账户 —— 这样您就可以在账户之间切换,而无需重新运行 wrangler login

当您在代理机构工作时,使用配置文件为每个客户保留单独的登录,或者将暂存(staging)和生产(production)环境分隔到不同的账户中。在您的 Wrangler 配置文件 中将配置文件与 account_id 配对,这样命令就不会访问到错误的账户。

# 为每个账户创建一个配置文件,选择它能访问的账户
wrangler auth create client-a
wrangler auth activate client-a ~/clients/client-a

wrangler auth create client-b
wrangler auth activate client-b ~/clients/client-b

使用 --profile 标志以特定配置文件运行单个命令:

wrangler deploy --profile personal

在 CI 和其他自动化环境中,CLOUDFLARE_API_TOKEN 仍然优先于所有配置文件。

有关设置、解析顺序和完整命令参考,请参阅身份验证配置文件(Authentication profiles)

在仪表板中跟踪 Workers 和 Durable Objects 的内存使用情况

您现在可以使用 Workers 指标(Metrics)选项卡中新增的 Memory Usage(内存使用情况) 图表,监控您的 WorkersDurable Objects 在多次调用中消耗了多少内存,图表按 P50、P90、P99 和 P999 百分位数进行了细分。

内存使用情况图表显示了带有部署标记的 P50、P90、P99 和 P999 百分位数

内存使用情况测量的是每次调用时的 V8 isolate 内存,受限于 每个 isolate 128 MB 的限制 —— 单个 isolate 可以处理许多并发请求并在它们之间共享内存。

使用内存使用情况图表可以:

  • 跟踪内存趋势 —— 在导致 Exceeded Memory(超出内存)错误之前,发现可能表明存在内存泄漏的渐进式内存增加。
  • 与部署关联 —— 图表上的部署标记可帮助您确定新版本是否引入了内存回归。
  • 合理调整您的 Worker 规模 —— 了解您的基准内存占用量,以及在达到 128 MB 限制之前您还有多少余量。

对于 Durable Objects,内存使用情况反映了对象保存的内存中状态(类属性、缓存、活动的 WebSocket 连接),该状态在多次调用之间保持不变,直到对象被休眠或逐出。在逐出、休眠或崩溃时,此状态不会保留,因此请将任何重要内容持久化保存到存储中。

要查看内存使用情况,请打开您的 WorkerDurable Object 命名空间Metrics(指标) 选项卡。对于 Durable Objects,您可以按 DO ID 或名称进行过滤,以深入查看特定对象的内存使用情况。您还可以通过 GraphQL Analytics API 使用 workersInvocationsAdaptive 数据集以编程方式查询内存使用情况 —— 从 quantiles.memoryUsageBytesP50quantiles.memoryUsageBytesP999 的字段以字节为单位返回百分位数。

对于本地内存调试,您还可以使用 DevTools 剖析内存以获取堆快照并识别导致高内存占用的特定对象。

Workers fetch 请求现在支持 cf.vary

Workers fetch() 请求现在支持 cf.vary 请求选项。使用 cf.vary 可以控制 Cloudflare 如何为单个子请求缓存具有 Vary 标头的源服务器响应。

src/index.jsjs
export default {
	async fetch(request) {
		return fetch(request, {
			cf: {
				vary: {
					default: { action: "bypass" },
					headers: {
						accept: {
							action: "normalize",
							media_types: ["text/html", "application/json"],
						},
						"accept-language": {
							action: "normalize",
							languages: ["en", "fr", "de"],
						},
					},
				},
			},
		});
	},
};
src/index.tsts
export default {
	async fetch(request): Promise<Response> {
		return fetch(request, {
			cf: {
				vary: {
					default: { action: "bypass" },
					headers: {
						accept: {
							action: "normalize",
							media_types: ["text/html", "application/json"],
						},
						"accept-language": {
							action: "normalize",
							languages: ["en", "fr", "de"],
						},
					},
				},
			},
		});
	},
} satisfies ExportedHandler;

有关更多信息,请参阅 cf.vary

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

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 现在会将恢复状态回放到在恢复途中连接的客户端,因此 useAgentChatisRecovering 会立即反映进行中的恢复,而不是显得冻结。
  • 终端连接失败。 客户端在终端 WebSocket 关闭事件上停止重新连接,并通过 AgentClientuseAgentuseAgentChat 上的 connectionError / onConnectionError 暴露它们。
  • Agent-tool 子节点恢复。 在部署后,健康的长期运行子 agent 运行不再被作为 interrupted(中断)放弃(对于 @cloudflare/thinkAIChatAgent 皆是如此)。
  • 来自子 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 文档

Durable Objects 新增 `us` 管辖区(Jurisdiction)

Durable Objects 现在支持 us 管辖区(jurisdiction),允许您创建仅在美国境内运行并存储数据的 Durable Objects。当您需要将 Durable Object 的计算和存储保留在美国境内以满足数据驻留要求时,请使用 us 管辖区。

像使用任何其他管辖区一样,创建一个受限于 us 管辖区的命名空间:

// Worker
export default {
	async fetch(request, env) {
		const usSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("us");
		const stub = usSubnamespace.getByName("general");
		return stub.fetch(request);
	},
};

Workers 仍可从世界任何地方访问受限于 us 管辖区的 Durable Objects。管辖区限制仅控制 Durable Object 本身在何处运行和持久化数据。

如需查看支持的管辖区的完整列表,请参阅数据位置 — 限制 Durable Objects 至特定管辖区

使用新的 cloudflare:test 辅助函数测试 Durable Object 逐出(eviction)

@cloudflare/vitest-pool-workers 包现在包含了从 cloudflare:test 导出的 evictDurableObjectevictAllDurableObjects 测试辅助函数。

这些辅助函数允许您测试 Durable Object 在逐出发生时的行为,模拟闲置 Durable Object 从内存中逐出的实际生产生命周期。

有关更多背景信息,请参阅 Durable Object 的生命周期

import { evictDurableObject, evictAllDurableObjects } from "cloudflare:test";
import { env } from "cloudflare:workers";

const id = env.COUNTER.idFromName("my-counter");
const stub = env.COUNTER.get(id);

// 逐出特定 stub 所指向的 Durable Object 实例
await evictDurableObject(stub);

// 关闭 WebSockets 而不是将它们休眠
await evictDurableObject(stub, { webSockets: "close" });

// 逐出当前在可逐出命名空间中运行的所有 Durable Objects
await evictAllDurableObjects();

这些辅助函数在 @cloudflare/[email protected] 及更高版本中可用。

请在 测试 API 参考测试 Durable Objects 指南中了解更多信息。

新增亚太地区位置提示:apac-ne 和 apac-se

Durable Objects 现在支持两个针对亚太地区的新位置提示:apac-ne(东北亚)和 apac-se(东南亚)。当您希望在亚太地区内进行更细粒度的托管放置,而不是使用更宽泛的 apac 提示时,请使用 apac-neapac-se

像使用任何其他 locationHint 一样使用这些新提示:

// 东北亚(日本、韩国等)
const stubNE = env.MY_DURABLE_OBJECT.get(id, { locationHint: "apac-ne" });

// 东南亚(新加坡、印度尼西亚等)
const stubSE = env.MY_DURABLE_OBJECT.get(id, { locationHint: "apac-se" });

如果您的用户分布在整个亚太地区,现有的 apac 提示仍是正确的选择。只有当您的流量明显集中在某一个子区域,且您希望将该受众的往返时间降至最低时,才使用 apac-neapac-se。默认行为以及我们通常建议的做法是,除非绝对需要,否则不添加位置提示,这将在尽可能靠近发起请求的地方创建 Durable Object 以减少延迟。

与所有位置提示一样,这些都是尽力而为的建议。Cloudflare 会将 Durable Object 放置在附近的数据中心,而不一定是提示的确切位置。

如需查看支持的提示的完整列表,请参阅数据位置 — 提供位置提示

适用于 AI 智能体(agent)部署的临时账户

AI 智能体(agent)现在可以直接向 Cloudflare 部署 Workers,而无需用户先进行注册、打开基于浏览器的 OAuth 流程、点击仪表板或创建 API 令牌(API token)。当智能体尝试在没有 Cloudflare 凭证的情况下进行部署时,Wrangler 可以指示其使用 --temporary 重新运行,然后将 Worker 部署到临时预览账户中。

要在您的智能体中尝试此操作,请更新到 Wrangler 4.102.0 或更高版本,确保您已退出登录(wrangler logout),然后让您的智能体构建某些内容并将其部署到 Cloudflare。该智能体应当遵循 Wrangler 的输出并使用 --temporary 标志进行部署。

图表显示 AI 智能体部署、验证并重新部署 Worker 到临时账户,然后在身份验证后认领它并将其移动到永久账户
wrangler deploy --temporary

临时部署将保持在线 60 分钟。在此窗口期间,智能体可以验证 Worker、重新部署更改,并返回在线 Worker URL 和认领 URL。打开认领 URL 允许您登录或创建 Cloudflare 账户,并将临时账户转为永久账户。

临时预览账户目前支持有限的一组产品,包括 Workers、Workers Static Assets、Workers KV、D1、Durable Objects、Hyperdrive、Queues 和 SSL/TLS 证书。有关支持的产品、限制和认领行为,请参阅认领部署(临时账户)

有关更多背景信息,请参阅 Temporary Cloudflare Accounts for Agents

创建 PlanetScale Postgres 和 MySQL 数据库,统一记入您的 Cloudflare 账户账单

作为一个按需付费(pay-as-you-go)客户,您可以从 Cloudflare 创建 PlanetScale Postgres 和 MySQL 数据库,并通过您的 Cloudflare 账户结算 PlanetScale 数据库的使用费用。Cloudflare 合约客户将能够在 7 月份将 PlanetScale 的使用额度添加到其合约中,因此如果有兴趣,请联系您的 Cloudflare 账户团队。

从 Cloudflare 仪表板创建 PlanetScale 数据库,以体验针对区域数据访问进行了优化的全球分布式 Workers。

Go to Create a PlanetScale database ↗用户到 Workers、Hyperdrive 缓存、连接池和 PlanetScale 的请求流。

从 Cloudflare 创建的 PlanetScale 数据库通过 HyperdriveWorkers 协同工作。Hyperdrive 管理数据库连接池和查询缓存,因此您可以将 PlanetScale 用作 Workers 应用程序的集中式关系数据库,而无需更改数据库驱动程序、对象关系映射 (ORM) 库或 SQL 工具。

PlanetScale 的使用情况将在每个计费周期以美元总额的形式显示在您的 Cloudflare 发票上,价格遵循 PlanetScale 的标准定价。您可以通过 PlanetScale 的仪表板自检每个数据库的计费使用情况。

当您从 Cloudflare 仪表板创建 PlanetScale 数据库时,您将获得相同的 PlanetScale 开发人员体验,包括开发分支、查询洞察以及针对 Agent 的 Model Context Protocol (MCP) 服务端支持。

要开始使用,请参阅 PlanetScale Postgres and MySQL with Hyperdrive

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

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_markdownbrowser_extractbrowser_linksbrowser_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 的多项修复:

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

升级

要更新到最新版本:

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

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

在 Workers AI 上推出 GLM-5.2

我们很高兴宣布在 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。

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

Workers 追踪现在支持自定义 span

您现在可以使用 tracing.enterSpan() 在您的 Workers 代码中创建自定义追踪 span。自定义 span 与自动平台检测(fetch 调用、KV 读取、D1 查询以及其他平台操作)一起显示在您的追踪和 OpenTelemetry 导出中,并具有正确的父子嵌套关系。

该 API 可以通过 import { tracing } from "cloudflare:workers" 或通过处理程序上下文 ctx.tracing 访问:

import { tracing } from "cloudflare:workers";

export default {
  async fetch(request, env, ctx) {
    return tracing.enterSpan("handleRequest", async (span) => {
      span.setAttribute("url.path", new URL(request.url).pathname);
      const data = await env.MY_KV.get("key");
      return new Response(data);
    });
  },
};

Span 根据 JavaScript 异步上下文自动嵌套,并在回调返回或其返回的 Promise 解决时自动结束。Span 对象提供了 setAttribute(key, value) 用于附加元数据,以及 isTraced 属性用于检查当前请求是否正在被采样。

追踪瀑布图,显示与自动 KV 和 fetch 检测嵌套在一起的自定义 span

必须在您的 Wrangler 配置中启用追踪才能记录 span。

有关完整的 API 详细信息和示例,请参阅自定义 span

按对象 ID 或名称筛选 Durable Objects 指标

现在,您可以在 Cloudflare 仪表板中,按单个 Durable Object 的 ID名称 筛选 Durable Objects 命名空间的 指标 选项卡。此前,指标图表仅显示聚合的命名空间级数据,因此很难隔离特定对象的行为。

Go to Durable Objects ↗已按 ID 筛选为单个对象的 Durable Objects 指标选项卡,按调用状态显示每个对象的请求和错误。

开始在筛选器中输入 ID 或名称,然后从自动完成下拉列表中选择匹配项。自动完成仅显示在选定时间范围内有调用的对象,因此未出现的对象在该时间窗内未被调用。这并不一定意味着该对象已被删除。页面上的每个图表都会更新,以仅反映所选的对象。这使得在调试高流量对象、错误激增或意外存储使用时,更容易识别和调查单个 Durable Object。清除筛选器可返回命名空间级指标。

指标由 GraphQL Analytics API 提供支持,因此适用标准的分析行为,例如摄取延迟和采样

欲了解更多信息,请参阅指标和分析

从仪表板和 GraphQL API 跟踪 Dynamic Workers 的使用情况

Workers 概览页面上的 Dynamic Workers 使用情况

客户现在可以从 Cloudflare 仪表板的 Workers 概览页面查看在其计费周期内调用的 Dynamic Workers 数量。

此计数反映了 Cloudflare 在所选计费周期内将计费的 Dynamic Workers 数量。Dynamic Workers 的使用数据仅追溯到 2026 年 6 月 1 日。

您还可以通过 GraphQL Analytics API 查询此计数,方法是使用 workersInvocationsByOwnerAndScriptGroups 并选择 distinctDynamicWorkerCount

query getDynamicWorkersCount(
	$accountTag: string!
	$filter: AccountWorkersInvocationsByOwnerAndScriptGroupsFilter_InputObject
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			workersInvocationsByOwnerAndScriptGroups(limit: 10000, filter: $filter) {
				uniq {
					distinctDynamicWorkerCount
				}
			}
		}
	}
}

使用变量来设置账户和计费周期日期范围:

{
	"accountTag": "<ACCOUNT_ID>",
	"filter": {
		"date_geq": "2026-06-01",
		"date_leq": "2026-06-30"
	}
}

有关更多信息,请参阅 Dynamic Workers 定价

计费使用量和预算警报现已集成到产品侧边栏中

按需付费(Pay-as-you-go)客户现在可以直接从 Workers & PagesD1R2Workers KVQueuesVectorizeDurable ObjectsContainers 的产品概览页面查看计费使用量并创建预算警报。新的侧边栏小组件显示了当前时期的支出和账单周期日期范围,同时还提供了一个用于创建预算警报的按钮。

该小组件提取与计费使用量仪表板相同的数据,并与您的账单周期(或免费计划中的当前日期)保持一致,因此数据与您的发票相符。目前尚不支持 Enterprise 合约账户。

Durable Objects 产品侧边栏中的计费使用量小组件,显示当前时期的支出和按服务细分的明细

选择 **Create budget alert(创建预算警报)**会以内联方式打开预算警报流程,以便您在查看使用量的同一位置设置美元阈值。预算警报适用于您在所有产品上的账户级别总支出,而不仅仅是您创建该警报的产品页面。

有关更多信息,请参阅基于使用量的计费文档