agent-browser 使用指南：AI 时代的浏览器自动化利器

agent-browser 使用指南：AI 时代的浏览器自动化利器

前言

在 AI 智能体（AI Agent）快速发展的今天，让 AI 自主操控浏览器完成网页任务已成为开发者最迫切的需求之一。传统的 Playwright、Puppeteer 虽然功能强大，但它们面向人类开发者设计，API 复杂、输出冗余，AI 使用这些工具时常常面临 Token 消耗过大、响应延迟过高等问题。

Vercel Labs 开源的 agent-browser 正是为解决这一痛点而生——这是一款专为 AI 智能体设计的浏览器自动化命令行工具，使用 Rust 编写，通过网页无障碍树（Accessibility Tree）实现 AI 对页面元素的精准交互。GitHub 星标超过 3 万，npm 周下载量超过 65 万，已成为 AI 浏览器自动化领域最具影响力的项目之一。

本文将带你从零开始，全面掌握 agent-browser 的安装、配置与使用技巧。

一、agent-browser 是什么？

1.1 项目定位

agent-browser 是一款专为 AI Agent 设计的浏览器自动化命令行工具（CLI），核心特点包括：

• AI 原生设计：输出的是紧凑的“可访问性树（Accessibility Tree）”而非庞大的 DOM 树，Token 消耗比传统 Playwright MCP 方案减少高达 93%。
• 基于引用的交互系统：通过 snapshot 命令生成元素引用（如 @e1、@e2），AI 可直接通过引用操作元素，无需编写脆弱的选择器。
• 高性能跨平台：核心 CLI 由 Rust 编写，响应快、性能高。通过 Node.js 作为后备（fallback），保证在 macOS、Linux、Windows 上的兼容性。
• 功能全面：提供超过 50 个命令，涵盖导航、表单填写、点击、截图、网络请求拦截等所有浏览器操作。

1.2 为什么要用 agent-browser？

传统方案如 Playwright MCP 的输出是结构化 JSON，Token 消耗约为 agent-browser 的 5.7 倍。agent-browser 采用 CLI-first 架构，AI 通过执行 shell 命令来控制浏览器，大幅降低 Token 消耗和延迟。同时，agent-browser 的守护进程（daemon）独立运行，无需 Node.js 运行时，启动更快、资源占用更少。

1.3 工作原理

agent-browser 通过 Chrome DevTools Protocol（CDP）直接与浏览器通信，无需 WebDriver 中间层。其核心技术栈为：85% Rust + 12.4% TypeScript，采用三层架构——Rust CLI 层负责解析命令、CDP Daemon 负责浏览器进程管理、Chrome for Testing 则提供自动化专用浏览器内核。

此外，市面上也存在其他类似“Agent Browser”概念的云平台产品，例如 Bright Data 的 Agent Browser 提供了云端的浏览器自动化平台，内置反反爬能力和 CAPTCHA 自动求解功能。本文主要聚焦于开源的 agent-browser（Vercel Labs 出品），这也是 GitHub 上被广泛使用的解决方案。

二、环境准备：你需要什么？

在开始安装之前，请确保你的系统满足以下条件：

• Node.js：用于安装 npm 包和运行后备层
• Chrome 浏览器：可以通过 agent-browser 的 install 命令自动下载 Chrome for Testing（Google 官方的自动化测试版 Chrome），也可以使用系统中已有的 Chrome、Brave 或 Playwright 安装的 Chromium

可选需求：

• Rust：仅在从源码构建时需要
• pnpm：从源码构建时需要

三、安装 agent-browser

3.1 全局安装（推荐，全平台适用）

npm install -g agent-browser
agent-browser install

第一条命令安装 agent-browser 的 CLI。第二条命令会自动下载 Chrome for Testing，首次安装必须执行。

3.2 macOS 用户：Homebrew 安装

brew install agent-browser
agent-browser install

3.3 项目内安装（本地依赖）

如果希望在项目中固定版本：

npm install agent-browser
agent-browser install

之后可以通过 package.json 的 scripts 或直接调用 agent-browser。

