Agent Browser

# Agent Browser Skill

使用带有 ref 的可访问性树快照实现快速浏览器自动化，以进行确定性元素选择。

## 为什么使用此工具而非内置浏览器工具

**使用 agent-browser 时：** - 自动化多步骤工作流 - 需要确定性元素选择 - 性能至关重要 - 处理复杂的单页应用 (SPA) - 需要会话隔离

**使用内置浏览器工具时：** - 需要用于分析的截图/PDF - 需要视觉检查 - 需要浏览器扩展集成

## 核心工作流

```bash # 1. Navigate and snapshot agent-browser open https://example.com agent-browser snapshot -i --json

# 2. Parse refs from JSON, then interact agent-browser click @e2 agent-browser fill @e3 "text"

# 3. Re-snapshot after page changes agent-browser snapshot -i --json ```

## 关键命令

### 导航 ```bash agent-browser open <url> agent-browser back | forward | reload | close ```

### 快照（始终使用 -i --json） ```bash agent-browser snapshot -i --json # Interactive elements, JSON output agent-browser snapshot -i -c -d 5 --json # + compact, depth limit agent-browser snapshot -s "#main" -i # Scope to selector ```

### 交互（基于 Ref） ```bash agent-browser click @e2 agent-browser fill @e3 "text" agent-browser type @e3 "text" agent-browser hover @e4 agent-browser check @e5 | uncheck @e5 agent-browser select @e6 "value" agent-browser press "Enter" agent-browser scroll down 500 agent-browser drag @e7 @e8 ```

### 获取信息 ```bash agent-browser get text @e1 --json agent-browser get html @e2 --json agent-browser get value @e3 --json agent-browser get attr @e4 "href" --json agent-browser get title --json agent-browser get url --json agent-browser get count ".item" --json ```

### 检查状态 ```bash agent-browser is visible @e2 --json agent-browser is enabled @e3 --json agent-browser is checked @e4 --json ```

### 等待 ```bash agent-browser wait @e2 # Wait for element agent-browser wait 1000 # Wait ms agent-browser wait --text "Welcome" # Wait for text agent-browser wait --url "**/dashboard" # Wait for URL agent-browser wait --load networkidle # Wait for network agent-browser wait --fn "window.ready === true" ```

### 会话（隔离的浏览器） ```bash agent-browser --session admin open site.com agent-browser --session user open site.com agent-browser session list # Or via env: AGENT_BROWSER_SESSION=admin agent-browser ... ```

### 状态持久化 ```bash agent-browser state save auth.json # Save cookies/storage agent-browser state load auth.json # Load (skip login) ```

### 截图和 PDF ```bash agent-browser screenshot page.png agent-browser screenshot --full page.png agent-browser pdf page.pdf ```

### 网络控制 ```bash agent-browser network route "**/ads/*" --abort # Block agent-browser network route "**/api/*" --body '{"x":1}' # Mock agent-browser network requests --filter api # View ```

### Cookie 和存储 ```bash agent-browser cookies # Get all agent-browser cookies set name value agent-browser storage local key # Get localStorage agent-browser storage local set key val ```

### 标签页和 Frames ```bash agent-browser tab new https://example.com agent-browser tab 2 # Switch to tab agent-browser frame @e5 # Switch to iframe agent-browser frame main # Back to main ```

## 快照输出格式

```json { "success": true, "data": { "snapshot": "...", "refs": { "e1": {"role": "heading", "name": "Example Domain"}, "e2": {"role": "button", "name": "Submit"}, "e3": {"role": "textbox", "name": "Email"} } } } ```

## 最佳实践

1. **始终使用 `-i` 标志** - 专注于可交互元素 2. **始终使用 `--json`** - 更易于解析 3. **等待稳定** - `agent-browser wait --load networkidle` 4. **保存认证状态** - 使用 `state save/load` 跳过登录流程 5. **使用会话** - 隔离不同的浏览器上下文 6. **使用 `--headed` 进行调试** - 查看正在发生的情况

## 示例：搜索和提取

```bash agent-browser open https://www.google.com agent-browser snapshot -i --json # AI identifies search box @e1 agent-browser fill @e1 "AI agents" agent-browser press Enter agent-browser wait --load networkidle agent-browser snapshot -i --json # AI identifies result refs agent-browser get text @e3 --json agent-browser get attr @e4 "href" --json ```

## 示例：多会话测试

```bash # Admin session agent-browser --session admin open app.com agent-browser --session admin state load admin-auth.json agent-browser --session admin snapshot -i --json

# User session (simultaneous) agent-browser --session user open app.com agent-browser --session user state load user-auth.json agent-browser --session user snapshot -i --json ```

## 安装

```bash npm install -g agent-browser agent-browser install # Download Chromium agent-browser install --with-deps # Linux: + system deps ```

## 致谢

技能由 Yossi Elkrief ([@MaTriXy](https://github.com/MaTriXy)) 创建

agent-browser CLI 由 [Vercel Labs](https://github.com/vercel-labs/agent-browser) 开发