跳转到内容
搜索文档

更新日志

Cloudflare 的最新更新与改进。

Agents SDK 包支持 AI SDK v6 和 v7

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

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

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

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

使用 Devin Outposts 在 Cloudflare 上运行 Devin

Devin Outposts 允许您在 Cloudflare 上运行 Devin Agent。每个 Devin 会话在由 Cloudflare Containers 支持的独立沙箱中运行,因此 Agent 可以在隔离环境中执行代码并使用开发工具。

当您希望 Devin 会话在 Cloudflare 托管的基础设施上运行,且每个会话相互隔离时,请使用 Devin Outposts。

Devin 界面显示已选择 Cloudflare 作为 Outposts 虚拟环境

如需快速入门,请参阅使用 Devin Outposts 在 Cloudflare 上运行 Devin

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

Markdown 转换的纯文本输出

Markdown 转换服务现在支持一个新的 output 转换选项,用于控制转换后内容的格式。

output.format 设置为 text 以接收移除了 Markdown 语法的纯文本。默认值为 markdown,因此现有转换不受影响。

使用 env.AI 绑定(binding):

await env.AI.toMarkdown(
	{ name: "page.html", blob: new Blob([html]) },
	{
		conversionOptions: {
			output: { format: "text" },
		},
	},
);
await env.AI.toMarkdown(
	{ name: "page.html", blob: new Blob([html]) },
	{
		conversionOptions: {
			output: { format: "text" },
		},
	},
);

或者调用 REST API:

curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/tomarkdown \
  -H 'Authorization: Bearer {API_TOKEN}' \
  -F '[email protected]' \
  -F 'conversionOptions={"output": {"format": "text"}}'

当您请求文本输出时,每个结果的 format 字段会被设置为 text。有关更多详细信息,请参阅转换选项

按精确对象键筛选 AI Search 列表项

AI Search 中,您可以将文件上传到实例,或连接诸如 R2 存储桶之类的数据源,从而让您能够使用自然语言搜索您的内容。每个文件都成为由对象 **key(其文件名或路径)**标识的 项(item)列表项端点会返回实例中的项。

该端点现在接受 key 查询参数,因此您可以通过精确的对象键查找单个项,而无需翻页浏览整个列表。这为您知道键但不知道 ID 的情况补充了现有的 item_id 筛选器。

curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances/<INSTANCE_NAME>/items?key=docs/readme.md" \
  -H "Authorization: Bearer <API_TOKEN>"

键在每个数据源中是唯一的,因此当多个数据源中存在相同的键时,请将 keysource 结合使用(例如 source=builtin)以消除歧义。

有关更多信息,请参阅管理项

Workers AI toMarkdown 和 AI Search 现在支持 GIF 和 BMP 图像转换

除了已支持的 JPEG、PNG、WebP 和 SVG 格式外,Workers AI Markdown 转换 (toMarkdown) 现在还支持 .gif.bmp 图像文件。

GIF 和 BMP 文件与其他格式运行相同的图像流水线。根据需要调整每张图像的大小(对于动态 GIF,仅使用第一帧),然后传递给目标检测模型以识别其包含的内容。这些检测到的目标会提示视觉模型编写图像的自然语言描述,该描述将变成可搜索、机器可读的 Markdown。

AI Search 会自动使用 toMarkdown 来处理它引入的文件,因此下一次您的索引同步时会自动包含任何 .gif.bmp 文件,无需更改任何配置。当您的内容混合了多种格式时,例如充满屏幕截图的支持知识库或 BMP 扫描件的存档,这将非常有用。

详细了解 Markdown 转换 以及 AI Search 支持的文件类型的完整列表。

Moondream 3.1 现已在 Workers AI 上可用

我们与 Moondream 合作,将其最新模型 @cf/moondream/moondream3.1-9B-A2B 引入 Workers AI。Moondream 3.1 是一款基于混合专家(mixture-of-experts)架构构建的快速视觉语言模型,总参数量为 9B,活跃参数量为 2B,可在保持快速、高性价比推理的同时提供前沿级别的视觉推理。

Moondream 3.1 专为实际视觉任务而设计,具备 32K token 上下文窗口,用于处理复杂查询和结构化输出。

关键能力

  • Query(查询) — 针对图像提出开放式问题,带有一个可选的推理参数
  • Caption(描述) — 生成图像的简短、正常或长描述
  • Point(指向) — 返回与目标词组匹配的对象坐标
  • Detect(检测) — 返回与目标词组匹配的对象边界框