3.4 Rust 环境：Cargo 安装

cargo install agent-browser
agent-browser install

3.5 从源码构建

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 用户在安装时需要加上 –with-deps 参数来自动安装系统依赖。

3.6 国内用户安装注意事项

在国内网络环境下，agent-browser install 可能会因无法访问 Chrome for Testing 下载地址而失败。解决方案：

3.7 升级

升级到最新版本只需一条命令，agent-browser 会自动检测你的安装方式（npm、Homebrew 或 Cargo）并执行相应更新：

agent-browser upgrade

3.8 安装 TypeScript 封装（可选）

如果你更喜欢面向对象的编程方式，可以使用社区提供的 TypeScript 封装库：

npm install @sigodenjs/agent-browser

import { Browser } from '@sigodenjs/agent-browser';

const browser = new Browser({ headed: true });
await browser.goto('https://example.com');
await browser.fill('#search', 'hello world');
await browser.click('button[type="submit"]');
const title = await browser.get.title();
const snap = await browser.snapshot();
await browser.close();

该封装提供了与 CLI 命令一一对应的面向对象 API，支持导入在带有 sourcemap 的 TypeScript/JavaScript 项目中使用。

四、基础使用手册

4.1 核心工作流

agent-browser 的操作遵循一个简单而强大的模式：打开页面 → 获取快照 → 操作元素。这是一个典型的基础示例：

# 1. 打开网页
agent-browser open https://example.com

# 2. 获取页面快照（生成元素引用）
agent-browser snapshot -i

# 输出示例：
# – 链接 "Made with love by Vercel" [ref=e1]
# – 链接 "agent-browser" [ref=e2]
# – 按钮 "Ask AI" [ref=e26]

# 3. 使用引用进行交互
agent-browser click @e2
agent-browser fill @e3 "test@example.com"

# 4. 截图保存
agent-browser screenshot page.png

# 5. 关闭浏览器
agent-browser close

快照机制是 agent-browser 的核心创新：它会智能识别页面中的可交互元素，为每个元素分配一个唯一引用（如 @e1、@e2）。AI 可以直接通过引用操作元素，大幅降低 Token 消耗。

4.2 常用命令速查

4.3 快照的高级用法

快照支持多种模式来满足不同场景需求：

# 获取所有可交互元素的引用（推荐）
agent-browser snapshot -i

# 包含鼠标光标可交互的元素
agent-browser snapshot -i -C

# 包含 URL 信息
agent-browser snapshot -i –urls

4.4 常用交互命令

# — 点击与输入 —
agent-browser click "@e1" # 点击元素
agent-browser dblclick "@e1" # 双击元素
agent-browser type "@e2" "hello" # 逐字输入
agent-browser fill "@e2" "hello world" # 清空并填充
agent-browser press Enter # 按键操作

# — 表单操作 —
agent-browser select "@e3" "California" # 选择下拉选项
agent-browser check "@e4" # 勾选复选框
agent-browser uncheck "@e4" # 取消勾选

# — 鼠标操作 —
agent-browser hover "@e1" # 悬停元素
agent-browser focus "@e1" # 聚焦元素
agent-browser drag "@e1" "@e2" # 拖拽元素

# — 滚动 —
agent-browser scroll down 300 # 向下滚动
agent-browser scrollintoview "@e5" # 滚动到元素可见

4.5 等待机制

等待页面加载或特定条件是一门艺术。agent-browser 提供了灵活的等待命令：

# 等待网络空闲（确保页面加载完成）
agent-browser wait –load networkidle

# 等待特定元素出现
agent-browser wait @e15

# 等待特定文本出现
agent-browser wait –text "登录成功"

# 等待 URL 变化
agent-browser wait –url "https://example.com/dashboard"

4.6 使用传统选择器

除了快照引用，agent-browser 也支持 CSS 选择器，兼容传统使用习惯：

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

4.7 执行 JavaScript

agent-browser eval "document.title"

可以用来读取页面数据、获取渲染后的元素状态，或触发复杂的页面逻辑。

