Agent Browser

When to use this skill

Use this skill whenever the user wants to:

• Automate browser interactions via CLI commands
• Use browser automation for AI agents
• Navigate websites and interact with pages using command-line tools
• Use refs-based element selection for deterministic automation
• Integrate browser automation into AI agent workflows
• Capture snapshots of web pages with accessibility trees
• Fill forms, click elements, and extract content via CLI
• Use semantic locators for more reliable element selection
• Work with browser automation in agent mode with JSON output
• Manage multiple browser sessions
• Debug browser automation with headed mode
• Use authenticated sessions with custom headers
• Connect to existing browsers via CDP
• Stream browser viewport for live preview

How to use this skill

This skill is organized to match the agent-browser official documentation structure (https://github.com/vercel-labs/agent-browser/blob/main/README.md). When working with agent-browser:

1. Install agent-browser:

• Load examples/getting-started/installation.md for installation instructions

2. Quick Start:

• Load examples/quick-start/quick-start.md for basic workflow examples

3. Learn core commands:

• Load examples/commands/basic-commands.md for basic commands (open, click, fill, etc.)
• Load examples/commands/advanced-commands.md for advanced commands (snapshot, eval, etc.)
• Load examples/commands/get-info/ for information retrieval commands
• Load examples/commands/check-state/ for state checking commands
• Load examples/commands/find-elements/ for semantic locator commands
• Load examples/commands/wait/ for wait commands
• Load examples/commands/mouse-control/ for mouse control commands
• Load examples/commands/browser-settings/ for browser configuration
• Load examples/commands/cookies-storage/ for cookies and storage management
• Load examples/commands/network/ for network interception
• Load examples/commands/tabs-windows/ for tab and window management
• Load examples/commands/frames/ for iframe handling
• Load examples/commands/dialogs/ for dialog handling
• Load examples/commands/debug/ for debugging commands
• Load examples/commands/navigation/ for navigation commands
• Load examples/commands/setup/ for setup commands

4. Understand selectors:

• Load examples/selectors/refs.md for refs-based selection (@e1, @e2, etc.)
• Load examples/selectors/traditional-selectors.md for CSS, XPath, and semantic locators

5. Use agent mode:

• Load examples/agent-mode/introduction.md for agent mode overview
• Load examples/agent-mode/optimal-workflow.md for optimal AI workflow
• Load examples/agent-mode/integration.md for integrating with AI agents

6. Advanced features:

• Load examples/advanced/sessions.md for session management
• Load examples/advanced/headed-mode.md for debugging with visible browser
• Load examples/advanced/authenticated-sessions.md for authentication via headers
• Load examples/advanced/custom-executable.md for custom browser executable
• Load examples/advanced/cdp-mode.md for Chrome DevTools Protocol integration
• Load examples/advanced/streaming.md for browser viewport streaming
• Load examples/advanced/architecture.md for architecture overview
• Load examples/advanced/platforms.md for platform support
• Load examples/advanced/usage-with-agents.md for AI agent integration patterns

7. Configure options:

• Load examples/options/global-options.md for global CLI options
• Load examples/options/snapshot-options.md for snapshot-specific options
• Load examples/options/session-options.md for session management options

8. Reference API documentation when needed:

• api/commands.md - Complete command reference
• api/selectors.md - Selector reference
• api/options.md - Options reference

9. Use templates for quick start:

• templates/basic-automation.md - Basic automation workflow
• templates/ai-agent-workflow.md - AI agent workflow template

Doc mapping (one-to-one with official documentation)

• See examples and API files → https://github.com/vercel-labs/agent-browser

Examples and Templates

This skill includes detailed examples organized to match the official documentation structure. All examples are in the examples/ directory (see mapping above).

To use examples:

• Identify the topic from the user's request
• Load the appropriate example file from the mapping above
• Follow the instructions, syntax, and best practices in that file
• Adapt the code examples to your specific use case

To use templates:

• Reference templates in templates/ directory for common scaffolding
• Adapt templates to your specific needs and coding style

API Reference

• Commands API: api/commands.md - Complete command reference with syntax and examples
• Selectors API: api/selectors.md - Selector types and usage reference
• Options API: api/options.md - All options reference

Best Practices

1. Use Refs: Prefer refs (@e1, @e2) over traditional selectors for deterministic automation 2. Snapshot First: Always snapshot before interacting with elements to get refs 3. Agent Mode: Use --json flag for machine-readable output in agent mode 4. Session Management: Use --session to maintain state across commands 5. Interactive Snapshot: Use -i flag for interactive snapshot selection 6. Semantic Locators: Use semantic locators (role/name) when refs are not available 7. Error Handling: Check command exit codes and error messages 8. Wait for Navigation: Commands automatically wait for navigation to complete 9. Headed Mode: Use --headed for debugging, headless for production 10. CDP Integration: Use --cdp for Chrome DevTools Protocol integration 11. Streaming: Use AGENT_BROWSER_STREAM_PORT for live browser preview 12. Authenticated Sessions: Use --headers for authentication without login flows 13. Custom Executable: Use --executable-path for serverless deployments or custom browsers 14. Snapshot Options: Combine -i, -c, -d, -s options to optimize snapshot output

Resources

• GitHub Repository: https://github.com/vercel-labs/agent-browser
• Official README: https://github.com/vercel-labs/agent-browser/blob/main/README.md
• Agent Mode Documentation: https://agent-browser.dev/agent-mode
• Issues: https://github.com/vercel-labs/agent-browser/issues

Keywords

agent-browser, CLI browser automation, AI agents, browser automation CLI, refs, snapshot, agent mode, semantic locators, browser automation tool, command-line browser, AI agent browser, deterministic selectors, accessibility tree, browser commands, web automation CLI, sessions, headed mode, authenticated sessions, CDP mode, streaming, Chrome DevTools Protocol, Playwright, browser automation for AI

国内适配

• 支持中文文档和中文注释
• 示例代码兼容国内开发环境
• 提供中文 FAQ 和常见问题解答

能力边界

✅ 适用场景

• 当你需要使用此技能对应的技术栈时
• 当项目需要遵循最佳实践时
• 当需要快速上手或深入理解核心概念时

⚠️ 需要注意

• 复杂业务逻辑需要结合具体场景调整
• 性能优化需要根据实际数据量评估

❌ 不适用场景

• 不相关的技术栈或框架
• 需要完全自定义的特殊场景

使用流程

Step 1: 环境准备

确保开发环境已安装必要的依赖和工具。

Step 2: 配置初始化

根据项目需求进行基础配置。

Step 3: 核心功能使用

按照示例代码实现核心功能。

Step 4: 测试验证

运行测试确保功能正常。

Step 5: 部署上线

完成开发后进行部署和监控。

Commands API | 命令 API

API Reference

Complete command reference for agent-browser CLI.

Navigation Commands

open, goto, navigate

Navigate to a URL.

Syntax:

agent-browser open <url> [options]

Options:

• --session <name>: Use named session
• --headers <json>: Custom HTTP headers
• --headed: Run in headed mode
• --json: JSON output

Example:

agent-browser open https://example.com --session my-session --json

Interaction Commands

click

Click an element.

Syntax:

agent-browser click <selector> [options]

Options:

• --session <name>: Use named session
• --button <button>: Mouse button (left, right, middle)
• --json: JSON output

Example:

agent-browser click @e1 --session my-session --json

dblclick

Double-click an element.

Syntax:

agent-browser dblclick <selector> [options]

Example:

agent-browser dblclick @e1

Input Commands

type

Type text into an element.

Syntax:

agent-browser type <selector> <text> [options]

Example:

agent-browser type @e1 "Hello World"

fill

Fill an input field.

Syntax:

agent-browser fill <selector> <text> [options]

Example:

agent-browser fill @e1 "user@example.com"

press

Press a key.

Syntax:

agent-browser press <selector> <key> [options]

Example:

agent-browser press @e1 Enter

keydown, keyup

Key down/up events.

Syntax:

agent-browser keydown <selector> <key> [options]
agent-browser keyup <selector> <key> [options]

Form Commands

focus

Focus an element.

Syntax:

agent-browser focus <selector> [options]

select

Select an option.

Syntax:

agent-browser select <selector> <value> [options]

check, uncheck

Check/uncheck a checkbox.

Syntax:

agent-browser check <selector> [options]
agent-browser uncheck <selector> [options]

Mouse Commands

hover

Hover over an element.

Syntax:

agent-browser hover <selector> [options]

scroll

Scroll element or page.

Syntax:

agent-browser scroll <selector> [options]
agent-browser scroll --to <selector> [options]

Information Commands

get text

Get text content.

Syntax:

agent-browser get text <selector> [options]

get attribute

Get attribute value.

Syntax:

agent-browser get attribute <selector> <name> [options]

get property

Get property value.

Syntax:

agent-browser get property <selector> <name> [options]

Advanced Commands

snapshot

Get accessibility tree with refs.

Syntax:

agent-browser snapshot [options]

Options:

• -i, --interactive: Interactive mode
• -c, --compact: Compact format
• -d, --depth <n>: Depth limit
• -s, --selector <sel>: Filter by selector
• --full, -f: Full snapshot
• -n, --name <name>: Filter by name
• --exact, -e: Exact name match
• --json: JSON output

Example:

agent-browser snapshot -i --json --session my-session

eval

Evaluate JavaScript.

Syntax:

agent-browser eval <expression> [options]

Example:

agent-browser eval "document.title"

screenshot

Take screenshot.

Syntax:

agent-browser screenshot <path> [options]

Options:

• --full: Full page screenshot

pdf

Generate PDF.

Syntax:

agent-browser pdf <path> [options]

Options:

• --format <format>: Paper format
• --print-background: Print background

close

Close page or browser.

Syntax:

agent-browser close [options]

Options:

• --all: Close all pages

Common Options

All commands support:

• --session <name>: Use named session
• --json: JSON output
• --headed: Headed mode
• --debug: Debug output

Key Points

• All commands support --session for state management
• Use --json for machine-readable output
• Commands automatically wait for navigation
• Use refs (@e1, @e2) for reliable selection
• Commands return appropriate exit codes

Options API | 选项 API

API Reference

Complete options reference for agent-browser.

Global Options

--session, -s

Use named session for state management.

Example:

agent-browser open https://example.com --session my-session

Environment Variable: AGENT_BROWSER_SESSION

--headers

Custom HTTP headers (JSON format).

Example:

agent-browser open https://example.com --headers '{"User-Agent": "MyBot"}'

Environment Variable: AGENT_BROWSER_HEADERS

--executable-path

Custom browser executable path.

Example:

agent-browser open https://example.com --executable-path /path/to/chromium

Environment Variable: AGENT_BROWSER_EXECUTABLE_PATH

--headed

Run in headed mode (visible browser).

Example:

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

--cdp

Connect via Chrome DevTools Protocol.

Example:

agent-browser open https://example.com --cdp 9222

--json

JSON output format.

Example:

agent-browser snapshot --json

--debug

Enable debug output.

Example:

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

Snapshot Options

-i, --interactive

Interactive snapshot mode.

Example:

agent-browser snapshot -i

-c, --compact

Compact snapshot format.

Example:

agent-browser snapshot -c

-d, --depth

Limit snapshot depth.

Example:

agent-browser snapshot -d 2

-s, --selector

Filter by selector.

Example:

agent-browser snapshot -s "main"

--full, -f

Full snapshot with all details.

Example:

agent-browser snapshot --full

-n, --name

Filter by accessible name.

Example:

agent-browser snapshot -n "Submit"

--exact, -e

Exact name match.

Example:

agent-browser snapshot -n "Submit" --exact

Command-Specific Options

--button

Mouse button for click (left, right, middle).

Example:

agent-browser click @e1 --button right

--to

Scroll to element.

Example:

agent-browser scroll --to @e1

--all

Close all pages.

Example:

agent-browser close --all

--format

PDF paper format.

Example:

agent-browser pdf output.pdf --format A4

--print-background

Print background in PDF.

Example:

agent-browser pdf output.pdf --print-background

Environment Variables

• AGENT_BROWSER_SESSION: Default session name
• AGENT_BROWSER_HEADERS: Default headers (JSON)
• AGENT_BROWSER_EXECUTABLE_PATH: Default executable path

Key Points

• Global options apply to all commands
• Snapshot options are specific to snapshot command
• Environment variables can set defaults
• Options can be combined
• Use --json for agent mode
• Use --session for state management

Selectors API | 选择器 API

API Reference

Complete selector reference for agent-browser.

Refs

Deterministic element identifiers from snapshot.

Format: @e1, @e2, @e3, etc.

Example:

agent-browser click @e1
agent-browser fill @e2 "text"

Advantages:

• Deterministic
• Fast
• AI-friendly
• Stable across page changes

CSS Selectors

Standard CSS selector syntax.

Examples:

agent-browser click button
agent-browser click .submit-button
agent-browser click #login-btn
agent-browser click input[name="email"]
agent-browser click form .submit

XPath Selectors

XPath expression syntax (must be quoted).

Examples:

agent-browser click "//button"
agent-browser click "//button[@type='submit']"
agent-browser click "//button[text()='Submit']"
agent-browser click "//form[@id='login']//button"

Semantic Locators

Accessibility-focused selectors.

Format: role=<role>, role=<role> name=<name>

Examples:

agent-browser click role=button
agent-browser click role=button name="Submit"
agent-browser click role=textbox name="Email"
agent-browser click role=link name="Login"
agent-browser get text role=heading name="Welcome" level=1

ID and Class Selectors

Simple ID and class selectors.

Examples:

agent-browser click #my-button
agent-browser click .my-class
agent-browser click .btn.primary
agent-browser click button.primary

Selector Priority

1. Refs (preferred): Most reliable, deterministic 2. Semantic Locators: Accessibility-focused, stable 3. CSS Selectors: Simple, but can break 4. XPath: Powerful, but complex

When to Use Each

• Refs: Always prefer for AI agents and deterministic automation
• Semantic Locators: When structure might change, accessibility-focused
• CSS Selectors: Simple, stable HTML structure
• XPath: Complex relationships, text-based selection

Key Points

• Refs are the most reliable selector type
• Get refs from snapshot command
• Semantic locators are more maintainable
• CSS selectors are simple but fragile
• XPath is powerful but complex
• Always prefer refs when available

Architecture | 架构

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example explains the architecture of agent-browser.

Key Concepts

• Client-daemon architecture
• Rust CLI (fast native binary)
• Node.js daemon
• Fallback mechanism
• Browser engine (Chromium, Firefox, WebKit)

Architecture Overview

agent-browser uses a client-daemon architecture:

1. Rust CLI (fast native binary)

• Parses commands
• Communicates with daemon
• Fast startup and execution

2. Node.js Daemon

• Manages Playwright browser instance
• Handles browser automation
• Persists between commands for fast subsequent operations

3. Fallback

• If native binary unavailable, uses Node.js directly
• Ensures compatibility across platforms

Daemon Lifecycle

# First command starts daemon automatically
agent-browser open example.com  # Daemon starts here

# Subsequent commands reuse daemon (fast)
agent-browser snapshot           # Reuses existing daemon
agent-browser click @e1         # Reuses existing daemon

# Daemon persists until explicitly closed
agent-browser close              # Daemon stops

Browser Engine

• Default: Chromium (bundled with Playwright)
• Also supports: Firefox and WebKit via Playwright protocol
• Custom: Can use custom executable via --executable-path

Performance Benefits

• Fast startup: Native Rust binary parses commands quickly
• Persistent daemon: Browser instance reused between commands
• Efficient communication: Client-daemon model reduces overhead
• Fallback support: Node.js fallback ensures compatibility

Key Points

• Client-daemon architecture for performance
• Rust CLI for fast command parsing
• Node.js daemon manages browser instance
• Daemon persists between commands (fast)
• Fallback to Node.js if native binary unavailable
• Supports Chromium (default), Firefox, and WebKit

Authenticated Sessions | 认证会话

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates how to use custom HTTP headers for authentication, skipping login flows.

Key Concepts

• Authentication via HTTP headers
• Origin-scoped headers (security)
• Skipping login flows
• Multiple origins with different auth tokens
• Global headers vs origin-scoped headers

Example: Basic Authentication

# Set headers for specific origin (scoped to api.example.com only)
agent-browser open api.example.com --headers '{"Authorization": "Bearer <token>"}'

# All requests to api.example.com include the auth header
agent-browser snapshot -i --json
agent-browser click @e2

# Navigate to another domain - headers are NOT sent (safe!)
agent-browser open other-site.com  # No auth header sent

Example: Multiple Origins

# Set headers for first origin
agent-browser open api.example.com --headers '{"Authorization": "Bearer token1"}'
agent-browser snapshot -i

# Set headers for second origin
agent-browser open api.acme.com --headers '{"Authorization": "Bearer token2"}'
agent-browser snapshot -i

Example: Global Headers

# Set global headers (all domains)
agent-browser set headers '{"X-Custom-Header": "value"}'

# All subsequent requests include the header
agent-browser open example.com
agent-browser open other-site.com  # Header included here too

Example: Use Cases

# 1. Skip login flows - Authenticate via headers instead of UI
agent-browser open dashboard.example.com --headers '{"Authorization": "Bearer <token>"}'
agent-browser snapshot -i

# 2. Switch users - Start new sessions with different auth tokens
agent-browser --session user1 open api.example.com --headers '{"Authorization": "Bearer token1"}'
agent-browser --session user2 open api.example.com --headers '{"Authorization": "Bearer token2"}'

# 3. API testing - Access protected endpoints directly
agent-browser open api.example.com/protected --headers '{"Authorization": "Bearer <token>"}'
agent-browser get text @e1

Key Points

• Use --headers flag to set HTTP headers for specific origin
• Headers are scoped to the origin (security feature)
• Use set headers for global headers (all domains)
• Useful for skipping login flows and API testing
• Headers are not leaked to other domains (safe)

CDP Mode | Chrome DevTools Protocol 模式

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates how to connect to an existing browser via Chrome DevTools Protocol (CDP).

Key Concepts

• Connecting to existing browsers via CDP
• Controlling Electron apps
• Remote debugging
• WebView2 applications
• CDP endpoint connection

Example: Connect Once

# Start Chrome with remote debugging
# google-chrome --remote-debugging-port=9222

# Connect once
agent-browser connect 9222

# Run commands without --cdp flag
agent-browser snapshot
agent-browser tab
agent-browser click @e1
agent-browser close

Example: Pass CDP on Each Command

# Start Chrome with remote debugging
# google-chrome --remote-debugging-port=9222

# Pass --cdp on each command
agent-browser --cdp 9222 snapshot
agent-browser --cdp 9222 tab
agent-browser --cdp 9222 click @e1

Example: Electron App

# Start Electron app with remote debugging
# electron --remote-debugging-port=9222

# Connect and control
agent-browser connect 9222
agent-browser snapshot -i
agent-browser click @e1

Example: WebView2 Application

# Start WebView2 app with remote debugging enabled
# (depends on application configuration)

# Connect via CDP
agent-browser connect 9222
agent-browser snapshot
agent-browser click @e1

Example: Chrome/Chromium Instance

# Start Chrome with remote debugging
# google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Connect and automate
agent-browser connect 9222
agent-browser open example.com
agent-browser snapshot -i
agent-browser click @e2

Key Points

• Use connect <port> to connect once, or --cdp <port> on each command
• Enables control of Electron apps, Chrome instances, WebView2 apps
• Any browser exposing a CDP endpoint can be controlled
• Useful for debugging and testing existing browser instances
• After connect, subsequent commands don't need --cdp flag

Custom Browser Executable | 自定义浏览器可执行文件

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates how to use a custom browser executable instead of the bundled Chromium.

Key Concepts

• Custom browser executable path
• Serverless deployment (lightweight builds)
• System browsers
• Custom builds
• Environment variable vs CLI flag

Example: Via CLI Flag

# Use custom browser executable
agent-browser --executable-path /path/to/chromium open example.com
agent-browser --executable-path /path/to/chromium snapshot

Example: Via Environment Variable

# Set custom executable path
export AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium

# All commands use the custom executable
agent-browser open example.com
agent-browser snapshot

Example: Serverless Deployment (Vercel/AWS Lambda)

import chromium from '@sparticuz/chromium';
import { BrowserManager } from 'agent-browser';

export async function handler() {
  const browser = new BrowserManager();
  await browser.launch({
    executablePath: await chromium.executablePath(),
    headless: true,
  });
  // ... use browser
}

Example: Using System Chrome

# macOS
agent-browser --executable-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" open example.com

# Linux
agent-browser --executable-path /usr/bin/google-chrome open example.com

# Windows
agent-browser --executable-path "C:\Program Files\Google\Chrome\Application\chrome.exe" open example.com

Example: Lightweight Builds

# Use lightweight Chromium build for serverless
export AGENT_BROWSER_EXECUTABLE_PATH=/path/to/lightweight-chromium
agent-browser open example.com

Key Points

• Use --executable-path flag or AGENT_BROWSER_EXECUTABLE_PATH environment variable
• Useful for serverless deployments (lightweight builds like @sparticuz/chromium)
• Can use system browsers or custom builds
• Default bundled Chromium is ~684MB, lightweight builds are ~50MB
• Useful for environments with size constraints

Headed Mode | 有界面模式

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates how to run agent-browser in headed mode (visible browser window) for debugging.

Key Concepts

• Running browser in visible mode
• Debugging browser automation
• Visual verification of actions
• Headless vs headed mode

Example: Basic Headed Mode

# Open browser in visible mode
agent-browser open example.com --headed

# All subsequent commands will use the visible browser
agent-browser snapshot
agent-browser click @e1
agent-browser fill @e2 "test"

Example: Debugging Workflow

# Start with visible browser for debugging
agent-browser open example.com --headed

# Take snapshot to see what's available
agent-browser snapshot -i

# Interact and watch the browser
agent-browser click @e2
agent-browser fill @e3 "test@example.com"

# Take screenshot to verify
agent-browser screenshot debug.png

# Close when done
agent-browser close

Example: Switching Between Headed and Headless

# Debug with visible browser
agent-browser open example.com --headed
agent-browser snapshot -i
agent-browser click @e1

# Switch to headless for production
agent-browser close
agent-browser open example.com  # Headless by default
agent-browser click @e1

Key Points

• Use --headed flag to show browser window
• Useful for debugging and visual verification
• Headless mode is default (faster, no UI)
• Headed mode is slower but allows visual inspection
• Use headed mode during development, headless for production

Platforms | 平台支持

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example lists the supported platforms for agent-browser.

Key Concepts

• Platform support matrix
• Native Rust binary availability
• Node.js fallback
• Platform-specific considerations

Platform Support

Installation by Platform

macOS:

npm install -g agent-browser
agent-browser install

Linux:

npm install -g agent-browser
agent-browser install --with-deps  # Install system dependencies

Windows:

npm install -g agent-browser
agent-browser install

Platform-Specific Notes

macOS:

• Native Rust binary available for ARM64 and x64
• Falls back to Node.js if binary unavailable
• No additional system dependencies required

Linux:

• Native Rust binary available for ARM64 and x64
• Requires system dependencies (install with --with-deps)
• Falls back to Node.js if binary unavailable

Windows:

• Native Rust binary available for x64
• Falls back to Node.js if binary unavailable
• No additional system dependencies required

Key Points

• Native Rust binary available for all major platforms
• Node.js fallback ensures compatibility
• Linux requires system dependencies
• All platforms support headless and headed modes
• Cross-platform compatibility maintained

Sessions | 会话管理

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates how to manage multiple isolated browser sessions with agent-browser.

Key Concepts

• Multiple isolated browser instances
• Session management via --session flag or environment variable
• Listing and managing active sessions
• Session isolation (cookies, storage, history, auth state)

Example: Using Named Sessions

# Start session 1
agent-browser --session agent1 open site-a.com
agent-browser --session agent1 click "#button"

# Start session 2 (isolated from session 1)
agent-browser --session agent2 open site-b.com
agent-browser --session agent2 fill "#input" "value"

# Each session has its own:
# - Browser instance
# - Cookies and storage
# - Navigation history
# - Authentication state

Example: Using Environment Variable

# Set session via environment variable
export AGENT_BROWSER_SESSION=agent1
agent-browser open example.com
agent-browser click "#btn"

# Switch to different session
export AGENT_BROWSER_SESSION=agent2
agent-browser open other-site.com

Example: Listing Active Sessions

# List all active sessions
agent-browser session list

# Output:
# Active sessions:
# -> default
#    agent1
#    agent2

Example: Show Current Session

# Show current session name
agent-browser session

# Output:
# Current session: agent1

Example: Session Isolation

# Session 1: Login to site A
agent-browser --session user1 open site-a.com
agent-browser --session user1 fill "#email" "user1@example.com"
agent-browser --session user1 fill "#password" "pass1"
agent-browser --session user1 click "#login"

# Session 2: Login to site A with different user (isolated)
agent-browser --session user2 open site-a.com
agent-browser --session user2 fill "#email" "user2@example.com"
agent-browser --session user2 fill "#password" "pass2"
agent-browser --session user2 click "#login"

# Each session maintains its own authentication state

Key Points

• Use --session <name> to create isolated browser sessions
• Each session has its own browser instance, cookies, storage, and history
• Use AGENT_BROWSER_SESSION environment variable for convenience
• List active sessions with agent-browser session list
• Sessions persist until browser is closed

Streaming | 流式传输

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates how to stream the browser viewport via WebSocket for live preview or "pair browsing".

Key Concepts

• Streaming browser viewport via WebSocket
• Live preview
• Pair browsing (human + AI agent)
• WebSocket protocol
• Programmatic API

Example: Enable Streaming

# Set stream port environment variable
export AGENT_BROWSER_STREAM_PORT=9223

# Start browser with streaming
agent-browser open example.com

# WebSocket server starts on port 9223
# Connect to ws://localhost:9223 to receive frames

Example: WebSocket Protocol

Receive frames:

{
  "type": "frame",
  "data": "<base64-encoded-jpeg>",
  "metadata": {
    "deviceWidth": 1280,
    "deviceHeight": 720,
    "pageScaleFactor": 1,
    "offsetTop": 0,
    "scrollOffsetX": 0,
    "scrollOffsetY": 0
  }
}

Send mouse events:

{
  "type": "input_mouse",
  "eventType": "mousePressed",
  "x": 100,
  "y": 200,
  "button": "left",
  "clickCount": 1
}

Send keyboard events:

{
  "type": "input_keyboard",
  "eventType": "keyDown",
  "key": "Enter",
  "code": "Enter"
}

Send touch events:

{
  "type": "input_touch",
  "eventType": "touchStart",
  "touchPoints": [{ "x": 100, "y": 200 }]
}

Example: Programmatic API

import { BrowserManager } from 'agent-browser';

const browser = new BrowserManager();
await browser.launch({ headless: true });
await browser.navigate('https://example.com');

// Start screencast
await browser.startScreencast((frame) => {
  // frame.data is base64-encoded image
  // frame.metadata contains viewport info
  console.log('Frame received:', frame.metadata.deviceWidth, 'x', frame.metadata.deviceHeight);
}, {
  format: 'jpeg',
  quality: 80,
  maxWidth: 1280,
  maxHeight: 720,
});

// Inject mouse events
await browser.injectMouseEvent({
  type: 'mousePressed',
  x: 100,
  y: 200,
  button: 'left',
});

// Inject keyboard events
await browser.injectKeyboardEvent({
  type: 'keyDown',
  key: 'Enter',
  code: 'Enter',
});

// Stop when done
await browser.stopScreencast();

Example: Pair Browsing Workflow

# 1. Start streaming
export AGENT_BROWSER_STREAM_PORT=9223
agent-browser open example.com

# 2. Human connects to ws://localhost:9223
# 3. Human can watch AI agent actions in real-time
# 4. Human can also interact (send mouse/keyboard events)
# 5. AI agent continues automation while human watches

Key Points

• Set AGENT_BROWSER_STREAM_PORT environment variable to enable streaming
• WebSocket server starts on specified port
• Receive frames (base64-encoded JPEG) and metadata
• Send input events (mouse, keyboard, touch)
• Useful for live preview and pair browsing scenarios
• Programmatic API available for advanced use cases

Usage with AI Agents | 与 AI 智能体一起使用

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates how to integrate agent-browser with AI agents.

Key Concepts

• Integration with AI agents
• Just ask the agent approach
• AGENTS.md / CLAUDE.md instructions
• Claude Code skill
• Optimal workflow patterns

Example: Just Ask the Agent

The simplest approach - just tell your agent to use it:

Use agent-browser to test the login flow. Run agent-browser --help to see available commands.

The --help output is comprehensive and most agents can figure it out from there.

Example: AGENTS.md / CLAUDE.md

For more consistent results, add to your project or global instructions file:

## Browser Automation

Use `agent-browser` for web automation. Run `agent-browser --help` for all commands.

Core workflow:
1. `agent-browser open <url>` - Navigate to page
2. `agent-browser snapshot -i` - Get interactive elements with refs (@e1, @e2)
3. `agent-browser click @e1` / `fill @e2 "text"` - Interact using refs
4. Re-snapshot after page changes

Example: Claude Code Skill

For Claude Code, a skill provides richer context:

Option 1: Copy from node_modules

cp -r node_modules/agent-browser/skills/agent-browser .claude/skills/

Option 2: Download directly

mkdir -p .claude/skills/agent-browser
curl -o .claude/skills/agent-browser/SKILL.md \
  https://raw.githubusercontent.com/vercel-labs/agent-browser/main/skills/agent-browser/SKILL.md

Example: Optimal AI Workflow

# 1. Navigate and get snapshot
agent-browser open example.com
agent-browser snapshot -i --json   # AI parses tree and refs

# 2. AI identifies target refs from snapshot
# 3. Execute actions using refs
agent-browser click @e2
agent-browser fill @e3 "input text"

# 4. Get new snapshot if page changed
agent-browser snapshot -i --json

Example: Integration Patterns

Pattern 1: Simple Automation

# Agent executes commands sequentially
agent-browser open example.com
agent-browser snapshot -i
agent-browser click @e1
agent-browser fill @e2 "value"
agent-browser click @e3

Pattern 2: With Error Handling

# Agent checks for errors
agent-browser open example.com || echo "Failed to open"
agent-browser snapshot -i || echo "Failed to snapshot"
agent-browser click @e1 || echo "Failed to click"

Pattern 3: With JSON Output

# Agent parses JSON responses
agent-browser snapshot -i --json | jq '.data.refs'
agent-browser get text @e1 --json | jq '.data'

Key Points

• Just ask the agent - simplest approach
• Add instructions to AGENTS.md / CLAUDE.md for consistency
• Use Claude Code skill for richer context
• Follow optimal workflow: snapshot → identify refs → interact → re-snapshot
• Use --json flag for machine-readable output
• Combine with error handling for robust automation

Agent Integration | 代理集成

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates how to integrate agent-browser with AI agents.

Key Concepts

• Integrating with Claude
• Integrating with Cursor
• Integrating with Copilot
• Integrating with OpenAI
• Integrating with Gemini
• Adding to agent skills

Example: Claude Integration

# Add to Claude's skills/AGENTS.md or similar
# agent-browser: Browser automation CLI for AI agents
# - Use snapshot --json to get page state
# - Use refs (@e1, @e2) for element selection
# - Use --session to maintain state

Example: Cursor Integration

# Configure Cursor to use agent-browser
# Add agent-browser commands to Cursor's tool set
# Use JSON output for structured responses

Example: Basic Integration Pattern

// Example: Node.js integration
const { exec } = require('child_process');
const util = require('util');
const execPromise = util.promisify(exec);

async function agentBrowserCommand(command) {
  try {
    const { stdout, stderr } = await execPromise(
      `agent-browser ${command} --json`
    );
    return JSON.parse(stdout);
  } catch (error) {
    return { error: error.message };
  }
}

// Usage
const snapshot = await agentBrowserCommand('snapshot --session my-task');
const refs = snapshot.refs;
await agentBrowserCommand(`click ${refs['@e1'].ref} --session my-task`);

Example: Python Integration

import subprocess
import json

def agent_browser_command(command):
    try:
        result = subprocess.run(
            f"agent-browser {command} --json",
            shell=True,
            capture_output=True,
            text=True
        )
        return json.loads(result.stdout)
    except Exception as e:
        return {"error": str(e)}

# Usage
snapshot = agent_browser_command("snapshot --session my-task")
refs = snapshot.get("refs", {})
agent_browser_command(f"click {refs['@e1']['ref']} --session my-task")

Example: Agent Skill Definition

## agent-browser

Browser automation CLI tool for AI agents.

### Commands:
- `agent-browser open <url>` - Navigate to URL
- `agent-browser snapshot --json` - Get page snapshot with refs
- `agent-browser click <ref>` - Click element by ref
- `agent-browser fill <ref> <text>` - Fill input by ref

### Workflow:
1. Open page: `agent-browser open <url> --session <name> --json`
2. Snapshot: `agent-browser snapshot --json --session <name>`
3. Interact: Use refs from snapshot
4. Verify: Snapshot again after changes

Example: Agent Workflow Integration

# Agent receives task: "Login to example.com"

# Step 1: Agent executes
agent-browser open https://example.com/login --session task1 --json

# Step 2: Agent gets snapshot
agent-browser snapshot --json --session task1

# Step 3: Agent parses JSON, identifies:
# - @e1 = email input
# - @e2 = password input  
# - @e3 = login button

# Step 4: Agent fills form
agent-browser fill @e1 "user@example.com" --session task1 --json
agent-browser fill @e2 "password" --session task1 --json

# Step 5: Agent submits
agent-browser click @e3 --session task1 --json

# Step 6: Agent verifies
agent-browser snapshot --json --session task1

Key Points

• Integrate via command-line interface
• Use --json for structured output
• Parse JSON responses in your agent code
• Use sessions for state management
• Follow standard workflow pattern
• Handle errors appropriately
• Document agent-browser in agent skills
• Use refs for reliable element selection

Agent Mode Introduction | 代理模式介绍

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates agent mode in agent-browser for AI agent integration.

Key Concepts

• What is agent mode
• JSON output format
• Machine-readable commands
• AI agent integration
• Agent mode benefits

Example: Basic Agent Mode

# Enable JSON output for machine-readable format
agent-browser snapshot --json

# Output example:
# {
#   "type": "snapshot",
#   "refs": {
#     "@e1": {
#       "role": "button",
#       "name": "Submit",
#       "selector": "button.submit"
#     }
#   }
# }

Example: JSON Output for Commands

# Get text with JSON output
agent-browser get text @e1 --json

# Output:
# {
#   "type": "text",
#   "value": "Submit",
#   "ref": "@e1"
# }

# Get attribute with JSON
agent-browser get attribute @e1 href --json

# Output:
# {
#   "type": "attribute",
#   "name": "href",
#   "value": "/login",
#   "ref": "@e1"
# }

Example: Snapshot in Agent Mode

# Snapshot with JSON for AI parsing
agent-browser snapshot --json

# Compact JSON output
agent-browser snapshot -c --json

# Interactive snapshot with JSON
agent-browser snapshot -i --json

Example: Complete Agent Mode Workflow

# 1. Open page
agent-browser open https://example.com --json

# 2. Get snapshot
agent-browser snapshot --json

# 3. Parse refs from JSON output
# AI agent identifies: @e1 = login button, @e2 = email input

# 4. Interact using refs
agent-browser fill @e2 "user@example.com" --json
agent-browser click @e1 --json

# 5. Verify result
agent-browser snapshot --json

Example: Agent Mode with Session

# Start session
agent-browser open https://example.com --session agent-session --json

# Continue in same session
agent-browser snapshot --session agent-session --json
agent-browser click @e1 --session agent-session --json
agent-browser fill @e2 "text" --session agent-session --json

Example: Error Handling in Agent Mode

# Commands return JSON errors
agent-browser click @e999 --json

# Output:
# {
#   "error": "Element not found",
#   "ref": "@e999",
#   "command": "click"
# }

Key Points

• Agent mode uses --json flag for machine-readable output
• JSON output is essential for AI agent integration
• Snapshot with JSON provides structured refs
• All commands support --json flag
• Use sessions to maintain state across commands
• Error messages are also in JSON format
• Agent mode enables deterministic automation

Optimal AI Workflow | 最优 AI 工作流

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates the optimal workflow for AI agents using agent-browser.

Key Concepts

• Standard workflow steps
• Snapshot-first approach
• Ref-based interaction
• State management
• Error recovery

Example: Standard Workflow

# Step 1: Open the page
agent-browser open https://example.com --session my-task --json

# Step 2: Get snapshot with refs
agent-browser snapshot -i --json --session my-task

# Step 3: AI agent parses snapshot JSON
# Identifies available elements and their refs:
# @e1 = login button
# @e2 = email input
# @e3 = password input

# Step 4: Interact using refs
agent-browser fill @e2 "user@example.com" --session my-task --json
agent-browser fill @e3 "password123" --session my-task --json
agent-browser click @e1 --session my-task --json

# Step 5: Verify page changed (snapshot again)
agent-browser snapshot --json --session my-task

# Step 6: Continue with new refs from updated snapshot
agent-browser click @e4 --session my-task --json

Example: Snapshot-First Pattern

# Always snapshot before interaction
agent-browser snapshot --json > current-state.json

# AI agent analyzes snapshot
# Decides next action based on available refs

# Execute action
agent-browser click @e1 --json

# Snapshot again to verify
agent-browser snapshot --json > new-state.json

Example: Ref-Based Interaction

# Get refs
agent-browser snapshot --json

# Use refs (deterministic)
agent-browser click @e1 --json
agent-browser fill @e2 "text" --json
agent-browser click @e3 --json

# Refs are stable and reliable

Example: State Management with Sessions

# Create session
agent-browser open https://example.com --session task1 --json

# All subsequent commands use same session
agent-browser snapshot --session task1 --json
agent-browser click @e1 --session task1 --json
agent-browser fill @e2 "text" --session task1 --json

# Session maintains browser state

Example: Error Recovery

# Try action
agent-browser click @e1 --json

# If error, snapshot again
agent-browser snapshot --json

# Get updated refs
# Retry with new refs
agent-browser click @e2 --json

Example: Complete Task Workflow

# 1. Initialize
agent-browser open https://example.com/login --session login-task --json

# 2. Analyze page
agent-browser snapshot --json --session login-task > page1.json

# 3. Fill form
agent-browser fill @e2 "user@example.com" --session login-task --json
agent-browser fill @e3 "password" --session login-task --json

# 4. Submit
agent-browser click @e1 --session login-task --json

# 5. Verify success
agent-browser snapshot --json --session login-task > page2.json

# 6. Continue if needed
agent-browser click @e4 --session login-task --json

Key Points

• Always start with open command
• Always snapshot before interacting
• Use refs from snapshot for interaction
• Use --session to maintain state
• Snapshot again after page changes
• Use --json for machine-readable output
• Handle errors by re-snapshotting
• Follow: open → snapshot → interact → snapshot pattern

Advanced Commands | 高级命令

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates how to use advanced agent-browser commands.

Key Concepts

• Snapshot command
• Eval command
• Screenshot and PDF
• Close command
• Command options

Example: Snapshot

# Basic snapshot (accessibility tree with refs)
agent-browser snapshot

# Interactive snapshot
agent-browser snapshot -i

# Compact snapshot
agent-browser snapshot -c

# Snapshot with depth limit
agent-browser snapshot -d 2

# Snapshot specific element
agent-browser snapshot -s "main"

# Full snapshot
agent-browser snapshot --full

# Snapshot with JSON output
agent-browser snapshot --json

Example: Eval

# Evaluate JavaScript
agent-browser eval "document.title"

# Evaluate with return value
agent-browser eval "document.querySelector('h1').textContent"

# Evaluate complex expression
agent-browser eval "Array.from(document.querySelectorAll('a')).map(a => a.href)"

Example: Screenshot and PDF

# Take screenshot
agent-browser screenshot output.png

# Screenshot full page
agent-browser screenshot output.png --full

# Generate PDF
agent-browser pdf output.pdf

# PDF with options
agent-browser pdf output.pdf --format A4 --print-background

Example: Close

# Close current page
agent-browser close

# Close all pages
agent-browser close --all

Example: Snapshot Workflow

# 1. Open page
agent-browser open https://example.com

# 2. Get snapshot with refs
agent-browser snapshot -i --json

# 3. Use refs from snapshot
agent-browser click @e1
agent-browser fill @e2 "text"

# 4. Snapshot again after interaction
agent-browser snapshot --json

Example: Eval Workflow

# Open page
agent-browser open https://example.com

# Extract data using eval
agent-browser eval "document.querySelectorAll('article').length"

# Get all links
agent-browser eval "Array.from(document.querySelectorAll('a')).map(a => ({text: a.textContent, href: a.href}))"

# Check if element exists
agent-browser eval "!!document.querySelector('.modal')"

Key Points

• Use snapshot to get accessibility tree with refs
• Use -i for interactive snapshot selection
• Use --json for machine-readable output
• Use eval for custom JavaScript execution
• Use screenshot and pdf for capturing pages
• Always snapshot before interacting with elements
• Use refs from snapshot for reliable element selection

Basic Commands | 基础命令

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates how to use basic agent-browser commands.

Key Concepts

• Navigation commands
• Interaction commands
• Input commands
• Form commands
• Mouse commands

Example: Navigation

# Open a URL (aliases: goto, navigate)
agent-browser open https://example.com

# Open with session
agent-browser open https://example.com --session my-session

Example: Clicking Elements

# Click an element using ref
agent-browser click @e1

# Click using CSS selector
agent-browser click button.submit

# Click using XPath
agent-browser click "//button[@type='submit']"

# Double-click
agent-browser dblclick @e2

# Right-click
agent-browser click @e3 --button right

Example: Typing and Filling

# Type text into an element
agent-browser type @e1 "Hello World"

# Fill an input field
agent-browser fill @e2 "username@example.com"

# Press a key
agent-browser press @e1 Enter

# Key down
agent-browser keydown @e1 Control

# Key up
agent-browser keyup @e1 Control

Example: Form Interactions

# Focus an element
agent-browser focus @e1

# Select an option
agent-browser select @e1 "Option 1"

# Check a checkbox
agent-browser check @e1

# Uncheck a checkbox
agent-browser uncheck @e1

Example: Mouse Actions

# Hover over an element
agent-browser hover @e1

# Scroll
agent-browser scroll @e1

# Scroll to element
agent-browser scroll @e1 --to

Example: Getting Element Information

# Get text content
agent-browser get text @e1

# Get attribute
agent-browser get attribute @e1 href

# Get property
agent-browser get property @e1 value

Example: Command Chaining

# Open page, then click
agent-browser open https://example.com && agent-browser click @e1

# Using session for state
agent-browser open https://example.com --session test
agent-browser click @e1 --session test
agent-browser fill @e2 "text" --session test

Key Points

• Use open to navigate to URLs
• Use refs (@e1, @e2) for deterministic selection
• Commands automatically wait for navigation
• Use --session to maintain state
• Commands support CSS selectors, XPath, and semantic locators
• All commands return appropriate exit codes

Installation | 安装

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates how to install agent-browser CLI tool.

Key Concepts

• npm global installation
• Installing browser binaries
• Building from source
• System dependencies
• Custom executable path

Example: npm Installation (Recommended)

# Install agent-browser globally
npm install -g agent-browser

# Install browser binaries
agent-browser install

Example: Building from Source

# Clone the repository
git clone https://github.com/vercel-labs/agent-browser.git
cd agent-browser

# Install dependencies
pnpm install

# Build the project
pnpm build

# For native builds
pnpm build:native

# Link globally (optional)
pnpm link --global

Example: Linux System Dependencies

# Install with system dependencies (recommended)
agent-browser install --with-deps

# Or manually install Playwright dependencies
# Ubuntu/Debian
sudo apt-get install -y \
  libnss3 \
  libnspr4 \
  libatk1.0-0 \
  libatk-bridge2.0-0 \
  libcups2 \
  libdrm2 \
  libdbus-1-3 \
  libxkbcommon0 \
  libxcomposite1 \
  libxdamage1 \
  libxfixes3 \
  libxrandr2 \
  libgbm1 \
  libasound2

# Fedora
sudo dnf install -y \
  nss \
  nspr \
  atk \
  at-spi2-atk \
  cups-libs \
  libdrm \
  dbus \
  libxkbcommon \
  libXcomposite \
  libXdamage \
  libXfixes \
  libXrandr \
  mesa-libgbm \
  alsa-lib

Example: Custom Executable Path

# Set custom browser executable path
export AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium

# Or use --executable-path flag
agent-browser open example.com --executable-path /path/to/chromium

Example: Verify Installation

# Check version
agent-browser --version

# Test basic command
agent-browser open example.com

Key Points

• Install globally with npm install -g agent-browser
• Run agent-browser install to download browser binaries
• Install system dependencies on Linux
• Use custom executable path if needed
• Verify installation with --version flag

Global Options | 全局选项

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates global options available in agent-browser.

Key Concepts

• Session management
• Headers configuration
• Headed/headless mode
• Executable path
• CDP integration
• Debug mode
• JSON output

Example: Session Management

# Create named session
agent-browser open https://example.com --session my-session

# Use session in subsequent commands
agent-browser click @e1 --session my-session
agent-browser fill @e2 "text" --session my-session

# Session maintains browser state

Example: Headers Configuration

# Set custom headers
agent-browser open https://example.com --headers '{"User-Agent": "MyBot/1.0"}'

# Or use environment variable
export AGENT_BROWSER_HEADERS='{"User-Agent": "MyBot/1.0"}'
agent-browser open https://example.com

Example: Headed Mode

# Run in headed mode (visible browser)
agent-browser open https://example.com --headed

# Useful for debugging
agent-browser snapshot --headed
agent-browser click @e1 --headed

Example: Executable Path

# Use custom browser executable
agent-browser open https://example.com --executable-path /path/to/chromium

# Or use environment variable
export AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium
agent-browser open https://example.com

Example: CDP Integration

# Connect to existing Chrome via CDP
agent-browser open https://example.com --cdp 9222

# Use with Chrome running with remote debugging
# chrome --remote-debugging-port=9222

Example: Debug Mode

# Enable debug output
agent-browser open https://example.com --debug

# Debug shows detailed information
agent-browser snapshot --debug

Example: JSON Output

# Get JSON output for all commands
agent-browser open https://example.com --json
agent-browser snapshot --json
agent-browser click @e1 --json
agent-browser get text @e1 --json

Example: Combining Options

# Use multiple options together
agent-browser open https://example.com \
  --session my-task \
  --headed \
  --headers '{"User-Agent": "MyBot"}' \
  --json

# All subsequent commands can use session
agent-browser snapshot --session my-task --json
agent-browser click @e1 --session my-task --json

Example: Environment Variables

# Set session via environment
export AGENT_BROWSER_SESSION=my-session
agent-browser open https://example.com
agent-browser click @e1  # Uses my-session automatically

# Set executable path
export AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium

# Set headers
export AGENT_BROWSER_HEADERS='{"User-Agent": "MyBot"}'

Key Points

• Use --session to maintain state across commands
• Use --headers for custom HTTP headers
• Use --headed for visible browser (debugging)
• Use --executable-path for custom browser
• Use --cdp for Chrome DevTools Protocol
• Use --debug for detailed output
• Use --json for machine-readable output
• Options can be set via environment variables

Session Options | 会话选项

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates session management options in agent-browser.

Key Concepts

• Creating sessions
• Using sessions
• Session state
• Session persistence
• Environment variables

Example: Creating Sessions

# Create session on open
agent-browser open https://example.com --session my-session

# Session is created and maintained

Example: Using Sessions

# All commands can use the session
agent-browser open https://example.com --session task1
agent-browser snapshot --session task1
agent-browser click @e1 --session task1
agent-browser fill @e2 "text" --session task1
agent-browser click @e3 --session task1

Example: Session State

# Session maintains browser state
agent-browser open https://example.com --session login
agent-browser fill @e1 "user@example.com" --session login
agent-browser fill @e2 "password" --session login
agent-browser click @e3 --session login

# Now logged in, continue in same session
agent-browser snapshot --session login
agent-browser click @e4 --session login

Example: Multiple Sessions

# Create multiple independent sessions
agent-browser open https://site1.com --session session1
agent-browser open https://site2.com --session session2

# Work with each independently
agent-browser snapshot --session session1
agent-browser snapshot --session session2

Example: Environment Variable

# Set session via environment variable
export AGENT_BROWSER_SESSION=my-session

# Commands automatically use session
agent-browser open https://example.com
agent-browser snapshot
agent-browser click @e1

Example: Session with JSON

# Session with JSON output
agent-browser open https://example.com --session task1 --json
agent-browser snapshot --session task1 --json
agent-browser click @e1 --session task1 --json

Example: Session Workflow

# Complete workflow with session
agent-browser open https://example.com/login --session login-task --json

# Step 1: Analyze page
agent-browser snapshot --session login-task --json

# Step 2: Fill form
agent-browser fill @e1 "user@example.com" --session login-task --json
agent-browser fill @e2 "password" --session login-task --json

# Step 3: Submit
agent-browser click @e3 --session login-task --json

# Step 4: Verify
agent-browser snapshot --session login-task --json

# Step 5: Continue
agent-browser click @e4 --session login-task --json

Key Points

• Use --session <name> to create/maintain sessions
• Sessions preserve browser state
• All commands can use --session
• Multiple sessions can run independently
• Set session via environment variable
• Sessions work with JSON output
• Sessions maintain cookies and state
• Use sessions for multi-step workflows

Snapshot Options | 快照选项

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates snapshot-specific options in agent-browser.

Key Concepts

• Interactive snapshot
• Compact format
• Depth limit
• Selector filter
• Full snapshot
• Name option
• Exact match

Example: Interactive Snapshot

# Interactive mode for selecting elements
agent-browser snapshot -i

# Or long form
agent-browser snapshot --interactive

# Allows interactive element selection

Example: Compact Format

# Compact snapshot output
agent-browser snapshot -c

# Or long form
agent-browser snapshot --compact

# More concise output format

Example: Depth Limit

# Limit snapshot depth
agent-browser snapshot -d 2

# Or long form
agent-browser snapshot --depth 2

# Limits how deep the tree goes

Example: Selector Filter

# Snapshot specific element and its children
agent-browser snapshot -s "main"

# Or long form
agent-browser snapshot --selector "main"

# Only snapshots matching selector

Example: Full Snapshot

# Full snapshot (all details)
agent-browser snapshot --full

# Or short form
agent-browser snapshot -f

# Includes all element details

Example: Name Option

# Snapshot with name filter
agent-browser snapshot -n "Submit"

# Or long form
agent-browser snapshot --name "Submit"

# Filters by accessible name

Example: Exact Match

# Exact name match
agent-browser snapshot --name "Submit" --exact

# Or short form
agent-browser snapshot -n "Submit" -e

# Requires exact name match

Example: Combining Snapshot Options

# Interactive, compact, with depth limit
agent-browser snapshot -i -c -d 2

# Full snapshot of specific selector
agent-browser snapshot --full -s "form"

# JSON output with compact format
agent-browser snapshot -c --json

# Interactive snapshot with JSON
agent-browser snapshot -i --json

Example: Snapshot Workflow

# 1. Get full snapshot
agent-browser snapshot --full --json

# 2. Get compact snapshot for overview
agent-browser snapshot -c --json

# 3. Get snapshot of specific area
agent-browser snapshot -s "main" --json

# 4. Interactive snapshot to find element
agent-browser snapshot -i --json

Key Points

• Use -i for interactive element selection
• Use -c for compact, concise output
• Use -d to limit tree depth
• Use -s to snapshot specific element
• Use --full for complete details
• Use -n to filter by name
• Use --exact for exact name matching
• Combine options as needed
• Always use --json in agent mode

Quick Start | 快速开始

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates the quick start workflow with agent-browser.

Key Concepts

• Basic workflow
• Using refs
• Traditional selectors
• Common commands

Example: Basic Workflow

# 1. Open a page
agent-browser open example.com

# 2. Get snapshot with refs
agent-browser snapshot
# Output:
# - heading "Example Domain" [ref=e1] [level=1]
# - button "Submit" [ref=e2]
# - textbox "Email" [ref=e3]
# - link "Learn more" [ref=e4]

# 3. Click by ref from snapshot
agent-browser click @e2

# 4. Fill by ref
agent-browser fill @e3 "test@example.com"

# 5. Get text by ref
agent-browser get text @e1

# 6. Take screenshot
agent-browser screenshot page.png

# 7. Close browser
agent-browser close

Example: Traditional Selectors

# Using CSS selectors
agent-browser click "#submit"
agent-browser fill "#email" "test@example.com"

# Using semantic locators
agent-browser find role button click --name "Submit"

Example: Complete Workflow

# Navigate
agent-browser open example.com

# Get snapshot
agent-browser snapshot

# Interact using refs
agent-browser click @e2
agent-browser fill @e3 "test@example.com"
agent-browser get text @e1

# Capture
agent-browser screenshot page.png

# Close
agent-browser close

Key Points

• Start with open to navigate
• Use snapshot to get refs
• Use refs (@e1, @e2) for interaction
• Use traditional selectors as fallback
• Always close when done

Refs | 引用

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates how to use refs for element selection in agent-browser.

Key Concepts

• What are refs
• Getting refs from snapshot
• Using refs in commands
• Refs advantages
• Refs workflow

Example: Getting Refs from Snapshot

# Get snapshot with refs
agent-browser snapshot

# Output example:
# @e1 button "Submit"
# @e2 input[name="email"]
# @e3 a[href="/login"]

Example: Using Refs in Commands

# Click using ref
agent-browser click @e1

# Fill using ref
agent-browser fill @e2 "user@example.com"

# Get text using ref
agent-browser get text @e3

# Multiple refs
agent-browser click @e1
agent-browser fill @e2 "text"
agent-browser click @e3

Example: Interactive Snapshot for Refs

# Interactive snapshot to select element and get ref
agent-browser snapshot -i

# This allows you to interactively select elements and see their refs

Example: Refs with JSON Output

# Get snapshot as JSON with refs
agent-browser snapshot --json

# Output example:
# {
#   "refs": {
#     "@e1": {
#       "role": "button",
#       "name": "Submit",
#       "selector": "button.submit"
#     },
#     "@e2": {
#       "role": "textbox",
#       "name": "Email",
#       "selector": "input[name='email']"
#     }
#   }
# }

Example: Complete Refs Workflow

# 1. Open page
agent-browser open https://example.com

# 2. Get snapshot with refs
agent-browser snapshot --json > snapshot.json

# 3. Parse refs from JSON (in your script)
# @e1 = submit button
# @e2 = email input
# @e3 = password input

# 4. Use refs for interaction
agent-browser fill @e2 "user@example.com" --session login
agent-browser fill @e3 "password123" --session login
agent-browser click @e1 --session login

Example: Refs Advantages

# Refs are deterministic - same element always gets same ref
agent-browser snapshot
# @e1 button "Login"

# Even if page structure changes, ref points to same element
agent-browser click @e1  # Always clicks the Login button

# Traditional selector might break:
agent-browser click "button.login"  # Might not work if class changes

Key Points

• Refs are deterministic identifiers (@e1, @e2, etc.)
• Get refs from snapshot command
• Refs are AI-friendly and stable
• Use --json flag for machine-readable refs
• Refs work better than CSS selectors for dynamic pages
• Always snapshot before using refs
• Refs persist within a session

Traditional Selectors | 传统选择器

官方文档: https://github.com/vercel-labs/agent-browser/blob/main/README.md

Instructions

This example demonstrates how to use traditional selectors (CSS, XPath, semantic locators) in agent-browser.

Key Concepts

• CSS selectors
• XPath selectors
• Semantic locators
• ID and class selectors
• When to use each type

Example: CSS Selectors

# Element selector
agent-browser click button

# Class selector
agent-browser click .submit-button

# ID selector
agent-browser click #login-btn

# Attribute selector
agent-browser click input[name="email"]

# Descendant selector
agent-browser click form .submit

# Pseudo-selector
agent-browser click button:first-child

Example: XPath Selectors

# Basic XPath
agent-browser click "//button"

# XPath with attribute
agent-browser click "//button[@type='submit']"

# XPath with text
agent-browser click "//button[text()='Submit']"

# XPath with contains
agent-browser click "//button[contains(@class, 'submit')]"

# Complex XPath
agent-browser click "//form[@id='login']//button[@type='submit']"

Example: Semantic Locators

# Role-based selector
agent-browser click role=button

# Role with name
agent-browser click role=button name="Submit"

# Role with accessible name
agent-browser click role=textbox name="Email"

# Link by accessible name
agent-browser click role=link name="Login"

# Heading by level and name
agent-browser get text role=heading name="Welcome" level=1

Example: ID and Class Selectors

# ID selector
agent-browser click #my-button

# Class selector
agent-browser click .my-class

# Multiple classes
agent-browser click .btn.primary

# Element with class
agent-browser click button.primary

Example: Combining Selectors

# CSS selector in command
agent-browser fill input[name="email"] "user@example.com"

# XPath in command
agent-browser click "//form//button[@type='submit']"

# Semantic locator in command
agent-browser click role=button name="Submit"

Example: When to Use Each Selector

# Use CSS selectors for:
# - Simple, stable selectors
# - Well-structured HTML
agent-browser click button.submit

# Use XPath for:
# - Complex element relationships
# - Text-based selection
agent-browser click "//button[text()='Submit']"

# Use semantic locators for:
# - Accessibility-focused selection
# - When structure might change
agent-browser click role=button name="Submit"

# Use refs for:
# - Deterministic selection (preferred)
# - AI agent workflows
agent-browser click @e1

Key Points

• CSS selectors: Simple and fast, but can break with structure changes
• XPath: Powerful but complex, good for text-based selection
• Semantic locators: Accessibility-focused, more stable
• Refs: Most reliable, preferred for AI agents
• Choose selector type based on stability needs
• Semantic locators are more maintainable than CSS
• Always prefer refs when available

AI Agent Workflow Template | AI 代理工作流模板

Template

Complete AI agent workflow using agent-browser with JSON output.

#!/bin/bash

SESSION="agent-task"

# Step 1: Open page
agent-browser open https://example.com/login --session $SESSION --json

# Step 2: Get snapshot with refs (JSON)
agent-browser snapshot --json --session $SESSION > snapshot1.json

# Step 3: AI agent parses snapshot1.json
# Identifies: @e1 = email input, @e2 = password input, @e3 = login button

# Step 4: Fill form
agent-browser fill @e1 "user@example.com" --session $SESSION --json
agent-browser fill @e2 "password123" --session $SESSION --json

# Step 5: Submit
agent-browser click @e3 --session $SESSION --json

# Step 6: Verify page changed
agent-browser snapshot --json --session $SESSION > snapshot2.json

# Step 7: AI agent analyzes snapshot2.json
# Identifies new refs: @e4 = dashboard link, @e5 = settings button

# Step 8: Continue interaction
agent-browser click @e4 --session $SESSION --json
agent-browser snapshot --json --session $SESSION > snapshot3.json

Python Integration Example

import subprocess
import json

def agent_browser(command):
    result = subprocess.run(
        f"agent-browser {command} --json",
        shell=True,
        capture_output=True,
        text=True
    )
    return json.loads(result.stdout)

# Workflow
session = "my-task"

# Open page
agent_browser(f"open https://example.com --session {session}")

# Get snapshot
snapshot = agent_browser(f"snapshot --json --session {session}")
refs = snapshot.get("refs", {})

# Interact
agent_browser(f"fill {refs['@e1']['ref']} user@example.com --session {session}")
agent_browser(f"fill {refs['@e2']['ref']} password --session {session}")
agent_browser(f"click {refs['@e3']['ref']} --session {session}")

# Verify
new_snapshot = agent_browser(f"snapshot --json --session {session}")

Usage

1. Install agent-browser: npm install -g agent-browser && agent-browser install 2. Use the template workflow 3. Parse JSON output in your agent code 4. Use refs for element interaction 5. Snapshot after each page change

Key Points

• Always use --json for machine-readable output
• Use --session to maintain state
• Snapshot before and after interactions
• Parse JSON to extract refs
• Use refs for reliable element selection
• Follow: open → snapshot → interact → snapshot pattern

Basic Automation Template | 基础自动化模板

Template

Basic browser automation workflow using agent-browser.

#!/bin/bash

# Step 1: Open the page
agent-browser open https://example.com --session my-task

# Step 2: Get snapshot with refs
agent-browser snapshot --session my-task

# Step 3: Interact with elements using refs
agent-browser click @e1 --session my-task
agent-browser fill @e2 "text" --session my-task
agent-browser click @e3 --session my-task

# Step 4: Verify changes
agent-browser snapshot --session my-task

# Step 5: Take screenshot
agent-browser screenshot output.png --session my-task

Usage

1. Install agent-browser: npm install -g agent-browser && agent-browser install 2. Copy the template script 3. Customize URLs and selectors 4. Run the script: bash script.sh

Customization

• Change the URL in open command
• Modify refs based on snapshot output
• Add more interaction commands
• Adjust session name
• Add error handling