Browser Agent

Browser Agent

Choose the smallest workflow that can produce the required evidence. The skill owns that judgment; agent and chromeDebug own deterministic execution.

Choose the execution path

Do not spawn a worker merely to wrap one deterministic browser operation.

Spawn

Give the browser worker a bounded packet with explicit scope, acceptance, and return requirements. The profile routes the task to relevant CDP domains, runs the configured initial analysis, and starts the worker.

agent({queries:[{
  reasoning: "The audit needs dependent security, storage, and network phases.",
  type: "spawn",
  profile: "browser",
  name: "browser-audit",
  task: "Goal: audit the login flow\nContext: inspect https://example.com\nScope: security headers, cookies, storage, and login traffic\nOwnership: browser inspection only; do not modify repository files\nAcceptance: report evidence for every requested surface\nReturn: emit [FINDING], [ACTION], and terminal [DONE], [BLOCKED], or [FAILED] lines",
  url: "https://example.com",
  port: 9222,
  launch: false,
  runNow: true
}]})
→ { agentId: "abc123…" }

Use launch:true only when the tool should start Chrome. runNow:true performs the routed initial analysis before the worker starts; use runNow:false when an existing authenticated or interactive state must be preserved for the worker.

Spawn first. Lifecycle operations that reference the returned agentId must be separate calls.

Multi-turn lifecycle

agent({queries:[{reasoning:"Collect the current browser-worker snapshot.", type:"wait", agentId:"abc123…"}]})
agent({queries:[{reasoning:"Queue the next audit phase.", type:"message", agentId:"abc123…", delivery:"followUp", message:"Now inspect /api/login and compare its cookie behavior."}]})
agent({queries:[{reasoning:"Inspect the complete retained result.", type:"inspect", agentId:"abc123…", full:true}]})
agent({queries:[{reasoning:"Release the completed browser worker.", type:"kill", agentId:"abc123…", remove:true}]})

Use inspect without agentId to list all workers. wait returns the current transcript snapshot; repeat it only when fresh output is expected. Use steer when the current direction must change before the worker's next model step. Use message with delivery:"followUp" to queue the next phase.

Output protocol

The browser worker prefixes evidence lines:

Relay findings and actions with their evidence. A terminal prefix is a worker claim, not proof: compare it with the acceptance criteria and inspect full output when the result matters.

If the worker emits [BLOCKED], resolve the missing input and send it through agent with type:"message". Always kill and remove the worker after collecting the final result.

Long-running work

For monitors or user-interaction flows, use short snapshot checks while other useful work continues:

agent({queries:[{reasoning:"Check browser-monitor progress.", type:"inspect", agentId:"abc123…"}]})

If a worker is stuck well beyond the expected duration, interrupt its current turn without destroying the process, inspect the result, then either redirect or remove it:

agent({queries:[{reasoning:"Interrupt the unresponsive browser turn.", type:"abort", agentId:"abc123…", full:true}]})
agent({queries:[{reasoning:"Inspect the interrupted browser worker.", type:"inspect", agentId:"abc123…", full:true}]})
agent({queries:[{reasoning:"Release the interrupted browser worker.", type:"kill", agentId:"abc123…", remove:true}]})

Parallel browser lanes

Parallelize only independent inspections. Use separate debugging ports and give each worker disjoint scope. Multiple spawn queries may share one call; collect and reconcile every result before finalizing.

agent({queries:[
  {reasoning:"Run the independent security lane.", type:"spawn", profile:"browser", name:"security-lane", task:"Goal: audit browser security\nContext: inspect https://example.com\nScope: headers, cookies, and storage\nOwnership: read-only browser inspection on port 9222\nAcceptance: evidence for each security surface\nReturn: findings and terminal status", url:"https://example.com", port:9222},
  {reasoning:"Run the independent performance lane.", type:"spawn", profile:"browser", name:"performance-lane", task:"Goal: audit browser performance\nContext: inspect https://example.com\nScope: web vitals, heap, layout, and script metrics\nOwnership: read-only browser inspection on port 9223\nAcceptance: measured evidence for each metric family\nReturn: metrics, actions, and terminal status", url:"https://example.com", port:9223}
]})

chromeDebug scheme guide

Inspect the live chromeDebug tool schema before constructing a low-level call. For protocol details, use references/CDP_QUICK_REF.md.

Recovery