agent-browser：面向 AI Agent 的浏览器自动化

最后更新: 2026-09-11 11:02:01 +0800 +0800
tags: Ai | Agents | Browser | Automation | Rust
原文以英文撰写。您正在阅读AI翻译版本。

agent-browser 是一个面向 AI Agent 设计的 Apache-2.0 浏览器自动化 CLI。它不要求 Agent 生成完整的 Playwright 程序，而是将导航、交互、检查、状态、网络和可观测性操作公开为 Shell 命令。持久化原生守护进程会在这些命令之间保留浏览器实例。

该项目结合了以下三个理念：

  1. 紧凑的可访问性快照为模型提供页面的结构化视图，而无需发送完整 DOM。
  2. 快照引用用于在后续命令中标识元素。
  3. 长生命周期守护进程将浏览器生命周期与每个 CLI 进程的生命周期分离。

截至 2026 年 9 月 11 日，当前版本为 0.37.1。项目变化迅速，因此本文中依赖版本的行为均链接到 0.37.1 源代码修订版。

浏览器自动化为何需要面向 Agent 的接口 #

Playwright 及类似库提供了精确的浏览器 API，但由 LLM 驱动的进程直接使用这些 API 时，会产生额外成本：

  • 生成的源代码会消耗上下文，并且需要运行时。
  • 原始 DOM 包含脚本、样式、隐藏节点和框架生成的结构，而这些内容很少有助于下一步操作。
  • 根据一次观察生成的 CSS 选择器可能会在重新渲染后失效。
  • 独立脚本需要显式管理浏览器和上下文的生命周期。

agent-browser 改变的是接口，而不是浏览器。Agent 观察紧凑的树，选择一项操作，执行一条命令，然后再次观察：

flowchart LR
    Goal[User Goal] --> Model[Agent]
    Model -->|open or snapshot| CLI[agent-browser CLI]
    CLI --> Daemon[Native Daemon]
    Daemon -->|CDP or WebDriver| Browser[Browser]
    Browser --> Daemon
    Daemon -->|Snapshot and Refs| Model
    Model -->|click @e2| CLI

模型仍然负责决定执行什么，而 CLI 提供稳定的操作词汇并管理浏览器状态。根据项目概览，典型的文本快照约使用 200–400 个 Token，而完整 DOM 则使用 3,000–5,000 个 Token。这些数字是项目估算值，而不是独立基准测试结果，但其根本原因很明确：可访问性树省略了 Agent 不需要的大量实现细节。

架构 #

每次调用都会启动一个小型 CLI 客户端。客户端解析参数并与原生 Rust 守护进程通信；守护进程负责拥有或连接浏览器，并通过 Chrome DevTools Protocol（CDP）发送命令。

flowchart TB
    subgraph Commands[Short-Lived Processes]
        C1[open]
        C2[snapshot]
        C3[click]
    end

    Socket[Local IPC]
    Daemon[Persistent Rust Daemon]
    CDP[Chrome DevTools Protocol]
    Chrome[Chrome or Chromium]

    C1 --> Socket
    C2 --> Socket
    C3 --> Socket
    Socket --> Daemon
    Daemon --> CDP
    CDP --> Chrome

持久化很重要，因为登录状态、打开的标签页、Cookie jar 和内存中的应用状态会在 Shell 命令之间保留。守护进程会自动启动。默认情况下，它会保存已配置的恢复状态，关闭本地拥有的无头浏览器，并在连续一小时没有命令或控制面板输入后退出。有头浏览器、Safari 和 iOS WebDriver 会话，以及通过 CDP 连接的浏览器不受默认关闭行为影响。可通过 --idle-timeout 或 AGENT_BROWSER_IDLE_TIMEOUT_MS 配置超时时间。

当前版本采用原生 Rust 实现；早期的 Node.js 和 Playwright 守护进程已经移除。由于原生路径直接使用 CDP，Chrome 和 Chromium 是主要目标。项目还提供：

  • 兼容 CDP 的 Lightpanda 引擎，但不支持有头模式、扩展和持久化配置文件；
  • 通过 Appium 和 XCUITest 在 iOS Simulator 中运行 Safari；以及
  • 面向 Browser Use、Browserbase、Browserless、Kernel 和 AWS Bedrock AgentCore 的云浏览器提供商。

不同后端的能力并不完全相同。例如，带标注的屏幕截图可以在 CDP 路径上运行，但不能在 Safari WebDriver 路径上运行。

安装和运行 agent-browser #

npm 包会安装平台专用的原生二进制文件：

sh 
npm install -g agent-browser
agent-browser install

agent-browser install 会查找兼容的现有浏览器，或者下载 Chrome for Testing。Linux 主机还可以请求安装浏览器系统依赖：

sh 
agent-browser install --with-deps

