pai-browser-use

⚠️ Early Stage Project This project is currently in early development. APIs and features may change. We welcome your feedback and contributions!

• 🐛 Found a bug? Submit an issue
• 💡 Have ideas or suggestions? Join the discussion
• 🤝 Want to contribute? Check out our Contributing Guide

Pydantic AI Toolsets for browser automation using Chrome DevTools Protocol (CDP).

Inspired by browser-use, designed for Pydantic AI agents.

Features

• Browser Automation Tools: Navigation, state inspection, interaction, and element queries
• Multi-Modal Screenshots: Automatic image splitting for long pages with ToolReturn support
• Type-Safe CDP Integration: Direct access to cdp-use API with full type hints
• Fully Tested: Comprehensive test suite with Docker-based Chrome container

Installation

Use pip:

pip install pai-browser-use

Or use uv:

uv add pai-browser-use

Quick Start

Prerequisites

Start a Chrome instance with CDP enabled:

# Option 1: Using Chrome directly
google-chrome --remote-debugging-port=9222

# Option 2: Using Docker container
./dev/start-browser-container.sh

Basic Usage

import os
from pydantic_ai import Agent
from pai_browser_use import BrowserUseToolset

agent = Agent(
    model="anthropic:claude-sonnet-4-5",
    system_prompt="You are a helpful assistant.",
    toolsets=[
        BrowserUseToolset(cdp_url="http://localhost:9222/json/version"),
    ],
)

result = await agent.run("Find the number of stars of the wh1isper/pai-browser-use repo")
print(result.output)

See examples/agent.py for a complete example.

Configuration

BrowserUseToolset supports configuration via environment variables. See .env.example for all available options.

You can override environment variables by passing explicit parameters:

toolset = BrowserUseToolset(
    cdp_url="http://localhost:9222/json/version",
    max_retries=10,              # Override PAI_BROWSER_USE_MAX_RETRIES
    prefix="custom_browser",     # Override PAI_BROWSER_USE_PREFIX
    always_use_new_page=True,    # Override PAI_BROWSER_USE_ALWAYS_USE_NEW_PAGE
    auto_cleanup_page=False,     # Override PAI_BROWSER_USE_AUTO_CLEANUP_PAGE
)

Priority: Explicit parameters > Environment variables > Defaults

Page Management

• always_use_new_page: When True, creates a new browser page instead of reusing existing ones. Defaults to False.
• auto_cleanup_page: When True, automatically closes created pages on context exit. Defaults to False.

Use Case Examples:

# Default behavior: Reuse existing page, no cleanup needed
toolset = BrowserUseToolset(cdp_url="http://localhost:9222/json/version")

# Create new page but keep it open for debugging/inspection (default when using always_use_new_page)
toolset = BrowserUseToolset(
    cdp_url="http://localhost:9222/json/version",
    always_use_new_page=True,   # Create fresh page
    # auto_cleanup_page defaults to False - page remains open
)

# Create new page and automatically clean up (for production/batch processing)
toolset = BrowserUseToolset(
    cdp_url="http://localhost:9222/json/version",
    always_use_new_page=True,   # Create fresh page
    auto_cleanup_page=True,     # Clean up after execution
)

Logging

Use PAI_BROWSER_USE_LOG_LEVEL environment variable to set logging level. The default is ERROR. Set to DEBUG for more verbose logging.

Development

# Install dependencies
uv sync

# Run tests
pytest tests/

# Run example
python examples/agent.py

# Try DEBUG logging demo (shows extracted content)
PAI_BROWSER_USE_LOG_LEVEL=DEBUG python demo_debug_logging.py

License

BSD 3-Clause License - see LICENSE for details.