站点图标 高效码农

AI智能体浏览器自动化革命：一文读懂Agent-Browser核心技术及实战指南

高效码农

深入解析 Agent-Browser：AI智能体的浏览器自动化利器

Agent-Browser 是一款专为AI智能体设计的无头浏览器自动化命令行工具。这个基于Rust的CLI工具通过Node.js后备机制，为开发者提供了快速、高效的浏览器自动化解决方案。它采用客户端-守护进程架构，利用Playwright的Chromium浏览器引擎，支持macOS ARM64/x64、Linux ARM64/x64以及Windows x64平台，能够以原生Rust二进制文件或Node.js后备方式运行。

核心技术架构与优势

Agent-Browser的设计理念围绕AI智能体的实际需求展开，其架构包含三个关键组件：负责命令解析和守护进程通信的Rust CLI原生二进制文件、管理Playwright浏览器实例的Node.js守护进程，以及在原生二进制文件不可用时直接运行的Node.js后备机制。守护进程在首次命令时自动启动，并在命令之间保持持久化状态，确保后续操作的快速响应。
与传统的浏览器自动化工具相比，Agent-Browser特别针对大语言模型（LLM）进行了优化。它引入了Refs机制，从快照中提供确定性的元素选择，无需重复查询DOM，这为LLM提供了最佳的工作流程。此外，工具支持JSON格式的机器可读输出、通过Refs的高性能元素交互，以及专为AI设计的快照+ref工作流。

安装与部署指南

通过npm安装（推荐）

npm安装是最简单的方式，适合大多数用户场景：

npm install -g agent-browser
agent-browser install

执行agent-browser install命令会自动下载Chromium浏览器到本地环境，整个过程无需手动干预。

从源码安装

对于需要自定义编译的开发者，可以从源码构建：

git clone https://github.com/vercel-labs/agent-browser
cd agent-browser
pnpm install
pnpm build
pnpm build:native
pnpm link --global
agent-browser install

从源码构建需要Rust编译器工具链，可通过https://rustup.rs获取。构建过程包括依赖安装、项目构建、原生二进制编译以及全局链接，最终同样需要执行agent-browser install来下载浏览器。

Linux系统依赖

在Linux环境下，需要额外安装系统依赖：

agent-browser install --with-deps

或者手动执行：

npx playwright install-deps chromium

这一步骤确保Linux系统具备运行Chromium所需的系统库和依赖项。

核心命令详解

浏览器导航与基础操作

浏览器自动化的第一步通常是导航到目标页面：

agent-browser open example.com

open命令支持多个别名：goto和navigate，功能完全相同。导航到页面后，可以执行多种交互操作：

  • click <sel> – 点击元素
  • dblclick <sel> – 双击元素
  • focus <sel> – 聚焦元素
  • type <sel> <text> – 在元素中输入文本
  • fill <sel> <text> – 清除并填充元素
  • press <key> – 按下按键（如Enter、Tab、Control+a），别名key
  • keydown <key> – 按住按键
  • keyup <key> – 释放按键
  • hover <sel> – 悬停在元素上
  • select <sel> <val> – 选择下拉选项
  • check <sel> – 勾选复选框
  • uncheck <sel> – 取消勾选
  • scroll <dir> [px] – 滚动页面（方向：up/down/left/right）
  • scrollintoview <sel> – 滚动到元素可见区域，别名scrollinto
  • drag <src> <tgt> – 拖放操作
  • upload <sel> <files> – 上传文件

页面信息获取

获取页面信息是验证测试结果的重要手段：

agent-browser get text <sel>
agent-browser get html <sel>
agent-browser get value <sel>
agent-browser get attr <sel> <attr>
agent-browser get title
agent-browser get url
agent-browser get count <sel>
agent-browser get box <sel>

这些命令分别用于获取元素的文本内容、内部HTML、输入值、指定属性、页面标题、当前URL、匹配元素数量以及元素的边界框信息。

状态检查

验证元素状态对于确保测试准确性至关重要：

agent-browser is visible <sel>
agent-browser is enabled <sel>
agent-browser is checked <sel>

这些命令返回布尔值，指示元素是否可见、启用或被勾选。

语义定位器与元素查找

语义定位器（Semantic Locators）提供了一种更自然、更健壮的元素查找方式：

agent-browser find role <role> <action> [value]
agent-browser find text <text> <action>
agent-browser find label <label> <action> [value]
agent-browser find placeholder <ph> <action> [value]
agent-browser find alt <text> <action>
agent-browser find title <text> <action>
agent-browser find testid <id> <action> [value]
agent-browser find first <sel> <action> [value]
agent-browser find last <sel> <action> [value]
agent-browser find nth <n> <sel> <action> [value]

