组件官网地址：agent-browser — AI 代理的无头浏览器自动化 CLI

引言：从爬虫脚本到 AI 助手

在过去的二十余年里，浏览器自动化技术经历了从 Selenium、Puppeteer 到 Playwright 的演进。这些工具各有特点，但在 AI 大语言模型蓬勃发展的今天，它们都面临着一个共同的挑战：如何让 AI 智能体高效地与浏览器交互？

传统浏览器自动化工具的设计初衷是为人类程序员服务的。它们返回复杂的 JSON 对象、完整的 DOM 树或海量的调试信息。这些数据格式对于人类开发者来说或许是友好的，但对于 tokens 资源弥足珍贵的 AI 上下文窗口而言，却是一种沉重的负担。

**Vercel Labs 推出的 **agent-browser 正是为解决这一痛点而诞生的。作为一个 100% 原生 Rust 编写的浏览器自动化 CLI 工具，它将 AI 智能体的体验置于设计的核心位置，提供紧凑的文本输出、确定性的元素引用机制，以及完整的自动化能力。

核心特性：专为 AI 设计的浏览器自动化

Agent 优先的设计理念

传统的浏览器自动化工具往往以「功能完备」为目标，倾向于返回尽可能多的信息。而 agent-browser 反其道而行之，将「上下文效率」作为首要设计原则。

**当你执行 **agent-browser snapshot -i 命令时，返回的不是庞大的 DOM 树或 JSON 对象，而是一个紧凑的可访问性（Accessibility）树。每个可交互元素都被赋予一个唯一的引用标识符，如 @e1、@e2。这种设计使得 token 消耗从传统方式的 3000-5000 tokens 降低到仅需 200-400 tokens。

Ref 引用机制

传统的元素选择依赖 CSS 选择器或 XPath，这些方式存在明显缺陷：页面结构的微小变化可能导致选择器失效；动态生成的选择器缺乏可读性；AI 难以从复杂的 CSS 语法中理解元素的语义。

agent-browser 的 Ref 机制完美解决了这些问题。当你获取页面快照时，每个元素都会获得一个基于快照内容的稳定引用。AI 可以直接使用这些引用进行交互，而无需理解底层的 DOM 结构。

完整命令集

agent-browser 提供了 50+ 条命令，覆盖浏览器自动化的方方面面：

  • 导航与交互：open、click、fill、type、hover、scroll
  • 表单处理：check、uncheck、select
  • 截图与录制：screenshot、record、pdf
  • 网络控制：network route、network abort、network mock
  • 存储管理：cookies、storage local、storage session
  • 调试工具：console、errors、trace、profiler

跨平台支持

agent-browser 提供原生 Rust 二进制文件，支持 macOS（ARM64 和 x64）、Linux（ARM64 和 x64）以及 Windows（x64）。无论是桌面端开发还是 CI/CD 环境，都能获得一致的体验。

快速开始：5 分钟入门指南

安装

agent-browser 提供多种安装方式，推荐全局安装以获得最佳性能：

1
2
3
4
5
6
7
8
9
10
11
# 通过 npm 全局安装（推荐）
npm install -g agent-browser

# 首次使用时下载 Chrome 浏览器
agent-browser install

# 或者不安装直接试用
npx agent-browser open example.com

# macOS 用户也可通过 Homebrew 安装
brew install agent-browser

核心工作流

**agent-browser 的交互模式遵循一个简洁而强大的循环：**打开页面 → 获取快照 → 交互元素 → 重新快照。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 1. 打开目标页面
agent-browser open example.com

# 2. 获取可交互元素的快照
agent-browser snapshot -i
# 输出示例：
# @e1 [heading] "Example Domain"
# @e2 [link] "More information..."

# 3. 使用 Ref 进行交互
agent-browser click @e2

# 4. 页面变化后重新获取快照
agent-browser snapshot -i

命令链接

在单个 shell 调用中链接多个命令可以获得更好的性能，因为浏览器通过后台守护进程持久运行：

1
2
3
4
5
6
7
8
# 在一次调用中完成导航、等待和快照
agent-browser open example.com && agent-browser wait --load networkidle && agent-browser snapshot -i

# 批量填写表单
agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "password" && agent-browser click @e3

# 导航并截图
agent-browser open example.com && agent-browser screenshot page.png

实际示例：自动化登录流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 完整登录流程演示
agent-browser open https://example.com/login
agent-browser snapshot -i
# 假设输出：
# @e1 [textbox] "Username"
# @e2 [textbox] "Password" 
# @e3 [button] "Login"
# @e4 [link] "Forgot password?"

agent-browser fill @e1 "myuser"
agent-browser fill @e2 "secretpass"
agent-browser click @e3

