agent-browser

专为 AI Agent 设计的浏览器自动化 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（仅首次运行需要）

从源码构建

需要 Node.js 24+、pnpm 11+ 以及 Rust 环境。

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。系统会自动检测已有的 Chrome、Brave、Playwright 和 Puppeteer 安装。守护进程无需 Playwright 或 Node.js 环境。
• Node.js 24+ 和 pnpm 11+ - 仅在从源码构建时需要。
• Rust - 仅在从源码构建时需要（请参阅上文“从源码构建”部分）。

快速入门

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

Headless Chromium 截图默认会隐藏原生滚动条，以保证截图内容一致。 如需保留原生滚动条，请在启动时添加 --hide-scrollbars false 参数。

传统选择器（同样支持）

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

命令

核心命令

agent-browser open                    # 启动浏览器（不进行导航）；停留在 about:blank
agent-browser open <url>              # 启动并导航至 URL（别名：goto, navigate）
agent-browser click <selector>        # 点击元素（使用 --new-tab 在新标签页打开）
agent-browser dblclick <selector>     # 双击元素
agent-browser focus <selector>        # 聚焦元素
agent-browser type <selector> <text>  # 向元素输入内容
agent-browser fill <selector> <text>  # 清除并填入内容
agent-browser press <key>             # 按键 (Enter, Tab, Control+a) (别名：key)
agent-browser keyboard type <text>    # 以真实键盘输入方式输入（无选择器，针对当前焦点）
agent-browser keyboard inserttext <text> # 直接插入文本，不触发键盘事件（无选择器）
agent-browser keydown <key>           # 按下按键
agent-browser keyup <key>             # 松开按键
agent-browser hover <selector>        # 悬停在元素上
agent-browser select <selector> <opt> # 选择下拉选项
agent-browser check <selector>        # 勾选复选框
agent-browser uncheck <selector>      # 取消勾选复选框
agent-browser scroll <dir> [px]       # 滚动 (up/down/left/right, --selector <selector>)
agent-browser scrollintoview <selector> # 将元素滚动至视图内（别名：scrollinto）
agent-browser drag <src> <dest>       # 拖拽
agent-browser upload <selector> <path> # 上传文件
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 <path>              # 保存为 PDF
agent-browser snapshot                # 获取带引用 ID 的无障碍树（最适合 AI 使用）
agent-browser eval <js>               # 执行 JavaScript (-b 用于 base64, --stdin 用于管道输入)
agent-browser connect <url>           # 通过 CDP 连接至浏览器
agent-browser stream enable [--port <port>]  # 启动运行时 WebSocket 流
agent-browser stream status           # 显示运行时流状态及绑定端口
agent-browser stream disable          # 停止运行时 WebSocket 流
agent-browser close                   # 关闭浏览器