SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场agent-browser

agent-browser

智能体与模型

查看项目

更新于 10-15 15:27

技能介绍

用途

agent-browser 是一款浏览器自动化 CLI 工具，专为 AI 智能体设计。当需要与网站交互时（导航页面、填写表单、点击按钮、截图等）可使用它。它通过 CDP 直接驱动 Chrome/Chromium。

安装

可通过以下任一方式安装：

  • npm i -g agent-browser
  • brew install agent-browser
  • cargo install agent-browser

运行 agent-browser install 下载 Chrome，运行 agent-browser upgrade 更新到最新版本。

核心工作流

每次浏览器自动化遵循同一模式：

  1. 导航：agent-browser open <url>
  2. 快照：agent-browser snapshot -i（获取 @e1、@e2 等元素引用）
  3. 交互：使用引用进行点击、填写、选择
  4. 重新快照：导航或 DOM 变化后获取新引用

示例：

agent-browser open https://example.com/form
agent-browser snapshot -i
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i

命令链式调用

命令可用 && 在单次 shell 调用中链式执行。浏览器通过后台守护进程在命令间保持，因此链式调用安全且比分开调用更高效。当不需要读取中间命令输出时使用 &&（如 open + wait + screenshot）；当需要先解析输出时（如先 snapshot 发现引用再交互）则应分开执行。

认证处理

有以下几种方式：

  • 选项 1：从用户浏览器导入认证（一次性任务最快）。使用 agent-browser --auto-connect state save ./auth.json 连接用户已登录的 Chrome，再用 --state ./auth.json 使用该状态。注意状态文件包含明文会话令牌，需加入 .gitignore，可用 AGENT_BROWSER_ENCRYPTION_KEY 加密。
  • 选项 2：持久化配置文件（重复任务最简单）。首运行用 --profile ~/.myapp 手动或自动登录，之后运行即已认证。
  • 选项 3：会话名称（自动保存/恢复 cookies + localStorage）。用 --session-name myapp 指定，close 时自动保存，下次自动恢复。
  • 选项 4：认证保管库（凭据加密存储，按名称登录）。用 agent-browser auth save myapp --url ... --username user --password-stdin 保存，用 agent-browser auth login myapp 登录。auth login 会等待登录表单选择器出现后再填写/点击，在延迟的 SPA 登录页更可靠。
  • 选项 5：状态文件（手动保存/加载）。登录后用 agent-browser state save ./auth.json，未来会话用 agent-browser state load ./auth.json。

OAuth、2FA、基于 cookie 的认证及令牌刷新模式参见 references/authentication.md。

常用命令

导航：open <url>（别名 goto、navigate）、close 快照：snapshot -i（推荐）、snapshot -i -C（含光标交互元素）、snapshot -s "#selector"（限定 CSS 选择器） 交互：click @e1、click @e1 --new-tab、fill @e2 "text"（清空后输入）、type @e2 "text"（不清空）、select @e1 "option"、check @e1、press Enter、keyboard type "text"、keyboard inserttext "text"、scroll down 500 等 获取信息：get text @e1、get url、get title、get cdp-url 等待：wait @e1、wait --load networkidle、wait --url "/page"、wait 2000、wait --text、wait --fn、wait "#spinner" --state hidden 下载：download @e1 ./file.pdf、wait --download ./output.zip、--download-path ./downloads 网络：network requests、network route "/api/*" --abort、network har start/stop 视口与设备：set viewport 1920 1080、set device "iPhone 14" 截图：screenshot、--full、--annotate、--screenshot-dir、--screenshot-format jpeg --screenshot-quality 80、pdf output.pdf 剪贴板：clipboard read/write/copy/paste 差异对比：diff snapshot、diff screenshot --baseline、diff url <url1> <url2>

批处理执行

向 batch 管道传入 JSON 字符串数组数组，可在单次调用中执行多条命令，避免逐命令启动开销。

echo '[
  ["open", "https://example.com"],
  ["snapshot", "-i"],
  ["click", "@e1"],
  ["screenshot", "result.png"]
]' | agent-browser batch --json

使用 --bail 在首个错误时停止。当命令序列已知且不依赖中间输出时使用 batch；需要解析输出时使用分开命令或 && 链。

常见模式

表单提交、认证保管库认证（推荐）、状态持久化认证、会话持久化、iframe 工作（快照自动内联 iframe 内容，引用带 frame 上下文，可直接交互，无需切换 frame）、数据提取、并行会话、连接现有 Chrome、暗色模式、视口与响应式测试、可视化调试（--headed、highlight、inspect、record、profiler）、本地文件（file:// URL）、iOS 模拟器（-p ios）。

安全

所有安全特性均为可选。默认情况下 agent-browser 对导航、动作或输出不施加限制。

  • 内容边界（推荐用于 AI 智能体）：启用 --content-boundaries（或环境变量 AGENT_BROWSER_CONTENT_BOUNDARIES=1）将页面来源输出包裹在标记中，帮助 LLM 区分工具输出与不可信页面内容。
  • 域名白名单：AGENT_BROWSER_ALLOWED_DOMAINS="example.com,*.example.com" 限制导航到受信域名，通配符 *.example.com 也匹配裸域 example.com。对非允许域名的子资源请求、WebSocket 和 EventSource 连接也会被阻断。
  • 动作策略：使用策略文件（AGENT_BROWSER_ACTION_POLICY=./policy.json）门控破坏性动作，示例默认 deny。