pai-browser-use 0.2.0

Pydantic AI Toolsets for browser use

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.

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.