AgentSkillsCN

agent-browser

当某项任务需要无头浏览器自动化（导航、点击、填写表单、提取文本、截屏）时，应避免使用基于 Playwright 的工具，而优先选择 agent-browser CLI。

SKILL.md
--- frontmatter
name: agent-browser
description: Use when a task needs headless browser automation (navigate, click, fill forms, extract text, take screenshots) and Playwright-based tooling should be avoided; prefer the agent-browser CLI.

agent-browser

Overview

Use agent-browser (CLI) for deterministic, scriptable headless browser automation via snapshots and stable element refs (@e1, @e2, ...).

Core Workflow

  1. •Open a page: agent-browser open <url>
  2. •Get a ref-based accessibility snapshot: agent-browser snapshot -i
  3. •Interact using refs (preferred) or selectors:
    • •Click: agent-browser click @e2
    • •Fill: agent-browser fill @e3 "text"
    • •Press: agent-browser press Enter
  4. •Extract info:
    • •Visible text: agent-browser get text @e1
    • •URL/title: agent-browser get url / agent-browser get title
  5. •Capture artifacts:
    • •Screenshot: agent-browser screenshot --full path/to.png
    • •Trace: agent-browser trace start / agent-browser trace stop path/to-trace.json.gz

Quick Reference

Common Flags

  • •Reuse a session across commands: --session <name> (or AGENT_BROWSER_SESSION=<name>)
  • •Machine-readable output: --json
  • •Debug output: --debug
  • •Run with a visible window (debugging): --headed

Playwright → agent-browser Mapping

IntentPlaywright conceptagent-browser command
Navigatepage.goto(url)agent-browser open <url>
Snapshota11y snapshot / locator discoveryagent-browser snapshot -i
Clicklocator.click()agent-browser click <sel> or agent-browser click @eN
Filllocator.fill()agent-browser fill <sel> <text> or agent-browser fill @eN <text>
Typelocator.type()agent-browser type <sel> <text>
Press keypage.keyboard.press()agent-browser press <key>
Wait for elementpage.waitForSelector()agent-browser wait <sel>
Read textlocator.innerText()agent-browser get text <sel>
Screenshotpage.screenshot()agent-browser screenshot [--full] [path]
Evaluate JSpage.evaluate()agent-browser eval <js>

Examples

Login/Form Flow (ref-first)

bash
export AGENT_BROWSER_SESSION="acme-login"
agent-browser open "https://example.com/login"
agent-browser snapshot -i
agent-browser fill @e12 "user@example.com"
agent-browser fill @e13 "correct horse battery staple"
agent-browser click @e14
agent-browser wait @e20
agent-browser get text @e20

Auth Headers (origin-scoped)

bash
agent-browser open "https://example.com"
agent-browser --headers '{"Authorization":"Bearer YOUR_TOKEN"}' open "https://example.com/protected"
agent-browser snapshot -i --json

Common Mistakes

  • •Not using --session when a multi-step flow spans multiple commands.
  • •Clicking with brittle CSS selectors when a snapshot -i ref is available.
  • •Forgetting --json when downstream steps require structured parsing.
  • •In sandboxed environments, the agent-browser daemon may fail to start due to restricted writes to user cache/home; rerun with the necessary filesystem permissions.
  • •If the browser can’t launch, run agent-browser install (may require network access).