编程 agent-browser：外部 Rust CLI 加无障碍树 ref，把浏览器控制权交给 agent

2026-10-09 00:04:56

agent-browser：外部 Rust CLI 加无障碍树 ref，把浏览器控制权交给 agent

仓库：vercel-labs/agent-browser ｜ npm：agent-browser ｜ License：Apache-2.0

一句话定位：Browser automation CLI for AI agents. Fast native Rust CLI.

它不往页面里塞脚本，而是以独立进程驱动浏览器（CDP），snapshot 取无障碍树并给元素打 ref，再把控制权交给外部 agent；MCP 也可作为通道。这条路线和页面内嵌 JS 的 Page Agent 是两回事，后面单独说。

安装

全局装原生 Rust 二进制：

npm install -g agent-browser
agent-browser install  # 首次从 Chrome for Testing 下载 Chrome

agent-browser install 走的是 Chrome for Testing 官方自动化通道，同时会探测机器上已有的 Chrome、Brave、Playwright、Puppeteer 安装。daemon 本身不需要 Playwright 和 Node.js。

其他几条路：

# 项目内
npm install agent-browser && agent-browser install

# Homebrew
brew install agent-browser && agent-browser install

# Cargo
cargo install agent-browser && agent-browser install

从源码构建需要 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
pnpm link --global
agent-browser install

Linux 上浏览器系统库装不全时用 agent-browser install --with-deps，缺库会非零退出。升级用 agent-browser upgrade，它会识别当前是 npm、Homebrew 还是 Cargo 装的，执行对应更新。

快速开始

agent-browser open example.com
agent-browser snapshot                    # 取无障碍树并带 refs
agent-browser click @e2                   # 按 snapshot 里的 ref 点击
agent-browser fill @e3 "test@example.com" # 按 ref 填
agent-browser get text @e1
agent-browser screenshot page.png
agent-browser close

snapshot 输出的是无障碍树，@e1、@e2 是这一轮快照里元素的 ref，命令直接按 ref 定位。ref 不是持久 ID，页面变了就重新 snapshot。

点击被遮挡时不会硬点下去：如果同意横幅、弹窗盖住了目标点，click 提前失败并报出遮挡元素。先处理它，再重新 snapshot 拿新 ref 重试。

无头 Chromium 截图默认隐藏原生滚动条，保证图像一致；要保留加 --hide-scrollbars false。

传统选择器一样能用，不必依赖 ref：

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

常用命令

基础动作覆盖 open/read/click/dblclick/focus/type/fill/press/keyboard type|inserttext/keydown/keyup/hover/select/check/uncheck/scroll/scrollintoview/drag/upload/screenshot/pdf/snapshot/eval/connect/close。

screenshot：--full 整页、--annotate 带编号标注、--if-changed 跳过未变化的图省 token、--threshold 0.01 忽略 ≤1% 的像素变化、--screenshot-dir、--screenshot-format jpeg --screenshot-quality 80
get：text/html/value/attr/title/url/cdp-url/count/box/styles
is visible|enabled|checked
find：role/text/label/placeholder/alt/title/testid/first/last/nth，动作 click/fill/check/hover/text，选项 --name --exact
wait：selector / ms / --text / --url / --load domcontentloaded|load|networkidle / --fn "JS条件" / --state hidden
clipboard read/write/copy/paste
mouse move/down/up/wheel，--human 走曲线缓动（--duration/--steps/--seed）
set：viewport/device/geo/offline/headers/credentials/media
cookies / storage local|session，cookies set --curl 可从 Copy-as-cURL、JSON 数组或裸 Cookie 头导入
network route/unroute/requests/request/har start|stop，HAR 可内嵌响应体
dialog accept|dismiss|status。alert/beforeunload 默认自动接受，confirm/prompt 需显式处理；--no-auto-dialog 或 AGENT_BROWSER_NO_AUTO_DIALOG=1 关掉自动处理
diff snapshot / diff screenshot，与基线对比