其他受支持的安装路径包括 npx、项目本地 npm 依赖、macOS 上的 Homebrew，以及 Cargo。已安装的守护进程不需要 Playwright。npm 分发包将 Node.js 24 声明为要求，因为其启动器会选择原生二进制文件；而通过 Homebrew 安装的二进制文件不需要 Node.js 守护进程。构建该仓库时需要 pnpm 11 和 Rust。安装指南还介绍了 agent-browser doctor，它会检查浏览器发现、配置、守护进程文件、提供商连接，以及临时无头启动。

最小交互序列如下：

sh 
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e2
agent-browser screenshot page.png
agent-browser close

CLI 包含 50 多条命令。相关命令组包括导航、表单、键盘和指针输入、标签页、框架、文件、Cookie、存储、网络路由、HAR 捕获、屏幕截图、PDF 生成、视频录制、性能分析和差异比较。agent-browser read <url> 可以在不启动 Chrome 的情况下获取 Agent 可读取的内容，而 agent-browser mcp 则通过 MCP stdio 服务器公开命令接口。

快照和元素引用 #

snapshot 是核心抽象。它会序列化可访问性树，并为元素分配引用：

text 
@e1 [heading] "Documentation" [level=1]
@e2 [input type="search"] placeholder="Search"
@e3 [button] "Submit"

Agent 无需自行编造 CSS 选择器即可执行操作：

sh 
agent-browser fill @e2 "session persistence"
agent-browser click @e3

多个过滤器可以减少上下文使用量：

选项效果
-i、--interactive仅包含可交互元素
-c、--compact移除空的结构元素
-d、--depth限制树深度
-s、--selector将树限制在某个 CSS 选择器内
-u、--urls包含链接目标

引用属于生成它们的页面状态。导航和有意义的 DOM 变化会使引用失效，因此可靠的 Agent 会在每次状态转换后重新获取快照：

sh 
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i

并非所有应用都适合等待 networkidle，因为分析、流式传输和轮询可能使网络活动持续存在。如果存在可观测的应用条件，应优先等待该条件：

sh 
agent-browser wait "#account-dashboard"
agent-browser wait --url "**/account"

snapshot 文档还介绍了单层 iframe 展开。子引用会保留框架上下文，因此命令可以直接操作可访问 iframe 中的元素，而不需要单独切换框架。无法访问可访问性树的跨源框架会被省略。

可访问性并不编码所有视觉事实。Canvas 内容、没有标签的图标、重叠元素和布局缺陷都需要像素信息。带标注的屏幕截图会叠加类似 [2] 的标签，并将其对应到 @e2：

sh 
agent-browser screenshot --annotate page.png

因此，快照应驱动语义交互，而当语义信息不足时，屏幕截图提供视觉证据。

会话、配置文件和状态 #

命名会话可以隔离浏览器实例：

sh 
agent-browser --session buyer open https://shop.example
agent-browser --session admin open https://admin.example
agent-browser session list

每个本地管理的会话都拥有独立的 Cookie、存储、历史记录和认证状态。通过 CDP 连接到同一个现有 Chrome 的会话是例外，因为它们共享同一个 Chrome 实例，并绑定到不同标签页。--pin-tab 可以防止绑定标签页关闭后，会话静默移动到另一个标签页。

三种持久化机制分别解决不同问题：

机制用途
命名会话隔离并发浏览器实例
--profile导入浏览器配置文件，或使用持久化配置文件目录
--state 或 --restore保存并重新加载 Cookie 和 Web Storage

仅有会话名称并不能让数据在守护进程关闭后继续存在。将 --session <name> 与 --restore 结合使用，可在 ~/.agent-browser/sessions/ 下启用自动加载状态和定期保存。

状态文件包含认证材料，因此不得提交到源代码管理系统。设置 64 个字符的十六进制 AGENT_BROWSER_ENCRYPTION_KEY 后，可以使用 AES-256-GCM 加密恢复状态。会话指南介绍了配置文件复制行为、自动保存时间、过期和加密。

配置和部署后端 #

配置按照从低到高的优先级解析：

  1. ~/.agent-browser/config.json；
  2. ./agent-browser.json；
  3. AGENT_BROWSER_* 环境变量；以及
  4. 命令行标志。

项目发布了官方 JSON Schema，因此可以通过编辑器或 CI 作业验证项目配置。

本地执行可以启动无头或有头 Chrome。--executable-path 用于选择特定的 Chromium 系列二进制文件。--cdp 则连接到本地端口、ws:// 端点或 wss:// 端点：

sh 
agent-browser --cdp 9222 snapshot
agent-browser --cdp "wss://browser.example/cdp?token=..." snapshot

提供商模式会将浏览器基础设施迁移到受支持的服务，同时保留相同的 CLI：

sh 
BROWSERBASE_API_KEY=... \
  agent-browser --provider browserbase open https://example.com