4.8 数据提取

agent-browser 提供了一套强大的 get 子命令用于数据提取：

# 获取文本内容
agent-browser get text "@e1"

# 获取 HTML 内容
agent-browser get html ".result"

# 获取元素属性
agent-browser get attr "@e2" "href"

# 获取页面标题
agent-browser get title

# 获取当前 URL
agent-browser get url

# 获取元素数量
agent-browser get count ".item"

五、进阶功能详解

5.1 有头模式与无头模式

• 无头模式（默认）：浏览器在后台静默运行，不显示窗口，适合服务器环境和批量任务。
• 有头模式：显示浏览器窗口，方便调试和观察：

agent-browser open https://example.com –headed

5.2 多标签页管理

agent-browser 支持同时管理多个浏览器标签页：

# 新建标签页
agent-browser tab new https://github.com

# 切换到指定 tab
agent-browser tab 2

# 列出所有标签页
agent-browser tab list

# 关闭当前标签页
agent-browser tab close

5.3 认证管理

agent-browser 提供多种认证状态管理方案：

方案一：Auth Vault（推荐）

# 保存凭据…
echo "password" | agent-browser auth save github \\
–url https://github.com/login \\
–username user \\
–password-stdin

# …之后随时登录
agent-browser auth login github

方案二：Chrome Profile 复用

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

利用已有的 Chrome 用户配置文件，直接使用已登录的会话。

方案三：状态文件保存/加载

agent-browser state save ./auth.json
agent-browser state load ./auth.json

将认证状态持久化到文件，跨会话复用。

5.4 网络监控与拦截

# 查看网络请求
agent-browser network requests

# 拦截特定请求
agent-browser network route "**/api/*" –abort

# 录制 HAR 文件
agent-browser network har start
agent-browser network har stop ./capture.har

这对于调试 AJAX 请求、分析页面加载性能或拦截不需要的请求非常有用。

5.5 会话隔离

agent-browser 支持多个独立的浏览器实例，每个实例有自己的 Cookie、LocalStorage 和身份验证状态：

# 创建独立会话
agent-browser session create –name "my_session"

# 使用指定会话打开页面
agent-browser open https://example.com –session "my_session"

这对于需要同时登录多个账号的场景（如多账号管理、A/B 测试等）特别有用。

5.6 命令链式调用与批处理

# 链式调用（&& 连接多个命令）
agent-browser fill @e1 "text" && agent-browser click @e2

# 批处理（单次调用执行多个命令）
agent-browser batch \\
"open https://example.com" \\
"snapshot -i" \\
"screenshot"

批处理可以减少往返次数，进一步提高 Token 效率。

5.7 截图与 PDF 导出

# 标准截图
agent-browser screenshot page.png

# 全页截图
agent-browser screenshot page.png –full

# 导出 PDF
agent-browser pdf page.pdf

5.8 文件操作

# 上传文件
agent-browser upload "@e1" ./document.pdf

# 下载文件
agent-browser download "@e2" ./downloads/

5.9 键盘高级操作

# 在当前焦点元素上模拟真实键盘输入
agent-browser keyboard type "hello"

# 不触发 key 事件直接插入文本
agent-browser keyboard inserttext "hello"

# 按住/释放特定键
agent-browser keydown Control
agent-browser keyup Control

六、与 AI Agent 集成

6.1 内置 AI 对话模式

agent-browser 内置了 chat 命令，支持通过自然语言直接控制浏览器：

agent-browser chat

进入交互式 REPL 模式后，可以用自然语言描述任务，agent-browser 会自动规划并执行操作。

6.2 集成到 Cursor / Claude Code / Codex

安装 agent-browser skill 后，你可以在主流 AI 编码助手中直接控制浏览器：

npx skills add vercel-labs/agent-browser –skill agent-browser

安装完成后，在 Cursor、Claude Code 或 Codex 中就可以直接给 AI 下达浏览器操控指令，例如“打开百度首页并截图”。

6.3 与 AI Agent 搭配的使用模式