边缘实时视觉

像实时摄像头馈送、机器人、内容审核和交互式智能体之类的视觉工作负载,需要毫秒级而不是秒级的响应。Moondream 3.1 较小的活跃占用(2B 活跃参数)与 Workers AI 的无服务器、全球分布式推理完美结合:请求可在靠近您用户的地方运行,且流式响应几乎可以立即开始返回 token。

在我们的测试中,首个 token 在大约 20–30 毫秒内流式返回,并且在每项任务中结果都非常迅速。以下示例端到端时间(客户端观察到的中位数,包括网络往返时间)是针对一张简单的、单一主体的图像。实际延迟很大程度上取决于图像以及您所要求的详细程度。

任务 端到端 (p50)
query ~770 ms
caption ~480 ms
point ~145 ms
detect ~160 ms

在这样的速度下,您可以在处理请求时以内联方式调用模型,而无需将工作推送到后台队列或单独的服务。这开启了那些“如果响应缓慢就会破坏体验”的使用场景:在存储用户上传的图像前对其进行审核、在视频帧中定位对象以驱动实时叠加层、在提交表单时从文档中提取字段,或者让智能体在单轮内检查屏幕截图并决定其下一步操作。

快速入门

通过 Workers AI 绑定(binding) (env.AI.run()) 或 /ai/run 处的 REST API 来使用 Moondream 3.1。您还可以在这些端点中搭配使用 AI Gateway

欲了解更多信息,请参阅 Moondream 3.1 模型页面定价

Browser Run 无障碍树新端点

Browser Run 现在支持独立的 /accessibilityTree 端点,为 Agent 和自动化工作流提供对已渲染网页浏览器无障碍树的直接访问。

无障碍树是浏览器对已渲染页面的结构化视图:角色、名称、状态、值和层级关系。它对无障碍工具很有用,同时也对需要页面结构而无需处理原始 HTML 噪音或截图成本的 AI Agent 和自动化工作流非常实用。

对于 AI Agent 而言,这意味着减少了从像素推断信息以及解析 HTML 的工作。您可以直接提供页面结构,帮助 Agent 识别可用元素并判断其可执行的操作。

使用新的 /accessibilityTree 端点,当您只需要页面的语义结构时,可以直接请求无障碍树。如果需要在单次 API 调用中获取多种页面格式,可以使用 /snapshot 端点,该端点同时返回 Markdown、HTML 和截图。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-run/accessibilityTree' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/"
}'
{
	"success": true,
	"result": {
		"accessibilityTree": {
			"role": "RootWebArea",
			"name": "Example Domain",
			"children": [
				{
					"role": "heading",
					"name": "Example Domain",
					"level": 1
				},
				{
					"role": "link",
					"name": "Learn more"
				}
			]
		}
	}
}

使用 interestingOnly 仅返回语义上有意义的节点,或使用 root 捕获特定子树的无障碍树。

请参阅 /accessibilityTree 文档 以获取使用示例和支持的参数。

使用 Wrangler CLI 管理 AI Search 同步作业

当您将数据源连接到您的 AI Search 实例时,AI Search 会运行同步作业以使您的索引与您的内容保持最新。您现在可以直接从 Wrangler 管理这些作业。

例如,您可以使用 jobs create 命令从您的 CI/CD 或自动化流水线触发同步作业,以便在推送更改时刷新索引:

wrangler ai-search jobs create my-instance

这将创建一个异步同步作业,该作业会检查数据源中的更改,并发送新增、修改或删除的文件以进行索引。 以下命令可用:

命令 说明
wrangler ai-search jobs create 触发新的同步作业
wrangler ai-search jobs list 列出实例的同步作业
wrangler ai-search jobs get 获取作业详情
wrangler ai-search jobs cancel 取消正在运行的作业
wrangler ai-search jobs logs 查看作业的日志条目

所有命令都接受 --namespace/-n(默认为 default)和 --json,以输出自动化和 AI 代理可以直接解析的结构化数据。listlogs 命令还支持用于分页的 --page--per-page,并且除非您传递 -y/--force,否则 cancel 会提示确认。

有关完整的用法详细信息,请参阅 AI Search Wrangler 命令文档

降低向量变更的端到端延迟

我们大幅提升了 Vectorize 预写日志(WAL)的吞吐量。因此,向量变更变为可查询的端到端延迟显著降低:中位延迟从 2 分钟降至 30 秒以内,p99 延迟从 5 分钟降至 2 分钟以内。

