Agent Browser

Agent Browser Skill

Headless browser automation using Playwright Python. Provides accessibility tree snapshots with @e# element references for deterministic interaction, screenshot capture, form filling, and multi-command execution sequences.

Quick Start

Scrape page content (prints to stdout, saves to output/):

python skills/agent-browser/scripts/browse.py \
  --operation scrape \
  --url "https://example.com"

With a custom output directory:

python skills/agent-browser/scripts/browse.py \
  --output-dir output \
  --operation screenshot \
  --url "https://example.com" \
  --full-page

Supported Operations

Parameters

Output Location

Results are always printed to stdout as JSON. For scrape, snapshot, execute, and screenshot operations, output files are also saved to ./output/ by default, or to the directory given by --output-dir.

Snapshot and Element References

The snapshot command returns an accessibility tree with @e# element references:

python skills/agent-browser/scripts/browse.py \
  --operation snapshot --url "https://httpbin.org/forms/post" --interactive

Output (in the snapshot field of the JSON response):

    [@e1] [textbox] Customer name:
    [@e2] [textbox] Telephone:
    [@e3] [textbox] E-mail address:
      [@e4] [radio] Small
      [@e5] [radio] Medium
      [@e6] [radio] Large
      [@e7] [checkbox] Bacon
      [@e8] [checkbox] Extra Cheese
    [@e11] [textbox] Preferred delivery time:
    [@e12] [textbox] Delivery instructions:
    [@e13] [button] Submit order

Use these refs in the execute operation for deterministic element interaction.

Important: @e# refs only persist within a single execute session. Each separate scrape/snapshot call launches a new browser, so refs from one call cannot be used in another. For multi-step workflows, always use the execute operation.

Standard Workflow Pattern

Most browser automation follows this pattern using the execute operation:

1. Open URL          → open <url>
2. Get snapshot      → snapshot -i
3. Interact          → click/fill/type @e#
4. Wait (if needed)  → wait --load
5. Capture result    → screenshot

Example: Form Submission via Execute

python skills/agent-browser/scripts/browse.py \
  --operation execute \
  --commands '[
    {"cmd": "open", "args": ["https://example.com/login"]},
    {"cmd": "wait", "args": ["--load"]},
    {"cmd": "snapshot", "args": ["-i"]},
    {"cmd": "fill", "args": ["@e1", "myuser"]},
    {"cmd": "fill", "args": ["@e2", "mypassword"]},
    {"cmd": "click", "args": ["@e3"]},
    {"cmd": "wait", "args": ["--load"]},
    {"cmd": "screenshot", "args": ["result.png"]}
  ]'

Execute Command Reference

The execute operation runs a sequence of commands in a single browser session. Each command is {"cmd": "<name>", "args": [...]}.

Navigation

Element Interaction

Information Retrieval

Snapshots and Screenshots

Waiting

JavaScript

Selector Types

• @e# refs: From snapshot output (e.g., @e1, @e2) -- must run snapshot first within the same execute session
• CSS selectors: Standard CSS (e.g., #submit, .btn-primary)
• XPath: XPath expressions (e.g., //button[@type="submit"])

Authenticated Sessions

Use the --profile flag to load a persistent browser profile with saved cookies and login state. Profiles are managed with the browser-profile skill.

Setup (one-time):

python skills/browser-profile/scripts/manage.py \
  --operation create --name sistrix --url "https://www.sistrix.com/"

Usage in automation:

python skills/agent-browser/scripts/browse.py \
  --operation scrape \
  --url "https://app.sistrix.com/visibility-index/example.com" \
  --profile sistrix

Without --profile, the browser runs in ephemeral mode (no cookies, no session persistence).

Output Format

All operations return JSON to stdout. For scrape and snapshot operations, the accessibility tree is included in the snapshot field so agents can read it without opening saved files.

{
  "success": true,
  "operation": "scrape",
  "output_file": "output/browser_scrape_20250123T1430.json",
  "summary": "Scraped https://example.com - 3 elements found",
  "snapshot": "[@e1] [link] More information...\n...",
  "stats": {
    "url": "https://example.com",
    "element_count": 3,
    "interactive_count": 3
  }
}

For execute, per-step results are included in the results array.

Error Handling

Errors are returned as JSON to stdout (not stderr) so agents always see them:

{
  "success": false,
  "error": "Click failed: Timeout 30000ms exceeded",
  "operation": "click"
}

• Navigation failures: Returns error with details
• Timeout: Commands timeout after specified duration (default 30s)
• Element not found: Returns descriptive error with selector info
• Execute chain: Stops on first error (except for wait/close)

Prerequisites

Playwright Python with Chromium browser:

pip install playwright
playwright install chromium

Comparison with claude-chrome

Resources

scripts/

• browse.py - Main Python wrapper using Playwright