将 agent-browser 集成到 AI Agent 的核心模式是：AI Agent 通过调用 agent-browser 的命令行接口来控制浏览器，agent-browser 返回紧凑的文本输出供 AI 分析决策。在智能决策层的循环中，AI 解析快照、规划下一步操作，再调用 agent-browser 执行。浏览器操作由 agent-browser 的 CDP Daemon 独立管理，AI 只需要发出 shell 命令即可完成复杂的网页自动化任务。

七、实战场景与示例

7.1 场景一：自动化新闻采集与数据抓取

利用 agent-browser，AI 可以自动完成新闻采集的完整流程：先导航到新闻网站并关闭弹窗，再滚动页面加载更多内容，接着通过快照获取所有新闻链接，逐篇提取标题、摘要和正文，最后将数据输出为结构化 JSON 交由 AI 进一步处理或存储。整个过程无需人工干预。

7.2 场景二：智能表单填写

AI 驱动 agent-browser 可以自动填写各种网页表单：先导航到表单页面获取快照，再根据元素引用逐一填写输入框（如姓名、邮箱、地址等），接着选择下拉菜单选项、勾选复选框，最后点击提交按钮并等待成功提示。这对批量报名、调查问卷填写、客户信息录入等场景特别实用——agent-browser 提供了专门的 fill、select、check、press 等命令，能处理大多数表单交互。

7.3 场景三：多平台内容发布

结合 AI 内容生成能力，agent-browser 可以登录多个平台自动发布内容。典型流程是：首先通过 Auth Vault 自动登录；然后导航到内容发布页面；再利用 fill 或 inserttext 填写标题和正文；接着通过 upload 功能上传图片附件；最后提交并验证发布结果。多标签页管理功能可以同时向多个平台发布。

7.4 场景四：电商比价与竞品监控

利用 agent-browser 的多标签页和网络监控功能，AI 可以同时打开多个电商平台，搜索相同商品，提取价格、评价数据，通过 get text 和 get attr 提取结构化信息，最终输出完整的比价报告。

八、同类工具对比与选择

agent-browser vs Playwright/Puppeteer

agent-browser vs Playwright MCP

Playwright MCP 的输出是结构化 JSON，Token 消耗约为 agent-browser 的 5.7 倍；Playwright 需要 Node.js 运行时，而 agent-browser 的 daemon 独立运行，启动更快。在 Token 成本和响应速度方面，agent-browser 有明显优势。

注：如果你需要云端的浏览器自动化能力，可以考虑 Bright Data 的 Agent Browser 等商业产品。它们能自动绕过 CAPTCHA、反爬检测，适合大规模自动化任务，但需要付费使用。本文介绍的 agent-browser 是完全开源的解决方案，适合大多数开发场景。

九、局限性与注意事项

当前局限

• 仅支持 Chrome：agent-browser 通过 Chrome DevTools Protocol 与 Chrome 通信，不支持 Firefox、Safari 等其他浏览器。
• 无内置 AI 模型：需要与 AI Agent 配合使用，本身不包含智能决策能力。
• 对现代 Web 框架的适配：虽然支持 React SPA（通过 pushstate 命令操作浏览器历史记录），但在某些复杂场景下仍需额外处理。

使用建议

结语

agent-browser 代表了浏览器自动化工具的一次范式转移——从“面向人类开发者”到“面向 AI 智能体”。它以极低的 Token 消耗、出色的性能和 AI 友好的设计，正在成为 AI Agent 开发者不可或缺的工具。GitHub 3 万星标、npm 65 万周下载量的数据也印证了这一点。

无论你是想构建自动化新闻采集系统、智能表单填写机器人，还是让 AI 助手真正地“上网干活”，agent-browser 都值得你深入学习和使用。

更加值得期待的是，agent-browser 正在快速迭代更新，截至本文发布时已在 4 天内连续发布了 6 个版本，项目活力可见一斑。未来它有望集成更多 AI 原生能力，进一步降低开发者门槛，让 AI 上网操控成为每个人都触手可及的能力。