Using the browser-operator Agent

When to Spawn

Spawn browser-operator whenever the task requires actual browser interaction — not just fetching HTML or calling an API. If you can get the data via curl or a direct API call, do that instead. Only use browser-operator when you need to operate the UI as a human would.

---

Prompt Template

GOAL: <one sentence — what to accomplish>
URL: <full starting URL, e.g. http://localhost:3001/dashboard>
AUTH: <"none" | /path/to/.auth/user.json | "cookies:name=val;name2=val2">
SUCCESS: <observable signal — e.g. "URL changes to /projects/<id>">
RETURN: <what data to extract — e.g. "project ID from URL" or "screenshot">
CONSTRAINTS: <optional: max_steps=10, session=myapp>

---

Common AUTH Patterns

No auth:

AUTH: none

Next-Auth / authjs (localhost dev):

AUTH: /Users/d/Developer/<project>/apps/viewer/src/test/.auth/user.json

Manual cookie string:

AUTH: cookies:authjs.session-token=abc123;authjs.csrf-token=xyz789

---

Task Examples

Login and verify

GOAL: Log in with test credentials and confirm dashboard loads
URL: http://localhost:3000/login
AUTH: none
SUCCESS: URL contains /dashboard after login
RETURN: Final URL
CONSTRAINTS: max_steps=8

Form fill + submit

GOAL: Click "New Project", fill name "Alpha Test", set type "Web", submit
URL: http://localhost:3000/projects
AUTH: /Users/d/Developer/myapp/.auth/user.json
SUCCESS: URL changes to /projects/<id>
RETURN: New project ID from URL
CONSTRAINTS: max_steps=12

Data extraction

GOAL: Extract all project names from the projects list
URL: http://localhost:3000/projects
AUTH: /Users/d/Developer/myapp/.auth/user.json
SUCCESS: List loaded (no spinner visible)
RETURN: JSON array of project names
CONSTRAINTS: max_steps=5

---

How to Spawn

Agent(
  subagent_type="browser-operator",
  description="Browser task: <one-line summary>",
  prompt="""
GOAL: <goal>
URL: <url>
AUTH: <auth>
SUCCESS: <success signal>
RETURN: <return spec>
CONSTRAINTS: <optional>
"""
)

---

Parsing RESULT

RESULT:
  success: true
  goal: "..."
  steps_taken: 7
  data: ["Item A", "Item B"]
  current_url: http://localhost:3000/projects
  screenshot: captured
  error: null
  notes: "List had 2 items"

Check success, read data, inspect notes for context.

---

Anti-Patterns

Wrong	Right
Vague GOAL: "do something on the site"	"Click the 'Export CSV' button"
Missing SUCCESS signal	Always specify what done looks like
Not specifying RETURN	Always say what data to bring back
Spawning for API calls	Only spawn for actual UI interaction
max_steps > 20	Break large flows into sub-tasks