agent-browser

agent-browser 技能

真正适用于 AI Agent 的浏览器自动化工具。由 Vercel Labs 专为 LLM 驱动的工作流打造。

为什么它比其他方案更好

1. 确定性引用（改变游戏规则）

传统工具的问题：

• 网站更改时，CSS 选择器会失效
• XPath 脆弱且难以阅读
• 基于坐标的点击在响应式布局中会失败
• 基于视觉的方案速度慢、成本高

agent-browser 的解决方案：

# 1. Get snapshot with stable refs
agent-browser snapshot -i --json
# Output: - button "Submit" [ref=e2]

# 2. Use that ref forever — it points to the EXACT element
agent-browser click @e2

• 引用是确定性的——@e2 始终指向快照中的同一个元素
• 无需重新查询 DOM——直接引用更快、更可靠
• 针对 AI 优化——LLM 能自然地解析无障碍树，而不是杂乱的 CSS

2. 无障碍树优于截图/HTML

传统工具会提供原始 HTML（信息杂乱）或截图（需要视觉模型）。

agent-browser 提供的是无障碍树——一种简洁、语义化的表示，呈现人类（或屏幕阅读器）所感知的内容：

- heading "Billing" [level=1]
- link "Make a payment" [ref=e10]
- button "Submit" [ref=e2]
- textbox "Email" [ref=e3]

• 语义角色（按钮、链接、文本框、标题）
• 易于人类理解的标签
• 层级结构
• 非常适合 LLM 理解

3. 专为 AI Agent 打造

特性	传统工具	agent-browser
元素定位	脆弱的选择器	确定性引用
页面理解	原始 HTML	无障碍树
输出格式	文本日志	结构化 JSON
速度	慢（每条命令都启动完整浏览器）	快（守护进程持续运行）
AI 集成	事后才考虑	专门打造

4. 快速架构

• Rust CLI——原生二进制文件，可即时解析命令
• Node.js 守护进程——命令之间浏览器保持就绪
• **第一条命令：**约 2s（守护进程启动）
• **后续命令：**约 100ms

前置条件

npm install -g agent-browser
agent-browser install  # Download Chromium (~30s)

核心 AI 工作流

专为 LLM Agent 设计的工作流：

# Step 1: Navigate
agent-browser open https://example.com

# Step 2: Get structured snapshot (the AI "sees" the page)
agent-browser snapshot -i --json

# Step 3: AI picks refs from JSON, execute actions
agent-browser click @e2
agent-browser fill @e3 "[email protected]"

# Step 4: Re-snapshot after changes (state verification)
agent-browser snapshot -i --json

# Step 5: Done
agent-browser close

命令

导航

agent-browser open example.com
agent-browser open example.com --json            # JSON response
agent-browser open example.com --headed          # Visible browser

快照（杀手级功能）

agent-browser snapshot                           # Full accessibility tree
agent-browser snapshot -i                        # Interactive only (faster)
agent-browser snapshot -i --json                 # JSON for AI parsing
agent-browser snapshot -i -c -d 5 --json         # Compact, depth-limited

交互（使用确定性引用）

agent-browser click @e2                          # Click element @e2
agent-browser fill @e3 "text"                    # Fill and clear
agent-browser type @e3 "text"                    # Type without clearing
agent-browser press Enter                        # Press key
agent-browser hover @e4                          # Hover

状态验证

agent-browser get text @e1                       # Get element text
agent-browser get url                            # Current URL
agent-browser is visible @e2                     # Check visibility

会话管理

agent-browser --session login open site.com      # Isolated session
agent-browser --profile ~/.myprofile open site   # Persistent cookies
agent-browser close                              # Clean up

选择器策略（按可靠性排序）

1. 引用（最佳选择——请使用）

# From snapshot output — deterministic and stable
agent-browser click @e2
agent-browser fill @e3 "text"

2. 语义定位器（良好）

agent-browser find role button click --name "Submit"
agent-browser find label "Email" fill "[email protected]"

3. CSS 选择器（适用于静态网站）

agent-browser click "#submit"
agent-browser click ".btn-primary"

4. 文本/XPath（最后手段）

agent-browser click "text=Submit"
agent-browser click "xpath=//button[1]"

快照选项

控制 AI“看到”的内容：

标志	用途
-i	仅显示可交互元素（按钮、链接、输入框）——推荐
-C	包含可通过光标交互的元素（onclick、cursor:pointer）
-c	精简模式（移除空的结构元素）
-d <n>	限制树的深度
-s <sel>	限定 CSS 选择器的范围（例如 #main）
--json	机器可读的 JSON 输出——AI 必备

推荐的 AI 命令：

agent-browser snapshot -i -c --json

选项

标志	说明
--json	JSON 输出，包含 success/data/error 结构
--headed	显示浏览器窗口（用于调试）
--session <name>	隔离的浏览器会话
--profile <path>	用于保存 Cookie/登录信息的持久配置文件
--cdp <port>	通过 DevTools Protocol 连接到现有的 Chrome
--headers <json>	为每个来源设置身份验证标头

示例：完整的登录流程

# Start
agent-browser open https://portal.aeronetpr.com

# Get page structure
SNAPSHOT=$(agent-browser snapshot -i --json)
# AI parses JSON: sees textbox @e1 (Username), textbox @e2 (Password), button @e3 (Login)

# Execute login
agent-browser fill @e1 "username"
agent-browser fill @e2 "password"
agent-browser click @e3

# Verify success (wait for navigation, re-snapshot)
sleep 2
agent-browser snapshot -i --json

# Done
agent-browser close

给 AI Agent 的提示

1. 始终使用 --json——结构化输出比文本更容易解析
2. 使用 -i 标志——仅包含可交互元素的快照更精简、更快、更清晰
3. 操作后重新获取快照——验证状态是否按预期更改
4. 优先相信引用而非选择器——快照中的 @e2 优于可能发生变化的 #id
5. 引用过期时使用语义定位器——find role button click 更可靠
6. 会话持久化——一次 open，执行多条命令，再一次 close

与其他工具的比较

工具	最适合的场景	agent-browser 的优势
Puppeteer/Playwright	开发测试	为人类构建；选择器脆弱
Selenium	传统测试	速度慢、开销大、基于选择器
browser-use	Python Agent	agent-browser 的引用系统更出色
截图 + 视觉识别	视觉任务	agent-browser 的速度快 10 倍，成本低 100 倍
OpenClaw browser tool	简单任务	agent-browser 更擅长处理复杂流程

何时使用此技能

在以下情况下使用 agent-browser：

• 自动化多步骤网页工作流
• 填写复杂表单
• 需要可靠、可重复的自动化
• 处理动态或现代网页应用
• 重视成本（无需调用视觉 API）

在以下情况下使用 OpenClaw 内置的浏览器工具：

• 简单的单页检查
• 需要快速截图
• Chrome 中已有经过身份验证的会话

资源

• Vercel Labs 仓库： https://github.com/vercel-labs/agent-browser
• 此技能仓库： https://github.com/clawdbrunner/skill-agent-browser