agent-browser

为 AI Agent 设计的无头浏览器（Headless browser）自动化 CLI 工具。基于原生 Rust 构建，速度极快。

安装

全局安装（推荐）

安装原生 Rust 二进制文件：

npm install -g agent-browser
agent-browser install  # 下载 Chrome for Testing (仅首次运行需要)

项目安装（本地依赖）

适用于希望在 package.json 中固定版本的项目：

npm install agent-browser
agent-browser install

随后通过 package.json 的 scripts 脚本或直接调用 agent-browser 使用。

Homebrew (macOS)

brew install agent-browser
agent-browser install  # 下载 Chrome for Testing (仅首次运行需要)

Cargo (Rust)

cargo install agent-browser
agent-browser install  # 下载 Chrome for Testing (仅首次运行需要)

从源码构建

git clone https://github.com/vercel-labs/agent-browser
cd agent-browser
pnpm install
pnpm build
pnpm build:native   # 需要安装 Rust (https://rustup.rs)
pnpm link --global  # 使 agent-browser 在全局可用
agent-browser install

Linux 依赖

在 Linux 上，需安装系统依赖：

agent-browser install --with-deps

更新

升级到最新版本：

agent-browser upgrade

它会自动检测你的安装方式（npm、Homebrew 或 Cargo）并执行相应的更新命令。

系统要求

• Chrome - 运行 agent-browser install 从 Chrome for Testing（Google 官方自动化渠道）下载 Chrome。该守护进程不需要 Playwright 或 Node.js。
• Rust - 仅在从源码构建时需要（参见上方的“从源码构建”部分）。

快速入门

agent-browser open example.com
agent-browser snapshot                    # 获取带引用的无障碍树 (accessibility tree)
agent-browser click @e2                   # 通过快照中的引用点击元素
agent-browser fill @e3 "test@example.com" # 通过引用填写内容
agent-browser get text @e1                # 通过引用获取文本
agent-browser screenshot page.png
agent-browser close

传统选择器（同样支持）

agent-browser click "#submit"
agent-browser fill "#email" "test@example.com"
agent-browser find role button click --name "Submit"

命令

核心命令

agent-browser open               # 导航到 URL (别名: goto, navigate)
agent-browser click              # 点击元素 (--new-tab 在新标签页打开)
agent-browser dblclick           # 双击元素
agent-browser focus              # 聚焦元素
agent-browser type         # 输入内容到元素
agent-browser fill         # 清除并填写内容
agent-browser press              # 按键 (Enter, Tab, Control+a) (别名: key)
agent-browser keyboard type     # 使用真实按键类型输入 (无需选择器，针对当前焦点)
agent-browser keyboard inserttext   # 插入文本但不触发按键事件 (无需选择器)
agent-browser keydown            # 按下按键
agent-browser keyup              # 释放按键
agent-browser hover              # 悬停在元素上
agent-browser select        # 选择下拉选项
agent-browser check              # 勾选复选框
agent-browser uncheck            # 取消勾选复选框
agent-browser scroll  [px]       # 滚动 (up/down/left/right, --selector )
agent-browser scrollintoview     # 将元素滚动到视图中 (别名: scrollinto)
agent-browser drag          # 拖拽元素
agent-browser upload      # 上传文件
agent-browser screenshot [path]       # 截图 (--full 全屏截图，未指定路径则保存至临时目录)
agent-browser screenshot --annotate   # 带数字标签的标注截图
agent-browser screenshot --screenshot-dir ./shots    # 保存至自定义目录
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf               # 保存为 PDF
agent-browser snapshot                # 获取带引用的无障碍树 (最适合 AI 使用)
agent-browser eval                # 运行 JavaScript (-b 表示 base64, --stdin 表示管道输入)
agent-browser connect           # 通过 CDP 连接浏览器
agent-browser stream enable [--port ]  # 启动运行时 WebSocket 流
agent-browser stream status           # 显示运行时流状态及绑定端口
agent-browser stream disable          # 停止运行时 WebSocket 流
agent-browser close                   # 关闭浏览器 (别名: quit, exit)
agent-browser close --all             # 关闭所有活动会话

获取信息

agent-browser get text           # 获取文本内容
agent-browser get html           # 获取 innerHTML
agent-browser get value          # 获取输入框值
agent-browser get attr     # 获取属性
agent-browser get title               # 获取页面标题
agent-browser get url                 # 获取当前 URL
agent-browser get cdp-url             # 获取 CDP WebSocket URL (用于 DevTools、调试)
agent-browser get count          # 统计匹配元素数量