开发者值得收藏：agent-browser 从安装到核心用法完整介绍

你有没有遇到过这种情况：

让 AI 帮你测试一个网页登录流程，它先说“我看到了按钮”，然后点错；让它填表，它不知道输入框到底是哪一个；让它检查页面状态，它只能靠截图猜。

对人来说，浏览网页是一件很自然的事：看到按钮就点，看到输入框就填，看到弹窗就关掉。

但对 AI Agent 来说，浏览器其实是一个很难稳定操作的环境。

DOM 太复杂，选择器会变，页面会异步加载，弹窗会挡住按钮，登录态还经常失效。传统自动化工具当然能做这些事，但它们更多是为人写脚本设计的，而不是为 AI 一步步理解页面、选择目标、执行动作设计的。

这就是 agent-browser 这个工具有意思的地方。

它不是单纯再造一个 Playwright，也不是只提供一个截图工具，而是把浏览器自动化包装成了一套更适合 AI Agent 使用的 CLI 工作流。

一句话概括：agent-browser 是一个给 AI Agent 使用的浏览器自动化 CLI，底层是原生 Rust，目标是让 Agent 更稳定、更可控地操作网页。

agent-browser 核心能力总览

1. agent-browser 到底是什么？

从 README 的描述看，它的定位非常直接：

Browser automation CLI for AI agents. Fast native Rust CLI.

翻译成人话就是：这是一个给 AI Agent 用的浏览器自动化命令行工具。

它可以做常见浏览器自动化工具能做的事，比如打开网页、点击按钮、填写表单、截图、导出 PDF、读取文本、操作 cookie 和 storage、监听网络请求、处理弹窗、多标签页切换等。

但它真正特别的地方，不在于“功能多”，而在于它把这些能力整理成了更适合 AI 使用的形态。

最典型的例子就是 snapshot 和 ref。

传统写自动化脚本时，我们经常会写：

agent-browser click "#submit"
agent-browser fill "#email" "test@example.com"

这种 CSS selector 方式 agent-browser 也支持。

但对 AI 来说，更自然的方式是先观察页面，再基于观察结果行动：

agent-browser open example.com
agent-browser snapshot
agent-browser click @e2
agent-browser fill @e3 "test@example.com"
agent-browser get text @e1
agent-browser screenshot page.png
agent-browser close

snapshot 会输出页面的 accessibility tree，并给可交互元素分配稳定的引用，比如 @e1、@e2、@e3。

AI 只需要先读懂 snapshot：这里有一个标题、那里有一个按钮、下面有一个邮箱输入框。然后它可以直接对 @e2 执行点击，对 @e3 执行填写。

这比让 AI 从一大坨 HTML 里猜 selector，要可靠得多。

2. 为什么它更适合 AI Agent？

我觉得 agent-browser 最核心的设计思路是：不要假设 AI 一开始就知道怎么操作页面，而是给它一个“观察—决策—行动—再观察”的闭环。

README 里推荐的 AI 工作流大概是这样：

agent-browser open example.com
agent-browser snapshot -i --json
agent-browser click @e2
agent-browser fill @e3 "input text"
agent-browser snapshot -i --json

这个流程很像人类操作网页：

1. 1. 先打开页面。
2. 2. 看看有哪些可点、可填的元素。
3. 3. 选择目标执行动作。
4. 4. 页面变化后重新观察。

这里有两个细节很实用。

第一，snapshot -i 可以只看 interactive elements，也就是按钮、输入框、链接这类真正需要操作的元素。这样可以减少上下文噪音。

第二，页面变化后重新 snapshot。因为网页不是静态文档，点完按钮可能出现弹窗，提交表单后可能跳转，懒加载也可能改变元素位置。旧的 @e2 不应该被无限复用，重新观察才更稳。

README 还特别提到：如果点击失败是因为按钮被 consent banner 或 modal 盖住，agent-browser 会尽早失败，并告诉你是哪个元素挡住了点击点。这个设计对 AI 很关键，因为它不是“点了没反应然后继续瞎试”，而是给出明确反馈：你得先处理遮挡元素。

这类反馈越明确，Agent 越不容易陷入乱点、乱猜、重复失败。

3. 安装和上手：5 分钟跑起来

agent-browser 的安装方式比较全。

如果你只是想全局使用，最推荐的是 npm：

npm install -g agent-browser
agent-browser install

第二条命令会在首次使用时下载 Chrome for Testing，这是 Google 官方的自动化浏览器通道。

macOS 用户也可以用 Homebrew：

brew install agent-browser
agent-browser install

Rust 用户可以用 Cargo：

