Skip to main content

​
Browser Extension Architecture

The PraisonAI browser automation uses a 3-layer architecture for AI-powered browser control.
The bridge server and extension support ship in the standalone praisonai-browser package. Install them with pip install "praisonai-browser[server]" (or pip install "praisonai[all]"). The praisonai browser … commands keep working unchanged.

​
Communication Flow

  1. CLI sends start_session with goal
  2. Bridge Server routes to Extension
  3. Extension captures page state (screenshot, elements)
  4. Extension sends observation to Bridge
  5. Bridge processes with BrowserAgent (LLM decision)
  6. Bridge returns action to Extension
  7. Extension executes action via CDP
  8. Loop continues until goal complete

​
Architecture Diagram

​
Running the Browser Agent

​
Message Types

​
Extension Readiness Wait

Before sending start_session, run_browser_agent_with_progress polls the bridge /health endpoint until an extension connects. The poll caps at min(15.0, timeout) seconds — a caller passing timeout=2.0 waits at most 2 seconds. Set PRAISONAI_BROWSER_SKIP_EXTENSION_WAIT=1 to skip the poll entirely (for unit tests / mocked bridges). See Environment Variables.
Skip the readiness poll only for tests or mocked bridges — never for live runs, where it exists to catch a disconnected extension before start_session.

​
Troubleshooting

​
Extension Not Connecting

If you see “Extension did not connect after 15s”:
  1. Check extension console:
    • Go to chrome://extensions/
    • Find “PraisonAI Browser Agent”
    • Click “service worker” link
    • Look for errors
  2. Kill stale Chrome processes:
  3. Rebuild extension:
  4. Check bridge server:
    Expected output:
    connections counts all WebSocket clients (extension, CLI, curl’d probes). Check extension_connections >= 1 instead — it counts only clients whose Origin starts with chrome-extension://, so a stray CLI probe won’t make it look connected. connections >= 1 alone is no longer sufficient. extension_busy and active_session_id (added in PraisonAI #3095 hardening) tell you whether the extension is currently owned by a session — a healthy-and-idle bridge shows extension_busy: false. praisonai browser run fails fast with an “Extension already running a session” error rather than hanging when this is true. Servers older than that commit omit both fields; treat missing as false / null.
    Servers older than PraisonAI #3115 don’t return extension_connections. The CLI helpers (doctor extension, the launch poller) fall back to connections in that case.

​
No Observations Sent

If session starts but times out:
  • Check extension console for [PraisonAI] onStartAutomation FATAL ERROR
  • CDP debugger may fail to attach
  • Page may be a chrome:// URL (unsupported)

​
Debug Mode

This enables verbose logging and saves screenshots to ~/.praisonai/browser_screenshots/.

​
Performance Profiling

Track timing breakdown for each automation step:

​
Sample Output

​
Timing Breakdown