Vectorize p99 WAL 批次端到端延迟改善

这意味着插入、upsert 和删除操作将更快地反映在查询结果中,提升语义搜索、推荐和检索增强生成(RAG)工作负载的数据新鲜度。您无需更改代码或配置即可受益于此改进。

有关更多信息,请参阅 Vectorize 文档

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

控制 AI Search 相似性缓存新鲜度

AI Search 现在让您能够更好地控制相似性缓存新鲜度。相似性缓存通过重用语义相似查询的响应,有助于降低延迟和推理成本。

通过这些更新,您可以选择允许重用响应的时间长度,并在缓存的响应可能过时时将其清除。

缓存持续时间现在默认为 48 小时

以前,AI Search 缓存响应的固定时间为 30 天。缓存的响应现在使用实例的 cache_ttl 设置,默认值为 48 小时

您可以在创建或更新实例时设置 cache_ttl,以选择从 10 分钟到 6 天不等的缓存持续时间。

当您的源内容变化频繁且新鲜度更重要时,请使用较短的 TTL。当您的内容稳定且您希望更多地重用缓存时,请使用较长的 TTL。

例如,将 cache_ttl 设置为 518400 以将缓存的响应保留 6 天:

{
	"cache_ttl": 518400
}

清除缓存响应

您还可以按需清除实例的所有缓存响应。清除缓存响应不会删除已索引的内容或源文件。

这会阻止 AI Search 重用以前缓存的响应,因此后续的相似查询会生成新鲜的答案并重新填充缓存。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/instances/$INSTANCE_NAME/purge_cache" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

您还可以从 Cloudflare 仪表板中的实例设置页面清除缓存响应。

请参阅相似性缓存以获取支持的 cache_ttl 值的完整列表以及有关缓存行为的更多详细信息。

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。

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

在 AI Gateway 日志中查看请求的用户代理(User Agent)

AI Gateway 日志现在能够捕获发起每个请求的客户端的用户代理(User Agent),从而更容易识别是哪个 SDK、库或应用程序发送了流经您网关的流量。例如,您可以区分来自 openai-python 的请求与来自自定义应用程序或 Cloudflare Worker 的请求。

用户代理会与每个日志条目中的其他详细信息一起显示,并且您可以在仪表板中按用户代理(等于、不等于或包含)对日志进行筛选。

欲了解更多信息,请参阅日志记录

Moonshot AI Kimi K2.7 Code 现已在 Workers AI 上可用

@cf/moonshotai/kimi-k2.7-code 现已在 Workers AI 上可用。Kimi K2.7 Code 是 Kimi K2 系列中针对代码进行了优化的变体,基于混合专家(Mixture-of-Experts)架构构建,总参数量为 1T,每个 token 的活跃参数量为 32B。

改进的编码和智能体性能

K2.7 Code 在编码和智能体基准测试中相比 K2.6 实现了显著提升:

  • +21.8%,在 Kimi Code Bench v2 上
  • +11.0%,在 Program Bench 上
  • +31.5%,在 MLS Bench Lite 上

推理效率

K2.7 Code 与 K2.6 相比,使用的推理 token 减少了 30%,从而减少了“过度思考”并降低了重推理工作负载的推理成本。

关键能力

  • 262.1k token 上下文窗口,用于在长期运行的智能体任务中保留完整的对话历史记录、工具定义和代码库
  • 长周期编码,具有改进的指令遵循和更高的端到端编码任务成功率
  • 视觉输入,用于随文本一起处理图像
  • 可通过 chat_template_kwargs.thinking 配置推理深度的思维模式
  • 多轮工具调用,用于构建在多个对话轮次中调用工具的智能体
  • 支持 JSON schema 的结构化输出

与 Kimi K2.6 的区别

如果您正在从 Kimi K2.6 迁移,请注意以下几点:

  • K2.7 Code 针对编码任务进行了优化,具备改进的基准测试性能和推理效率
  • 缓存的输入 token 定价为每百万(M)token 0.19 美元(而 K2.6 为 0.16 美元)
  • API 使用方式完全相同 —— 无需更改参数

快速入门

通过 Workers AI 绑定(binding) (env.AI.run())、/ai/run 处的 REST API,或者 /v1/chat/completions 处的兼容 OpenAI 的端点来使用 Kimi K2.7 Code。您还可以在这些端点中搭配使用 AI Gateway

