vercel-labs/agent-browser

GitHub: vercel-labs/agent-browser

专为 AI 智能体设计的无头浏览器自动化 CLI，通过快照引用机制和 JSON 输出让大语言模型能够高效、安全地操控浏览器完成复杂 Web 交互任务。

Stars: 19638 | Forks: 1148

# agent-browser 面向 AI agents 的 Headless browser 自动化 CLI。快速的 Rust CLI，带有 Node.js 回退支持。 ## 安装 ### 全局安装（推荐）安装原生 Rust 二进制文件以获得最佳性能： ``` npm install -g agent-browser agent-browser install # Download Chromium ``` 这是最快的选项 —— 命令直接通过原生 Rust CLI 运行，解析开销为亚毫秒级。 ### 快速开始（无需安装）如果你想在不安裈的情况下试用，可以直接使用 `npx` 运行： ``` npx agent-browser install # Download Chromium (first time only) npx agent-browser open example.com ``` ### 项目安装（本地依赖）适用于希望在 `package.json` 中固定版本的项目： ``` npm install agent-browser npx agent-browser install ``` 然后通过 `npx` 或 `package.json` 脚本使用： ``` npx agent-browser open example.com ``` ### Homebrew (macOS) ``` brew install agent-browser agent-browser install # Download Chromium ``` ### 从源码构建 ``` git clone https://github.com/vercel-labs/agent-browser cd agent-browser pnpm install pnpm build pnpm build:native # Requires Rust (https://rustup.rs) pnpm link --global # Makes agent-browser available globally agent-browser install ``` ### Linux 依赖项在 Linux 上，安装系统依赖： ``` agent-browser install --with-deps # 或手动执行：npx playwright install-deps chromium ``` ## 快速开始 ``` agent-browser open example.com agent-browser snapshot # Get accessibility tree with refs agent-browser click @e2 # Click by ref from snapshot agent-browser fill @e3 "test@example.com" # Fill by ref agent-browser get text @e1 # Get text by ref agent-browser screenshot page.png agent-browser close ``` ### 传统选择器（同样支持） ``` agent-browser click "#submit" agent-browser fill "#email" "test@example.com" agent-browser find role button click --name "Submit" ``` ## 命令 ### 核心命令 ``` agent-browser open # Navigate to URL (aliases: goto, navigate) agent-browser click # Click element (--new-tab to open in new tab) agent-browser dblclick # Double-click element agent-browser focus # Focus element agent-browser type # Type into element agent-browser fill # Clear and fill agent-browser press # Press key (Enter, Tab, Control+a) (alias: key) agent-browser keyboard type # Type with real keystrokes (no selector, current focus) agent-browser keyboard inserttext # Insert text without key events (no selector) agent-browser keydown # Hold key down agent-browser keyup # Release key agent-browser hover # Hover element agent-browser select # Select dropdown option agent-browser check # Check checkbox agent-browser uncheck # Uncheck checkbox agent-browser scroll [px] # Scroll (up/down/left/right, --selector ) agent-browser scrollintoview # Scroll element into view (alias: scrollinto) agent-browser drag # Drag and drop agent-browser upload # Upload files agent-browser screenshot [path] # Take screenshot (--full for full page, saves to a temporary directory if no path) agent-browser screenshot --annotate # Annotated screenshot with numbered element labels agent-browser pdf # Save as PDF agent-browser snapshot # Accessibility tree with refs (best for AI) agent-browser eval # Run JavaScript (-b for base64, --stdin for piped input) agent-browser connect # Connect to browser via CDP agent-browser close # Close browser (aliases: quit, exit) ``` ### 获取信息 ``` agent-browser get text # Get text content agent-browser get html # Get innerHTML agent-browser get value # Get input value agent-browser get attr # Get attribute agent-browser get title # Get page title agent-browser get url # Get current URL agent-browser get count # Count matching elements agent-browser get box # Get bounding box agent-browser get styles # Get computed styles ``` ### 检查状态 ``` agent-browser is visible # Check if visible agent-browser is enabled # Check if enabled agent-browser is checked # Check if checked ``` ### 查找元素（语义定位器） ``` agent-browser find role [value] # By ARIA role agent-browser find text # By text content agent-browser find label [value] # By label agent-browser find placeholder [value] # By placeholder agent-browser find alt # By alt text agent-browser find title # By title attr agent-browser find testid [value] # By data-testid agent-browser find first [value] # First match agent-browser find last [value] # Last match agent-browser find nth [value] # Nth match ``` **操作：** `click`, `fill`, `type`, `hover`, `focus`, `check`, `uncheck`, `text` **选项：** `--name ` （按可访问名称过滤角色），`--exact` （要求精确文本匹配） **示例：** ``` 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 ``` ### 等待 ``` agent-browser wait # Wait for element to be visible agent-browser wait # Wait for time (milliseconds) agent-browser wait --text "Welcome" # Wait for text to appear agent-browser wait --url "**/dash" # Wait for URL pattern agent-browser wait --load networkidle # Wait for load state agent-browser wait --fn "window.ready === true" # Wait for JS condition ``` **加载状态：** `load`, `domcontentloaded`, `networkidle` ### 鼠标控制 ``` agent-browser mouse move # Move mouse agent-browser mouse down [button] # Press button (left/right/middle) agent-browser mouse up [button] # Release button agent-browser mouse wheel [dx] # Scroll wheel ``` ### 浏览器设置 ``` agent-browser set viewport # Set viewport size agent-browser set device # Emulate device ("iPhone 14") agent-browser set geo # Set geolocation agent-browser set offline [on|off] # Toggle offline mode agent-browser set headers # Extra HTTP headers agent-browser set credentials