cargo install agent-browser
agent-browser install

如果是 Linux 环境，还可以一次性安装系统依赖：

agent-browser install --with-deps

最小上手流程可以这样跑：

agent-browser open example.com
agent-browser snapshot
agent-browser click @e2
agent-browser fill @e3 "test@example.com"
agent-browser get text @e1
agent-browser screenshot page.png
agent-browser close

当然，真实页面里你通常不会盲目点击 @e2。正确做法是先看 snapshot 输出，确认哪个 ref 对应哪个元素，再执行后续命令。

如果你更习惯传统选择器，它也支持：

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

也就是说，它没有强迫你放弃原来的自动化习惯，而是在 selector 之外，额外提供了一条更适合 AI 的 ref 工作流。

4. 不只是点点点：它的能力覆盖很广

如果只看 Quick Start，你可能会觉得 agent-browser 就是一个命令行版浏览器操作器。

但 README 往下看会发现，它覆盖的范围其实很完整。

4.1 页面操作能力

基础动作包括 click、dblclick、focus、type、fill、press、hover、select、check、uncheck、scroll、drag、upload 等。

这些能力足够覆盖大多数表单填写、页面跳转、按钮点击、上传文件、拖拽交互场景。

4.2 读取和判断能力

它可以读取文本、HTML、input value、attribute、title、URL、元素数量、bounding box、computed styles。

也可以判断元素是否 visible、enabled、checked。

这对自动化验收很重要，因为测试不只是“点了”，还要知道点完以后页面是否真的变成了预期状态。

4.3 等待、网络和调试能力

agent-browser 支持等待 selector、等待文本、等待 URL、等待 load state，也支持用 JS 条件等待。

网络方面，它能 route 请求、mock response、查看 network requests、记录 HAR。

调试方面，它能看 console、page errors、trace、profiler，也能打开 DevTools。

这些能力让它不只是“自动点网页”，而是可以参与比较完整的 Web 调试和验收流程。

4.4 截图、diff 和可视化

screenshot 不仅能保存页面截图，还支持 annotated screenshot：在可交互元素上覆盖编号标签。

这些编号和 ref 对应，比如截图里的 [2] 对应 @e2。

这对多模态 AI 很有用：模型既可以看图理解布局，也可以用 ref 精准执行动作。

它还支持 screenshot diff 和 snapshot diff，可以比较当前页面和 baseline 的差异，适合做 UI 回归检查。

5. 性能和架构：Rust CLI + daemon

agent-browser 的另一个重点是性能。

它的架构是：

1. 1. Rust CLI：负责解析命令，与 daemon 通信。
2. 2. Rust daemon：使用直接 CDP 控制浏览器，不要求 daemon 依赖 Node.js。

daemon 会在第一次命令时自动启动，并在后续命令之间复用浏览器会话。

这点很适合 Agent 场景。

因为 AI 操作浏览器往往不是一次性脚本，而是一轮一轮地执行：打开页面、观察、点击、再观察、填写、再检查。如果每一步都重新启动浏览器，体验会非常差。

README 还提供了 batch 命令，可以在一次调用里执行多条命令，减少多步骤流程的启动开销：

agent-browser batch "open https://example.com" "snapshot -i" "screenshot"

或者通过 JSON stdin 传入：

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

这类设计明显不是只为人类手敲命令准备的，而是为 Agent、脚本、CI 流程准备的。

6. MCP、Skills、Chat、Dashboard：Agent 集成很完整

agent-browser 还可以作为 MCP Server 使用：

agent-browser mcp
agent-browser mcp --tools core,network,react

它把工具分成多个 profile，例如 core、network、state、debug、tabs、react、mobile、all。

这个设计很实用，因为 MCP 工具太多时，上下文会变重。默认只加载 core，可以保持日常浏览器自动化的上下文更小；需要网络、React、移动端能力时，再按需打开。

README 里还提到，它支持通过 skills 给 AI coding assistant 提供更完整的使用说明：

npx skills add vercel-labs/agent-browser

并且 skill 内容会匹配当前安装的 CLI 版本，避免说明文档和实际命令脱节。

除此之外，它还有 chat 命令和 Observability Dashboard。

chat 可以把自然语言转换成 agent-browser 命令来执行；dashboard 则可以在本地网页里看到 live viewport、activity feed、console output，甚至创建新 session。

对开发者来说，这意味着你不一定只能在黑盒里等 Agent 跑完。你可以观察它到底打开了什么页面、执行了什么命令、哪里报错了。

7. 登录态、Session 和安全边界

浏览器自动化绕不开登录态。