欲了解更多信息,请参阅 Kimi K2.7 Code 模型页面定价

Browser Run /snapshot 端点新增 formats 参数

Browser Run/snapshot 端点 现在支持 formats 参数,允许您在单次 API 调用中返回多种页面格式。此前,/snapshot 仅返回 HTML 内容和截图。您现在还可以在同一响应中包含 Markdown 和无障碍树。

这些格式对 AI Agent 工作流特别有用:

  • Markdown 提供了页面内容的高效 token 表示形式,LLM 可直接处理,无需解析 HTML 标记。
  • 无障碍树提供了页面元素的结构化表示,包括角色、标签和层级关系,帮助 LLM 理解页面结构并导航其内容。

以下示例在一次调用中返回截图、Markdown 和无障碍树:

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/snapshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "formats": ["screenshot", "markdown", "accessibilityTree"]
  }'
import Cloudflare from "cloudflare";

const client = new Cloudflare({
	apiToken: process.env["CLOUDFLARE_API_TOKEN"],
});

const snapshot = await client.browserRendering.snapshot.create({
	account_id: process.env["CLOUDFLARE_ACCOUNT_ID"],
	url: "https://example.com/",
	formats: ["screenshot", "markdown", "accessibilityTree"],
});

console.log(snapshot.markdown);
console.log(snapshot.accessibilityTree);
interface Env {
	BROWSER: BrowserRun;
}

export default {
	async fetch(request, env): Promise<Response> {
		return await env.BROWSER.quickAction("snapshot", {
			url: "https://example.com/",
			formats: ["screenshot", "markdown", "accessibilityTree"],
		});
	},
} satisfies ExportedHandler<Env>;

您必须至少请求两种格式。如果只需要一种格式,请使用相应的单格式端点,例如 /screenshot/markdown

请参阅 /snapshot 文档 以获取完整的支持值列表。

使用 Wrangler CLI 管理 AI Search 命名空间

AI Search 现在支持命名空间级别的 Wrangler 命令,这使得从您的终端、脚本和代理工作流程中管理命名空间(namespaces)变得更加容易。

以下命令可用:

命令 描述
wrangler ai-search namespace list 列出 AI Search 命名空间
wrangler ai-search namespace create 创建新的 AI Search 命名空间
wrangler ai-search namespace get 获取命名空间的详细信息
wrangler ai-search namespace update 更新命名空间描述
wrangler ai-search namespace delete 删除 AI Search 命名空间

直接从 CLI 为新应用程序或租户创建命名空间:

wrangler ai-search namespace create docs-production --description "Production documentation search"

通过分页列出命名空间,或按名称或描述进行过滤:

wrangler ai-search namespace list --search docs --page 1 --per-page 10

--jsonlistcreategetupdate 结合使用,以返回自动化和 AI 代理可以直接解析的结构化输出。

实例级别的命令现在也支持 --namespace 标志,因此您可以从 CLI 与特定命名空间内的实例进行交互:

wrangler ai-search list --namespace docs-production

有关完整的用法详情,请参阅 AI Search Wrangler 命令文档

已弃用 Sandbox SDK 功能

今天我们宣布弃用 Sandbox SDK 的若干功能。自首次发布以来,SDK 已大幅成长和成熟。随着 Agent 工作流的发展,我们已发布了许多新功能和实验性内容,让开发者能够轻松地将安全的隔离代码执行集成到其工作流中。

我们希望 SDK 在快速迭代代码库的同时,继续为 Agent 工作流提供稳定的基础。这些已弃用的功能要么已被更新的功能所取代,要么采用率较低。它们将保留在代码库中直至 2026 年 7 月 9 日,之后将不再出现在未来的 Sandbox SDK 版本中。

HTTP 和 WebSocket 传输

2026 年 4 月,我们发布了新的 RPC 传输并弃用了 WebSocket 传输。此设置控制沙箱容器与 Workers 生态系统的通信方式。RPC 传输消除了 HTTP 和 WebSocket 传输的两种限制。自 2026 年 6 月 9 日起,它是推荐的默认选项。HTTP 和 WebSocket 传输将不再出现在 2026 年 7 月 9 日后发布的 Sandbox SDK 版本中。

如需在 2026 年 7 月 9 日之前迁移,请将 SANDBOX_TRANSPORT 变量更新为 rpc,或在调用 getSandbox() 时设置 transport 选项。更多信息,请参阅传输配置文档

Desktop

