Browser Agent Deep Dive
This guide explains how PraisonAI browser automation works under the hood, covering all execution modes, APIs, and integration patterns.Package Layout
Heavy browser code lives in the standalone Tier-2 packagepraisonai_browser; the agents tier keeps only lightweight protocol types.
Install with
pip install praisonai-browser. Import from praisonai_browser; from praisonai.browser import … still works via the shim.
Environment Variables
Environment variables tune the bridge server’s security posture and extension-readiness behaviour before a run starts.
The skip only triggers on the truthy values above.
PRAISONAI_BROWSER_SKIP_EXTENSION_WAIT=false (or 0, no, off, or any inherited value) leaves the readiness check active.
Testing without a live extension
1
Mock the websocket layer
Patch the websocket layer (
unittest.mock, pytest-asyncio, etc.) so the bridge server is never reached.2
Enable the skip
1, true, yes, on (case-insensitive) enables the skip. Anything else — including false / 0 — leaves the readiness check active.3
Run against the mock
The readiness poll used to block on the aiohttp
/health loop before the mock got a chance. With the skip set, the run hits the mock immediately.The readiness poll now caps at
min(15.0, timeout) seconds. A caller passing timeout=2.0 waits at most 2 seconds, not the full 15.Quick Start
1
Extension mode (default)
2
CDP mode (headless)
3
Playwright mode
Architecture Overview
Instruction Flow (Extension Mode)
This diagram shows exactly how your instruction flows through the system:Key Points
- User → CLI: User provides goal via
praisonai browser run "goal" - CLI → Server: CLI connects over WebSocket, sends
start_session - Server → Extension: Server forwards
start_automationto Chrome extension - Extension → Page: Extension uses CDP to capture page state (DOM, screenshot)
- Extension → Server: Sends observation with page details
- Server → Agent: Passes observation to BrowserAgent
- Agent → LLM: Agent builds prompt with goal + context, gets action from LLM
- Server → Extension: Forwards action (click, type, scroll, etc.)
- Extension → Page: Executes action via CDP
- Loop: Repeats until agent returns
done: trueor timeout
Execution Modes
Comparison Table
Extension Mode (Default)
How It Works
Backend APIs
CLI Usage
Programmatic Usage
server.start() blocks for the lifetime of the server; use server.start_background() when you need the calling thread to continue. The pre-bind port check is a CLI concern, not a BrowserServer responsibility — probe it yourself if you need it:Limitations
CDP Mode
How It Works
Backend APIs
Prerequisites
CLI Usage
Programmatic Usage
Sync Wrappers
Playwright Mode
How It Works
Backend APIs
Prerequisites
CLI Usage
Programmatic Usage
Page Inspection Commands
These commands work via CDP (Chrome must be running with--remote-debugging-port=9222).
CLI Reference
Python API
Agent Memory & Sessions
Session Isolation
Each browser session now uses Agent’s built-in session management:Memory Flow
Common Patterns
Sequential Tasks (CDP Mode)
Headless Screenshot
Page Scraping
Troubleshooting
Debug CLI Commands
Session Tracking
Both agent-side and server-side sessions are tracked in the same SQLite database:Extension Mode Issues
CDP Mode Issues
Playwright Mode Issues
Chrome Extension Console Logs
- Go to
chrome://extensions - Find “PraisonAI Browser Agent”
- Click “Service worker” link to open DevTools
- Check Console for
[PraisonAI]and[Bridge]logs
Manual Extension Load (Chrome 137+ / Windows)
Chrome 137+ on Windows blocks the automated--load-extension flag praisonai browser launch uses, so the debug profile opens empty. Load the extension into your daily Chrome once and it just works.
launch prints the exact Load unpacked path plus a curl verification step instead of a generic error. Follow the recipe below.
1
Open your daily Chrome
Use your normal Chrome (Work profile) — not a fresh debug profile.
2
Enable Developer mode
Toggle Developer mode on (top-right).
3
Load the dist folder
Click Load unpacked and select the dist path printed by
praisonai browser launch (typically ~/.praisonai/browser/extension/dist).4
Confirm the bridge connection
Open the PraisonAI side panel and confirm it connects to Check A connected extension returns:
ws://127.0.0.1:8765/ws.If you launched with --no-server, start the bridge first:/health directly (expect extension_connections >= 1):extension_busy and active_session_id (added in PraisonAI #3095 hardening) show whether a session currently owns the extension — a healthy-and-idle bridge reports extension_busy: false. Servers older than that commit omit both fields; treat missing as false / null.5
Verify
If your organisation forbids Developer mode, run
praisonai browser run "task" --engine cdp — the CDP engine drives Chrome via --remote-debugging-port=9222 and does not need the extension at all. See CDP Mode.praisonai browser reload remains available for picking up extension code changes, but it is not the fix for the Chrome 137+ auto-load block — use the Load unpacked flow above.Common Log Patterns
Action Verification
All actions return{ success, error }:
- success=true: CDP operation completed
- success=false: Error message indicates what failed
Best Practices
Pick the engine for your use case
Pick the engine for your use case
Use extension mode for interactive debugging, CDP for headless Chrome automation, and Playwright when you need Firefox or WebKit or reliable multi-session runs.
Isolate sessions with session_id
Isolate sessions with session_id
Pass a unique
session_id per task so chat_history does not leak between parallel or sequential automations. Call agent.reset() between unrelated goals.Start Chrome with remote debugging for CDP
Start Chrome with remote debugging for CDP
CDP mode requires Chrome on
--remote-debugging-port=9222. Run praisonai browser pages to confirm tabs before starting an agent run.Diagnose failures with doctor and --debug
Diagnose failures with doctor and --debug
Run
praisonai browser doctor when extension sessions stall, and add --debug to surface CDP and bridge logs. Check ~/.praisonai/browser_sessions.db for step history.praisonai browser doctor extension decides success by reading the bridge /health extension_connections count (source of truth — works even when the extension is loaded into your daily Chrome instead of the debug profile). CDP :9222 is reported as informational. A doctor failure now means “the extension is genuinely not connected to the bridge” — follow the manual-load steps above.Related
Browser Agent
Extension mode setup and CLI reference
praisonai-browser Package
Install, CLI, imports, and backward compatibility for the Tier-2 package

