Agent Skills Finder
V

agent-browser

作者 vercel-labs

agent-browser 是为 AI agents 和 shell 脚本设计的 Chrome/Chromium 浏览器自动化 CLI。你可以用它打开页面、导航、点击、填写表单、抓取快照、截图、录屏、性能 profiling、管理会话、处理认证流程，以及自动化端到端浏览器操作流程。

Stars0
收藏0
评论0
分类浏览器自动化
安装命令
npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser
AutomationCliChromeChrome Devtools ProtocolAgent Browser测试
概览

Overview

What is agent-browser?

agent-browser 是一款命令行浏览器自动化工具，专为 AI agents 和基于 shell 的工作流设计。它通过 Chrome DevTools Protocol (CDP) 直接连接 Chrome 或 Chromium，让你可以在终端或 agent 运行环境中脚本化真实浏览器行为。

使用 agent-browser，你可以：

  • 打开并导航网页（agent-browser open <url>）
  • 通过结构化快照发现页面中的交互元素
  • 点击按钮、跟随链接、与表单交互
  • 填写输入框、输入文本、发送按键
  • 获取页面快照，了解页面结构和可用操作
  • 管理会话并保留登录等认证状态
  • 走通认证流程（包括需要人工辅助的 OAuth 和 2FA）
  • 使用代理进行地域测试或在企业网络环境中访问
  • 记录性能 trace 用于 profiling
  • 录制浏览器会话视频，用于调试或文档说明

Who is agent-browser for?

如果你有以下需求，agent-browser 会比较适合：

  • 运行需要真实浏览器控制的 AI agent 或自动化框架
  • 希望用 CLI 优先的方式自动化 Chrome/Chromium 流程
  • 需要对 LLM 友好的、可靠的元素定位（基于精简的 @refs）
  • 自动化登录、表单提交、多步 Web 应用流程
  • 将可复现的测试、演示或调试会话记录成视频或 trace

它在这些场景下尤其有用：

  • 浏览器自动化：脚本化导航、点击、表单填写
  • 工作流自动化：端到端流程，例如“登录 → 导航 → 导出报表”
  • 测试自动化：Web 应用的冒烟测试、回归检查和性能 profiling

When agent-browser is and is not a good fit

在以下情况适合使用 agent-browser：

  • 你可以本地运行 CLI，并能访问 Chrome 或 Chromium
  • 你希望将可预测、可脚本化的浏览器行为暴露给 AI agent
  • 你需要对会话、cookies 和认证进行精细控制

在以下情况可能不太适合：

  • 无法在宿主机上安装或运行 Chrome/Chromium
  • 只需要原始 HTML 或简单 HTTP 请求（使用纯 HTTP client 或爬虫可能更简单）
  • 需要在特定语言或 runtime 中，通过与其它浏览器自动化库深度耦合的方式控制无头浏览器

How to Use

Installation options

agent-browser 支持多种安装方式，可以根据你的环境选择：

  • npm (Node.js)

    npm i -g agent-browser

  • Homebrew (macOS/Linux)

    brew install agent-browser

  • Rust / Cargo

    cargo install agent-browser

安装 CLI 后，先运行内置的 Chrome 安装脚本：

agent-browser install

该命令会下载并配置一个兼容的 Chrome/Chromium 版本。后续如有新版本，可运行：

agent-browser upgrade

如果你在某个 agent 平台中将 agent-browser 作为 skill 使用，也可以通过以下方式添加：

npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser

请查看仓库中的 SKILL.md 文件，获取关于该 skill 最新的集成与接线说明。

Core browser automation workflow

每个 agent-browser 自动化流程基本都遵循一个简单循环：open → snapshot → interact → re-snapshot。

  1. 打开目标页面

    agent-browser open https://example.com/form

  2. 通过快照发现页面元素
    使用交互式快照模式，获取带有 @refs 的可点击、可填写元素精简列表：

    agent-browser snapshot -i

    输出示例（简化版）：

    @e1 [input type="email"]
@e2 [input type="password"]
@e3 [button] "Submit"

  3. 基于 refs 进行交互

    agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3

  4. 等待并重新快照

    agent-browser wait --load networkidle
agent-browser snapshot -i

这种模式让 AI agent 可以基于紧凑的结构视图而不是整个 DOM 来推理，大幅降低上下文占用。

Command reference basics

agent-browser 提供了一整套丰富的命令（详见 references/commands.md），包括：

  • Navigation

    agent-browser open <url>
agent-browser back
agent-browser forward
agent-browser reload
agent-browser close

  • Snapshot and refs

    agent-browser snapshot          # 输出完整树
agent-browser snapshot -i       # 仅输出交互元素（推荐）
agent-browser snapshot -c       # 精简输出
agent-browser snapshot -d 3     # 限制深度
agent-browser snapshot -s "#main"  # 只对匹配 CSS selector 的区域快照

  • Interactions

    agent-browser click @e1
agent-browser dblclick @e1
agent-browser hover @e1
agent-browser focus @e1
agent-browser fill @e2 "text"
agent-browser type @e2 "text"
agent-browser press Enter

关于 @refs 的生成规则及有效期，详见 references/snapshot-refs.md。

Working with sessions and authentication

agent-browser 内置会话和认证相关能力，适合用于登录流程、多账号测试或隔离不同用户角色。

  • 命名会话（见 references/session-management.md）：

    # 会话 "auth"：执行登录流程
agent-browser --session auth open https://app.example.com/login

# 会话 "public"：单独的公共浏览会话
agent-browser --session public open https://example.com

    每个会话都有隔离的 cookies、storage、cache 和 history。

  • 会话状态持久化：

    # 保存 cookies 和 storage
agent-browser state save ./auth-state.json