# 等待登录完成并验证
agent-browser wait --url "**/dashboard"
agent-browser snapshot -i

核心技术：Ref 引用与快照系统

可访问性树

与传统 DOM 快照不同，agent-browser 返回的是基于浏览器可访问性 API 构建的语义树。这种格式有三重优势：

  1. 语义化 — 元素以其角色（role）呈现，如 heading、button、textbox，而非原始 HTML 标签
  2. AI 可读 — 文本输出自然易读，AI 无需解析复杂的嵌套结构
  3. 稳定可靠 — 基于可访问性层而非渲染层，受页面样式变化影响更小

快照选项

snapshot 命令提供丰富的选项以适应不同场景：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 默认：完整可访问性树
agent-browser snapshot

# 仅可交互元素（推荐用于 AI）
agent-browser snapshot -i

# 包含光标交互元素（检测 cursor:pointer 等）
agent-browser snapshot -i -C

# 紧凑模式（移除空元素）
agent-browser snapshot -c

# 限制深度
agent-browser snapshot -d 3

# 限定范围到特定元素
agent-browser snapshot -s "#main-content"

语义定位器

除了 Ref 引用，agent-browser 还支持语义定位器，这是一种更接近自然语言的元素查找方式：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 按角色查找
agent-browser find role button click --name "Submit"

# 按标签文本查找
agent-browser find label "Email" fill "test@example.com"

# 按占位符查找
agent-browser find placeholder "Search..." fill "query"

# 按 alt 属性查找
agent-browser find alt "Logo" click

# 按测试 ID 查找
agent-browser find testid "submit-btn" click

Ref 生命周期

理解 Ref 的生命周期至关重要：Ref 是相对于特定快照的。当页面内容发生变化（导航、DOM 更新、动态加载）时，原有的 Ref 会失效，需要重新获取快照。

1
2
3
4
5
6
7
8
# 错误的做法：跨页面变更使用旧 Ref
agent-browser click @e1  # 点击链接，页面跳转
agent-browser click @e1  # 此时 @e1 可能指向完全不同的元素

# 正确的做法：每次页面变更后重新快照
agent-browser click @e1
agent-browser snapshot -i  # 获取新页面快照
agent-browser click @e2   # 使用新 Ref

标注截图

当文本快照不足以理解页面结构时，标注截图提供了视觉上下文：

1
agent-browser screenshot --annotate ./page.png

**生成的截图会在每个可交互元素上叠加编号标签，与 Ref 对应。例如，标注 **[1] 对应 @e1。

进阶功能：Diff、会话与 CDP 模式

快照对比

验证自动化操作的效果是 AI 代理的常见需求。diff snapshot 命令可以对比当前快照与基准快照：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 记录基准状态
agent-browser snapshot -i

# 执行操作
agent-browser fill @e3 "test@example.com"
agent-browser click @e4

# 对比变化
agent-browser diff snapshot
# 输出示例：
# - textbox "Email" [ref=e3]
# + textbox "Email" [ref=e3]: "test@example.com"
# - button "Submit" [ref=e4]
# + button "Submit" [ref=e4] [disabled]
# 3 additions, 2 removals, 3 unchanged

截图对比

视觉回归测试是 Web 开发的重要环节。agent-browser 支持像素级的截图对比：

1
2
3
4
5
6
7
8
# 对比当前截图与基准
agent-browser diff screenshot --baseline before.png

# 指定输出路径
agent-browser diff screenshot --baseline before.png --output diff.png

# 调整容差阈值
agent-browser diff screenshot --baseline before.png --threshold 0.2

URL 对比

对比两个不同 URL 的页面状态，用于环境一致性验证：

1
2
3
4
5
# 对比预发布和生产环境
agent-browser diff url https://staging.example.com https://prod.example.com --screenshot

# 完整页面截图对比
agent-browser diff url https://v1.example.com https://v2.example.com --screenshot --full

会话隔离

agent-browser 支持多个独立的浏览器实例，每个实例有独立的 cookies、存储和认证状态：

1
2
3
4
5
6
# 不同的会话
agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com

# 列出活动会话
agent-browser session list

持久化配置

**使用 **--profile 参数可以持久化浏览器状态：

1
2
3
4
# 登录一次后持久化
agent-browser --profile \x7e/.myapp-profile open myapp.com
# 后续使用自动恢复登录状态
agent-browser --profile ~/.myapp-profile open myapp.com/dashboard

CDP 模式

通过 Chrome DevTools Protocol 连接现有浏览器，实现更灵活的控制：

1
2
3
4
5
6
7
8
9
10
# 启动 Chrome 并启用调试
google-chrome --remote-debugging-port=9222

