Skip to main content

​
Browser Extension Architecture

The PraisonAI browser automation uses a 3-layer architecture for AI-powered browser control.

​
Communication Flow

Python CLI ──► Bridge Server ◄──► Chrome Extension
     │              │                    │
     │              │                    │
 start_session  observation/action      CDP
  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

┌─────────────────────────────────────────────────────────────┐
│                     Python CLI                               │
│  praisonai browser launch "goal"                            │
└─────────────────────┬───────────────────────────────────────┘
                      │ WebSocket
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                  Bridge Server (FastAPI)                     │
│  - Routes messages CLI ↔ Extension                          │
│  - Hosts BrowserAgent for LLM decisions                     │
│  - WebSocket endpoint: ws://localhost:8765/ws               │
└─────────────────────┬───────────────────────────────────────┘
                      │ WebSocket
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                Chrome Extension                              │
│  - Background service worker                                │
│  - CDP debugger for page control                            │
│  - Captures screenshots, clickable elements                 │
│  - Executes click/type/scroll actions                       │
└─────────────────────────────────────────────────────────────┘

​
Running the Browser Agent

# Simple usage (auto-selects engine)
praisonai browser launch "go to google and search for AI"

# Force extension mode
praisonai browser launch "go to google" --engine extension

# Force CDP mode (no extension required)
praisonai browser launch "go to google" --engine cdp

# Debug mode
praisonai browser launch "test" --debug

​
Message Types

TypeDirectionDescription
start_sessionCLI → ServerStart new automation
observationExt → ServerPage state snapshot
actionServer → ExtNext action to execute
statusServer → BothSession status updates
stop_sessionAny → ServerEnd 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: 
    pkill -f "Google Chrome"
  3. Rebuild extension: 
    cd /path/to/praisonai-chrome-extension
npm run build
  4. Check bridge server: 
    curl http://localhost:8765/health

​
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

praisonai browser launch "test" --debug
This enables verbose logging and saves screenshots to ~/.praisonai/browser_screenshots/.

​
Performance Profiling

Track timing breakdown for each automation step: 
# Basic profiling with timing summary
praisonai browser launch "search for AI" --engine cdp --profile

# Deep profiling with cProfile trace
praisonai browser launch "search for AI" --engine cdp --deep-profile

​
Sample Output

📊 Performance Profile
──────────────────────────────────────────────────────────────────────
Total Time: 24.2s | Steps: 3 | Avg: 8.1s/step

Step |    LLM | Screen | Action | Verify | Stable |  Total
   0 |   2.4s |   0.0s |   1.0s |   0.0s |   0.0s |   3.5s
   1 |   2.2s |   0.0s |   0.2s |   0.0s |   0.0s |   2.5s

Bottlenecks: LLM 51% | Verify 0% | Stable 0%

​
Timing Breakdown

MetricDescription
LLMTime spent waiting for LLM decision
ScreenScreenshot capture time
ActionCDP action execution time
VerifyAction verification time
StablePage stability wait time