# HTTP basic auth agent-browser set media [dark|light] # Emulate color scheme ``` ### Cookies & 存储 ``` agent-browser cookies # Get all cookies agent-browser cookies set # Set cookie agent-browser cookies clear # Clear cookies agent-browser storage local # Get all localStorage agent-browser storage local # Get specific key agent-browser storage local set # Set value agent-browser storage local clear # Clear all agent-browser storage session # Same for sessionStorage ``` ### 网络 ``` agent-browser network route # Intercept requests agent-browser network route --abort # Block requests agent-browser network route --body # Mock response agent-browser network unroute [url] # Remove routes agent-browser network requests # View tracked requests agent-browser network requests --filter api # Filter requests ``` ### 标签页 & 窗口 ``` agent-browser tab # List tabs agent-browser tab new [url] # New tab (optionally with URL) agent-browser tab # Switch to tab n agent-browser tab close [n] # Close tab agent-browser window new # New window ``` ### Frames ``` agent-browser frame # Switch to iframe agent-browser frame main # Back to main frame ``` ### 对话框 ``` agent-browser dialog accept [text] # Accept (with optional prompt text) agent-browser dialog dismiss # Dismiss ``` ### Diff ``` agent-browser diff snapshot # Compare current vs last snapshot agent-browser diff snapshot --baseline before.txt # Compare current vs saved snapshot file agent-browser diff snapshot --selector "#main" --compact # Scoped snapshot diff agent-browser diff screenshot --baseline before.png # Visual pixel diff against baseline agent-browser diff screenshot --baseline b.png -o d.png # Save diff image to custom path agent-browser diff screenshot --baseline b.png -t 0.2 # Adjust color threshold (0-1) agent-browser diff url https://v1.com https://v2.com # Compare two URLs (snapshot diff) agent-browser diff url https://v1.com https://v2.com --screenshot # Also visual diff agent-browser diff url https://v1.com https://v2.com --wait-until networkidle # Custom wait strategy agent-browser diff url https://v1.com https://v2.com --selector "#main" # Scope to element ``` ### 调试 ``` agent-browser trace start [path] # Start recording trace agent-browser trace stop [path] # Stop and save trace agent-browser profiler start # Start Chrome DevTools profiling agent-browser profiler stop [path] # Stop and save profile (.json) agent-browser console # View console messages (log, error, warn, info) agent-browser console --clear # Clear console agent-browser errors # View page errors (uncaught JavaScript exceptions) agent-browser errors --clear # Clear errors agent-browser highlight # Highlight element agent-browser state save # Save auth state agent-browser state load # Load auth state agent-browser state list # List saved state files agent-browser state show # Show state summary agent-browser state rename # Rename state file agent-browser state clear [name] # Clear states for session agent-browser state clear --all # Clear all saved states agent-browser state clean --older-than # Delete old states ``` ### 导航 ``` agent-browser back # Go back agent-browser forward # Go forward agent-browser reload # Reload page ``` ### 设置 ``` agent-browser install # Download Chromium browser agent-browser install --with-deps # Also install system deps (Linux) ``` ## 会话运行多个隔离的浏览器实例： ``` # 不同会话 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 # 输出： # 活动会话： # -> default # agent1 # 显示当前会话 agent-browser session ``` 每个会话都有其独立的： - 浏览器实例 - Cookies 和存储 - 导航历史 - 认证状态 ## 持久化配置文件默认情况下，浏览器状态（cookies, localStorage, 登录会话）是临时的，并在浏览器关闭时丢失。使用 `--profile` 在浏览器重启之间持久化状态： ``` # 使用持久化配置文件目录 agent-browser --profile ~/.myapp-profile open myapp.com # 登录一次，然后重用已认证的会话 agent-browser --profile ~/.myapp-profile open myapp.com/dashboard # 或通过环境变量 AGENT_BROWSER_PROFILE=~/.myapp-profile agent-browser open myapp.com ``` 配置文件目录存储： - Cookies 和 localStorage - IndexedDB 数据 - Service workers - 浏览器缓存 - 登录会话 **提示**：为不同的项目使用不同的配置文件路径，以保持其浏览器状态隔离。 ## 会话持久化或者，使用 `--session-name` 在浏览器重启之间自动保存和恢复 cookies 和 localStorage： ``` # 为 "twitter" 会话自动保存/加载状态 agent-browser --session-name twitter open twitter.com # 登录一次，然后状态自动持久化 # 状态文件存储在 ~/.agent-browser/sessions/ # 或通过环境变量 export AGENT_BROWSER_SESSION_NAME=twitter agent-browser open twitter.com ``` ### 状态加密使用 AES-256-GCM 对保存的会话数据进行静态加密： ``` # 生成密钥：openssl rand -hex 32 export AGENT_BROWSER_ENCRYPTION_KEY=<64-char-hex-key> # 状态文件现已自动加密 agent-browser --session-name secure open example.com ``` | 变量 | 描述 | |----------|-------------| | `AGENT_BROWSER_SESSION_NAME` | 自动保存/加载状态持久化名称 | | `AGENT_BROWSER_ENCRYPTION_KEY` | 用于 AES-256-GCM 加密的 64 字符十六进制密钥 | | `AGENT_BROWSER_STATE_EXPIRE_DAYS` | 自动删除 N 天前的状态（默认值：30） | ## 安全性 agent-browser 包含用于安全部署 AI agents 的安全功能。所有功能均为可选 —— 在你显式启用某项功能之前，现有工作流不受影响： - **Authentication Vault** —— 本地存储凭据（始终加密），按名称引用。LLM 永远不会看到密码。如果未设置 `AGENT_BROWSER_ENCRYPTION_KEY`，则会在 `~/.agent-browser/.encryption-key` 自动生成一个密钥：`echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin` 然后 `agent-browser auth login github` - **Content Boundary Markers** —— 用分隔符包裹页面输出，以便 LLMs 能够区分工具输出和不可信内容：`--content-boundaries` - **Domain Allowlist** —— 将导航限制在受信任的域（像 `*.example.com` 这样的通配符也会匹配裸域）：`--allowed-domains "example.com,*.example.com"`。对非允许域的子资源请求（脚本、图像、fetch）和 WebSocket/EventSource 连接也会被阻止。包含你的目标页面依赖的任何 CDN 域（例如 `*.cdn.example.com`）。 - **Action Policy** —— 使用静态策略文件把关破坏性操作：`--action-policy ./policy.json` - **Action Confirmation** —— 对敏感操作类别要求显式批准：`--confirm-actions eval,download` - **Output Length Limits** —— 防止上下文泛洪：`--max-output 50000` | 变量 | 描述 | |----------|-------------| | `AGENT_BROWSER_CONTENT_BOUNDARIES` | 用边界标记包裹页面输出 | | `AGENT_BROWSER_MAX_OUTPUT` | 页面输出的最大字符数 | | `AGENT_BROWSER_ALLOWED_DOMAINS` | 逗号分隔的允许域模式 | | `AGENT_BROWSER_ACTION_POLICY` | 操作策略 JSON 文件路径 | | `AGENT_BROWSER_CONFIRM_ACTIONS` | 需要确认的操作类别 | | `AGENT_BROWSER_CONFIRM_INTERACTIVE` | 启用交互式确认提示 | 详情请参阅 [安全文档](https://agent-browser.vercel.app/security)。 ## Snapshot 选项 `snapshot` 命令支持过滤以减小输出大小： ``` agent-browser snapshot # Full accessibility tree agent-browser snapshot -i # Interactive elements only (buttons, inputs, links) agent-browser snapshot -i -C # Include cursor-interactive elements (divs with onclick, etc.) agent-browser snapshot -c # Compact (remove empty structural elements) agent-browser snapshot -d 3 # Limit depth to 3 levels agent-browser snapshot -s "#main" # Scope to CSS selector agent-browser snapshot -i -c -d 5 # Combine options ``` | 选项 | 描述 | |--------|-------------| | `-i, --interactive` | 仅显示交互元素（按钮、链接、输入框） | | `-C, --cursor` | 包含光标交互元素（cursor:pointer, onclick, tabindex） | | `-c, --compact` | 移除空的结构性元素 | | `-d, --depth ` | 限制树深度 | | `-s, --selector ` | 范围限定为 CSS 选择器 | `-C` 标志对于使用自定义可点击元素（divs, spans）而非标准按钮/链接的现代 Web 应用非常有用。 ## 带注释的截图 `--annotate` 标志在截图中的交互元素上覆盖编号标签。每个标签 `[N]` 对应引用 `@eN`，因此相同的引用既适用于视觉工作流，也适用于基于文本的工作流。 ``` agent-browser screenshot --annotate # -> 屏幕截图已保存至 /tmp/screenshot-2026-02-17T12-00-00-abc123.png # [1] @e1 button "Submit" # [2] @e2 link "Home" # [3] @e3 textbox "Email" ``` 在带注释的截图之后，引用会被缓存，因此你可以立即与元素进行交互： ``` agent-browser screenshot --annotate ./page.png agent-browser click @e2 # Click the "Home" link labeled [2] ``` 这对于可以推理视觉布局、未标记的图标按钮、canvas 元素或文本可访问性树无法捕获的视觉状态的多模态 AI 模型非常有用。 ## 选项 | 选项 | 描述 | |--------|-------------| | `--session ` | 使用隔离会话（或 `AGENT_BROWSER_SESSION` 环境变量） | | `--session-name ` | 自动保存/恢复会话状态（或 `AGENT_BROWSER_SESSION_NAME` 环境变量） | | `--profile ` | 持久化浏览器配置文件目录（或 `AGENT_BROWSER_PROFILE` 环境变量） | | `--state ` | 从 JSON 文件加载存储状态（或 `AGENT_BROWSER_STATE` 环境变量） | | `--headers ` | 设置作用域为 URL 来源的 HTTP 标头 | | `--executable-path ` | 自定义浏览器可执行文件（或 `AGENT_BROWSER_EXECUTABLE_PATH` 环境变量） | | `--extension ` | 加载浏览器扩展（可重复；或 `AGENT_BROWSER_EXTENSIONS` 环境变量） | | `--args ` | 浏览器启动参数，以逗号或换行符分隔（或 `AGENT_BROWSER_ARGS` 环境变量） | | `--user-agent ` | 自定义 User-Agent 字符串（或 `AGENT_BROWSER_USER_AGENT` 环境变量） | | `--proxy ` | 带可选认证的代理服务器 URL（或 `AGENT_BROWSER_PROXY` 环境变量） | | `--proxy-bypass ` | 绕过代理的主机（或 `AGENT_BROWSER_PROXY_BYPASS` 环境变量） | | `--ignore-https-errors` | 忽略 HTTPS 证书错误（对于自签名证书有用） | | `--allow-file-access` | 允许 file:// URL 访问本地文件（仅限 Chromium） | | `-p, --provider ` | 云浏览器提供商（或 `AGENT_BROWSER_PROVIDER` 环境变量） | | `--device ` | iOS 设备名称，例如 "iPhone 15 Pro"（或 `AGENT_BROWSER_IOS_DEVICE` 环境变量） | | `--json` | JSON 输出（用于 agents） | | `--full, -f` | 全页面截图 | | `--annotate` | 带有编号元素标签的带注释截图（或 `AGENT_BROWSER_ANNOTATE` 环境变量） | | `--headed` | 显示浏览器窗口（非 headless）（或 `AGENT_BROWSER_HEADED` 环境变量） | | `--cdp ` | 通过 Chrome DevTools Protocol 连接（端口或 WebSocket URL） | | `--auto-connect` | 自动发现并连接到正在运行的 Chrome（或 `AGENT_BROWSER_AUTO_CONNECT` 环境变量） | | `--color-scheme ` | 颜色方案：`dark`, `light`, `no-preference`（或 `AGENT_BROWSER_COLOR_SCHEME` 环境变量） | | `--download-path ` | 默认下载目录（或 `AGENT_BROWSER_DOWNLOAD_PATH` 环境变量） | | `--content-boundaries` | 用边界标记包裹页面输出以保障 LLM 安全（或 `AGENT_BROWSER_CONTENT_BOUNDARIES` 环境变量） | | `--max-output ` | 将页面输出截断为 N 个字符（或 `AGENT_BROWSER_MAX_OUTPUT` 环境变量） | | `--allowed-domains ` | 逗号分隔的允许域模式（或 `AGENT_BROWSER_ALLOWED_DOMAINS` 环境变量） | | `--action-policy ` | 操作策略 JSON 文件路径（或 `AGENT_BROWSER_ACTION_POLICY` 环境变量） | | `--confirm-actions ` | 需要确认的操作类别（或 `AGENT_BROWSER_CONFIRM_ACTIONS` 环境变量） | | `--confirm-interactive` | 交互式确认提示；如果 stdin 不是 TTY 则自动拒绝（或 `AGENT_BROWSER_CONFIRM_INTERACTIVE` 环境变量） | | `--engine ` | 浏览器引擎：`chrome`（默认），`lightpanda`；意味着 `--native`（或 `AGENT_BROWSER_ENGINE` 环境变量） | | `--native` | [实验性] 使用原生 Rust daemon 而非 Node.js（或 `AGENT_BROWSER_NATIVE` 环境变量） | | `--config ` | 使用自定义配置文件（或 `AGENT_BROWSER_CONFIG` 环境变量） | | `--debug` | 调试输出 | ## 配置创建一个 `agent-browser.json` 文件来设置持久化默认值，而不是在每条命令上重复标志。 **位置（从低到高优先级）：** 1. `~/.agent-browser/config.json` —— 用户级默认值 2. `./agent-browser.json` —— 项目级覆盖（位于工作目录中） 3. `AGENT_BROWSER_*` 环境变量覆盖配置文件值 4. CLI 标志覆盖所有其他设置 **示例 `agent-browser.json`：** ``` { "headed": true, "proxy": "http://localhost:8080", "profile": "./browser-data", "userAgent": "my-agent/1.0", "ignoreHttpsErrors": true } ``` 使用 `--config ` 或 `AGENT_BROWSER_CONFIG` 加载特定的配置文件，而不是默认配置： ``` agent-browser --config ./ci-config.json open example.com AGENT_BROWSER_CONFIG=./ci-config.json agent-browser open example.com ``` 上表中的所有选项都可以使用 camelCase 键在配置文件中设置（例如，`--executable-path` 变为 `"executablePath"`，`--proxy-bypass` 变为 `"proxyBypass"`）。为了向前兼容，未知键将被忽略。布尔标志接受可选的 `true`/`false` 值以覆盖配置设置。例如，`--headed false` 会禁用配置中的 `"headed": true`。单独的 `--headed` 等同于 `--headed true`。自动发现但缺失的配置文件会被静默忽略。如果 `--config ` 指向缺失或无效的文件，agent-browser 将退出并报错。来自用户和项目配置的扩展是合并（连接）的，而不是替换。 ## 默认超时标准操作（点击、等待、填充等）的默认 Playwright 超时时间为 25 秒。这有意低于 CLI 的 30 秒 IPC 读取超时，以便 Playwright 返回适当的错误，而不是 CLI 因 EAGAIN 而超时。通过环境变量覆盖默认超时： ``` # 为慢速页面设置更长的超时时间（毫秒） export AGENT_BROWSER_DEFAULT_TIMEOUT=45000 ``` | 变量 | 描述 | |----------|-------------| | `AGENT_BROWSER_DEFAULT_TIMEOUT` | 默认 Playwright 超时时间（毫秒）（默认值：25000） | ## 选择器 ### Refs（推荐用于 AI） Refs 提供从快照中进行确定性元素选择： ``` # 1. 获取带有 refs 的快照 agent-browser snapshot # 输出： # - heading "Example Domain" [ref=e1] [level=1] # - button "Submit" [ref=e2] # - textbox "Email" [ref=e3] # - link "Learn more" [ref=e4] # 2. 使用 refs 进行交互 agent-browser click @e2 # Click the button agent-browser fill @e3 "test@example.com" # Fill the textbox agent-browser get text @e1 # Get heading text agent-browser hover @e4 # Hover the link ``` **为什么使用 refs？** - **确定性**：Ref 指向快照中的确切 - **快速**：无需重新查询 DOM - **AI 友好**：快照 + ref 工作流对 LLMs 来说是最佳的 ### 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" ``` ## Agent 模式使用 `--json` 获得机器可读的输出： ``` agent-browser snapshot --json # 返回：{"success":true,"data":{"snapshot":"...","refs":{"e1":{"role":"heading","name":"Title"},...}}} agent-browser get text @e1 --json agent-browser is visible @e2 --json ``` ### 最佳 AI 工作流 ``` # 1. 导航并获取快照 agent-browser open example.com agent-browser snapshot -i --json # AI parses tree and refs # 2. AI 从快照中识别目标 refs # 3. 使用 refs 执行操作 agent-browser click @e2 agent-browser fill @e3 "input text" # 4. 如果页面发生变化，获取新的快照 agent-browser snapshot -i --json ``` ### 命令链可以在单个 shell 调用中使用 `&&` 链接命令。浏览器通过后台 daemon 持久化，因此链接既安全又更高效： ``` # 在一个调用中完成打开、等待加载和快照 agent-browser open example.com && agent-browser wait --load networkidle && agent-browser snapshot -i # 链式多重交互 agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "pass" && agent-browser click @e3 # 导航并截图 agent-browser open example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png ``` 当你不需要中间输出时使用 `&&`。当你需要先解析输出时（例如，在交互之前先快照以发现 refs），请单独运行命令。 ## Headed 模式显示浏览器窗口以进行调试： ``` agent-browser open example.com --headed ``` 这会打开一个可见的浏览器窗口，而不是以 headless 方式运行。 ## 认证会话使用 `--headers` 为特定来源设置 HTTP 标头，无需登录流程即可实现认证： ``` # Headers 仅作用于 api.example.com agent-browser open api.example.com --headers '{"Authorization": "Bearer "}' # 对 api.example.com 的请求包含 auth header agent-browser snapshot -i --json agent-browser click @e2 # 导航到另一个域名 - headers 不会被发送（安全！） agent-browser open other-site.com ``` 这对于以下情况很有用： - **跳过登录流程** - 通过标头而不是 UI 进行认证 - **切换用户** - 使用不同的认证令牌启动新会话 - **API 测试** - 直接访问受保护的端点 - **安全性** - 标头的作用域限于来源，不会泄露给其他域要为多个来源设置标头，请在每个 `open` 命令中使用 `--headers`： ``` agent-browser open api.example.com --headers '{"Authorization": "Bearer token1"}' agent-browser open api.acme.com --headers '{"Authorization": "Bearer token2"}' ``` 对于全局标头（所有域），使用 `set headers`： ``` agent-browser set headers '{"X-Custom-Header": "value"}' ``` ## 自定义浏览器可执行文件使用自定义浏览器可执行文件代替捆绑的 Chromium。这对于以下情况很有用： - **Serverless 部署**：使用轻量级 Chromium 构建，如 `@sparticuz/chromium`（~50MB vs ~684MB） - **系统浏览器**：使用现有的 Chrome/Chromium 安装 - **自定义构建**：使用修改过的浏览器构建 ### CLI 用法 ``` # 通过 flag agent-browser --executable-path /path/to/chromium open example.com # 通过环境变量 AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com ``` ### Serverless 示例 (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, }); // ... use browser } ``` ## 本地文件使用 `file://` URL 打开并交互本地文件（PDF, HTML 等）： ``` # 启用文件访问（JavaScript 访问本地文件所需） agent-browser --allow-file-access open file:///path/to/document.pdf agent-browser --allow-file-access open file:///path/to/page.html # 截取本地 PDF 的屏幕截图 agent-browser --allow-file-access open file:///Users/me/report.pdf agent-browser screenshot report.png ``` `--allow-file-access` 标志添加了 Chromium 标志（`--allow-file-access-from-files`, `--allow-file-access`），允许 `file://` URL： - 加载和渲染本地文件 - 通过 JavaScript（XHR, fetch）访问其他本地文件 - 加载本地资源（图像、脚本、样式表） **注意：** 此标志仅适用于 Chromium。出于安全考虑，默认情况下处于禁用状态。 ## CDP 模式通过 Chrome DevTools Protocol 连接到现有浏览器： ``` # 使用以下命令启动 Chrome：google-chrome --remote-debugging-port=9222 # 连接一次，然后运行命令时无需 --cdp agent-browser connect 9222 agent-browser snapshot agent-browser tab agent-browser close # 或在每个命令中传递 --cdp agent-browser --cdp 9222 snapshot # 通过 WebSocket URL 连接到远程浏览器 agent-browser --cdp "wss://your-browser-service.com/cdp?token=..." snapshot ``` `--cdp` 标志接受： - 端口号（例如 `9222`），用于通过 `http://localhost:{port}` 进行本地连接 - 完整的 WebSocket URL（例如 `wss://...` 或 `ws://...`），用于远程浏览器服务这能够控制： - Electron 应用程序 - 启用了远程调试的 Chrome/Chromium 实例 - WebView2 应用程序 - 任何暴露 CDP 端点的浏览器 ### 自动连接使用 `--auto-connect` 自动发现并连接到正在运行的 Chrome 实例，而无需指定端口： ``` # 自动发现正在运行且启用了远程调试的 Chrome agent-browser --auto-connect open example.com agent-browser --auto-connect snapshot # 或通过环境变量 AGENT_BROWSER_AUTO_CONNECT=1 agent-browser snapshot ``` 自动连接通过以下方式发现 Chrome： 1. 从默认用户数据目录读取 Chrome 的 `DevToolsActivePort` 文件 2. 回退到探测常见的调试端口（9222, 9229）这在以下情况下很有用： - Chrome 144+ 通过 `chrome://inspect/#remote-debugging` 启用了远程调试（使用动态端口） - 你希望零配置连接到现有浏览器 - 你不想跟踪 Chrome 正在使用哪个端口 ## 流式传输（浏览器预览）通过 WebSocket 流式传输浏览器视口，用于实时预览或“结对浏览”，人类可以与 AI agent 一起观看和交互。 ### 启用流式传输设置 `AGENT_BROWSER_STREAM_PORT` 环境变量： ``` AGENT_BROWSER_STREAM_PORT=9223 agent-browser open example.com ``` 这将在指定端口启动一个 WebSocket 服务器，流式传输浏览器视口并接受输入事件。 ### WebSocket 协议连接到 `ws://localhost:9223` 以接收帧并发送输入： **接收帧：** ``` { "type": "frame", "data": "", "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'); // Start screencast await browser.startScreencast((frame) => { // frame.data is base64-encoded image // frame.metadata contains viewport info console.log('Frame received:', frame.metadata.deviceWidth, 'x', frame.metadata.deviceHeight); }, { format: 'jpeg', quality: 80, maxWidth: 1280, maxHeight: 720, }); // Inject mouse events await browser.injectMouseEvent({ type: 'mousePressed', x: 100, y: 200, button: 'left', }); // Inject keyboard events await browser.injectKeyboardEvent({ type: 'keyDown', key: 'Enter', code: 'Enter', }); // Stop when done await browser.stopScreencast(); ``` ## 架构 agent-browser 采用 client-daemon 架构： 1. **Rust CLI**（快速原生二进制文件）—— 解析命令，与 daemon 通信 2. **Node.js Daemon**（默认）—— 管理 Playwright 浏览器实例 3. **Native Daemon**（实验性，`--native`）—— 纯 Rust daemon，使用直接 CDP，无需 Node.js 4. **Fallback** —— 如果原生二进制文件不可用，则直接使用 Node.js Daemon 在第一次命令时自动启动，并在命令之间持久存在，以实现快速的后续操作。 **浏览器引擎：** 默认使用 Chromium。默认的 Node.js daemon 也通过 Playwright 支持 Firefox 和 WebKit。实验性的 native daemon 直接使用 Chrome DevTools Protocol (CDP) 通信，支持基于 Chromium 的浏览器和 Safari（通过 WebDriver）。 ## 实验性：Native 模式 Native daemon 是一个纯 Rust 实现，通过 CDP 直接与 Chrome 通信，消除了 Node.js 和 Playwright 依赖。它目前是**实验性的**且为可选启用。 ### 启用 Native 模式 ``` # 通过 flag agent-browser --native open example.com # 通过环境变量（推荐用于持久化使用） export AGENT_BROWSER_NATIVE=1 agent-browser open example.com ``` 或添加到你的配置文件（`agent-browser.json`）： ``` {"native": true} ``` ### 有何不同 | | 默认 (Node.js) | Native (`--native`) | |---|---|---| | **Runtime** | Node.js + Playwright | 纯 Rust 二进制文件 | | **Protocol** | Playwright 协议 | 直接 CDP / WebDriver | | **安装大小** | 较大（Node.js + npm deps） | 较小（单个二进制文件） | | **浏览器支持** | Chromium, Firefox, WebKit | Chromium, Safari (通过 WebDriver) | | **稳定性** | 稳定 | 实验性 | ### 已知限制 - 尚不支持 Firefox 和 WebKit（仅限 Chromium 和 Safari） - 某些 Playwright 特有的功能（跟踪格式、HAR 导出）不可用 - Native daemon 和 Node.js daemon 共享同一个会话 socket，因此你不能在同一会话中同时运行两者。切换模式前请使用 `agent-browser close`。 ## 平台 | 平台 | 二进制文件 | 回退 | |----------|--------|----------| | macOS ARM64 | Native Rust | Node.js | | macOS x64 | Native Rust | Node.js | | Linux ARM64 | Native Rust | Node.js | | Linux x64 | Native Rust | Node.js | | Windows x64 | Native Rust | Node.js | ## 配合 AI Agents 使用 ### 直接询问 agent 最简单的方法 —— 直接告诉你的 agent 使用它： ``` Use agent-browser to test the login flow. Run agent-browser --help to see available commands. ``` `--help` 输出非常全面，大多数 agents 都能从那里弄清楚如何使用。 ### AI 编程助手（推荐）将技能添加到你的 AI 编程助手以获得更丰富的上下文： ``` npx skills add vercel-labs/agent-browser ``` 这适用于 Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, 和 Windsurf。该技能从仓库获取，因此会自动保持最新 —— 不要从 `node_modules` 复制 `SKILL.md`，因为它会变得过时。 ### Claude Code 作为 Claude Code 技能安装： ``` npx skills add vercel-labs/agent-browser ``` 这会将技能添加到项目中的 `.claude/skills/agent-browser/SKILL.md`。该技能教会 Claude Code 完整的 agent-browser 工作流，包括 snapshot-ref 交互模式、会话管理和超时处理。 ### AGENTS.md / CLAUDE.md 为了获得更一致的结果，添加到你的项目或全局指令文件： ``` ## 浏览器自动化 Use `agent-browser` for web automation. Run `agent-browser --help` for all commands. Core workflow: 1. `agent-browser open ` - 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 ``` ## 集成 ### iOS 模拟器在 iOS 模拟器中控制真实的 Mobile Safari，以进行真实的移动 Web 测试。需要带有 Xcode 的 macOS。 **设置：** ``` # 安装 Appium 和 XCUITest driver npm install -g appium appium driver install xcuitest ``` **使用：** ``` # 列出可用的 iOS 模拟器 agent-browser device list # 在特定设备上启动 Safari agent-browser -p ios --device "iPhone 16 Pro" open https://example.com # 与桌面版命令相同 agent-browser -p ios snapshot -i agent-browser -p ios tap @e1 agent-browser -p ios fill @e2 "text" agent-browser -p ios screenshot mobile.png # 移动端特定命令 agent-browser -p ios swipe up agent-browser -p ios swipe down 500 # 关闭会话 agent-browser -p ios close ``` 或使用环境变量： ``` export AGENT_BROWSER_PROVIDER=ios export AGENT_BROWSER_IOS_DEVICE="iPhone 16 Pro" agent-browser open https://example.com ``` | 变量 | 描述 | |----------|-------------| | `AGENT_BROWSER_PROVIDER` | 设置为 `ios` 以启用 iOS 模式 | | `AGENT_BROWSER_IOS_DEVICE` | 设备名称（例如 "iPhone 16 Pro", "iPad Pro"） | | `AGENT_BROWSER_IOS_UDID` | 设备 UDID（设备名称的替代方案） | **支持的设备：** Xcode 中所有可用的 iOS 模拟器（iPhone, iPad），以及真实的 iOS 设备。 **注意：** iOS 提供商会启动模拟器，启动 Appium，并控制 Safari。首次启动大约需要 30-60 秒；后续命令会很快。 #### 真机支持 Appium 也支持通过 USB 连接的真实 iOS 设备。这需要额外的一次性设置： **1. 获取你的设备 UDID：** ``` xcrun xctrace list devices # 或 system_profiler SPUSBDataType | grep -A 5 "iPhone\|iPad" ``` **2. 签名 WebDriverAgent（一次性）：** ``` # 打开 WebDriverAgent Xcode 项目 cd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent open WebDriverAgent.xcodeproj ``` 在 Xcode 中： - 选择 `WebDriverAgentRunner` 目标 - 转到 Signing & Capabilities - 选择你的 Team（需要 Apple Developer 帐户，免费层级即可） - 让 Xcode 自动管理签名 **3. 配合 agent-browser 使用：** ``` # 通过 USB 连接设备，然后： agent-browser -p ios --device "" open https://example.com # 或者如果设备名称唯一，直接使用设备名称 agent-browser -p ios --device "John's iPhone" open https://example.com ``` **真机注意事项：** - 首次运行会将 WebDriverAgent 安装到设备上（可能需要“信任”提示） - 设备必须解锁并通过 USB 连接 - 初始连接比模拟器稍慢 - 针对真实的 Safari 性能和行为进行测试 ### Browserbase [Browserbase](https://browserbase.com) 提供远程浏览器基础设施，使 agentic 浏览 agents 的部署变得简单。当在本地浏览器不可行的环境中运行 agent-browser CLI 时使用它。要启用 Browserbase，使用 `-p` 标志： ``` export BROWSERBASE_API_KEY="your-api-key" export BROWSERBASE_PROJECT_ID="your-project-id" agent-browser -p browserbase open https://example.com ``` 或使用环境变量用于 CI/scripts： ``` export AGENT_BROWSER_PROVIDER=browserbase export BROWSERBASE_API_KEY="your-api-key" export BROWSERBASE_PROJECT_ID="your-project-id" agent-browser open https://example.com ``` 启用后，agent-browser 会连接到 Browserbase 会话，而不是启动本地浏览器。所有命令的工作方式相同。从 [Browserbase Dashboard](https://browserbase.com/overview) 获取你的 API 密钥和项目 ID。 ### Browser Use [Browser Use](https://browser-use.com) 为 AI agents 提供云浏览器基础设施。当在本地浏览器不可用的环境（serverless, CI/CD 等）中运行 agent-browser 时使用它。要启用 Browser Use，使用 `-p` 标志： ``` export BROWSER_USE_API_KEY="your-api-key" agent-browser -p browseruse open https://example.com ``` 或使用环境变量用于 CI/scripts： ``` export AGENT_BROWSER_PROVIDER=browseruse export BROWSER_USE_API_KEY="your-api-key" agent-browser open https://example.com ``` 启用后，agent-browser 会连接到 Browser Use 云会话，而不是启动本地浏览器。所有命令的工作方式相同。从 [Browser Use Cloud Dashboard](https://cloud.browser-use.com/settings?tab=api-keys) 获取你的 API 密钥。有免费额度可供开始使用，之后采用按需付费定价。 ### Kernel [Kernel](https://www.kernel.sh) 为 AI agents 提供云浏览器基础设施，具有隐身模式和持久化配置文件等功能。要启用 Kernel，使用 `-p` 标志： ``` export KERNEL_API_KEY="your-api-key" agent-browser -p kernel open https://example.com ``` 或使用环境变量用于 CI/scripts： ``` export AGENT_BROWSER_PROVIDER=kernel export KERNEL_API_KEY="your-api-key" agent-browser open https://example.com ``` 通过环境变量进行可选配置： | 变量 | 描述 | 默认值 | |----------|-------------|---------| | `KERNEL_HEADLESS` | 在 headless 模式下运行浏览器（`true`/`false`） | `false` | | `KERNEL_STEALTH` | 启用隐身模式以避免机器人检测（`true`/`false`） | `true` | | `KERNEL_TIMEOUT_SECONDS` | 会话超时时间（秒） | `300` | | `KERNEL_PROFILE_NAME` | 用于持久化 cookies/logins 的浏览器配置文件名称（如果不存在则创建） | (无) | 启用后，agent-browser 会连接到 Kernel 云会话，而不是启动本地浏览器。所有命令的工作方式相同。 **配置文件持久化：** 当设置了 `KERNEL_PROFILE_NAME` 时，如果配置文件不存在，将会创建它。Cookies, logins, 和会话数据会在浏览器会话结束时自动保存回配置文件，以便在未来的会话中使用。从 [Kernel Dashboard](https://dashboard.onkernel.com) 获取你的 API 密钥。 ## 许可证 Apache-2.0

标签：AI 开发工具, AI 智能体, Chromium, GNU通用公共许可证, MITM代理, Node.js, Playwright, RPA, Rust, Web Scraping, 可视化界面, 威胁情报, 开发者工具, 无头浏览器, 浏览器自动化, 特征检测, 网络流量审计, 辅助功能树, 通知系统, 通知系统, 风险管理