agent-browser

Vercel Labs 推出的 AI 代理专用浏览器自动化 CLI，通过 Ref 系统实现高效率、低 Token 消耗的 Web 交互。

项目定位#

agent-browser 是一款 Agent-first 的无头浏览器自动化 CLI 工具，通过可访问性树和 Ref 系统为 AI 代理提供确定性交互与高上下文效率。

核心问题#

传统浏览器自动化工具（如 Puppeteer/Playwright 原生接口）输出的 DOM 树体量大（通常 3000-5000 tokens），且元素选择器（CSS/XPath）在动态页面中不稳定，不适合 AI 代理（LLM）直接消费和操作。

核心特点#

Agent-first 设计：输出格式针对 AI 上下文效率优化，紧凑输出约 200-400 tokens vs DOM 的 3000-5000 tokens
Ref-based 元素选择：基于可访问性树和引用的确定性元素定位（如 @e1、@e2）
快速：原生 Rust CLI 实现亚毫秒级命令解析
JSON 模式：--json 标志用于机器可读输出

技术栈#

TypeScript (58.7%)
Rust (36.1%)
Python (1.9%)
JavaScript (1.7%)
依赖：Playwright (浏览器驱动)

支持平台#

macOS (ARM64, x64)
Linux (ARM64, x64)
Windows (x64)

核心能力#

浏览器自动化#

导航控制: open、back、forward、reload
元素交互: click、fill、type、hover、drag、upload
键盘控制: press、keydown、keyup、keyboard type
表单操作: check、uncheck、select

信息获取#

页面快照: snapshot 命令返回带 refs 的可访问性树
文本提取: get text、get html、get value、get attr
页面状态: get title、get url、get count、get box、get styles
截图/PDF: screenshot（支持全页和注释）、pdf

高级功能#

会话管理: 多个隔离的浏览器实例（--session）
持久化配置: 配置文件和用户数据持久化（--profile、--session-name）
网络控制: 网络请求拦截、路由、mock 响应
存储管理: cookies、localStorage、sessionStorage 操作
多标签页/窗口: 标签页和窗口管理
CDP 连接: 通过 Chrome DevTools Protocol 连接外部浏览器

安全特性（可选）#

认证保险库: 本地加密存储凭证
内容边界标记: 标记页面输出以区分工具输出和不受信任内容
域名白名单: 限制导航到受信任的域名
操作策略: 使用策略文件控制破坏性操作
输出长度限制: 防止上下文洪水攻击

架构#

客户端-守护进程架构#

Rust CLI: 快速原生二进制文件，解析命令，与守护进程通信
Node.js Daemon: 管理 Playwright 浏览器实例
Fallback: 如果原生二进制不可用，直接使用 Node.js

浏览器引擎#

默认使用 Chromium
通过 Playwright 协议支持 Firefox 和 WebKit
支持自定义浏览器可执行文件

Ref 系统#

基于可访问性树生成确定性元素引用
避免重新查询 DOM，提高性能
AI 友好的文本输出格式

典型场景#

AI 代理自动化#

为 Claude Code、Cursor、GitHub Copilot、OpenAI Codex、Google Gemini 等提供浏览器自动化能力
适用于任何可以执行 shell 命令的 AI 代理

Web 测试#

登录流程测试
表单填写验证
页面交互测试
跨浏览器兼容性测试

数据提取#

网页内容抓取
结构化数据提取
截图和 PDF 生成

云端部署#

支持无服务器环境（Vercel、AWS Lambda）
集成第三方浏览器服务（Browserbase、Browser Use、Kernel）

安装方式#

全局安装（推荐）#

npm install -g agent-browser
agent-browser install  # 下载 Chromium

快速试用（无需安装）#

npx agent-browser open example.com

macOS Homebrew#

brew install agent-browser
agent-browser install  # 下载 Chromium

基础工作流#

# 1. 导航并获取快照
agent-browser open example.com
agent-browser snapshot -i

# 2. 使用 refs 交互
agent-browser click @e2
agent-browser fill @e3 "test@example.com"
agent-browser screenshot page.png

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

AI 代理模式#

# JSON 输出用于机器解析
agent-browser snapshot --json

# 紧凑的交互元素列表
agent-browser snapshot -i --json

关键 CLI 标志#

--json: 输出机器可读的 JSON 格式
--session <name>: 启动隔离的浏览器会话
--profile <path>: 指定持久化数据目录
--headed: 显示浏览器 GUI（默认无头）

关键环境变量#

AGENT_BROWSER_SESSION_NAME: 自动保存/加载会话状态
AGENT_BROWSER_ENCRYPTION_KEY: 64 字符十六进制密钥用于 AES-256-GCM 加密
AGENT_BROWSER_DEFAULT_TIMEOUT: 默认 Playwright 超时（毫秒，默认 25000）
AGENT_BROWSER_PROVIDER: 云浏览器提供商（browserbase/browseruse/kernel/ios）
AGENT_BROWSER_CONTENT_BOUNDARIES: 包装页面输出边界标记
AGENT_BROWSER_MAX_OUTPUT: 页面输出最大字符数
AGENT_BROWSER_ALLOWED_DOMAINS: 允许的域名模式列表

集成对象#

AI 工具: Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Google Gemini
云服务: Browserbase, Browser Use, Kernel, AWS Lambda/Vercel Serverless