Browser Agent Deep Dive
This guide explains how PraisonAI browser automation works under the hood, covering all execution modes, APIs, and integration patterns.Quick Start
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
| Feature | Extension Mode | CDP Mode | Playwright Mode |
|---|---|---|---|
| Requires Extension | ✅ Yes | ❌ No | ❌ No |
| Headless Support | ❌ No | ✅ Yes | ✅ Yes |
| Multi-Browser | Chrome only | Chrome only | Chrome, Firefox, WebKit |
| Session Limit | 1 at a time | Unlimited | Unlimited |
| API Used | chrome.debugger | CDP WebSocket | Playwright API |
| Best For | Interactive use | Headless automation | Cross-browser testing |
| Extra Dependencies | None | aiohttp, websockets | playwright |
Extension Mode (Default)
How It Works
Backend APIs
| API | Location | Purpose |
|---|---|---|
chrome.debugger.attach() | Extension | Attach to tab for control |
chrome.debugger.sendCommand() | Extension | Execute CDP commands |
Runtime.evaluate | CDP | Execute JavaScript |
Input.dispatchMouseEvent | CDP | Simulate clicks |
Input.dispatchKeyEvent | CDP | Simulate typing |
Page.captureScreenshot | CDP | Take screenshots |
CLI Usage
Programmatic Usage
Limitations
CDP Mode
How It Works
Backend APIs
| API | Purpose | Example |
|---|---|---|
GET /json | List all pages | http://localhost:9222/json |
DOM.getDocument | Get DOM tree | {"depth": 4} |
DOM.querySelector | Find element | {"selector": "#search"} |
Runtime.evaluate | Execute JS | {"expression": "..."} |
Input.dispatchMouseEvent | Click | {"type": "click", ...} |
Input.dispatchKeyEvent | Type | {"type": "keyDown", ...} |
Page.navigate | Go to URL | {"url": "..."} |
Prerequisites
CLI Usage
Programmatic Usage
Sync Wrappers
Playwright Mode
How It Works
Backend APIs
| Playwright API | Purpose | CDP Equivalent |
|---|---|---|
page.goto(url) | Navigate | Page.navigate |
page.click(selector) | Click element | Input.dispatchMouseEvent |
page.fill(selector, text) | Type text | Input.dispatchKeyEvent |
page.screenshot() | Capture screenshot | Page.captureScreenshot |
page.content() | Get HTML | DOM.getDocument |
page.evaluate(fn) | Execute JS | Runtime.evaluate |
page.wait_for_selector() | Wait for element | Custom polling |
Prerequisites
CLI Usage
Programmatic Usage
Page Inspection Commands
These commands work via CDP (Chrome must be running with--remote-debugging-port=9222).
CLI Reference
| Command | Description | Example |
|---|---|---|
praisonai browser pages | List all browser tabs | Shows ID, title, URL |
praisonai browser dom <id> | Get DOM tree | --depth 4 |
praisonai browser content <id> | Read page as text | --limit 2000 |
praisonai browser console <id> | Capture console logs | --timeout 2 |
praisonai browser js <id> "code" | Execute JavaScript | Returns result |
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
| Issue | Cause | Solution |
|---|---|---|
| ”Another debugger attached” | Previous session not cleaned up | praisonai browser reload or restart Chrome |
| Session timeout (0 steps) | Extension not connected | Check praisonai browser doctor, reload extension |
| Actions not executing | CDP commands failing | Enable --debug mode, check console logs |
| Back-to-back sessions fail | Extension mode limitation | Use CDP mode: --engine cdp |
| Side panel not loading | Invalid Chrome version | Check minimum_chrome_version in manifest.json |
CDP Mode Issues
| Issue | Cause | Solution |
|---|---|---|
| Connection refused | Chrome not started with debug port | Start with --remote-debugging-port=9222 |
| Page not found | Invalid page ID | Run praisonai browser pages |
| Timeout | Page still loading | Use wait_for_element() |
| No pages returned | Chrome not running | Start Chrome with debug flag |
Playwright Mode Issues
| Issue | Cause | Solution |
|---|---|---|
| Browser not installed | Missing Playwright browsers | playwright install chromium |
| Selector not found | Wrong selector or slow page | Add delays or use wait_for_selector() |
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
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.Related
Browser Agent
Extension mode setup and CLI reference
Browser CLI
Full
praisonai browser command reference
