> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Protocol[📋 praisonaiagents<br/>protocol types] --> Browser[⚙️ praisonai-browser<br/>implementation]
    Browser --> Wrapper[🤖 praisonai<br/>wrapper / shim]
    Browser --> Done[✅ Task complete]

    classDef proto fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef impl fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef wrap fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef ok fill:#10B981,stroke:#7C90A0,color:#fff

    class Protocol proto
    class Browser impl
    class Wrapper wrap
    class Done ok
```

## Quick Start

<Steps>
  <Step title="Install the package">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install praisonai-browser
    ```
  </Step>

  <Step title="Run a goal from the CLI">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai-browser run "Go to google and search praisonai"
    ```
  </Step>

  <Step title="Or use the Python API">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonai_browser import BrowserServer

    server = BrowserServer(port=8765, model="gpt-4o")
    server.start()  # Blocks; connect the Chrome extension to it
    ```
  </Step>
</Steps>

***

## Install

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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```

| Extra        | Adds                                          | Use it for                       |
| ------------ | --------------------------------------------- | -------------------------------- |
| *(none)*     | `rich`, `typer`, `click`                      | Core CLI and CDP agent           |
| `server`     | `fastapi`, `uvicorn`, `websockets`, `aiohttp` | Bridge server + Chrome extension |
| `playwright` | `playwright`                                  | Firefox/WebKit and headless runs |
| `all`        | Everything above                              | Full feature set                 |

<Note>
  `pip install "praisonai[all]"` (or `praisonai[browser]`) installs `praisonai-browser` for you as part of the umbrella product.
</Note>

***

## Console Entry Point

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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 …`.

***

## Python API

Import the public classes straight from `praisonai_browser`.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_browser import (
    BrowserServer,
    BrowserAgent,
    SessionManager,
    CDPBrowserAgent,
    run_cdp_only,
    run_hybrid,
)
```

| Export            | What it does                                        |
| ----------------- | --------------------------------------------------- |
| `BrowserServer`   | FastAPI + WebSocket bridge for the Chrome extension |
| `BrowserAgent`    | Decides the next action from a page observation     |
| `SessionManager`  | SQLite-backed session and step history              |
| `CDPBrowserAgent` | Drives Chrome directly over CDP (no extension)      |
| `run_cdp_only`    | One-call CDP automation runner                      |
| `run_hybrid`      | CDP with on-device fallback                         |

### Protocol Types

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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

| Old usage                                                   | Still works | Canonical form                                              |
| ----------------------------------------------------------- | ----------- | ----------------------------------------------------------- |
| `from praisonai.browser import BrowserServer, BrowserAgent` | ✅           | `from praisonai_browser import BrowserServer, BrowserAgent` |
| `from praisonai.browser.sessions import SessionManager`     | ✅           | `from praisonai_browser import SessionManager`              |
| `praisonai browser run "…"`                                 | ✅           | `praisonai-browser run "…"`                                 |
| `python -m praisonai.browser.server`                        | ✅           | `praisonai-browser start`                                   |

<Note>
  `praisonai.browser` is a compatibility shim that re-exports `praisonai_browser`, so existing scripts need no changes.
</Note>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Install only the extras you use">
    Core covers the CLI and CDP agent. Add `[server]` for the Chrome extension bridge and `[playwright]` for Firefox/WebKit or headless runs.
  </Accordion>

  <Accordion title="Prefer the canonical import">
    Import from `praisonai_browser` in new code. The `praisonai.browser` shim stays for existing scripts.
  </Accordion>

  <Accordion title="Use the standalone CLI in slim environments">
    `praisonai-browser` runs without the full wrapper, keeping browser-only images small.
  </Accordion>

  <Accordion title="Run doctor before your first session">
    `praisonai-browser doctor` checks the server, Chrome debugging, extension, and session database in one pass.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Browser Agent" icon="globe" href="/docs/features/browser-agent">
    Setup, CLI reference, and supported actions.
  </Card>

  <Card title="Browser Agent Deep Dive" icon="microscope" href="/docs/features/browser-agent-deep-dive">
    Execution modes, APIs, and package layout in detail.
  </Card>
</CardGroup>