支持的动作包括：click、fill、check、hover、text。
实际使用示例：

agent-browser find role button click --name "Submit"
agent-browser find text "Sign In" click
agent-browser find label "Email" fill "test@test.com"
agent-browser find first ".item" click
agent-browser find nth 2 "a" text

语义定位器基于ARIA角色、文本内容、标签、占位符、alt文本、title属性和data-testid等元数据，相比CSS选择器更加稳定可靠。

智能快照与Refs机制

快照（snapshot）是Agent-Browser的核心功能，它返回带有refs的可访问性树，专为AI智能体优化：

agent-browser snapshot

输出示例：

- heading "Example Domain" [ref=e1] [level=1]
- button "Submit" [ref=e2]
- textbox "Email" [ref=e3]
- link "Learn more" [ref=e4]

使用refs进行交互：

agent-browser click @e2
agent-browser fill @e3 "test@example.com"
agent-browser get text @e1
agent-browser hover @e4

Refs提供了确定性、高性能的元素选择方式，从快照中直接引用元素，无需重新查询DOM。这种机制对于LLM特别友好，快照+ref的工作流程是AI与网页交互的最优解。

快照选项

快照命令支持多种选项以减少输出大小：

agent-browser snapshot                    # 完整可访问性树
agent-browser snapshot -i                 # 仅交互元素（按钮、输入框、链接）
agent-browser snapshot -c                 # 紧凑模式（移除空结构元素）
agent-browser snapshot -d 3               # 限制深度为3级
agent-browser snapshot -s "#main"         # 限定到CSS选择器范围内
agent-browser snapshot -i -c -d 5         # 组合选项
选项 描述
-i, --interactive 仅显示交互元素（按钮、链接、输入框）
-c, --compact 移除空结构元素
-d, --depth <n> 限制树深度
-s, --selector <sel> 限定到CSS选择器范围内

高级功能

会话管理

Agent-Browser支持运行多个隔离的浏览器实例：

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

或者通过环境变量：

AGENT_BROWSER_SESSION=agent1 agent-browser click "#btn"

列出活动会话：

agent-browser session list

输出示例：

Active sessions:
-> default
   agent1

显示当前会话：

agent-browser session

每个会话拥有独立的浏览器实例、Cookie和存储、导航历史以及身份验证状态。这种设计允许同时进行多个独立的浏览器会话，适用于多用户或多任务场景。

等待机制

等待是处理动态网页的关键：

agent-browser wait <selector>         # 等待元素可见
agent-browser wait <ms>               # 等待指定毫秒数
agent-browser wait --text "Welcome"   # 等待文本出现
agent-browser wait --url "**/dash"    # 等待URL匹配模式
agent-browser wait --load networkidle # 等待加载状态
agent-browser wait --fn "window.ready === true"  # 等待JavaScript条件

支持的加载状态包括：load、domcontentloaded、networkidle。

浏览器设置与环境模拟

agent-browser set viewport <w> <h>    # 设置视口大小
agent-browser set device <name>       # 模拟设备（如"iPhone 14"）
agent-browser set geo <lat> <lng>     # 设置地理位置
agent-browser set offline [on|off]    # 切换离线模式
agent-browser set headers <json>      # 设置额外HTTP头
agent-browser set credentials <u> <p> # 设置HTTP基本认证
agent-browser set media [dark|light]  # 模拟颜色方案

这些设置允许模拟不同的设备、地理位置、网络状态和颜色主题，确保应用在各种环境下的表现。

Cookie与存储管理

agent-browser cookies                 # 获取所有Cookie
agent-browser cookies set <name> <val> # 设置Cookie
agent-browser cookies clear           # 清除Cookie
agent-browser storage local           # 获取所有localStorage
agent-browser storage local <key>     # 获取指定键
agent-browser storage local set <k> <v>  # 设置值
agent-browser storage local clear     # 清除所有
agent-browser storage session         # sessionStorage操作相同

Cookie和存储管理功能对于测试身份验证、数据持久化等功能至关重要。

网络拦截与模拟

agent-browser network route <url>              # 拦截请求
agent-browser network route <url> --abort      # 阻止请求
agent-browser network route <url> --body <json>  # 模拟响应
agent-browser network unroute [url]            # 移除路由
agent-browser network requests                 # 查看跟踪的请求
agent-browser network requests --filter api    # 过滤请求

网络拦截功能允许模拟API响应、阻止特定请求或修改请求/响应，是测试边界条件和错误场景的强大工具。

标签页与窗口管理