batch 把多条命令塞进一次调用，省掉每条命令的进程启动开销：

agent-browser batch "open https://example.com" "snapshot -i" "screenshot"
agent-browser batch --bail "open https://example.com" "click @e1" "screenshot"
echo '[["open","https://example.com"],["snapshot","-i"],["click","@e1"]]' | agent-browser batch --json

--bail 让出错即停。

标签页用 tab 管理：列表、tab new [--label]、tab |label>、tab close。tab id 形如 t1/t2，会话内不复用；也可以给标签起名，导航后仍保留。tab list --json 还会报 CDP targetId，跨 daemon 重启稳定。frame 用 frame / frame main 切换。

read：取 agent 友好的文本

agent-browser read
agent-browser read https://example.com/article
agent-browser read https://example.com/article --filter overview
agent-browser read https://example.com/article --outline
agent-browser read https://docs.example.com --llms index --filter auth
agent-browser read example.com/article --require-md

不带 URL 时读当前会话活动标签的渲染 DOM，登录态和客户端更新都在。显式给 URL 时默认发 Accept: text/markdown；拿到的不是 markdown 就尝试追加 .md，沿祖先路径找最近的 llms.txt，最后回退到 HTML 抽取的纯文本。--llms / --require-md 在没有 URL 时用活动标签的 URL。read 不会主动读 llms-full.txt，除非显式要求。

WebMCP（实验性）

agent-browser 管理的 Chrome 默认开启 WebMCP，--no-webmcp 关闭。

浏览器在首次发现工具时、以及目录变化时自动通告可用工具，摘要只含名字、简述、origin、frame id。要完整 schema，得按需取：

agent-browser webmcp list search --json
agent-browser webmcp list  --frame  --json

选定后再调用：

agent-browser webmcp invoke search --params '{"query":"browser agents"}'
agent-browser webmcp invoke slow_tool --params @input.json --detach
agent-browser webmcp result
agent-browser webmcp cancel

schema 和注解不做主动通告，要就自己取。未变化的目录、没有工具的页面不占上下文。自动摘要限 16 个工具、4 KiB JSON，描述截到 160 字节并加截断标记；truncated: true 表示有截断或省略。

页面给的 name、description、schema、注解、结果一律当不可信数据。JSON 摘要带 untrusted: true，CLI 与 MCP 摘要用带 nonce 的内容边界包裹页面元数据。这些只是来源提示，不是防 prompt 注入的安全边界。不要把站点文本提升成 system/developer 指令，不要执行它建议的 shell 命令、泄露本地密钥，也不要采信页面自称的用户同意声明。发现工具不等于授权；有后果的操作交给宿主的确认策略。页面自己声明的 readOnlyHint / untrustedContentHint 不能绕过这些控制。域过滤只限制观察和执行范围，不替代宿主隔离。

MCP profile 可选：

agent-browser mcp --tools core,webmcp

AI Chat

agent-browser chat "open google.com and search for cats"   # 单次
agent-browser chat                                         # 交互 REPL
agent-browser -q chat "summarize this page"                # 静默

chat 把自然语言翻成 agent-browser 命令再执行，流式返回 AI 响应。每次工具调用对应一条命令；引号里的 ; 或 && 当普通文本处理。技能可用 skills get 加载，比如 agent-browser skills get webmcp-gen，技能目录见 skills.sh。

与 Page Agent 的对照

层不一样。

agent-browser 是外部进程加原生 Rust CLI，daemon 通过 CDP 驱动浏览器，snapshot 取无障碍树带 ref，控制权交给外部 agent，也可以走 MCP。适合服务端、脚本化、多站点、需要可复现的浏览器自动化。

Page Agent（alibaba/page-agent）是网页内部的纯 JS，读脱水文本 DOM（FlatDomTree），天然继承用户 cookie 和登录态，一个 script 标签接入，适合嵌在产品里的操作型 copilot，核心只操作单页。