Agent Browser

使用 agent-browser 进行浏览器自动化

安装

推荐使用 npm

npm install -g agent-browser
agent-browser install
agent-browser install --with-deps

从源码构建

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

快速上手

agent-browser open         ## 导航至页面
agent-browser snapshot -i       ## 获取带引用（refs）的可交互元素
agent-browser click @e1         ## 通过引用点击元素
agent-browser fill @e2 "text"   ## 通过引用向输入框填充文本
agent-browser close             ## 关闭浏览器

核心工作流

1. 导航：agent-browser open
2. 快照：agent-browser snapshot -i（返回带引用（如 @e1、@e2）的可交互元素）
3. 使用快照中生成的引用进行交互
4. 在导航或 DOM 发生显著变化后，重新执行快照

命令列表

导航

agent-browser open       ## 导航至指定 URL
agent-browser back            ## 后退
agent-browser forward         ## 前进
agent-browser reload          ## 重新加载页面
agent-browser close           ## 关闭浏览器

快照（页面分析）

agent-browser snapshot            ## 输出完整可访问性树（accessibility tree）
agent-browser snapshot -i         ## 仅输出可交互元素（推荐使用）
agent-browser snapshot -c         ## 精简输出格式
agent-browser snapshot -d 3       ## 限制树深度为 3
agent-browser snapshot -s "#main" ## 限定作用域为 CSS 选择器匹配的元素

交互操作（使用快照中生成的 @ref）

agent-browser click @e1           ## 点击
agent-browser dblclick @e1        ## 双击
agent-browser focus @e1           ## 聚焦元素
agent-browser fill @e2 "text"     ## 清空后输入文本
agent-browser type @e2 "text"     ## 直接输入（不清空原有内容）
agent-browser press Enter         ## 按下按键
agent-browser press Control+a     ## 按下组合键
agent-browser keydown Shift       ## 按住按键不放
agent-browser keyup Shift         ## 释放按键
agent-browser hover @e1           ## 鼠标悬停
agent-browser check @e1           ## 勾选复选框
agent-browser uncheck @e1         ## 取消勾选复选框
agent-browser select @e1 "value"  ## 从下拉框中选择值
agent-browser scroll down 500     ## 页面向下滚动 500 像素
agent-browser scrollintoview @e1  ## 将元素滚动至可视区域
agent-browser drag @e1 @e2        ## 拖拽并放置（drag and drop）
agent-browser upload @e1 file.pdf ## 上传文件

获取信息

agent-browser get text @e1        ## 获取元素文本内容
agent-browser get html @e1        ## 获取 innerHTML
agent-browser get value @e1       ## 获取 input 元素当前值
agent-browser get attr @e1 href   ## 获取指定属性（如 href）
agent-browser get title           ## 获取页面标题
agent-browser get url             ## 获取当前 URL
agent-browser get count ".item"   ## 统计匹配 CSS 选择器的元素数量
agent-browser get box @e1         ## 获取元素边界框（bounding box）

检查状态

agent-browser is visible @e1      ## 检查元素是否可见
agent-browser is enabled @e1      ## 检查元素是否启用
agent-browser is checked @e1      ## 检查复选框/单选框是否已选中

截图与 PDF 导出

agent-browser screenshot          ## 截图并输出至标准输出（stdout）
agent-browser screenshot path.png ## 保存截图至指定文件
agent-browser screenshot --full   ## 截取整页（full page）
agent-browser pdf output.pdf      ## 保存当前页面为 PDF 文件

视频录制

agent-browser record start ./demo.webm    ## 开始录制（自动使用当前 URL 和页面状态）
agent-browser click @e1                   ## 执行操作
agent-browser record stop                 ## 停止录制并保存视频
agent-browser record restart ./take2.webm ## 停止当前录制并立即开始新录制

录制会创建一个全新上下文，但保留您当前会话中的 cookies 和 storage。若未指定 URL，录制将自动返回到当前页面。建议先探索页面流程，再开始录制以获得更流畅的演示效果。

等待（Wait）

agent-browser wait @e1                     ## 等待元素出现
agent-browser wait 2000                    ## 等待指定毫秒数
agent-browser wait --text "Success"        ## 等待指定文本出现
agent-browser wait --url "/dashboard"      ## 等待 URL 匹配指定路径
agent-browser wait --load networkidle      ## 等待网络请求空闲（network idle）
agent-browser wait --fn "window.ready"     ## 等待 JavaScript 条件满足（如全局变量 ready）

鼠标控制

agent-browser mouse move 100 200      ## 移动鼠标至指定坐标（x, y）
agent-browser mouse down left         ## 按下鼠标左键
agent-browser mouse up left           ## 释放鼠标左键
agent-browser mouse wheel 100         ## 向上滚动鼠标滚轮 100 单位

语义定位器（Semantic Locators，替代 ref 的方式）

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

浏览器设置