远程执行适用于 CI 和无服务器环境，但信任边界会发生变化。提供商凭据、浏览器会话保留、跨区域流量出口以及提供商端的启动行为都会成为部署问题。CDP 调试端点也授予对其浏览器的广泛控制权，因此不得将其暴露给不受信任的网络。

安全性需要显式配置 #

agent-browser 的所有安全功能都是选择启用。默认执行不会限制导航、操作或输出。因此，生产部署应将控制措施定义为 Agent Harness 的一部分：

json 
{
  "$schema": "https://agent-browser.dev/schema.json",
  "contentBoundaries": true,
  "maxOutput": 50000,
  "allowedDomains": [
    "app.example.com",
    "*.app.example.com",
    "cdn.example.net"
  ],
  "actionPolicy": "./agent-browser-policy.json"
}

限制性操作策略可以允许观察和普通导航，同时拒绝代码执行和文件传输：

json 
{
  "default": "deny",
  "allow": [
    "navigate",
    "snapshot",
    "click",
    "scroll",
    "wait",
    "get"
  ]
}

这些控制措施分别应对不同威胁：

  • 内容边界使用随机 nonce 和来源元数据包裹页面派生的输出，帮助编排器区分不受信任的页面文本和工具框架内容。
  • 域名允许列表会阻止不允许的导航和子资源，并在受支持的 Chromium 会话中禁用 WebRTC。
  • 操作策略允许或拒绝 eval、upload、download、network 和 state 等类别。
  • 确认机制会将选定类别置于编排器或交互式审批之后。
  • 输出限制会限制页面派生数据造成的上下文洪泛。
  • 认证凭据保管库会加密保存的凭据，并使密码不出现在常规守护进程 IPC 和 Agent 可见的输出中。

内容边界属于纵深防御，而不是模型会忽略提示注入的证明。域名过滤不是操作系统防火墙，WebSocket 或 EventSource 拦截也只是尽力而为。因此，强隔离应将 agent-browser 策略与容器限制、文件系统权限、网络出口策略和范围严格限定的凭据结合起来。

域名允许列表会有意拒绝若干组合，包括预先存在的 CDP 连接、配置文件、恢复状态以及 Safari/iOS 后端，因为这些模式可能在守护进程建立隔离之前执行现有内容。所需的 CDN、字体、API 和身份提供商域名也必须出现在允许列表中，否则网站将无法加载。

在 agent-browser 和 Playwright 之间进行选择 #

agent-browser 和 Playwright 位于不同的抽象层：

需求更适合的接口
AI Agent 必须通过 Shell 工具检查和操作任意页面agent-browser
测试套件需要断言、fixtures、重试、并行 Worker 和报告Playwright
工作流需要紧凑的观察结果和元素引用agent-browser
代码需要覆盖 Firefox、WebKit 和 ChromiumPlaywright
应用需要类型化的浏览器逻辑和纳入源代码管理的选择器Playwright
Agent 需要按命令持久化的浏览器状态agent-browser

Playwright 是端到端测试框架和浏览器自动化库；agent-browser 是面向 Agent 循环的命令接口。由于 fixtures、断言、追踪工具和多引擎覆盖属于代码，Playwright 仍然更适合确定性的测试程序。agent-browser 减少了从观察到操作的转换，因此适合开放式 Agent 工作。

Browser Use 位于另一层。agent-browser 可以通过 --provider browseruse 将 Browser Use 用作托管浏览器提供商，但该集成并不会让两个项目在功能上等价。如果需要由远程浏览器支持的 agent-browser 命令，应选择提供商集成；如果所需的应用接口是 Browser Use 的 SDK 和 Agent API，则应直接使用 Browser Use。

运维指南 #

可靠的部署应遵循以下规则：

  1. 固定 agent-browser 版本，因为命令行为和后端支持会持续演进。
  2. 在导航或 DOM 变更后重新获取快照，因为元素引用描述的是特定页面状态。
  3. 等待应用可见的条件，而不是假定固定延迟或通用的 networkidle。
  4. 按任务和主体隔离会话，然后避免将隔离的任务连接到同一个 Chrome 实例。
  5. 将屏幕截图、下载内容、视频、HAR 文件、配置文件和保存状态视为可能包含敏感信息的工件。
  6. 显式启用内容边界、输出限制、操作策略和域名限制。
  7. 在浏览器进程以下的层面实施文件系统和网络隔离，因为 CLI 级策略不能替代操作系统沙箱。

agent-browser 不会使浏览器 Agent 变得确定性。页面仍会变化，认证仍会过期，可访问性元数据可能不完整，模型决策仍然具有概率性。agent-browser 提供的是一种更窄且更具状态性的接口：浏览器不再是从头生成的一组脚本，而是一个具有紧凑观察结果、显式引用和可强制执行的操作类别的持久化工具。

参考资料 #

评论

在 GitHub 上阅读或评论（发表评论需要登录）