browser trained
mental model
a browser session is an isolation and authorization boundary. use a named, tool-managed session by default; operate a real account only through a tab the runtime already exposes and the user authorized.
examples
export AGENT_BROWSER_SESSION="$(agent-browser session id --scope worktree --prefix task)"agent-browser open https://example.comagent-browser snapshot -i
best practices
- use fresh snapshot refs and resnapshot after navigation or rendering.
- keep credentials and cookies out of prompts and output. If global guidance authorizes an isolated profile copy, treat its directory as private runtime state, verify the account after launch, and delete it through that procedure. Stop at login/OTP boundaries.
- record screenshots or other evidence only for the requested task, then close the named session.
strengths
agent-browser has an installed, version-matched core workflow. it is suitable for isolated automation, screenshots, extraction, and application testing.
weaknesses / pain points
a private browser profile is not a portable automation fixture. Chrome 136+ requires a non-default user-data directory for remote debugging. Its separate encryption context means a copied profile's login state must be verified after launch; it cannot be assumed from copied files alone.
gotchas
- never launch daily Chrome with a debugging port or
remote-allow-origins=*. - when real state is required, follow the global isolated-copy procedure; do not invent an alternate copy or inspect cookies to diagnose it.
- selectors and product menus change; inspect the current page before acting.
known bugs
no version-specific runtime bug is documented. Account-bound automation remains a user-authorization boundary and uses no profile helper.
troubleshooting
| symptom | root cause | fix |
|---|---|---|
| login is required | isolated session has no account | use an already-authorized tab or the global isolated-copy procedure, verify state, then stop for user authentication if absent |
| ref fails after an action | page changed | take a new interactive snapshot |
| requested profile is unavailable | browser isolation boundary | use the global isolated-copy procedure when authorized; never create a daily-Chrome debug bridge |
practiced cases
- the named-session workflow here matches the installed
agent-browser 0.35.1core workflow. Primary source: github.com/vercel-labs/agent-browser - Chrome's current remote-debugging policy is documented at developer.chrome.com/blog/remote-debugging-port.