agent-browser set viewport 1920 1080      ## 设置视口尺寸
agent-browser set device "iPhone 14"      ## 模拟设备类型
agent-browser set geo 37.7749 -122.4194   ## 设置地理位置（经纬度）
agent-browser set offline on              ## 启用离线模式
agent-browser set headers '{"X-Key":"v"}' ## 添加自定义 HTTP 请求头
agent-browser set credentials user pass   ## 设置 HTTP Basic Auth 凭据
agent-browser set media dark              ## 模拟深色主题（color scheme）

Cookies 与 Storage

agent-browser cookies                     ## 获取全部 cookies
agent-browser cookies set name value      ## 设置 cookie
agent-browser cookies clear               ## 清空所有 cookies
agent-browser storage local               ## 获取全部 localStorage 数据
agent-browser storage local key           ## 获取指定 localStorage key 的值
agent-browser storage local set k v       ## 设置 localStorage 中的键值对
agent-browser storage local clear         ## 清空全部 localStorage 数据

网络请求控制

agent-browser network route               ## 拦截匹配该 URL 的请求
agent-browser network route  --abort      ## 阻止（abort）匹配该 URL 的请求
agent-browser network route  --body '{}'  ## 返回模拟响应体（mock response）
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 2               ## 切换至第 2 个标签页
agent-browser tab close           ## 关闭当前标签页
agent-browser window new          ## 新建浏览器窗口

iframe 切换

agent-browser frame "#iframe"     ## 切入指定 iframe（通过 CSS 选择器）
agent-browser frame main          ## 切回主文档（main frame）

对话框处理

agent-browser dialog accept [text]  ## 接受（确认）对话框（可选填入文本）
agent-browser dialog dismiss        ## 取消（关闭）对话框

JavaScript 执行

agent-browser eval "document.title"   ## 执行 JavaScript 表达式并输出结果

状态管理（Session State）

agent-browser state save auth.json    ## 保存当前会话状态（含 cookies、storage 等）至文件
agent-browser state load auth.json    ## 从文件加载并恢复会话状态

示例：表单提交

agent-browser open https://example.com/form
agent-browser snapshot -i
## 输出示例：文本框 "Email" [ref=e1]，文本框 "Password" [ref=e2]，按钮 "Submit" [ref=e3]

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  ## 检查提交结果

示例：使用保存的状态完成认证

## 首次登录并保存状态
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "username"
agent-browser fill @e2 "password"
agent-browser click @e3
agent-browser wait --url "/dashboard"
agent-browser state save auth.json

## 后续会话：直接加载已保存状态
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard

会话（多浏览器并行运行）

agent-browser --session test1 open site-a.com
agent-browser --session test2 open site-b.com
agent-browser session list

JSON 输出（供程序解析）

添加 --json 参数以获取机器可读的 JSON 格式输出：

agent-browser snapshot -i --json
agent-browser get text @e1 --json

调试

agent-browser open example.com --headed              ## 显示浏览器窗口（GUI 模式）
agent-browser console                                ## 查看浏览器控制台日志
agent-browser console --clear                        ## 清空控制台日志
agent-browser errors                                 ## 查看页面 JavaScript 错误
agent-browser errors --clear                         ## 清空错误日志
agent-browser highlight @e1                          ## 高亮指定元素（便于定位）
agent-browser trace start                            ## 开始录制性能追踪（trace）
agent-browser trace stop trace.zip                   ## 停止追踪并保存为 ZIP 文件
agent-browser record start ./debug.webm              ## 从当前页面开始录制视频
agent-browser record stop                            ## 停止录制并保存
agent-browser --cdp 9222 snapshot                    ## 通过 Chrome DevTools Protocol（CDP）端口连接并执行快照

故障排查（Troubleshooting）

• 若在 Linux ARM64 系统上提示命令未找到，请使用 bin 目录下的完整路径。
• 若找不到目标元素，请先执行 snapshot 命令确认其引用（ref）是否正确。
• 若页面尚未加载完成，应在 open 或其他导航命令后添加 wait 命令。
• 使用 --headed 参数启动浏览器以可视化调试过程。

全局选项（Options）

• --session ：使用隔离的独立会话（session）。
• --json：启用 JSON 格式输出。
• --full：截取整页（full-page）截图。
• --headed：显示图形化浏览器窗口。
• --timeout：设置单条命令超时时间（单位：毫秒）。
• --cdp ：通过指定端口连接 Chrome DevTools Protocol。

注意事项（Notes）

• 引用（refs）在单次页面加载内保持稳定，但在页面导航后会失效并重新生成。
• 每次导航或 DOM 发生重大变更后，务必重新执行 snapshot 以获取最新 refs。
• 对于输入框（input field），请优先使用 fill 而非 type，以确保已有内容被清空。

提交问题（Reporting Issues）

• 功能使用类问题（Skill issues）：请前往 https://github.com/TheSethRose/Agent-Browser-CLI 提交 issue
• agent-browser CLI 工具本身的问题：请前往 https://github.com/vercel-labs/agent-browser 提交 issue