agent-browser¶

面向 AI 代理的浏览器自动化：打开页面、将其作为无障碍树读取，并从 shell 中对元素执行操作。

agent-browser 是一个原生 Rust CLI，它为 AI 代理提供一个可以逐条命令驱动的浏览器。snapshot 将页面以紧凑文本的形式返回，并为每个元素附带一个 ref，例如 @e1。代理对 ref 执行操作，再次读取页面以检查结果，然后重复这一过程。浏览器在命令之间保持打开状态，因此每一步都是一次简短的 shell 调用。

安装¶

npm install -g agent-browser
agent-browser install           # download Chrome for Testing (first time only)

• Homebrew： brew install agent-browser，然后运行 agent-browser install。
• Linux： agent-browser install --with-deps 还会安装浏览器的系统库。
• 无需安装： npx agent-browser open example.com。

项目安装、从源码构建、upgrade 和 doctor 在 安装 中有详细介绍。

快速开始¶

agent-browser open example.com
agent-browser snapshot -i       # interactive elements, each with a ref
agent-browser click @e1         # act on a ref from that snapshot
agent-browser get url           # check the result
agent-browser close

example.com 的快照：

- link "Learn more" [ref=e1]

• Refs 描述的是快照生成时页面的状态。在导航或 DOM 变化之后，请先获取新的快照，再使用 refs。
• CSS 选择器、文本、XPath 和语义定位器同样有效，例如 agent-browser find role button click --name "Submit"。参见 选择器。
• 当目标被隐藏、禁用、位于视口之外，或被其他元素（如同意横幅）遮挡时，点击会失败而不是报告成功。请关闭遮挡元素、获取新的快照并重试。

完整的入门教程见 快速开始。

工作原理¶

CLI 将每条命令发送给一个后台守护进程；该守护进程在第一条命令发出时启动，并通过 Chrome DevTools Protocol 控制浏览器。每个 --session 都有自己的守护进程和浏览器。默认情况下，守护进程在连续一小时没有收到命令后关闭无头浏览器并退出；如果配置了 会话持久化，则会先保存状态。

Chrome for Testing 是默认浏览器。你也可以通过 --cdp 或 --auto-connect 连接到正在运行的 Chrome（CDP 模式），使用 --engine 选择 Lightpanda 或 Obscura 引擎，在 iOS Simulator 中驱动 Mobile Safari，或使用云浏览器提供商，例如 Browserbase、Browserless、Browser Use、Kernel 或 AgentCore。

面向 AI 代理¶

CLI 附带了与其版本匹配的 skills：

agent-browser skills get core                 # the core loop, refs, waiting, and common workflows
agent-browser skills get core --ref commands  # one reference, such as the full command list
agent-browser skills get core --full          # adds the full command reference and templates
agent-browser skills list                     # specialized skills: electron, slack, dogfood, and more

从 skills.sh 将 discovery skill 安装到代理框架中：

npx skills add vercel-labs/agent-browser

安装后的 skill 是一个轻量存根，它告诉代理加载 agent-browser skills get core，因此其指令始终与已安装的 CLI 匹配。或者将其添加到你的 AGENTS.md：

Use `agent-browser` for browser automation. Before the first use, run
`agent-browser skills get core` and follow it.

对于 MCP 客户端，agent-browser mcp 会通过 stdio 启动一个 MCP 服务器。参见 MCP 服务器。

命令¶

运行 agent-browser --help 查看完整命令列表，或运行 agent-browser <command> --help 查看单个命令。

标志、环境变量和 agent-browser.json 在 配置中有文档说明。

平台¶

原生二进制文件适用于 macOS（ARM64、x64）、Linux（ARM64、x64、glibc 和 musl）以及 Windows（x64）。npm 包会为主机选择正确的二进制文件。

开发¶

从源码构建需要 Node.js 24 或更高版本、pnpm 11 或更高版本以及 Rust：

pnpm install
pnpm build:source               # builds the dashboard and the native CLI
pnpm link --global
agent-browser install

在 cli/ 中运行 Rust 检查：

cargo fmt -- --check
cargo clippy
cargo test
cargo test e2e -- --ignored --test-threads=1   # launches real headless Chrome

AGENTS.md 列出了每次变更时需要更新的文件、文档检查以及发布流程。

文档¶

• agent-browser.dev：简介、指南和参考
• 命令 和 配置
• 安全：身份验证保险库、域名允许列表、操作策略和内容边界
• Next.js 和 Vercel 以及 eve：在 Vercel Sandbox 和 eve 智能体中运行 agent-browser
• 更新日志

许可证¶

Apache-2.0