# 之后恢复
agent-browser state load ./auth-state.json
agent-browser open https://app.example.com/dashboard

  • 常见认证模式（见 references/authentication.md）：

    • 从已登录且启用调试的 Chrome 导入 cookies
    • 利用快照配合 fill/click 走完整套标准登录表单
    • 处理基于 cookie 的认证、HTTP basic auth 和 token 刷新

对于复杂的 OAuth 或 2FA 流程，首轮可能仍需要人工参与完成登录；之后 agent-browser 可以复用已保存的认证状态，无需重复登录。

Proxy support and network configuration

如果需要通过代理路由流量（例如做地域测试、速率控制或适配企业网络），可使用 references/proxy-support.md 中记录的配置方式：

  • 通过 CLI 参数配置 HTTP/HTTPS 代理

    agent-browser --proxy "http://proxy.example.com:8080" open https://example.com

  • 通过环境变量配置

    export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="https://proxy.example.com:8080"
agent-browser open https://example.com

  • SOCKS 代理

    export ALL_PROXY="socks5://proxy.example.com:1080"
agent-browser open https://example.com

Profiling and performance tracing

在测试自动化和性能排查场景中，agent-browser 可以捕获 Chrome 的性能 traces（详见 references/profiling.md）：

# 开始 profiling
agent-browser profiler start

# 执行你的场景
agent-browser open https://example.com
agent-browser click @e1
agent-browser wait 1000

# 停止并保存 trace
agent-browser profiler stop ./trace.json

你可以在 Chrome DevTools 的 Performance 面板或其他兼容工具中打开 trace.json，分析 JavaScript 执行、渲染和 user timing 等事件。

Video recording for debugging and documentation

agent-browser 可以录制浏览器会话视频，用于调试失败的自动化流程或制作操作指南（详见 references/video-recording.md）：

# 开始录制
agent-browser record start ./demo.webm

# 执行操作
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e1

# 停止录制
agent-browser record stop

你可以将这些 .webm 录屏嵌入文档、分享给团队成员，或附在 bug 报告中。

Using templates for common workflows

仓库的 templates/ 目录中包含了一些 shell 脚本模板，帮助你快速搭建可复用的自动化流程：

  • templates/form-automation.sh – 用于结构化地填写并提交表单
  • templates/authenticated-session.sh – 登录并持久化会话状态的示例
  • templates/capture-workflow.sh – 多步流程的快照或录制脚本模式

你可以复制并根据自己的环境、CI 任务或 agent pipeline 做相应改造。

FAQ

与简单的 HTTP 客户端相比，agent-browser 主要解决了哪些问题？

agent-browser 通过 CDP 控制真实的 Chrome/Chromium 实例，这意味着它可以处理：

  • 客户端渲染和复杂 JavaScript
  • 依赖浏览器 API 的单页应用（SPA）
  • 像真实用户一样的交互，例如点击、输入和按键
  • 可视化的加载时序、渲染行为和性能 traces

如果你只需要从简单接口拿到原始 HTML 或 JSON，用 HTTP 客户端就足够了。但凡涉及“像真实用户在浏览器中操作”的场景，agent-browser 会更合适。

如何为 agent-browser 安装 Chrome 或 Chromium？

使用 npm、Homebrew 或 Cargo 安装好 CLI 之后，运行：

agent-browser install

该命令会下载并配置一个 agent-browser 可以通过 CDP 控制的兼容版 Chrome/Chromium。之后如有新版本发布，可执行：

agent-browser upgrade

agent-browser 能复用我当前浏览器已登录的会话吗？

可以。references/authentication.md 介绍了如何使用 --remote-debugging-port 启动 Chrome，并从已登录会话中导入 cookies。导入后，你可以通过 agent-browser state save 保存认证状态，并在之后恢复，无需重新走完整个登录流程。

agent-browser 适合在 CI 中做自动化测试吗？

适合。agent-browser 是 CLI 工具，只要 CI 环境中能提供 Chrome/Chromium，就可以稳定运行。你可以：

  • 在测试套件中执行端到端流程
  • 在构建过程中采集性能 traces
  • 对失败场景进行录屏

在 CI 中，选择与你构建镜像匹配的安装方式（npm、Homebrew 或 Cargo），再通过 shell 脚本或你的 agent 框架来编排自动化流程即可。

agent-browser 如何帮助 AI agents 处理复杂页面？

agent-browser 不会直接输出完整 DOM，而是提供带稳定 @refs 的精简快照，仅覆盖关键元素（链接、按钮、输入框等）。这大幅降低了 token 消耗，并让 AI agent 更容易：

  • 理解页面结构
  • 通过 ref 精准选择元素
  • 发出精确的 click、fill 和 press 命令

references/snapshot-refs.md 详细说明了 refs 的生成策略、何时需要刷新，以及实现稳定自动化的最佳实践。

agent-browser 是否支持代理和企业网络环境？

支持。你可以通过 CLI 参数（--proxy）或环境变量（HTTP_PROXY、HTTPS_PROXY、ALL_PROXY）配置 HTTP、HTTPS 和 SOCKS 代理。references/proxy-support.md 涵盖了基础配置、认证代理、绕过规则以及常见故障排查建议。

想深入了解 agent-browser，应该从仓库里的哪些内容看起？

如果你想系统了解 agent-browser，推荐从以下内容开始：

  • 阅读 SKILL.md，获取整体概览和快速入门
  • 查看 references/commands.md，了解完整命令列表及其参数
  • 参考 references/authentication.md、references/session-management.md、references/snapshot-refs.md、references/profiling.md 和 references/video-recording.md 等专题文档
  • 浏览 templates/ 目录，获取可以直接改造复用的工作流脚本示例

评分与评论

暂无评分
分享你的评价
登录后即可为这个技能评分并发表评论。
G
0/10000
最新评论
保存中...