# 连接现有浏览器
agent-browser connect 9222
# 或者
agent-browser --cdp 9222 open example.com

# 连接远程 WebSocket 服务
agent-browser --cdp "wss://browser-service.com/cdp?token=..." snapshot

CDP 模式特别适用于控制 Electron 应用、已运行的 Chrome 实例，或连接云端浏览器服务。

流式传输

启用 WebSocket 流式传输可以实现实时浏览器预览：

1
AGENT_BROWSER_STREAM_PORT=9223 agent-browser open example.com

**连接 **ws://localhost:9223 可以接收实时帧数据和注入输入事件，实现「配对浏览」场景。

实用技巧：认证、状态与性能分析

Auth Vault

管理多个网站的认证凭据：

1
2
3
4
5
6
7
8
9
10
11
# 保存认证信息
echo "mypassword" | agent-browser auth save github \
  --url https://github.com/login \
  --username myuser \
  --password-stdin

# 使用保存的凭据登录
agent-browser auth login github

# 列出保存的配置文件
agent-browser auth list

状态导入

可以直接从已登录的 Chrome 浏览器导入认证状态：

1
2
3
4
5
6
7
8
# 1. 在 Chrome 中登录目标网站
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222

# 2. 导入认证状态
agent-browser --auto-connect state save ./my-auth.json

# 3. 在 agent-browser 中使用
agent-browser --state ./my-auth.json open https://app.example.com/dashboard

性能分析

使用内置的 Profiler 诊断页面性能问题：

1
2
3
4
5
6
7
8
9
# 启动性能分析
agent-browser profiler start

# 执行待测试的操作
agent-browser navigate https://example.com
agent-browser click "#slow-button"

# 停止并保存分析结果
agent-browser profiler stop ./trace.json

生成的文件可导入 Chrome DevTools 或 Perfetto 进行可视化分析。

会话自动保存

**使用 **--session-name 可以自动保存和恢复会话状态：

1
2
3
4
# 自动持久化 "twitter" 会话
agent-browser --session-name twitter open twitter.com
# 登录后，后续命令自动恢复登录状态
agent-browser --session-name twitter click "#compose"

生态集成：Skills 与 AI 助手

Skills 机制

agent-browser 提供预置的 Skills，为不同的 AI 助手赋能：

1
2
3
4
5
6
7
8
9
10
11
# 安装核心技能
npx skills add vercel-labs/agent-browser --skill agent-browser

# 安装测试技能
npx skills add vercel-labs/agent-browser --skill dogfood

# 安装 Slack 自动化技能
npx skills add vercel-labs/agent-browser --skill slack

# 安装 Electron 应用控制技能
npx skills add vercel-labs/agent-browser --skill electron

Dogfood 技能

一个结构化的探索性测试工作流。AI 代理会系统性地浏览应用，记录发现的每个问题，包括：

  • 编号的重现步骤
  • 步骤截图
  • 交互式 bug 的录制视频
  • 严重程度分类

适用场景

  • AI 编码助手 — Cursor、Claude Code、GitHub Copilot 等可以直接执行浏览器自动化任务
  • 自动化测试 — 视觉回归测试、表单测试、端到端测试
  • 数据提取 — 从动态网页提取结构化数据
  • 内容监控 — 定期检查页面变化
  • 表单填写 — 自动处理多步骤表单和登录流程

云端集成

agent-browser 支持连接多种云端浏览器服务：

1
2
3
4
5
6
7
# Browserbase
export BROWSERBASE_API_KEY="your-key"
agent-browser -p browserbase open https://example.com

# Browser Use
export BROWSER_USE_API_KEY="your-key"
agent-browser -p browseruse open https://example.com

总结与展望

agent-browser 代表了浏览器自动化领域的一次范式转移。它不再将「功能完备」作为唯一目标，而是将 AI 智能体的体验置于设计的核心。

通过 Ref 引用机制，agent-browser 实现了确定性的元素选择，AI 无需理解复杂的 CSS 选择器语法。通过紧凑的文本输出，它大幅降低了 token 消耗，使 AI 能够在有限的上下文窗口中处理更复杂的任务。50+ 条命令覆盖了从基础交互到高级调试的完整场景，而会话管理、状态持久化和 CDP 模式则提供了企业级的灵活性。

对于正在构建 AI 驱动的工作流程的开发者而言，agent-browser 提供了一个值得考虑的选择。它与主流 AI 编码助手（Claude Code、Cursor、Copilot 等）的无缝集成，使得「用自然语言描述，让 AI 执行浏览器操作」成为可能。

本文档基于 agent-browser 官方文档编写，涵盖核心功能至最新版本。如有更新，请以官方文档为准。