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

# Bot Browser Automation

> Give a messaging bot a local Playwright browser it can drive to complete web tasks

`--browser` gives your bot a `browser_automate` tool that drives a real local Chromium — no cloud API key required.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    User[💬 User] --> Bot[🤖 Bot Agent]
    Bot --> Tool[🔧 browser_automate]
    Tool --> PW[🎭 PlaywrightBrowserAgent]
    PW --> Chrome[🌐 Chromium]
    Chrome --> Result[✅ Result]

    classDef user fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef play fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class User,Bot agent
    class Tool,PW tool
    class Chrome play
    class Result result
```

## Quick Start

**1. Install the local browser**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install "praisonai-browser[playwright]"
playwright install chromium
```

This `playwright install chromium` step is required — no browsers are downloaded automatically by `pip install` in any tier.

**2. Enable on a bot**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Headed — a visible Chromium window opens
praisonai bot telegram --token $TELEGRAM_BOT_TOKEN --browser

# Headless — Chromium runs invisibly (recommended for servers)
praisonai bot telegram --token $TELEGRAM_BOT_TOKEN --browser --browser-headless
```

**3. Try it from your chat**

Message the bot from Telegram, Slack, or Discord:

> Go to news.ycombinator.com and tell me the top 3 stories.

The agent calls `browser_automate(goal="Get the top 3 stories", start_url="https://news.ycombinator.com")`, the local Chromium opens (or stays headless), and the bot replies with the summary.

***

## How It Works

`--browser` prefers local Playwright automation and falls back to the cloud tool only when the local browser is unavailable.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User as 💬 User
    participant Bot as 🤖 Bot
    participant Tool as 🔧 browser_automate
    participant PW as 🎭 PlaywrightBrowserAgent
    participant Chrome as 🌐 Chromium

    User->>Bot: "Summarise the top 3 stories"
    Bot->>Tool: browser_automate(goal, start_url)
    Tool->>PW: spawn local browser agent
    PW->>Chrome: navigate + snapshot + click
    Chrome-->>PW: page content
    PW-->>Tool: {"success": True, ...}
    Tool-->>Bot: result dict
    Bot-->>User: summary reply
```

| Piece | What it does |
| - | - |
| `browser_available()` | Returns `True` only when **both** `praisonai_browser` and `playwright` import. Guards against selecting local automation that would fail at launch. |
| `create_browser_tool(...)` | Builds the `browser_automate` callable the agent sees, passing through `model`, `headless`, and `profile`. |
| `BrowserBaseTool` (fallback) | Cloud scraping tool used when the local browser is missing. Requires BrowserBase credentials. |

***

## Configuration Options

| Option | Type | Default | Description |
| - | - | - | - |
| `--browser` | flag | off | Turn the tool on. Off by default so bots stay lightweight. |
| `--browser-headless` | flag | off | Run Chromium without a visible window. Recommended for servers. |
| `--browser-profile NAME` | `str` | `"default"` | Currently accepted but **not yet applied** — the local Playwright agent opens a fresh ephemeral context each session. |
| `--model MODEL` | `str` | `gpt-4o-mini` | Same flag as the bot's own model. Also drives the browser tool's internal LLM. |
| `browser_automate(goal, start_url)` | callable | `start_url="https://www.google.com"` | The tool the agent sees. `goal` is required; `start_url` defaults to Google. |

***

## Common Patterns

### Choosing local vs cloud

Use local Playwright for zero-credential dev boxes and personal automation; use the cloud fallback for serverless or no-Playwright environments.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start{Playwright<br/>installed?} -->|Yes| Local[🎭 Local Chromium<br/>no API key]
    Start -->|No| Cloud[☁️ BrowserBaseTool<br/>needs credentials]

    classDef decision fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef local fill:#10B981,stroke:#7C90A0,color:#fff
    classDef cloud fill:#F59E0B,stroke:#7C90A0,color:#fff

    class Start decision
    class Local local
    class Cloud cloud
```

### Combining with `--web`

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai bot slack --browser --browser-headless --web --memory
```

`--web` adds a search tool, `--browser` adds a real browser, and `--memory` lets the agent remember what it saw between messages.

***

## Best Practices

> [accordion] Use --browser-headless on servers
>
> Headed mode requires a display; on a headless server or Docker container the launch will fail. On a display-less host, wrap the command with `xvfb-run` to provide a virtual display.

> [accordion] Confirm which tool loaded from the startup log
>
> Three exact log lines tell you which mode you landed in:
>
> * `Local browser automation enabled (headless=…, profile=…)` — local Playwright is running.
> * `Browser tool enabled via BrowserBaseTool (cloud fallback). Install praisonai-browser for local automation.` — cloud fallback path.
> * `Browser tool not available. Install praisonai-browser (local) or praisonai-tools (cloud).` — `--browser` was a no-op; the agent has no browser tool.

> [accordion] Named profiles aren't yet honoured
>
> `--browser-profile` is accepted for forward-compatibility, but the current release always uses a fresh Chromium context. For a persistent profile, watch `praisonai-browser` upstream and use the CDP mode from [Browser Agent → Deep Dive](https://praison.ai/docs/features/browser-agent-deep-dive.md) in the meantime.

> [accordion] Failures reach the agent, not the process
>
> `browser_automate` returns `{"success": False, "error": "…"}` on Playwright errors instead of raising — the agent can retry, apologise, or fall back to `search_web`. This differs from `BrowserBaseTool`, which fails at construction if the API key is absent.

***

## Related

> [card] [Bot CLI](https://praison.ai/docs/cli/bot.md)
>
> All `praisonai bot` flags and platforms

> [card] [Bot Default Tools](https://praison.ai/docs/features/bot-default-tools.md)
>
> The tools every bot gets automatically

> [card] [Browser Agent (standalone)](https://praison.ai/docs/features/browser-agent.md)
>
> The standalone browser agent this wraps

> [card] [praisonai-browser Package](https://praison.ai/docs/features/praisonai-browser-package.md)
>
> Install matrix and Chromium extras


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.