praisonai-browser Package

Standalone Tier-2 package for AI browser automation: install, CLI, and imports

praisonai-browser is the standalone package that powers AI browser automation — the bridge server, CDP agent, and Playwright engine — usable on its own or inside the full praisonai stack.

from praisonaiagents import Agent

agent = Agent(name="browser-agent", instructions="Browse the web and complete tasks in Chrome.")
agent.start("Go to google and search praisonai, then summarise the top result.")

The agent states a goal; praisonai-browser drives Chrome until the task completes.

Quick Start

1. Install the package

   pip install praisonai-browser

2. Install a browser engine (once)

   playwright install chromium
   # or all engines:
   playwright install
   # Docker / CI (adds OS-level deps):
   playwright install chromium --with-deps

3. Run a goal from the CLI

   praisonai-browser run "Go to google and search praisonai"

4. Or use the Python API

   from praisonai_browser import BrowserServer
   
   server = BrowserServer(port=8765, model="gpt-4o")
   server.start()  # Blocks until Ctrl+C / SIGTERM; connect the Chrome extension to it

Install

Pick the extras you need — core alone covers the CLI and CDP agent.

pip install praisonai-browser            # core
pip install "praisonai-browser[server]"  # FastAPI bridge server
pip install "praisonai-browser[playwright]"  # cross-browser Playwright engine
pip install "praisonai-browser[all]"     # everything

Console Entry Point

The package ships a praisonai-browser console script that mirrors the praisonai browser subcommands.

praisonai-browser --help
praisonai-browser run "Go to google and search praisonai"
praisonai-browser doctor

Inside the full stack the same commands are available as praisonai browser ….

praisonai-browser run inherits the same engine-option matrix as the wrapper — the standalone entry point mirrors praisonai browser run exactly, including which flags reach the wire on each engine and the “Ignored on the … engine” warnings.

Python API

Import the public classes straight from praisonai_browser.

from praisonai_browser import (
    BrowserServer,
    BrowserAgent,
    SessionManager,
    CDPBrowserAgent,
    run_cdp_only,
    run_hybrid,
)

Hybrid runner: engine fallback chain

run_hybrid tries three engines in order — Extension, CDP, Playwright — and returns as soon as one runs.

import asyncio
from praisonai_browser import run_hybrid

async def main():
    result = await run_hybrid(
        "Search for PraisonAI on Google and open the first result",
        url="https://www.google.com",
        verbose=True,
    )
    print(result["engine"], result["success"])

asyncio.run(main())

The returned dict always includes:

• engine — "extension", "cdp", "playwright", or None when no engine is available.
• success — bool.
• error — present when no engine is available; tells you to start Chrome with --remote-debugging-port=9222 or run the extension bridge server.

Additional fields (summary, steps) depend on the selected engine.

SessionManager custom db_path

SessionManager stores session and step history in SQLite at ~/.praisonai/browser_sessions.db by default. Pass db_path to use a custom location — parent directories are auto-created.

from praisonai_browser import SessionManager

sm = SessionManager(db_path="/tmp/scratch/nested/subdir/browser.sqlite")

Protocol Types

The lightweight type definitions live in the agents tier and are shared across engines.

from praisonaiagents.tools.protocols.browser import (
    BrowserAction,
    BrowserActionType,
    BrowserObservation,
    BrowserSession,
)

BrowserActionType includes click, type, scroll, navigate, wait, screenshot, evaluate, submit, clear_input, and done.

Backward Compatibility

Everything from the pre-extraction layout keeps working.

Best Practices

Related