agent-browser tab                     # 列出标签页
agent-browser tab new [url]           # 新建标签页（可选URL）
agent-browser tab <n>                 # 切换到标签页n
agent-browser tab close [n]           # 关闭标签页
agent-browser window new              # 新建窗口

多标签页支持使得测试跨标签页交互、弹出窗口等复杂场景成为可能。

调试与开发辅助

agent-browser trace start [path]      # 开始录制跟踪
agent-browser trace stop [path]       # 停止并保存跟踪
agent-browser console                 # 查看控制台消息
agent-browser console --clear         # 清除控制台
agent-browser errors                  # 查看页面错误
agent-browser errors --clear          # 清除错误
agent-browser highlight <sel>         # 高亮元素
agent-browser state save <path>       # 保存身份验证状态
agent-browser state load <path>       # 加载身份验证状态

调试工具帮助开发者快速定位问题、分析页面行为和保存测试状态。

Agent模式与AI集成

使用--json标志获取机器可读的输出：

agent-browser snapshot --json

返回格式：

{
  "success": true,
  "data": {
    "snapshot": "...",
    "refs": {
      "e1": {"role": "heading", "name": "Title"},
      ...
    }
  }
}

最优AI工作流程：

# 1. 导航并获取快照
agent-browser open example.com
agent-browser snapshot -i --json   # AI解析树和refs
# 2. AI从快照中识别目标refs
# 3. 使用refs执行操作
agent-browser click @e2
agent-browser fill @e3 "input text"
# 4. 页面变化时获取新快照
agent-browser snapshot -i --json

这种工作流程特别适合与大语言模型集成，refs机制提供了确定性的元素选择，JSON输出便于解析和处理。

身份验证与头部设置

使用--headers为特定源设置HTTP头，无需登录流程即可进行身份验证：

agent-browser open api.example.com --headers '{"Authorization": "Bearer <token>"}'

头部设置仅对api.example.com生效，访问其他域名时不会发送这些头部，确保安全性。此功能适用于：

  • 跳过登录流程 – 通过头部进行身份验证而非UI
  • 切换用户 – 使用不同身份验证令牌启动新会话
  • API测试 – 直接访问受保护端点
  • 安全性 – 头部限定于源，不会泄露到其他域名
    为多个源设置头部：
agent-browser open api.example.com --headers '{"Authorization": "Bearer token1"}'
agent-browser open api.acme.com --headers '{"Authorization": "Bearer token2"}'

设置全局头部（所有域名）：

agent-browser set headers '{"X-Custom-Header": "value"}'

自定义浏览器可执行文件

使用自定义浏览器可执行文件替代捆绑的Chromium：

CLI使用

agent-browser --executable-path /path/to/chromium open example.com

通过环境变量：

AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com

此功能适用于：

  • 无服务器部署：使用轻量级Chromium构建如@sparticuz/chromium（约50MB vs 约684MB）
  • 系统浏览器：使用现有Chrome/Chromium安装
  • 自定义构建：使用修改后的浏览器构建

无服务器示例（Vercel/AWS Lambda）

import chromium from '@sparticuz/chromium';
import { BrowserManager } from 'agent-browser';
export async function handler() {
  const browser = new BrowserManager();
  await browser.launch({
    executablePath: await chromium.executablePath(),
    headless: true,
  });
  // ... 使用浏览器
}

CDP模式

通过Chrome DevTools协议连接现有浏览器：

agent-browser --cdp 9222 snapshot

连接Chrome远程调试（启动Chrome时需添加：google-chrome --remote-debugging-port=9222）：

agent-browser --cdp 9222 open about:blank

CDP模式使得控制以下应用成为可能：

  • Electron应用
  • 带远程调试的Chrome/Chromium实例
  • WebView2应用
  • 任何暴露CDP端点的浏览器

流式传输（浏览器预览）

通过WebSocket流式传输浏览器视口，用于实时预览或”配对浏览”，人类可以观看并与AI智能体并行交互。

启用流式传输

设置环境变量：

AGENT_BROWSER_STREAM_PORT=9223 agent-browser open example.com

这会在指定端口启动WebSocket服务器，流式传输浏览器视口并接受输入事件。

WebSocket协议

连接到ws://localhost:9223接收帧并发送输入。
接收帧：

{
  "type": "frame",
  "data": "<base64-encoded-jpeg>",
  "metadata": {
    "deviceWidth": 1280,
    "deviceHeight": 720,
    "pageScaleFactor": 1,
    "offsetTop": 0,
    "scrollOffsetX": 0,
    "scrollOffsetY": 0
  }
}

发送鼠标事件：

{
  "type": "input_mouse",
  "eventType": "mousePressed",
  "x": 100,
  "y": 200,
  "button": "left",
  "clickCount": 1
}