Desktop 功能作为 Sandbox SDK 功能演示而推出——可在沙箱中控制完整的浏览器环境。随着 Cloudflare Browser Run 的推出,该功能使用率极低。我们已在 0.10.2 中将其移除。

公开端口

我们最近在 Sandbox SDK 中发布了对 Cloudflare Tunnel 的支持。它为将沙箱中运行的服务公开到公共互联网提供了强大的 API,解决了许多人在本地开发和部署到 workers.dev 域名时遇到的问题。如需从 exposePort() 迁移到隧道,请参阅隧道 API 文档公开服务指南

默认会话

默认情况下,Sandbox SDK 中的 exec() 方法在所有调用之间维护一个默认会话,因此某次调用中的 cd 会在下一次调用中生效。这种便利性对手动编写 exec 语句的开发者有帮助,但会让 Agent 感到困惑,并导致难以追踪的 Bug。自 0.10.3 起,我们在 getSandbox() 接口上引入了 enableDefaultSession 标志来关闭此功能。默认会话这一概念——以及该标志——将在后续版本中移除。

我们建议今天就将 enableDefaultSession: false 设置为当前值,并在需要之前行为时使用 sandbox.createSession() API

其他变更

我们还在整合所有缓冲数据的 API,以默认支持流式传输。这包括 readFilewriteFileexec。流式等效方法将被移除。

我们正在探索将非核心功能(如代码解释器终端git API)移入辅助工具。这些功能将保留现有 API,因此迁移应该很简单。

后续步骤

如果您使用了上述任何功能,请参阅 2026 年弃用迁移指南。我们还提供了一个 Agent skill 来协助迁移。

如有任何问题,请在 Cloudflare 开发者 Discord 中提问。

使用支出限制控制 AI 成本

AI Gateway 现在支持支出限制(spend limits)——基于成本的预算,可追踪累计美元支出,并在超出预算时拦截请求。与限制请求次数的速率限制不同,支出限制是基于 Token 使用量和模型定价来追踪实际成本。

您可以按模型、提供商或自定义元数据维度来限定限制范围。例如,为每个用户分配每日 200 美元的预算,将网关总支出限制在每日 10,000 美元以内,或者限制每个用户对特定模型的每日支出上限为 50 美元。每条规则都使用可配置的时间窗口,可采用固定或滑动执行策略。

支出限制适用于具有已知定价模型的 统一计费(Unified Billing)BYOK(自带密钥) 请求。

欲了解更多细节,请参阅支出限制文档

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

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

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

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

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

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

Agents SDK v0.14.0:Agent 技能、信使(messengers)、计划任务、Workflows 以及强化的聊天恢复

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_skillread_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

使用 ThinkWorkflowstep.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 重新连接并回放它们遗漏的任何内容。
  • 可读的服务器 IDaddMcpServer 接受一个可选的 id,因此工具会呈现为可读的键(例如 tool_github_create_pull_request),而不是不透明的连接 ID。
  • 更好地处理并发请求 — 重叠的 JSON-RPC 请求现在可以跨 HTTP 和 RPC 传输正确关联到其响应。

其他改进

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

升级

要更新到最新版本:

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

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

通过 Cloudflare Tunnel 分享 sandbox 预览

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

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

直接从 Workers 使用 Browser Run Quick Actions

您现在可以使用浏览器绑定(browser binding)上的 quickAction() 方法,直接从 Cloudflare Worker 调用 Browser Run Quick Actions。这消除了对 API 令牌或外部 HTTP 请求的需求,从而简化了 Workers 与 Browser Run 的交互方式。您的 Worker 会在 Cloudflare 的网络上直接与 Browser Run 进行通信,使得代码更简单,延迟更低。

通过 quickAction() 方法,您可以:

要开始使用,请将浏览器绑定(browser binding)添加到您的 Wrangler 配置中:

{
  "compatibility_date": "2026-03-24",
  "browser": {
    "binding": "BROWSER"
  }
}
compatibility_date = "2026-03-24"

[browser]
binding = "BROWSER"

然后直接从您的 Worker 调用任何 Quick Action。例如,要截取屏幕截图:

const screenshot = await env.BROWSER.quickAction("screenshot", {
	url: "https://www.cloudflare.com/",
});
const screenshot = await env.BROWSER.quickAction("screenshot", {
  url: "https://www.cloudflare.com/",
});

quickAction() 方法需要 2026-03-24 或更晚的兼容性日期。

有关设置说明和可用操作的完整列表,请参阅 Browser Run Quick Actions