Skip to main content
The user describes a web goal; the browser agent drives Chrome via extension, CDP, or Playwright.

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 package praisonai_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.
Never set PRAISONAI_BROWSER_SKIP_EXTENSION_WAIT on a live run. It bypasses the readiness check, so the automation fails as soon as it sends start_session without a connected extension.

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

Any of 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

  1. User → CLI: User provides goal via praisonai browser run "goal"
  2. CLI → Server: CLI connects over WebSocket, sends start_session
  3. Server → Extension: Server forwards start_automation to Chrome extension
  4. Extension → Page: Extension uses CDP to capture page state (DOM, screenshot)
  5. Extension → Server: Sends observation with page details
  6. Server → Agent: Passes observation to BrowserAgent
  7. Agent → LLM: Agent builds prompt with goal + context, gets action from LLM
  8. Server → Extension: Forwards action (click, type, scroll, etc.)
  9. Extension → Page: Executes action via CDP
  10. Loop: Repeats until agent returns done: true or 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

Extension mode supports only one session at a time because Chrome’s chrome.debugger API only allows one debugger attachment per tab.

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

  1. Go to chrome://extensions
  2. Find “PraisonAI Browser Agent”
  3. Click “Service worker” link to open DevTools
  4. 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.
When auto-load fails, 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 ws://127.0.0.1:8765/ws.If you launched with --no-server, start the bridge first:
Check /health directly (expect extension_connections >= 1):
A connected extension returns:
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.
Chrome 137+ on Windows blocks the automated --load-extension argument for MV3 extensions. If praisonai browser launch opens a debug Chrome window without the PraisonAI extension icon, this is why. The manual Load unpacked step above is the fix.
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
The error is sent in the next observation, allowing the LLM to retry or try alternative actions.

Best Practices

Use extension mode for interactive debugging, CDP for headless Chrome automation, and Playwright when you need Firefox or WebKit or reliable multi-session runs.
Pass a unique session_id per task so chat_history does not leak between parallel or sequential automations. Call agent.reset() between unrelated goals.
CDP mode requires Chrome on --remote-debugging-port=9222. Run praisonai browser pages to confirm tabs before starting an agent run.
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.

Browser Agent

Extension mode setup and CLI reference

praisonai-browser Package

Install, CLI, imports, and backward compatibility for the Tier-2 package