agent-browser 提供了多种方式：

• • Chrome profile reuse：复用本机已有 Chrome 登录状态。
• • Persistent profile：指定 profile 路径，跨重启保存完整浏览器状态。
• • Session persistence：用 --session-name 自动保存和恢复 cookies、localStorage。
• • State file：加载之前保存的认证状态 JSON。
• • Auth vault：本地加密保存凭证，避免 LLM 直接看到密码。

例如你可以复用已有 Chrome profile：

agent-browser --profile Default open https://gmail.com

也可以给不同项目准备不同 session：

agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com

安全方面，它也提供了不少 Agent 场景需要的边界能力：

• • --content-boundaries：用边界标记包住页面输出，帮助 LLM 区分工具输出和不可信网页内容。
• • --allowed-domains：限制只能访问指定域名。
• • --action-policy：用静态策略文件限制敏感动作。
• • --confirm-actions：对 eval、download 等敏感动作要求确认。
• • --max-output：限制页面输出长度，避免上下文被撑爆。

这类能力很关键。

因为 AI Agent 一旦能操作浏览器，就不仅是“帮你点网页”，它也可能接触登录状态、页面内容、下载、执行 JS、跨站跳转等敏感动作。

工具层如果没有边界，后面很难靠提示词补救。

8. 适合哪些场景？

我觉得 agent-browser 比较适合下面几类场景。

8.1 AI 编程助手做网页验收

比如你让 AI 改了一个登录页、设置页、后台表单，它可以用 agent-browser 打开本地页面，snapshot 找到按钮和输入框，执行真实交互，再截图或读取文本确认结果。

这比“代码看起来没问题”更接近真实验收。

8.2 登录流和表单流程测试

登录、注册、找回密码、复杂表单提交，这些流程很适合用 ref 工作流拆成一轮轮操作。

尤其是页面变化后重新 snapshot，可以让 Agent 更稳地处理动态 UI。

8.3 网页巡检和资料抓取

如果你需要定期打开某些页面，读取标题、文本、链接、状态，或者截图留档，agent-browser 的 CLI 形态会比写完整脚本更轻。

8.4 CI 或 Serverless 浏览器任务

README 里给了 Vercel Sandbox 和 AWS Lambda 的示例，也支持自定义 browser executable，比如轻量 Chromium 构建。

这说明它不只考虑本机开发，也考虑自动化任务部署环境。

8.5 React 应用调试

它支持 React tree、inspect、renders、suspense，还支持 Web Vitals。

如果你做的是 Next.js、Remix、Vite React、TanStack Start 等 React 应用，这部分能力会比较有吸引力。

9. 使用前要注意什么？

虽然 agent-browser 很适合 AI Agent，但它不是魔法。

第一，页面变化后要重新 snapshot。旧 ref 不应该无脑复用。

第二，登录态文件和 state 文件可能包含敏感 token。README 也提醒了，state files 里有明文 session tokens，应该加到 .gitignore，不用时删除；需要加密时设置 AGENT_BROWSER_ENCRYPTION_KEY。

第三，--remote-debugging-port 这类能力只应该在可信机器上使用，因为本地其他进程可能连接并控制浏览器。

第四，如果在 Linux 上跑，可能需要：

agent-browser install --with-deps

第五，如果从源码构建，需要 Node.js 24+、pnpm 11+ 和 Rust。普通用户不建议一开始就走源码构建，直接 npm、Homebrew 或 Cargo 更省事。

10. 总结：它更像是 AI Agent 的浏览器手脚

agent-browser 最吸引我的地方，不是它列了多少命令，而是它把浏览器自动化重新整理成了适合 Agent 的交互模型。

snapshot 负责观察，@e1 这类 ref 负责精确定位，CLI 命令负责执行动作，重新 snapshot 负责确认状态变化。

这个闭环一旦跑通，AI 操作浏览器就不再完全依赖截图猜测，也不需要在复杂 DOM 里硬猜 selector。

如果你平时会用 AI 编程助手改前端页面、跑登录流程、检查网页状态，或者你正在折腾 Agent 自动化任务，agent-browser 值得收藏试一下。

我的建议是：先别急着研究所有命令。

从这几条开始就够了：

npm install -g agent-browser
agent-browser install
agent-browser open example.com
agent-browser snapshot -i
agent-browser screenshot page.png
agent-browser close

等你理解了 snapshot 和 ref 工作流，再去看 MCP、session、安全策略、dashboard、React introspection，那时候它的价值会更明显。

觉得有用可以先收藏，后面如果你想把 AI Agent 接入真实网页操作，这类工具大概率会越来越常见。