跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

浏览器

最后更新 查看 MarkdownAgent 设置

为 Agent 提供可在后续轮次回访的浏览器。Browser Run 会保持远程浏览器打开,因此只要浏览器会话仍然存活,Agent 就可以带着标签页、cookie 和登录会话从同一页面继续。

使用浏览器工具与网站交互、检查通过 JavaScript 渲染的页面或截取屏幕截图。配置内部主机名后,浏览器还可打开仅由代理提供服务的网站,例如其沙箱中的开发服务器或工作区文件夹。

回到同一个浏览器

研究助手可以打开仪表板、检查报告,并在后续轮次回到该页面。Browser 类会在 tool 调用之间保持远程浏览器会话打开,包括其标签页、cookie 和登录状态。browserTool adapter 让你的 harness 通过 Chrome DevTools Protocol (CDP) 使用该浏览器。

浏览器运行在 Agent 的 Durable Object 之外。对象会保存其会话标识符,并在休眠后重新连接,只要浏览器会话仍然存活。默认情况下,空闲浏览器最多保持存活 10 分钟。这不会永久保存浏览器:过期或崩溃会丢失其标签页、cookie 和登录状态。

与 Pi Durable 一起使用

请从 Pi Durable agent开始。在 Pi 软件包旁安装 Agents SDK:

npm i agents @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord @cloudflare/codemode

Pi 软件包是 agents 的可选 peer dependency,版本为 ~1.4.0。Pi Durable 是实验性功能,其 API 可能在次要版本中发生变化,因此每个 agents 版本仅支持一个 Pi 次要版本。请安装软件包管理器为 agents 解析出的版本。

本示例在普通 Durable Object 上安装 Browser 和 PiHarness。Pi 决定何时调用浏览器 tool。Lifecycle 启动这两个组件并提供它们的存储。

src/index.jsjs
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 });
	},
};
src/index.tsts
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

内部主机名是浏览器的一项功能,与代理 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 函数,因此可以使用该对象的绑定和状态。

三种主机名的动画示意图:example.com 连接到互联网;模型通过 browser.assignHost() 将 preview.internal 指向端口 5173,然后浏览器打开该地址,由你的代理从沙箱提供服务;api.internal 则直接连接另一个 Worker,绕过你的代理

添加内部主机名

若要添加内部主机名,请确保已安装 Agents SDK v0.31.0 ↗ 或更高版本。将 internalHosts 传递给 browserRun()。此配置适用于浏览器工具适配器或使用 browser.session() 实现的工具:

src/index.jsjs
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);
	}
}
src/index.tsts
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 与人工接管

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 不会在有人操作时暂停运行。改为在轮次之间交接:

  1. 模型到达它无法完成的步骤,例如登录页面,并向用户请求帮助。
  2. 你的应用调用 browser.liveView() 并向用户展示链接。
  3. 用户在 Live View 中完成该步骤。
  4. 在下一轮,模型在同一浏览器中继续,新的 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 API

模型会针对 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 必须在后续轮次回到同一页面、标签页或会话。
  • 你需要页面的屏幕截图。

旧版浏览器 tools

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 在暂停等待期间使会话过期,恢复会抛出清晰错误,模型重新开始。

宿主侧 helper

对于宿主侧接线,使用 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 approved
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 approved

从调度任务调用 connector.sweep()。connector.liveView() 返回共享会话的标签页和 Live View URL,以及每个标签页当前的 pageUrl,因此 Agent UI 可以标注标签页并跳过空白或内部页面。

审批与人工交接

使用 createBrowserRuntime 时,Code Mode 运行时可以在浏览器会话保持完整的情况下暂停运行。交接遵循以下模式:

  1. 模型调用 cdp.getLiveViewUrl() 获取当前标签页的链接。
  2. Agent 向用户展示链接。
  3. 模型进行需审批的调用,运行持久化暂停。
  4. 审批后,运行在同一会话中恢复。
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,在暂停和恢复中保持有效。

旧版 CDP 方法

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 的每个用户。

Kitesurf

要在 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 均不可用。

Quick Action 工具

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_scrape
import { 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 示例

浏览器 Agent 示例使用旧版 tools。它涵盖 Browser Run 设置、tool 定义和截图捕获。

浏览器 Agent

构建可浏览网页、检查页面、截取屏幕截图并调试前端问题的 Agent。

相关资源

Browser Run

在 Cloudflare 上运行浏览器自动化。

这篇文档对您有帮助吗?