Agent Browser - 适用于 AI 代理的无头浏览器自动化 CLI，支持可访问性树快照和基于引用的元素选择

快速的浏览器自动化，使用可访问性树快照并通过 Ref 标识实现确定性的元素选择。

为什么选择它而不是内置浏览器工具

在以下场景使用 agent-browser：

• 自动化多步骤工作流
• 需要确定性的元素定位
• 性能要求高
• 处理复杂的 SPA（单页应用）
• 需要会话隔离

在以下场景使用内置浏览器工具：

• 需要截图 / PDF 进行分析
• 需要目视检查页面
• 需要浏览器扩展集成

核心工作流

1. 打开页面并生成快照

agent-browser open https://example.com
agent-browser snapshot -i --json

2. 解析 JSON 中的 refs，然后交互

agent-browser click @e2
agent-browser fill @e3 "text"

3. 页面变更后再次快照

agent-browser snapshot -i --json

关键命令

页面导航

agent-browser open 
agent-browser back | forward | reload | close

快照（请始终使用 -i --json）

agent-browser snapshot -i --json          # 仅输出交互元素，JSON 格式
agent-browser snapshot -i -c -d 5 --json  # + 紧凑输出，深度限制
agent-browser snapshot -s "#main" -i      # 限定选择器范围

基于 Ref 的交互

agent-browser click @e2
agent-browser fill @e3 "text"
agent-browser type @e3 "text"
agent-browser hover @e4
agent-browser check @e5 | uncheck @e5
agent-browser select @e6 "value"
agent-browser press "Enter"
agent-browser scroll down 500
agent-browser drag @e7 @e8

获取信息

agent-browser get text @e1 --json
agent-browser get html @e2 --json
agent-browser get value @e3 --json
agent-browser get attr @e4 "href" --json
agent-browser get title --json
agent-browser get url --json
agent-browser get count ".item" --json

状态检查

agent-browser is visible @e2 --json
agent-browser is enabled @e3 --json
agent-browser is checked @e4 --json

等待

agent-browser wait @e2                    # 等待元素出现
agent-browser wait 1000                   # 等待指定毫秒数
agent-browser wait --text "Welcome"       # 等待文本出现
agent-browser wait --url "/dashboard"   # 等待 URL 匹配
agent-browser wait --load networkidle     # 等待网络空闲
agent-browser wait --fn "window.ready === true"

会话（独立浏览器上下文）

agent-browser --session admin open site.com
agent-browser --session user open site.com
agent-browser session list
# 或者通过环境变量：AGENT_BROWSER_SESSION=admin agent-browser ...

agent-browser state save auth.json        # 保存 cookie / storage
agent-browser state load auth.json        # 加载（跳过登录）

agent-browser screenshot page.png
agent-browser screenshot --full page.png
agent-browser pdf page.pdf

agent-browser network route "/ads/" --abort           # 阻断请求
agent-browser network route "/api/" --body '{"x":1}'  # Mock 响应
agent-browser network requests --filter api              # 查看请求

Cookie & Storage

agent-browser cookies                     # 获取全部 cookie
agent-browser cookies set name value
agent-browser storage local key           # 读取 localStorage
agent-browser storage local set key val

标签页 & 框架

agent-browser tab new https://example.com
agent-browser tab 2                       # 切换到第 2 个标签页
agent-browser frame @e5                   # 切换到 iframe
agent-browser frame main                  # 返回主框架

快照输出格式示例

{
  "success": true,
  "data": {
    "snapshot": "...",
    "refs": {
      "e1": {"role": "heading", "name": "Example Domain"},
      "e2": {"role": "button", "name": "Submit"},
      "e3": {"role": "textbox", "name": "Email"}
    }
  }
}

最佳实践

• 始终使用 -i 标志，只关注交互元素
• 始终使用 --json，便于解析
• 等待页面稳定：agent-browser wait --load networkidle
• 保存认证状态，避免重复登录
• 使用会话实现不同上下文的隔离
• 调试时加 --headed，直接看到浏览器界面

示例：搜索并抽取结果

agent-browser open https://www.google.com
agent-browser snapshot -i --json
# AI 识别搜索框 @e1
agent-browser fill @e1 "AI agents"
agent-browser press Enter
agent-browser wait --load networkidle
agent-browser snapshot -i --json
# AI 识别结果 refs
agent-browser get text @e3 --json
agent-browser get attr @e4 "href" --json

示例：多会话测试

# Admin 会话
agent-browser --session admin open app.com
agent-browser --session admin state load admin-auth.json
agent-browser --session admin snapshot -i --json
# User 会话（并行）
agent-browser --session user open app.com
agent-browser --session user state load user-auth.json
agent-browser --session user snapshot -i --json

安装方式

npm install -g agent-browser
agent-browser install                     # 下载 Chromium
agent-browser install --with-deps         # Linux：额外系统依赖

致谢

Skill 由 Yossi Elkrief (@MaTriXy) 创建

agent-browser CLI 由 Vercel Labs 提供