agent-browser

Agent Browser

Use the agent-browser CLI to open pages, read interactive snapshots, click, fill forms, wait, extract content, take screenshots, and run end-to-end web flows. When a normal probe confirms a login or anti-bot block, use the included real-Chrome bridge to capture and reuse auth state. If a site is live-session-only, keep using the same live real-Chrome process instead of relying on saved state.

Requirements: agent-browser CLI must be installed locally (npm install -g agent-browser, then agent-browser install) and real Google Chrome / Chrome must be available. The helper script uses only the Python standard library. On macOS/Linux use python3; on Windows PowerShell prefer $env:ORKAS_PYTHON when present, otherwise python.

Critical routing rule: for URL automation, the first browser command should be a normal task-scoped probe, followed by a task-scoped get url --json or snapshot -i --json. Do not run bare agent-browser ... for task work in a multi-task environment; use the helper's task subcommand so concurrent conversations do not share the default browser session. Do not call auto as the first command just because the URL may need login. The auth helper is not a detector. It is the confirmed-auth fallback. Call it only after the normal probe shows a login page, not-logged-in page, Google/browser-not-secure block, or anti-bot wall, or when the user explicitly asks to capture, refresh, or load a specific auth state. Never ask the user to finish a real login inside the agent-browser / Chrome for Testing window. If manual login is needed, use the auth helper so the user logs in with real Chrome.

Route The Work

Invoke the helper through the standard Skill Runner. Never resolve or execute its installed Marketplace path directly.

macOS/Linux shell:

ab() {
  "$ORKAS_NODE" "$ORKAS_PC_DIR/bin/run-skill.cjs" agent-browser ab_auth -- "$@"
}

Windows PowerShell:

& $env:ORKAS_NODE "$env:ORKAS_PC_DIR\bin\run-skill.cjs" agent-browser ab_auth -- task open "https://site.example/app"

Do not paste the POSIX ab() function, /dev/null, or heredocs into Windows PowerShell. Use the standard Runner command above there.

When later examples say ab <args>, treat that as the POSIX helper function above. On Windows PowerShell, append <args> after the Runner's -- separator.

Use the helper's task subcommand for ordinary browser automation. It runs agent-browser --session <task-session> ..., with a stable session derived from the task output directory when available. This prevents simultaneous task conversations from navigating, closing, or reusing refs in each other's browsers. When a registered auth state exists for the URL host, task open <url> preloads it into the current task session before navigating, so cross-task conversations can reuse login state without remembering a state-file path.

| Site state | Path | |---|---| | Any URL automation request, including a URL that may need login | First run helper task open <url>, then helper task get url --json or task snapshot -i --json. No real Chrome yet. | | Probe shows the target page is usable | Continue with helper task click/fill/get/wait. No real Chrome. | | Probe lands on a login page, not-logged-in page, Google/browser-not-secure block, or anti-bot wall | Stop. Do not ask the user to log in there. Switch to helper auto <url> [statefile]; omit statefile unless the user gave one. | | Public page is blocked by Cloudflare / Turnstile / another anti-bot wall | Use real Chrome through helper start <url>, then continue in the real-Chrome-connected session. Login is not required unless the user/task requires it. | | User explicitly asks to capture, refresh, or load a specific auth state file | Use helper start/save/use/auto directly as requested. | | Existing auth state is available and the probe confirms the page needs a logged-in session | Use helper auto <url> or use <statefile> <url> before normal task-scoped actions. | | Saved state verifies only while the server session is alive | Treat it as session-cookie-restorable: keep the live Chrome bridge open after login, but let future tasks load the registered state while it remains valid. | | Fresh verification of saved state still lands on login | Treat it as live-session-only: keep that real Chrome process open while the task still needs the session, and continue with ab run .... |

Do not infer auth requirements from URL shape alone. Even if the user says a URL probably needs login, probe first unless they specifically ask to capture, refresh, or load an auth state file.

Why The Auth Bridge Exists

Many sites, especially Google sign-in, block automation browsers with errors like "Couldn't sign you in" or "This browser or app may not be secure". The root cause is that agent-browser's automation browser can expose signals such as navigator.webdriver=true and a testing/headless user agent.

The reliable path is: do not log in inside the automation browser. Log in once with real Chrome, save cookies/storage, then let agent-browser load that state.

Some sites do not have restart-persistent auth. Their logged-in state may depend on session cookies that a normal browser deletes on close, or on a live server/browser session that cannot be restored from a file. The helper distinguishes:

• persistent-cookie: saved state has durable site cookies and verifies in a fresh task session.
• session-cookie-restorable: saved state contains site session cookies; it can be reloaded while the server session remains valid, but the real Chrome bridge should stay open as a fallback.
• live-session-only: saved state does not verify in a fresh task session; keep using the same live real-Chrome process with ab run ....

Auth Bridge Workflow

After a normal probe confirms auth is required, use auto by default. It first tries to reuse a host-registered state file from…