发送键盘事件：

{
  "type": "input_keyboard",
  "eventType": "keyDown",
  "key": "Enter",
  "code": "Enter"
}

发送触摸事件：

{
  "type": "input_touch",
  "eventType": "touchStart",
  "touchPoints": [{"x": 100, "y": 200}]
}

编程API

直接通过协议控制流式传输：

import { BrowserManager } from 'agent-browser';
const browser = new BrowserManager();
await browser.launch({ headless: true });
await browser.navigate('https://example.com');
// 开始截屏
await browser.startScreencast((frame) => {
  // frame.data是base64编码的图像
  // frame.metadata包含视口信息
  console.log('接收帧:', frame.metadata.deviceWidth, 'x', frame.metadata.deviceHeight);
}, {
  format: 'jpeg',
  quality: 80,
  maxWidth: 1280,
  maxHeight: 720,
});
// 注入鼠标事件
await browser.injectMouseEvent({
  type: 'mousePressed',
  x: 100,
  y: 200,
  button: 'left',
});
// 注入键盘事件
await browser.injectKeyboardEvent({
  type: 'keyDown',
  key: 'Enter',
  code: 'Enter',
});
// 完成时停止
await browser.stopScreencast();

选择器指南

Refs（AI推荐）

Refs提供从快照中确定性的元素选择：

# 1. 获取带refs的快照
agent-browser snapshot
# 2. 使用refs交互
agent-browser click @e2
agent-browser fill @e3 "test@example.com"
agent-browser get text @e1
agent-browser hover @e4

使用Refs的原因：

  • 确定性：Ref指向快照中的精确元素
  • 快速：无需重新查询DOM
  • AI友好：快照+ref工作流程对LLM最优

CSS选择器

agent-browser click "#id"
agent-browser click ".class"
agent-browser click "div > button"

文本与XPath

agent-browser click "text=Submit"
agent-browser click "xpath=//button"

语义定位器

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

常见问题解答

如何在AI智能体中使用Agent-Browser？

最简单的方法是直接告诉智能体使用它：”Use agent-browser to test the login flow. Run agent-browser –help to see available commands.”--help输出非常全面，大多数智能体可以从中理解用法。

如何获得更一致的结果？

将以下内容添加到项目或全局指令文件中：

## Browser Automation
Use `agent-browser` for web automation. Run `agent-browser --help` for all commands.
Core workflow:
1. `agent-browser open <url>` - Navigate to page
2. `agent-browser snapshot -i` - Get interactive elements with refs (@e1, @e2)
3. `agent-browser click @e1` / `fill @e2 "text"` - Interact using refs
4. Re-snapshot after page changes

Agent-Browser支持哪些浏览器引擎？

默认使用Chromium。守护进程还通过Playwright协议支持Firefox和WebKit。

如何显示浏览器窗口进行调试？

使用--headed标志：

agent-browser open example.com --headed

这会打开可见的浏览器窗口，而不是无头运行。

如何跳过登录流程？

使用--headers设置身份验证头：

agent-browser open api.example.com --headers '{"Authorization": "Bearer <token>"}'

头部限定于URL的源，请求到其他域名时不会发送这些头部。

如何在Vercel或AWS Lambda等无服务器环境中使用？

使用轻量级Chromium构建和自定义可执行路径：

import chromium from '@sparticuz/chromium';
import { BrowserManager } from 'agent-browser';
export async function handler() {
  const browser = new BrowserManager();
  await browser.launch({
    executablePath: await chromium.executablePath(),
    headless: true,
  });
}

如何连接到现有浏览器实例？

使用CDP模式：

agent-browser --cdp 9222 snapshot

连接到Chrome的远程调试端口（启动Chrome时需添加--remote-debugging-port=9222）。

如何实时监控AI智能体的浏览器操作？

设置流式传输环境变量并连接WebSocket：

AGENT_BROWSER_STREAM_PORT=9223 agent-browser open example.com

连接到ws://localhost:9223接收帧并发送输入事件。

如何减少快照的输出大小？

使用快照选项：

agent-browser snapshot -i -c -d 5

-i仅显示交互元素，-c紧凑模式移除空结构元素，-d 5限制深度为5级。

总结

Agent-Browser通过其独特的Refs机制、语义定位器、会话隔离、JSON输出模式以及流式预览功能，为AI智能体提供了强大而灵活的浏览器自动化能力。无论是进行Web应用测试、数据采集，还是构建AI驱动的自动化工作流，Agent-Browser都提供了简洁、高效的命令行接口和丰富的功能集，是开发者构建智能自动化解决方案的理想工具。

退出移动版