为 Agent 提供可在后续轮次回访的浏览器。Browser Run 会保持远程浏览器打开,因此只要浏览器会话仍然存活,Agent 就可以带着标签页、cookie 和登录会话从同一页面继续。
使用浏览器工具与网站交互、检查通过 JavaScript 渲染的页面或截取屏幕截图。配置内部主机名后,浏览器还可打开仅由代理提供服务的网站,例如其沙箱中的开发服务器或工作区文件夹。
研究助手可以打开仪表板、检查报告,并在后续轮次回到该页面。Browser 类会在 tool 调用之间保持远程浏览器会话打开,包括其标签页、cookie 和登录状态。browserTool adapter 让你的 harness 通过 Chrome DevTools Protocol (CDP) 使用该浏览器。
浏览器运行在 Agent 的 Durable Object 之外。对象会保存其会话标识符,并在休眠后重新连接,只要浏览器会话仍然存活。默认情况下,空闲浏览器最多保持存活 10 分钟。这不会永久保存浏览器:过期或崩溃会丢失其标签页、cookie 和登录状态。
请从 Pi Durable agent开始。在 Pi 软件包旁安装 Agents SDK:
npm i agents @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord @cloudflare/codemodeyarn add agents @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord @cloudflare/codemodepnpm add agents @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord @cloudflare/codemodebun add agents @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord @cloudflare/codemodePi 软件包是 agents 的可选 peer dependency,版本为 ~1.4.0。Pi Durable 是实验性功能,其 API 可能在次要版本中发生变化,因此每个 agents 版本仅支持一个 Pi 次要版本。请安装软件包管理器为 agents 解析出的版本。
本示例在普通 Durable Object 上安装 Browser 和 PiHarness。Pi 决定何时调用浏览器 tool。Lifecycle 启动这两个组件并提供它们的存储。
import { DurableObject } from "cloudflare:workers";
import { createModels } from "@earendil-works/pi-ai/models";
import { createRegistry, Harness } from "@earendil-works/pi-durable";
import { Browser, browserRun } from "agents/browser";
import { browserTool } from "agents/browser/pi";
import { PiHarness } from "agents/harness/pi";
import { Lifecycle } from "agents/lifecycle";
import { createAI } from "agents/models/pi-ai";
export class BrowserAssistant extends DurableObject {
ai = createAI({ binding: this.env.AI });
browser = new Browser({ provider: browserRun(this.env.BROWSER) });
registry = createRegistry();
harness = new PiHarness({
harness: ({ storage, context, onWake }) => {
const models = createModels();
models.setProvider(this.ai.provider);
this.registry.install({
name: "browser",
tools: [
browserTool({ browser: this.browser, loader: this.env.LOADER }),
],
});
return Harness.open(
storage,
{ models, registry: this.registry, onWake },
context,
);
},
defaults: { model: this.ai("@cf/zai-org/glm-5.3-flash") },
});
lifecycle = Lifecycle.install(this).use(this.browser).use(this.harness);
async ask(prompt) {
const { text } = await this.harness.prompt(prompt);
return text;
}
}
export default {
async fetch(request, env) {
const assistant = env.BrowserAssistant.getByName("demo");
const text = await assistant.ask(await request.text());
return Response.json({ text });
},
};import { DurableObject } from "cloudflare:workers";
import { createModels } from "@earendil-works/pi-ai/models";
import { createRegistry, Harness } from "@earendil-works/pi-durable";
import { Browser, browserRun } from "agents/browser";
import { browserTool } from "agents/browser/pi";
import { PiHarness } from "agents/harness/pi";
import { Lifecycle } from "agents/lifecycle";
import { createAI } from "agents/models/pi-ai";
export class BrowserAssistant extends DurableObject<Env> {
ai = createAI({ binding: this.env.AI });
browser = new Browser({ provider: browserRun(this.env.BROWSER) });
registry = createRegistry();
harness = new PiHarness({
harness: ({ storage, context, onWake }) => {
const models = createModels();
models.setProvider(this.ai.provider);
this.registry.install({
name: "browser",
tools: [
browserTool({ browser: this.browser, loader: this.env.LOADER }),
],
});
return Harness.open(
storage,
{ models, registry: this.registry, onWake },
context,
);
},
defaults: { model: this.ai("@cf/zai-org/glm-5.3-flash") },
});
lifecycle = Lifecycle.install(this).use(this.browser).use(this.harness);
async ask(prompt: string) {
const { text } = await this.harness.prompt(prompt);
return text;
}
}
export default {
async fetch(request: Request, env: Env) {
const assistant = env.BrowserAssistant.getByName("demo");
const text = await assistant.ask(await request.text());
return Response.json({ text });
},
} satisfies ExportedHandler<Env>;示例为演示使用一个命名 assistant。在应用中,请为每个已认证用户或 workspace 选择对象名称。
配置模型、浏览器、Worker Loader 和 Durable Object 绑定(binding):
{
"name": "persistent-browser-agent",
"main": "src/index.ts",
// Set this to today's date
"compatibility_date": "2026-11-20",
"compatibility_flags": ["nodejs_compat"],
"ai": { "binding": "AI" },
"browser": { "binding": "BROWSER" },
"worker_loaders": [{ "binding": "LOADER" }],
"durable_objects": {
"bindings": [{ "name": "BrowserAssistant", "class_name": "BrowserAssistant" }],
},
"migrations": [{ "tag": "v1", "new_sqlite_classes": ["BrowserAssistant"] }],
}name = "persistent-browser-agent"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-11-20"
compatibility_flags = [ "nodejs_compat" ]
[ai]
binding = "AI"
[browser]
binding = "BROWSER"
[[worker_loaders]]
binding = "LOADER"
[[durable_objects.bindings]]
name = "BrowserAssistant"
class_name = "BrowserAssistant"
[[migrations]]
tag = "v1"
new_sqlite_classes = [ "BrowserAssistant" ]使用 wrangler types生成 Env 类型。LOADER 绑定会为每次调用创建新的 Dynamic Worker,在其中运行模型的浏览器代码,且无法访问网络。代码只能通过浏览器 API访问浏览器。
browserTool 不使用 Code Mode,但仍需安装 @cloudflare/codemode。agents/browser 仍导出旧版浏览器工具,这些工具需要该依赖。
要试用持久化,在浏览器空闲超时内向同一个 assistant 发送两个 prompt:
curl http://localhost:8787 --data 'Open https://example.com and tell me the page title.'
curl http://localhost:8787 --data 'Take a screenshot of the page you already opened without navigating again.'第二轮可以使用现有标签页。Pi 将返回的屏幕截图作为图像存储在 tool 结果中。具备图像能力的模型可以看到它,UI 也可以从 transcript 显示它。本示例的 HTTP 响应只返回最终文本;要构建 UI,请参阅 Pi 事件流式传输。
默认情况下,每个 Pi 对话都有自己的活动标签页。sessions、forks 和 subagents 可以在不同页面上工作,但 cookie 和登录状态在同一个 Browser 内共享。标签页 scope 不是独立的浏览器配置文件。当用户需要独立登录会话时,请使用独立的浏览器。
在一段对话内,浏览器调用按顺序运行。模型可以在 CDP 命令中使用 sessionId: "active" 回到其活动标签页。要有意共享标签页,请向 Pi tools 传入相同的 scope 字符串。
如果浏览器过期、关闭或崩溃,下次使用时会创建替代浏览器。结果中的 notice 会告知返回的 scope,其先前浏览器状态已丢失。工具会使用新浏览器运行,不会恢复旧会话。notice 还会在页面打开新标签页,或其他对话关闭了该标签页或正在使用该标签页时通知模型。
Pi 不会自动重放因 evict 而中断的浏览器调用:重复执行可能会提交表单或点击按钮两次。模型会收到中断结果,并可以决定如何继续。停止对话不会取消已经在运行的浏览器调用。该调用会完成,或达到默认 60 秒的 timeoutMs。
在 browserRun(binding, options) 上设置 keepAliveMs、recording 和主机名 guardrails。从应用中调用 browser.liveView() 让人检查或控制同一个浏览器,调用 browser.close() 关闭它。持久化浏览器目前支持 Browser Run 的 Chromium 引擎。
内部主机名是浏览器的一项功能,与代理 harness 无关。Agents SDK 为 Pi Durable、AI SDK 和 TanStack AI 提供浏览器工具适配器。若要连接其他 harness,请使用 browser.session() 实现工具。无需预构建适配器。
| Harness | 导入 | 用法 |
|---|---|---|
| Pi Durable | 来自 agents/browser/pi 的 browserTool |
安装到 Pi registry extension 的 tools 数组中。 |
| AI SDK | 来自 agents/browser/ai-sdk 的 browserTool |
添加到传给 generateText 或 streamText 的 tools 对象。 |
| TanStack AI | 来自 agents/browser/tanstack-ai 的 browserTool |
添加到传给 chat 的 tools 数组。 |
| 其他 harness | 来自 agents/browser 的 Browser |
使用 browser.session() 实现工具;无需预构建适配器。 |
例如,在 Durable Object 内创建 AI SDK tool:
import { browserTool } from "agents/browser/ai-sdk";
const tools = {
browser: browserTool({
browser: this.browser,
loader: this.env.LOADER,
scope: conversationId,
}),
};
// Pass tools to generateText() or streamText().import { browserTool } from "agents/browser/ai-sdk";
const tools = {
browser: browserTool({
browser: this.browser,
loader: this.env.LOADER,
scope: conversationId,
}),
};
// Pass tools to generateText() or streamText().与 Pi 不同,省略 scope 时,AI SDK 和 TanStack AI adapter 共享一个活动标签页。传入对话标识符,可为每个对话提供自己的活动标签页。AI SDK adapter 会向 UI 暴露屏幕截图,并向模型发送文本摘要。TanStack AI 会省略屏幕截图,并引导模型改为读取页面内容。
对于没有预构建适配器的 harness,或要从自己的代码驱动浏览器时,请调用 browser.session({ scope })。无论你使用现有框架还是编写自己的 harness,此方法都适用。它会返回 browserTool 所依赖的连接,并采用相同的 sessionId: "active" 处理方式。完成后请关闭连接,以保存 scope 的活动标签页,并获取浏览器操作报告:
const session = this.browser.session({ scope: conversationId });
try {
await session.send({
method: "Page.navigate",
params: { url: "https://example.com" },
sessionId: "active",
});
} finally {
const report = await session.close();
// { restarted, newTabs, tabClosed, tabShared }, or undefined if unused
}const session = this.browser.session({ scope: conversationId });
try {
await session.send({
method: "Page.navigate",
params: { url: "https://example.com" },
sessionId: "active",
});
} finally {
const report = await session.close();
// { restarted, newTabs, tabClosed, tabShared }, or undefined if unused
}构建网站的代理需要在真实浏览器中检查结果。内部主机名允许代理浏览器预览容器中运行的开发服务器,而无需将其暴露到公共互联网。
内部主机名会将代理提供的网站交给浏览器,而不是访问互联网,例如 R2 存储桶中的静态资源、代理工作区中的文件夹、沙箱中的开发服务器或另一个 Worker。只有此浏览器可以访问这些主机名。
发往内部主机名的请求不会离开 Cloudflare。Browser Run 会通过 outbound Workers将请求发送到你的 Worker,而 Browser 会在 Durable Object 中调用相应主机的 fetch 函数,因此可以使用该对象的绑定和状态。
若要添加内部主机名,请确保已安装 Agents SDK v0.31.0 ↗ 或更高版本。将 internalHosts 传递给 browserRun()。此配置适用于浏览器工具适配器或使用 browser.session() 实现的工具:
import { DurableObject } from "cloudflare:workers";
import { Browser, browserRun } from "agents/browser";
import { Lifecycle } from "agents/lifecycle";
import { z } from "zod";
// Your own code: serve a workspace folder's files, and reach a port on your
// sandbox. Each returns a Response.
import { fetchSandboxPort, serveWorkspaceFolder } from "./hosts";
// Browser Run calls back into your Worker through this entrypoint.
export { InternalHostRouter } from "agents/browser";
export class BrowserAssistant extends DurableObject {
browser = new Browser({
provider: browserRun(this.env.BROWSER, {
guardrails: { allowedDomains: [] }, // internal hosts only
internalHosts: {
router: this.ctx.exports.InternalHostRouter,
hosts: {
"assets.internal": {
description: "Your app's static assets, served from an R2 bucket",
fetch: async (request) => {
const { pathname } = new URL(request.url);
const file = await this.env.ASSETS_BUCKET.get(
decodeURIComponent(pathname.slice(1)),
);
if (!file) return new Response("Not found", { status: 404 });
const headers = new Headers();
file.writeHttpMetadata(headers); // its Content-Type
return new Response(file.body, { headers });
},
},
"site.internal": {
description: "A workspace folder, such as a production build",
target: z.object({
folder: z
.string()
.startsWith("/workspace/")
.refine((path) => !path.split("/").includes("..")),
}),
fetch: (request, { folder }) =>
serveWorkspaceFolder(folder, request),
},
"preview.internal": {
description: "Your dev servers",
target: z.object({ port: z.number().int().min(1024) }),
fetch: (request, { port }) => fetchSandboxPort(port, request),
},
"api.internal": { worker: this.env.API },
},
},
}),
});
lifecycle = Lifecycle.install(this).use(this.browser);
// InternalHostRouter calls this method to reach your Browser.
fetchInternalHost(message) {
return this.browser.fetchInternalHost(message);
}
}import { DurableObject } from "cloudflare:workers";
import { Browser, browserRun, type InternalHostMessage } from "agents/browser";
import { Lifecycle } from "agents/lifecycle";
import { z } from "zod";
// Your own code: serve a workspace folder's files, and reach a port on your
// sandbox. Each returns a Response.
import { fetchSandboxPort, serveWorkspaceFolder } from "./hosts";
// Browser Run calls back into your Worker through this entrypoint.
export { InternalHostRouter } from "agents/browser";
export class BrowserAssistant extends DurableObject<Env> {
browser = new Browser({
provider: browserRun(this.env.BROWSER, {
guardrails: { allowedDomains: [] }, // internal hosts only
internalHosts: {
router: this.ctx.exports.InternalHostRouter,
hosts: {
"assets.internal": {
description: "Your app's static assets, served from an R2 bucket",
fetch: async (request) => {
const { pathname } = new URL(request.url);
const file = await this.env.ASSETS_BUCKET.get(
decodeURIComponent(pathname.slice(1)),
);
if (!file) return new Response("Not found", { status: 404 });
const headers = new Headers();
file.writeHttpMetadata(headers); // its Content-Type
return new Response(file.body, { headers });
},
},
"site.internal": {
description: "A workspace folder, such as a production build",
target: z.object({
folder: z
.string()
.startsWith("/workspace/")
.refine((path) => !path.split("/").includes("..")),
}),
fetch: (request, { folder }) =>
serveWorkspaceFolder(folder, request),
},
"preview.internal": {
description: "Your dev servers",
target: z.object({ port: z.number().int().min(1024) }),
fetch: (request, { port }) => fetchSandboxPort(port, request),
},
"api.internal": { worker: this.env.API },
},
},
}),
});
lifecycle = Lifecycle.install(this).use(this.browser);
// InternalHostRouter calls this method to reach your Browser.
fetchInternalHost(message: InternalHostMessage) {
return this.browser.fetchInternalHost(message);
}
}每个主机都包含 fetch 函数或 worker,并可选包含模型可读取的 description:
- 带有
fetch的主机会针对每个请求在 Durable Object 中运行该函数,并返回其Response。 - 带有
worker的主机(即服务绑定或ctx.exports入口点)会将请求直接发送到该 Worker,而不经过你的 Durable Object。
fetch 主机需要两处连接配置。从 Worker 的主模块导出 InternalHostRouter,并将其作为 router 传入。Browser Run 会调用它,而它会调用 Durable Object 的 fetchInternalHost() 方法。Agent 类内置了此方法,因此在 Agent 上无需另行配置。如果一个 Durable Object 上有多个 Browser,请使用 message.browser 选择指定的浏览器。
browserTool 会在工具描述中列出每个主机及其说明。模型可以打开 http://assets.internal/,或调用 browser.listHosts() 查看各主机及其指向的位置。
只有 fetch 的主机始终提供相同内容。添加 target 架构后,模型就可以选择主机提供的内容。在浏览器代码中,模型调用 browser.assignHost(),然后导航到该方法返回的 URL:
const { url } = await browser.assignHost({
host: "preview.internal",
target: { port: 5173 },
});
await browser.cdp({
method: "Page.navigate",
params: { url },
sessionId: "active",
});系统会根据架构检查目标,将其存储后作为第二个参数传递给 fetch 函数。target 接受标准 JSON Schema ↗,例如 Zod 4.2 或更高版本、ArkType,或通过适配器接入的 Valibot;适配器也会为参数提供类型。它还接受普通 JSON Schema 对象,此时参数类型为 unknown。
由模型选择目标。如果目标的一部分会在 fetch 函数中成为路径、URL 或命令,请在架构中加以限制,例如使用枚举、模式或范围,就像 site.internal 对其文件夹所做的那样。
分配会一直保留,直到被清除。即使浏览器被替换、Durable Object 被逐出或重新部署,分配也会保留。可分配主机在获得目标之前会返回 502。模型可以调用 browser.clearHost({ host }) 移除主机。在自己的代码中,可使用 this.browser.internalHosts.assign(host, target)、.clear(host) 和 .list()。
- 一个浏览器最多可配置八个内部主机名。
- 主机名必须是纯小写名称,并以
.internal、.test、.example或.invalid结尾,例如preview.internal,而不是http://preview.internal:5173。这些后缀不会在公共互联网上解析,因此主机无法冒充真实网站。 - 内部主机使用端口 80 上的普通 HTTP。不支持 HTTPS 或 WebSockets,因此开发服务器的热重载无法连接。
- 主机名集合在浏览器启动时固定。更改集合会在下次使用浏览器时替换浏览器。更改
fetch函数则不会。同样,将worker主机指向另一个 Worker 也不会替换浏览器,因此更改后请调用browser.close()。 - Guardrails不适用于内部主机。将
allowedDomains: []设为空数组,即可让浏览器只能访问内部主机。 - 宿主的
fetch函数抛出异常时,浏览器会收到502,并且系统会记录错误。页面不会看到错误消息。 - 内部主机仅在 Worker 已部署时可用。在本地开发中,浏览器启动时不会配置这些主机,并会记录警告。
- 请在顶层 Durable Object 或 Agent 上安装
Browser。目前尚不支持子 Agent。
Live View 让人实时观看或控制运行中的浏览器。当某一步需要人工时使用它,例如登录、多因素认证(MFA)、CAPTCHA 或敏感输入。
从应用调用 browser.liveView(),获取进入模型所用同一浏览器的链接。它会列出 Browser 中所有 scope 的每个打开标签页。它不会启动浏览器:当没有浏览器打开,或浏览器已关闭或过期时,它返回 undefined。
例如,向 Durable Object 添加一个方法,返回浏览器的网页及其 Live View 链接。在认证用户之后从 Worker 调用它:
export class BrowserAssistant extends DurableObject {
// Browser, harness, and lifecycle as in the Pi Durable example.
async getLiveView() {
const view = await this.browser.liveView({ mode: "tab" });
if (!view) {
return [];
}
return view.targets
.filter((tab) => tab.pageUrl?.startsWith("http"))
.map((tab) => ({
title: tab.title,
pageUrl: tab.pageUrl,
liveViewUrl: tab.url,
}));
}
}export class BrowserAssistant extends DurableObject<Env> {
// Browser, harness, and lifecycle as in the Pi Durable example.
async getLiveView() {
const view = await this.browser.liveView({ mode: "tab" });
if (!view) {
return [];
}
return view.targets
.filter((tab) => tab.pageUrl?.startsWith("http"))
.map((tab) => ({
title: tab.title,
pageUrl: tab.pageUrl,
liveViewUrl: tab.url,
}));
}
}browser.liveView() 返回带有以下字段的对象:
| 字段 | 描述 |
|---|---|
sessionId |
Browser Run 会话 ID。 |
targets |
每个打开标签页一条,包含其 targetId、Live View url,以及标签页当前的 pageUrl、title 和 type。 |
expiresInMs |
Live View URL 对启动连接保持有效的时间,大约五分钟。 |
传入 mode: "tab" 获得交互式页面视图,或传入 mode: "devtools" 获得完整 DevTools 检查器。省略 mode 以使用 Browser Run 的默认视图。
browserTool 不会在有人操作时暂停运行。改为在轮次之间交接:
- 模型到达它无法完成的步骤,例如登录页面,并向用户请求帮助。
- 你的应用调用
browser.liveView()并向用户展示链接。 - 用户在 Live View 中完成该步骤。
- 在下一轮,模型在同一浏览器中继续,新的 cookie 和登录状态已就位。
若有人关闭了模型的活动标签页,模型的下一个结果会说明该标签页已关闭。
调用 browser.close() 结束浏览器。该方法会删除 Browser Run 会话;如果没有打开的浏览器,则返回 false。下次使用 Browser 时会启动新的浏览器,结果中的 notice 会告知所有曾在旧浏览器中运行的作用域:其状态已丢失。
await this.browser.close();await this.browser.close();会话录制 将 Browser Run 会话捕获为结构化 rrweb 事件:DOM 变化、输入和导航,而不是视频。使用录制来审计或调试 Agent 在其浏览器中做了什么。
要开启录制,在 provider 选项中设置 recording: true:
export class BrowserAssistant extends DurableObject {
browser = new Browser({
provider: browserRun(this.env.BROWSER, { recording: true }),
});
}export class BrowserAssistant extends DurableObject<Env> {
browser = new Browser({
provider: browserRun(this.env.BROWSER, { recording: true }),
});
}该选项适用于 Browser 创建的每个浏览器,包括重启后的替代实例。每个 Browser Run 会话都有自己的录制。会话关闭后会 finalize 录制,发生在 browser.close() 之后,或浏览器空闲时间超过 keepAliveMs 时。
在浏览器打开时记下 Browser Run 会话 ID,然后在浏览器关闭后获取录制:
import { getBrowserRecording } from "agents/browser";
// While the browser is open. resolve() starts a browser if none is open.
const { sessionId } = await this.browser.resolve();
// After the browser closes:
const recording = await getBrowserRecording({
accountId: this.env.CF_ACCOUNT_ID,
apiToken: this.env.CF_API_TOKEN,
sessionId,
});
// recording.events holds one rrweb event array per tab, keyed by target ID.import { getBrowserRecording } from "agents/browser";
// While the browser is open. resolve() starts a browser if none is open.
const { sessionId } = await this.browser.resolve();
// After the browser closes:
const recording = await getBrowserRecording({
accountId: this.env.CF_ACCOUNT_ID,
apiToken: this.env.CF_API_TOKEN,
sessionId,
});
// recording.events holds one rrweb event array per tab, keyed by target ID.getBrowserRecording() 使用 Browser Run REST API,因此需要你的账户 ID 和具有 Browser Run 访问权限的 API token。Workers 绑定无法读取录制。录制保留 30 天,每会话上限两小时。
模型会针对 browser 对象编写异步箭头函数。接受参数的方法只接受一个对象:
| 方法 | 描述 |
|---|---|
browser.cdp({ method, params?, sessionId?, timeoutMs? }) |
发送 CDP 命令并返回其结果。 |
browser.attachToTarget({ targetId, timeoutMs? }) |
连接到标签页并将其设为活动标签页,然后为页面作用域调用返回 { sessionId }。 |
browser.spec({ domain? }) |
列出 CDP 协议的域,或返回某个域的命令、事件和类型。 |
browser.getDebugLog({ limit? }) |
返回此次调用的近期 CDP 流量,包括发送、接收和警告。 |
browser.clearDebugLog() |
清除 debug log。 |
browser.listHosts() |
列出内部主机名及其各自指向的位置。 |
browser.assignHost({ host, target }) |
将可分配的内部主机指向某个目标,并返回 { url }。 |
browser.clearHost({ host }) |
移除内部主机的目标。 |
浏览器有内部主机名时可使用 listHosts();其中某个主机具有 target 架构时可使用 assignHost() 和 clearHost()。该工具的说明涵盖此 API 以及模型常犯的 CDP 错误,因此模型无需先进行探索。
Browser API 还遵循以下规则:
sessionId: "active"寻址该 scope 的活动标签页。Browser.*和Target.*命令不需要sessionId。- 后续调用仍可使用来自
browser.attachToTarget()的sessionId。 - 每次调用都会在没有网络访问权限的新 Dynamic Worker 中运行。
fetch()和connect()会被阻止,因此代码只能通过browser与外部交互。 - 每次调用都会在
timeoutMs之后超时,默认值为 60 秒。 - 结果最多约 24,000 个字符,控制台输出最多 100 行。屏幕截图不得超过 1 MB。若要捕获长页面,请截取视口,或使用 JPEG。
模型无法发送以下命令,因为你的应用拥有浏览器及其 Live View 链接:
Browser.close、Browser.crash和Browser.crashGpuProcess。如需关闭标签页,模型会发送Target.closeTarget。Cloudflare.getLiveView和Cloudflare.handoff。Target.sendMessageToTarget和Target.exposeDevToolsProtocol,否则可借此发送其他被拒绝的命令。
要读取已知 URL 的页面或文档,请改用 web_fetch tool,而不是浏览器。它不会启动浏览器,因此每次读取都是一次 HTTP 请求。它还会将 PDF 和 Office 文档转换为 Markdown,并将长页面拆成模型可以依次读取的部分。
在页面需要浏览器时使用 browserTool:
- 页面用 JavaScript 渲染内容。
- 页面需要登录,或模型必须点击、输入或在多个页面间移动。
- Agent 必须在后续轮次回到同一页面、标签页或会话。
- 你需要页面的屏幕截图。
agents/browser/ai 中的 createBrowserTools 和 createBrowserRuntime 已弃用。它们仍可继续使用,直到被移除,但不会再有变更。agents/browser/tanstack-ai 中的 createBrowserTools、agents/browser 中的 BrowserConnector、Quick Action 工具,以及基于这些工具构建的 @cloudflare/think/tools/browser 中的 Think 浏览器工具也同样如此。新代码应使用 Browser 和 browserTool。
你可能仍会在以下情况使用旧版 tools:
- 你自己的浏览器。 使用
cdpUrl连接到你管理的 CDP 端点。Browser只支持 Browser Run 的 Chromium 引擎。 - Kitesurf。 Kitesurf 浏览器只在其 CDP WebSocket 存活期间存在,因此不能作为持久化浏览器。
- 一次运行内的审批或人工交接。 持久化 Code Mode 运行时 可以暂停运行以等待审批,并在浏览器会话保持完整的情况下恢复。
browserTool不会暂停运行。
你不需要旧版 tools 就能为每次运行获得新浏览器。使用 browserTool 时,在一轮之后调用 browser.close(),或设置较短的 keepAliveMs,以便下一次运行启动新浏览器。要不使用浏览器读取页面,请使用 web_fetch tool。
使用 Browser Run 和 Worker Loader 绑定创建浏览器工具,然后将这些工具传给模型调用。模型会在 browser_execute 工具中针对 cdp 对象编写代码,详见旧版 CDP 方法。
import { AIChatAgent } from "@cloudflare/ai-chat";
import { createBrowserTools } from "agents/browser/ai";
import { streamText, convertToModelMessages, stepCountIs } from "ai";
import { createAI } from "agents/models/ai-sdk";
export class BrowserAgent extends AIChatAgent {
async onChatMessage() {
const ai = createAI({ binding: this.env.AI });
const browserTools = createBrowserTools({
ctx: this.ctx,
browser: this.env.BROWSER,
loader: this.env.LOADER,
});
const result = streamText({
model: ai("@cf/zai-org/glm-4.7-flash"),
system: "You can inspect web pages with browser tools.",
messages: await convertToModelMessages(this.messages),
tools: browserTools,
stopWhen: stepCountIs(10),
});
return result.toUIMessageStreamResponse();
}
}import { AIChatAgent } from "@cloudflare/ai-chat";
import { createBrowserTools } from "agents/browser/ai";
import { streamText, convertToModelMessages, stepCountIs } from "ai";
import { createAI } from "agents/models/ai-sdk";
export class BrowserAgent extends AIChatAgent<Env> {
async onChatMessage() {
const ai = createAI({ binding: this.env.AI });
const browserTools = createBrowserTools({
ctx: this.ctx,
browser: this.env.BROWSER,
loader: this.env.LOADER,
});
const result = streamText({
model: ai("@cf/zai-org/glm-4.7-flash"),
system: "You can inspect web pages with browser tools.",
messages: await convertToModelMessages(this.messages),
tools: browserTools,
stopWhen: stepCountIs(10),
});
return result.toUIMessageStreamResponse();
}
}浏览器 tools 必须在 Durable Object(如 Agent)内创建。持久化运行时 facet 和会话存储位于其 ctx 上。helper 暴露一个持久化 CDP tool,以及存在 browser 绑定时的无状态 Quick Action tools:
| 工具 | 描述 |
|---|---|
browser_execute |
通过 CDP 对实时浏览器运行沙箱化代码——截图、DOM 读取、JavaScript 评估等。 |
browser_markdown |
将页面或原始 HTML 读取为 Markdown。 |
browser_extract |
使用 AI 从页面提取结构化数据。 |
browser_links |
列出页面上的链接。 |
browser_scrape |
按 CSS 选择器抓取特定元素。 |
TanStack AI 的 createBrowserTools 只返回 browser_execute。要发现协议 surface,模型调用 cdp.spec() 或运行时的内置 codemode.search() 和 codemode.describe()。
旧版工具与 browserTool 使用相同的 BROWSER 和 LOADER 绑定。有关 Wrangler 配置,请参阅与 Pi Durable 搭配使用。与 browserTool 不同,这些工具还需要 Worker 导出 CodemodeRuntime:
export { CodemodeRuntime } from "agents/browser";@cloudflare/codemode/vite 插件会自动添加 CodemodeRuntime 导出。
createBrowserTools 和 createBrowserRuntime 接受以下选项:
| 选项 | 默认值 | 描述 |
|---|---|---|
browser |
— | Browser Run 绑定。 |
cdpHeaders |
— | CDP URL 发现的标头,例如 Cloudflare Access 标头。 |
cdpUrl |
— | 自定义 CDP 端点。两者都设置时优先于 browser。 |
ctx |
当前 Agent 的 state | 托管运行时 facet 和会话存储的 Durable Object。 |
loader |
必填 | 用于沙箱化 execution 的 Worker Loader 绑定。 |
name |
"browser" |
Runtime 名称,即 executions 的持久化身份。 |
quickActions |
存在 browser 绑定时开启 |
要包含的 Quick Action tools。传入 false 或 { actions, maxChars, options }。 |
session |
{ mode: "one-shot" } |
会话生命周期模式、录制和引擎。 |
store |
Durable Object 存储 | Browser Run 会话 ID 的持久化存储。 |
timeout |
30000 |
以毫秒计的 execution 超时,也用作每条命令的 CDP 超时。 |
提供 browser 或 cdpUrl。仅设置 cdpUrl 时会跳过 Quick Action tools。
默认每次 execution 获得新的浏览器会话,运行结束时销毁(one-shot)。传入 session 选项可使用另外两种模式:
createBrowserTools({
ctx: this.ctx,
browser: this.env.BROWSER,
loader: this.env.LOADER,
session: { mode: "dynamic" }, // or { mode: "reuse", key: "main" }
});createBrowserTools({
ctx: this.ctx,
browser: this.env.BROWSER,
loader: this.env.LOADER,
session: { mode: "dynamic" }, // or { mode: "reuse", key: "main" }
});one-shot(默认)— 每次 execution 新会话;execution 达到终端状态时确定性清理。reuse— 命名共享会话,在显式关闭或 sweep 前跨 execution 持久化。dynamic— 以 one-shot 开始;模型可用cdp.startSession()提升会话(例如登录页面后),使后续 execution 在同一浏览器中继续。
会话在 Durable Object 存储中持久跟踪,因此可在休眠和审批暂停中存活。暂停等待人工审批的运行会与其浏览器会话、标签页和 cookie 一起恢复。若 Browser Run 在暂停等待期间使会话过期,恢复会抛出清晰错误,模型重新开始。
对于宿主侧接线,使用 createBrowserRuntime,它返回 { runtime, connector, tools }:
import { createBrowserRuntime } from "agents/browser/ai";
const { runtime, connector, tools } = createBrowserRuntime({
ctx: this.ctx,
browser: this.env.BROWSER,
loader: this.env.LOADER,
session: { mode: "dynamic" },
});
await connector.sessionInfo(); // Shared session ID and open tabs
await connector.liveView(); // Live View URLs for the shared session's tabs
await connector.closeSession(); // Close the shared session
await connector.sweep(); // Reclaim expired or stale sessions
await runtime.expirePaused(); // Reject stale pauses that were never approvedimport { createBrowserRuntime } from "agents/browser/ai";
const { runtime, connector, tools } = createBrowserRuntime({
ctx: this.ctx,
browser: this.env.BROWSER,
loader: this.env.LOADER,
session: { mode: "dynamic" },
});
await connector.sessionInfo(); // Shared session ID and open tabs
await connector.liveView(); // Live View URLs for the shared session's tabs
await connector.closeSession(); // Close the shared session
await connector.sweep(); // Reclaim expired or stale sessions
await runtime.expirePaused(); // Reject stale pauses that were never approved从调度任务调用 connector.sweep()。connector.liveView() 返回共享会话的标签页和 Live View URL,以及每个标签页当前的 pageUrl,因此 Agent UI 可以标注标签页并跳过空白或内部页面。
使用 createBrowserRuntime 时,Code Mode 运行时可以在浏览器会话保持完整的情况下暂停运行。交接遵循以下模式:
- 模型调用
cdp.getLiveViewUrl()获取当前标签页的链接。 - Agent 向用户展示链接。
- 模型进行需审批的调用,运行持久化暂停。
- 审批后,运行在同一会话中恢复。
async () => {
const { targetId } = await cdp.send({
method: "Target.createTarget",
params: { url: "https://example.com/login" },
});
const { url } = await cdp.getLiveViewUrl({ targetId, mode: "tab" });
return { needsHumanLogin: url };
};async () => {
const { targetId } = await cdp.send({
method: "Target.createTarget",
params: { url: "https://example.com/login" },
});
const { url } = await cdp.getLiveViewUrl({ targetId, mode: "tab" });
return { needsHumanLogin: url };
};传入 mode: "tab" 获得交互式页面视图,或传入 mode: "devtools" 获得完整 DevTools 检查器。URL 有效期约五分钟。再次调用 cdp.getLiveViewUrl() 创建新 URL。
每个 cdp.* 调用都记录在运行时的持久化 log 中。若运行因审批暂停或沙箱 abort,恢复会重放 log 并继续。因此 connector 调用必须顺序且确定性。模型代码不得对 CDP 调用使用 Promise.all,tool 说明会强制执行这一点。cdp.attachToTarget() 返回的 sessionId 是稳定 handle,在暂停和恢复中保持有效。
browser_execute 中的模型代码使用 cdp 对象。接受参数的方法只接受一个对象:
| 方法 | 描述 |
|---|---|
cdp.send({ method, params?, sessionId?, timeoutMs? }) |
发送 CDP 命令并返回其结果。 |
cdp.attachToTarget({ targetId, timeoutMs? }) |
附加到标签页并返回 { sessionId },作为页面范围 send 调用的 handle。 |
cdp.spec() |
返回来自实时浏览器的可搜索、规范化 CDP 协议描述。 |
cdp.getDebugLog({ limit? }) |
返回本次运行最近的 CDP 流量,包括发送、接收和警告。 |
cdp.clearDebugLog() |
清除 debug log。 |
browser_execute 还提供以下方法:
| 方法 | 可用性 | 描述 |
|---|---|---|
cdp.getLiveViewUrl({ targetId?, mode? }) |
Chromium 会话 | 为标签页创建 Live View URL。 |
cdp.startSession() |
reuse, dynamic |
提升或确保共享会话,并返回其信息。 |
cdp.sessionInfo() |
reuse, dynamic |
返回共享会话信息,或 null。 |
cdp.closeSession() |
reuse, dynamic |
关闭共享会话。 |
cdp.resetSession() |
reuse, dynamic |
关闭并替换共享会话。 |
要录制旧版会话,在 session 选项中设置 recording: true:
import { createBrowserRuntime } from "agents/browser/ai";
const { connector } = createBrowserRuntime({
ctx: this.ctx,
browser: this.env.BROWSER,
loader: this.env.LOADER,
session: { mode: "reuse", key: "main", recording: true },
});import { createBrowserRuntime } from "agents/browser/ai";
const { connector } = createBrowserRuntime({
ctx: this.ctx,
browser: this.env.BROWSER,
loader: this.env.LOADER,
session: { mode: "reuse", key: "main", recording: true },
});会话关闭后会 finalize 录制。在会话存活时用 connector.sessionInfo() 捕获会话 ID,然后按录制中所述用 getBrowserRecording() 获取录制。共享 reuse 或 dynamic 会话上的录制跨越完整会话生命周期,包括共享该会话 key 的每个用户。
要在 browser_execute 中使用 Kitesurf,在会话选项中选择它:
const tools = createBrowserTools({
ctx: this.ctx,
browser: this.env.BROWSER,
loader: this.env.LOADER,
session: { browser: "kitesurf" },
});const tools = createBrowserTools({
ctx: this.ctx,
browser: this.env.BROWSER,
loader: this.env.LOADER,
session: { browser: "kitesurf" },
});Kitesurf 浏览器限定在其 CDP WebSocket 范围内,因此只支持一次性 execution。会话复用、暂停与恢复、Live View、录制、keepAliveMs、通过 cdp.spec() 发现协议,以及基于 Kitesurf 的 Quick Actions 均不可用。
agents/browser/ai 中的 createQuickActionTools 为模型提供 Browser Run Quick Actions 的 tools。每次调用都是一次性请求:Browser Run 在新浏览器中加载页面、返回结果,然后关闭浏览器。Quick Actions 只需 browser 绑定,因此不需要 Durable Object、Worker Loader 或沙箱。要读取页面,优先使用 web_fetch tool。
Quick Actions 不与 browserTool 共享浏览器或登录。模型用 browserTool 登录过的站点,在 Quick Action 中不会处于登录状态。要读取受保护页面,请通过 options 传入 cookies 或 authenticate 等凭据。
import { createQuickActionTools } from "agents/browser/ai";
const tools = createQuickActionTools({ browser: this.env.BROWSER });
// browser_markdown, browser_extract, browser_links, browser_scrapeimport { createQuickActionTools } from "agents/browser/ai";
const tools = createQuickActionTools({ browser: this.env.BROWSER });
// browser_markdown, browser_extract, browser_links, browser_scrape传入 actions 选择 tools,传入 maxChars 限制结果,传入 options 设置请求:
const tools = createQuickActionTools({
browser: this.env.BROWSER,
maxChars: 20_000,
options: { gotoOptions: { waitUntil: "networkidle0" } },
});const tools = createQuickActionTools({
browser: this.env.BROWSER,
maxChars: 20_000,
options: { gotoOptions: { waitUntil: "networkidle0" } },
});每个 Quick Action 结果都限制为 maxChars(默认 50,000 个字符),在保护模型上下文窗口的同时保留结果形状。宿主提供的请求选项(如 cookies、authenticate、gotoOptions 和 viewport)通过 options 一次性传入,不暴露给模型。
Quick Actions 需要 Worker compatibility_date 为 2026-03-24 或更高,且本地 wrangler dev 时 browser 绑定需 remote: true。
浏览器 Agent 示例使用旧版 tools。它涵盖 Browser Run 设置、tool 定义和截图捕获。