Agent Browser

agent-browser — AI Agent 专属浏览器

核心优势

安装验证

agent-browser --version   # 应输出版本号（当前 0.15.2）

若未安装：

npm install -g agent-browser
agent-browser install      # 安装 Chromium

核心工作流

1. 打开页面 + 抓快照（核心循环）

agent-browser open <url>
agent-browser snapshot          # 输出带 @ref 的可交互元素树

快照格式示例：

- heading "Example Domain" [ref=e1] [level=1]
- link "Learn more" [ref=e2]

AI 直接用 @e1、@e2 引用元素，无需 CSS/XPath 选择器。

2. 常用操作命令

# 导航
agent-browser open <url>
agent-browser back / forward / reload

# 交互
agent-browser click @e3
agent-browser fill @e5 "搜索内容"
agent-browser press Enter
agent-browser hover @e7
agent-browser select @e4 "选项值"
agent-browser upload @e6 /path/to/file

# 信息获取
agent-browser get text @e2
agent-browser get title
agent-browser get url
agent-browser is visible @e1
agent-browser is enabled @e2

# 视觉工具
agent-browser screenshot /tmp/debug.png
agent-browser screenshot --annotate /tmp/annotated.png   # 带元素标注

# 等待
agent-browser wait @e1            # 等元素出现
agent-browser wait 2000           # 等 2 秒

# 执行 JS
agent-browser eval "document.title"

3. 语义查找（不用 @ref）

agent-browser find role button "提交"      # 按 ARIA role 找
agent-browser find text "登录"             # 按文本找
agent-browser find label "用户名"          # 按 label 找
agent-browser find placeholder "请输入"    # 按 placeholder 找

4. 状态管理

# 保存登录状态
agent-browser set session ~/.agent-sessions/github.json

# 后续会话复用
agent-browser open github.com --session ~/.agent-sessions/github.json

标准 Agent 任务模板

# Step 1: 打开目标页面
agent-browser open <url>

# Step 2: 抓快照，识别元素
agent-browser snapshot
# AI 分析快照，找到目标 @ref

# Step 3: 执行操作
agent-browser click @eN
agent-browser fill @eM "内容"
agent-browser press Enter

# Step 4: 等待并验证结果
agent-browser wait ".success-msg"
agent-browser get text ".result"

# Step 5: 截图留档（可选）
agent-browser screenshot /tmp/result.png

与 MCP Playwright 协作策略

用 agent-browser 的场景：

• token 预算紧张的长流程任务
• 需要控制 Electron 桌面 App（Discord、Figma、Notion 等）
• 简单的网页自动化脚本

继续用 MCP playwright 的场景：

• 已有 playwright MCP 连接且不想切换
• 需要精细的 Playwright API（network mock、tracing）
• 现有工作流已稳定

常见错误处理

进阶：连接现有浏览器

# 连接 CDP 调试端口（可复用已登录的 Chrome）
agent-browser connect 9222