OpenBrowser

https://docs.openbrowser.me
Admin
OpenBrowser is an AI-powered browser automation tool that enables users to automate browser tasks...
Tokens:38,332
Snippets:466
Trust Score:3.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install OpenBrowser from Source

Source: https://docs.openbrowser.me/quickstart

Clone the repository and install dependencies locally.

```bash
git clone https://github.com/billy-enrizky/openbrowser-ai.git
cd openbrowser-ai
uv pip install -e ".[agent]"
```

--------------------------------

### Run Development Examples

Source: https://docs.openbrowser.me/development/setup/local-setup

Executes the provided example scripts using the uv environment.

```bash
uv run examples/simple.py
```

--------------------------------

### OpenBrowser Quick Reference

Source: https://docs.openbrowser.me/quickstart_llm

A markdown-formatted guide covering installation, basic usage, and supported LLM classes.

```markdown
# OpenBrowser Quick Reference

## Installation
pip install openbrowser-ai

## Basic Usage
from openbrowser import Agent, Browser, ChatGoogle

agent = Agent(
    task="Your task here",
    llm=ChatGoogle(),  # or ChatOpenAI(), ChatAnthropic()
)
await agent.run()

## Key Classes
- Agent: Main automation agent
- Browser: Browser instance wrapper  
- BrowserSession: Low-level browser control
- BrowserProfile: Browser configuration

## Supported LLMs
- ChatGoogle (Gemini)
- ChatOpenAI (GPT-4)
- ChatAnthropic (Claude)
- ChatGroq, ChatOllama, ChatAWSBedrock, ChatAzureOpenAI
```

--------------------------------

### Create and Manage Browser Pages

Source: https://docs.openbrowser.me/customize/actor/examples

Demonstrates how to start the browser, create new pages (blank or with a URL), retrieve all open pages, get the current page, and close a specific page. Remember to call `browser.stop()` to clean up resources.

```python
from openbrowser import Browser

browser = Browser()
await browser.start()

# Create pages
page = await browser.new_page()  # Blank tab
page = await browser.new_page("https://example.com")  # With URL

# Get all pages
pages = await browser.get_pages()
current = await browser.get_current_page()

# Close page
await browser.close_page(page)
await browser.stop()
```

--------------------------------

### Clone and Navigate to Repository

Source: https://docs.openbrowser.me/examples/apps/ad-use

Download the source code and enter the ad-use example directory.

```bash
git clone https://github.com/billy-enrizky/openbrowser-ai.git
cd openbrowser/examples/apps/ad-use
```

--------------------------------

### Clone and Install Dependencies

Source: https://docs.openbrowser.me/development/setup/local-setup

Initializes the local development environment by cloning the repository and installing dependencies using uv or pip.

```bash
git clone https://github.com/billy-enrizky/openbrowser-ai
cd openbrowser-ai
uv sync --all-extras --dev
# or pip install -U git+https://github.com/billy-enrizky/openbrowser-ai.git
```

--------------------------------

### Configure Environment Variables

Source: https://docs.openbrowser.me/development/setup/local-setup

Sets up the required environment variables by copying the example configuration file.

```bash
# Copy the example environment file
cp .env.example .env

# set logging level
# OPENBROWSER_LOGGING_LEVEL=debug
```

--------------------------------

### Install OpenBrowser via uv

Source: https://docs.openbrowser.me/quickstart

Recommended installation method using uv for dependency management and isolated environments.

```bash
uv pip install "openbrowser-ai[agent]"
```

```bash
uv venv --python 3.12
source .venv/bin/activate
uv pip install "openbrowser-ai[agent]"
```

--------------------------------

### Clone Repository and Navigate

Source: https://docs.openbrowser.me/examples/apps/news-use

Clone the openbrowser-ai repository and navigate to the news-use example directory.

```bash
git clone https://github.com/billy-enrizky/openbrowser-ai.git
cd openbrowser/examples/apps/news-use
```

--------------------------------

### Install OpenBrowser via Shell Script

Source: https://docs.openbrowser.me/quickstart

Use curl or PowerShell to install OpenBrowser automatically. The local flag installs to ~/.local/bin without requiring sudo.

```bash
curl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh
```

```powershell
irm https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.ps1 | iex
```

```bash
curl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh -s -- --local
```

--------------------------------

### Clone and Install Vibetest

Source: https://docs.openbrowser.me/examples/apps/vibetest-use

Clone the repository, set up a Python virtual environment, and install the project dependencies including the OpenBrowser runtime.

```bash
git clone https://github.com/billy-enrizky/vibecheck.git
cd vibecheck

uv venv --python 3.11
source .venv/bin/activate

uv pip install -e .

uvx openbrowser-ai install
```

--------------------------------

### Custom Step Hook Example

Source: https://docs.openbrowser.me/customize/hooks

An example of a custom `on_step_start` hook that accesses agent state, browser information, and interacts with the browser. It demonstrates pausing and resuming the agent based on URL content.

```python
import asyncio
from pathlib import Path

from openbrowser import Agent, ChatOpenAI
from openbrowser.browser.events import ScreenshotEvent


async def my_step_hook(agent: Agent):
	# inside a hook you can access all the state and methods under the Agent object:
	#   agent.settings, agent.state, agent.task
	#   agent.tools, agent.llm, agent.browser_session
	#   agent.pause(), agent.resume(), agent.add_new_task(...), etc.

	# You also have direct access to the browser state
	state = await agent.browser_session.get_browser_state_summary()

	current_url = state.url
	visit_log = agent.history.urls()
	previous_url = visit_log[-2] if len(visit_log) >= 2 else None
	print(f'Agent was last on URL: {previous_url} and is now on {current_url}')
	cdp_session = await agent.browser_session.get_or_create_cdp_session()

	# Example: Get page HTML content
	doc = await cdp_session.cdp_client.send.DOM.getDocument(session_id=cdp_session.session_id)
	html_result = await cdp_session.cdp_client.send.DOM.getOuterHTML(
		params={'nodeId': doc['root']['nodeId']},
		session_id=cdp_session.session_id
	)
	page_html = html_result['outerHTML']

	# Example: Take a screenshot using the event system
	screenshot_event = agent.browser_session.event_bus.dispatch(ScreenshotEvent(full_page=False))
	await screenshot_event
	result = await screenshot_event.event_result(raise_if_any=True, raise_if_none=True)

	# Example: pause agent execution and resume it based on some custom code
	if '/finished' in current_url:
		agent.pause()
		Path('result.txt').write_text(page_html)
		input('Saved "finished" page content to result.txt, press [Enter] to resume...')
		agent.resume()


async def main():
	agent = Agent(
		task='Search for the latest news about AI',
		llm=ChatOpenAI(model='gpt-5-mini'),
	)

	await agent.run(
		on_step_start=my_step_hook,
		# on_step_end=...
		max_steps=10,
	)


if __name__ == '__main__':
	asyncio.run(main())

```

--------------------------------

### Install OpenBrowser via pipx

Source: https://docs.openbrowser.me/quickstart

Installs into an isolated environment with global command access.

```bash
pipx install openbrowser-ai
```

--------------------------------

### Install OpenBrowser via pip

Source: https://docs.openbrowser.me/quickstart

Standard pip installation with optional agent support.

```bash
pip install openbrowser-ai
```

```bash
pip install "openbrowser-ai[agent]"
```

--------------------------------

### Install Playwright and Aiohttp

Source: https://docs.openbrowser.me/examples/templates/playwright-integration

Install the necessary dependencies to enable Playwright integration.

```bash
uv pip install playwright aiohttp
```

--------------------------------

### Initialize and run an OpenBrowser agent

Source: https://docs.openbrowser.me/customize/agent/basics

Demonstrates the basic setup of an Agent with a task and LLM, followed by the asynchronous execution method.

```python
from openbrowser import Agent, ChatBrowserUse

agent = Agent(
    task="Search for latest news about AI",
    llm=ChatBrowserUse(),
)

async def main():
    history = await agent.run(max_steps=100)
```

--------------------------------

### Install OpenLIT and OpenBrowser

Source: https://docs.openbrowser.me/development/monitoring/openlit

Install the necessary packages via pip to begin using OpenLIT with OpenBrowser.

```bash
pip install openlit openbrowser
```

--------------------------------

### Install OpenBrowser via Homebrew

Source: https://docs.openbrowser.me/quickstart

Installs OpenBrowser into a Homebrew-managed virtual environment.

```bash
brew tap billy-enrizky/openbrowser
brew install openbrowser-ai
```

--------------------------------

### Start MCP Server

Source: https://docs.openbrowser.me/customize/integrations/mcp-server

Command to start the OpenBrowser MCP server in stdio mode.

```APIDOC
## Start MCP Server

### Description
Starts the OpenBrowser MCP server, making browser automation capabilities available to AI assistants.

### Method
Shell Command

### Endpoint
N/A

### Parameters
N/A

### Request Example
```bash
uvx openbrowser-ai --mcp
```

### Response
N/A
```

--------------------------------

### Start MCP Server

Source: https://docs.openbrowser.me/customize/integrations/mcp-server

Use this command to start the MCP server in stdio mode, ready for AI assistant connections.

```bash
uvx openbrowser-ai --mcp
```

--------------------------------

### Initial Actions Example

Source: https://docs.openbrowser.me/customize/agent/all-parameters

Define a list of actions to be executed before the main task begins, without LLM intervention. This is useful for setting up initial states.

```python
from openbrowser.agent import Agent
from openbrowser.actions import GoTo, TypeText

agent = Agent(initial_actions=[
    GoTo("https://www.google.com"),
    TypeText("hello world", "search_input_selector"),
])

```

--------------------------------

### Initialize CodeAgent

Source: https://docs.openbrowser.me/customize/code-agent/basics

Basic setup for running a task with CodeAgent using Google's LLM.

```python
import asyncio
from openbrowser import CodeAgent, ChatGoogle
from dotenv import load_dotenv

load_dotenv()

async def main():
    task = "Extract all products from example.com and save to products.csv"

    agent = CodeAgent(task=task, llm=ChatGoogle())
    await agent.run()

asyncio.run(main())
```

--------------------------------

### Install n8n OpenBrowser Node

Source: https://docs.openbrowser.me/development/n8n-integration

Install the OpenBrowser community node for n8n by running this command in your n8n installation directory. This is for self-hosted instances.

```bash
npm install n8n-nodes-openbrowser
```

--------------------------------

### Install openbrowser-ai

Source: https://docs.openbrowser.me/examples/apps/news-use

Install the latest version of the openbrowser-ai package using pip.

```bash
pip install -U openbrowser-ai
```

--------------------------------

### Install and Configure Laminar

Source: https://docs.openbrowser.me/development/monitoring/observability

Install the required package and set the project API key environment variable.

```bash
pip install 'lmnr[all]'
export LMNR_PROJECT_API_KEY=<your-project-api-key>
```

--------------------------------

### Custom System Prompt Example

Source: https://docs.openbrowser.me/customize/agent/all-parameters

Extend the default system prompt with additional instructions. This allows for fine-tuning the agent's behavior and constraints.

```python
from openbrowser.agent import Agent

agent = Agent(extend_system_message="Always answer in JSON format.")

```

--------------------------------

### Development Helper Scripts

Source: https://docs.openbrowser.me/development/setup/local-setup

Executes common development tasks including environment setup, linting, and testing.

```bash
# Complete setup script - installs uv, creates a venv, and installs dependencies
./bin/setup.sh

# Run all pre-commit hooks (formatting, linting, type checking)
./bin/lint.sh

# Run the core test suite that's executed in CI
./bin/test.sh
```

--------------------------------

### Implement a Fast Agent

Source: https://docs.openbrowser.me/examples/templates/fast-agent

A complete example demonstrating the integration of fast LLM models, optimized browser profiles, and flash mode for high-speed task execution.

```python
import asyncio
from dotenv import load_dotenv
load_dotenv()

from openbrowser import Agent, BrowserProfile

# Speed optimization instructions for the model
SPEED_OPTIMIZATION_PROMPT = """
Speed optimization instructions:
- Be extremely concise and direct in your responses
- Get to the goal as quickly as possible
- Use multi-action sequences whenever possible to reduce steps
"""


async def main():
	# 1. Use fast LLM - Llama 4 on Groq for ultra-fast inference
	from openbrowser import ChatGroq

	llm = ChatGroq(
		model='meta-llama/llama-4-maverick-17b-128e-instruct',
		temperature=0.0,
	)
	# from openbrowser import ChatGoogle

	# llm = ChatGoogle(model='gemini-flash-lite-latest')

	# 2. Create speed-optimized browser profile
	browser_profile = BrowserProfile(
		minimum_wait_page_load_time=0.1,
		wait_between_actions=0.1,
		headless=False,
	)

	# 3. Define a speed-focused task
	task = """
	1. Go to reddit https://www.reddit.com/search/?q=browser+agent&type=communities 
	2. Click directly on the first 5 communities to open each in new tabs
    3. Find out what the latest post is about, and switch directly to the next tab
	4. Return the latest post summary for each page
	"""

	# 4. Create agent with all speed optimizations
	agent = Agent(
		task=task,
		llm=llm,
		flash_mode=True,  # Disables thinking in the LLM output for maximum speed
		browser_profile=browser_profile,
		extend_system_message=SPEED_OPTIMIZATION_PROMPT,
	)

	await agent.run()


if __name__ == '__main__':
	asyncio.run(main())
```

--------------------------------

### Configure Ollama for OpenBrowser

Source: https://docs.openbrowser.me/customize/supported-models

Setup for using local models via Ollama. Requires the Ollama server to be running.

```python
from openbrowser import Agent, ChatOllama

llm = ChatOllama(model="llama3.1:8b")
```

--------------------------------

### Playwright and OpenBrowser Integration

Source: https://docs.openbrowser.me/examples/templates/playwright-integration

Full example demonstrating how to launch Chrome with remote debugging and connect Playwright to the session.

```python
import asyncio
import os
import subprocess
import sys
import tempfile

from pydantic import BaseModel, Field

# Check for required dependencies first - before other imports
try:
	import aiohttp  # type: ignore
	from playwright.async_api import Browser, Page, async_playwright  # type: ignore
except ImportError as e:
	print(f'❌ Missing dependencies for this example: {e}')
	print('This example requires: playwright aiohttp')
	print('Install with: uv add playwright aiohttp')
	print('Also run: playwright install chromium')
	sys.exit(1)

from openbrowser import Agent, BrowserSession, ChatOpenAI, Tools
from openbrowser.agent.views import ActionResult

# Global Playwright browser instance - shared between custom actions
playwright_browser: Browser | None = None
playwright_page: Page | None = None


# Custom action parameter models
class PlaywrightFillFormAction(BaseModel):
	"""Parameters for Playwright form filling action."""

	customer_name: str = Field(..., description='Customer name to fill')
	phone_number: str = Field(..., description='Phone number to fill')
	email: str = Field(..., description='Email address to fill')
	size_option: str = Field(..., description='Size option (small/medium/large)')


class PlaywrightScreenshotAction(BaseModel):
	"""Parameters for Playwright screenshot action."""

	filename: str = Field(default='playwright_screenshot.png', description='Filename for screenshot')
	quality: int | None = Field(default=None, description='JPEG quality (1-100), only for .jpg/.jpeg files')


class PlaywrightGetTextAction(BaseModel):
	"""Parameters for getting text using Playwright selectors."""

	selector: str = Field(..., description='CSS selector to get text from. Use "title" for page title.')


async def start_chrome_with_debug_port(port: int = 9222):
	"""
	Start Chrome with remote debugging enabled.
	Returns the Chrome process.
	"""
	# Create temporary directory for Chrome user data
	user_data_dir = tempfile.mkdtemp(prefix='chrome_cdp_')

	# Chrome launch command
	chrome_paths = [
		'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',  # macOS
		'/usr/bin/google-chrome',  # Linux
		'/usr/bin/chromium-browser',  # Linux Chromium
		'chrome',  # Windows/PATH
		'chromium',  # Generic
	]

	chrome_exe = None
	for path in chrome_paths:
		if os.path.exists(path) or path in ['chrome', 'chromium']:
			try:
				# Test if executable works
				test_proc = await asyncio.create_subprocess_exec(
					path, '--version', stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
				)
				await test_proc.wait()
				chrome_exe = path
				break
			except Exception:
				continue

	if not chrome_exe:
		raise RuntimeError('❌ Chrome not found. Please install Chrome or Chromium.')

	# Chrome command arguments
	cmd = [
		chrome_exe,
		f'--remote-debugging-port={port}',
		f'--user-data-dir={user_data_dir}',
		'--no-first-run',
		'--no-default-browser-check',
		'--disable-extensions',
		'about:blank',  # Start with blank page
	]

	# Start Chrome process
	process = await asyncio.create_subprocess_exec(*cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)

	# Wait for Chrome to start and CDP to be ready
	cdp_ready = False
	for _ in range(20):  # 20 second timeout
		try:
			async with aiohttp.ClientSession() as session:
				async with session.get(
					f'http://localhost:{port}/json/version', timeout=aiohttp.ClientTimeout(total=1)
				) as response:
					if response.status == 200:
						cdp_ready = True
						break
			except Exception:
				pass
		await asyncio.sleep(1)

	if not cdp_ready:
		process.terminate()
		raise RuntimeError('❌ Chrome failed to start with CDP')

	return process


async def connect_playwright_to_cdp(cdp_url: str):
	"""
	Connect Playwright to the same Chrome instance OpenBrowser is using.
	This enables custom actions to use Playwright functions.
	"""
	global playwright_browser, playwright_page

	playwright = await async_playwright().start()
	playwright_browser = await playwright.chromium.connect_over_cdp(cdp_url)

	# Get or create a page
	if playwright_browser and playwright_browser.contexts and playwright_browser.contexts[0].pages:
		playwright_page = playwright_browser.contexts[0].pages[0]
	elif playwright_browser:
		context = await playwright_browser.new_context()
		playwright_page = await context.new_page()
```

--------------------------------

### Run OpenBrowser via uvx

Source: https://docs.openbrowser.me/quickstart

Execute OpenBrowser directly without permanent installation, ideal for MCP clients.

```bash
# MCP server mode
uvx openbrowser-ai --mcp

# CLI daemon mode
uvx openbrowser-ai -c "await navigate('https://example.com')"
```

--------------------------------

### Initialize Ollama Chat Model

Source: https://docs.openbrowser.me/supported-models

Set up the ChatOllama model for local LLM inference. Requires Ollama to be installed and a model to be pulled (e.g., llama3.1:8b).

```python
llm = ChatOllama(model="llama3.1:8b")
```

--------------------------------

### Specific Task Prompting

Source: https://docs.openbrowser.me/customize/agent/prompting-guide

Use specific, numbered steps to guide the agent through tasks for better accuracy.

```python
task = """
1. Go to https://quotes.toscrape.com/
2. Use extract action with the query "first 3 quotes with their authors"
3. Save results to quotes.csv using write_file action
4. Do a google search for the first quote and find when it was written
"""
```

--------------------------------

### Basic Vibetest Prompts

Source: https://docs.openbrowser.me/examples/apps/vibetest-use

Examples of natural language prompts to initiate Vibetest scans on specified URLs with configurable agent counts and headless mode.

```text
> Vibetest my website with 5 agents: example.com
> Run vibetest on localhost:3000
> Run a headless vibetest on localhost:8080 with 10 agents
```

--------------------------------

### Flash Mode Example

Source: https://docs.openbrowser.me/customize/agent/all-parameters

Enable fast mode by setting `flash_mode` to True. This skips evaluation, next goal, and thinking steps, relying solely on memory. It overrides `use_thinking`.

```python
from openbrowser.agent import Agent

agent = Agent(flash_mode=True)

```

--------------------------------

### Secure Agent Setup with Azure OpenAI

Source: https://docs.openbrowser.me/examples/templates/secure

Set up a secure agent using Azure OpenAI with specific browser profile configurations and sensitive data filtering. Ensure environment variables for API key and endpoint are loaded.

```python
import asyncio
import os
from dotenv import load_dotenv
load_dotenv()
os.environ['ANONYMIZED_TELEMETRY'] = 'false'
from openbrowser import Agent, BrowserProfile, ChatAzureOpenAI

# Azure OpenAI configuration
api_key = os.getenv('AZURE_OPENAI_KEY')
azure_endpoint = os.getenv('AZURE_OPENAI_ENDPOINT')
llm = ChatAzureOpenAI(model='gpt-4.1-mini', api_key=api_key, azure_endpoint=azure_endpoint)

# Secure browser configuration
browser_profile = BrowserProfile(
    allowed_domains=['*google.com', 'example.com'], 
    enable_default_extensions=False
)

# Sensitive data filtering
sensitive_data = {'company_name': 'openbrowser'}

# Create secure agent
agent = Agent(
    task='Find the founders of the sensitive company_name',
    llm=llm,
    browser_profile=browser_profile,
    sensitive_data=sensitive_data
)

async def main():
    await agent.run(max_steps=10)

asyncio.run(main())
```

--------------------------------

### Run Browser Task with n8n

Source: https://docs.openbrowser.me/development/n8n-integration

Example of configuring the OpenBrowser node in n8n to execute a browser task. Specify instructions in natural language and optionally save browser data.

```text
Go to example.com, take a screenshot of the homepage, and extract all the main heading texts
```

--------------------------------

### Execute Python Code via MCP

Source: https://docs.openbrowser.me/customize/integrations/mcp-server

This is an example of how an AI assistant might use the `execute_code` tool to perform browser automation tasks. All functions are async and require `await`.

```python
# Example usage within an AI assistant prompt:
# "Navigate to example.com and extract all the links"
# "Search for 'browser automation' on Google and summarize the first 3 results"
# "Go to GitHub, find the openbrowser repository, and tell me about the latest release"
```

--------------------------------

### Initialize .env File

Source: https://docs.openbrowser.me/quickstart

Create a configuration file for API keys.

```bash
touch .env
```

--------------------------------

### Initialize Browser and Agent

Source: https://docs.openbrowser.me/customize/actor/basics

Demonstrates setting up the browser session, performing precise element interaction, and executing an AI-driven task.

```python
from openbrowser import Browser, Agent
from openbrowser.llm.openai import ChatOpenAI

async def main():
    llm = ChatOpenAI(api_key="your-api-key")
    browser = Browser()
    await browser.start()

    # 1. Actor: Precise navigation and element interactions
    page = await browser.new_page("https://github.com/login")
    email_input = await page.must_get_element_by_prompt("username field", llm=llm)
    await email_input.fill("your-username")

    # 2. Agent: AI-driven complex tasks
    agent = Agent(browser=browser, llm=llm)
    await agent.run("Complete login and navigate to my repositories")

    await browser.stop()
```

--------------------------------

### Perform Initial Login

Source: https://docs.openbrowser.me/examples/apps/msg-use

Run the login script to authenticate with WhatsApp Web via QR code.

```bash
python login.py
```

--------------------------------

### Initialize and Run OpenBrowser Agent

Source: https://docs.openbrowser.me/customize/browser/basics

Initialize a Browser instance, configure an Agent with a task and LLM, and then run the agent. Ensure the browser window is visible by setting headless to False.

```python
from openbrowser import Agent, Browser, ChatBrowserUse

browser = Browser(
	headless=False,  # Show browser window
	window_size={'width': 1000, 'height': 700},  # Set window size
)

agent = Agent(
	task='Search for OpenBrowser',
	browser=browser,
	llm=ChatBrowserUse(),
)


async def main():
	await agent.run()
```

--------------------------------

### Configure Production Best Practices

Source: https://docs.openbrowser.me/production

Implements production-ready settings including headless mode, domain restrictions, and proxy configuration.

```python
from openbrowser import Agent, Browser, ChatGoogle

browser = Browser(
    headless=True,
    allowed_domains=['*.example.com'],
    proxy={'server': 'http://proxy:8080'},
)

agent = Agent(
    task="Production task",
    browser=browser,
    llm=ChatGoogle(),
)
```

--------------------------------

### Initialize Browser with BrowserProfile

Source: https://docs.openbrowser.me/customize/browser/all-parameters

Demonstrates backward compatibility by passing a BrowserProfile to the Browser constructor.

```python
from openbrowser import BrowserProfile
profile = BrowserProfile(headless=False)
browser = Browser(browser_profile=profile)
```

--------------------------------

### Update openbrowser-ai package

Source: https://docs.openbrowser.me/customize/integrations/mcp-server

Ensures the latest version of the package is installed to support MCP functionality.

```bash
pip install --upgrade openbrowser-ai
```

--------------------------------

### BrowserSession Management

Source: https://docs.openbrowser.me/customize/actor/all-parameters

Manage browser sessions, including starting, stopping, and creating new pages.

```APIDOC
## Browser (BrowserSession)

Main browser session manager.

### Key Methods

```python  theme={null}
from openbrowser import Browser

browser = Browser()
await browser.start()

# Page management
page = await browser.new_page("https://example.com")
pages = await browser.get_pages()
current = await browser.get_current_page()
await browser.close_page(page)

# To stop the browser session
await browser.stop()
```

### Constructor Parameters

See [Browser Parameters](../browser/all-parameters) for complete configuration options.
```

--------------------------------

### Initialize an Agent with Tools

Source: https://docs.openbrowser.me/customize/tools/add

An Agent is initialized with a task, an LLM, and a set of tools. The agent will use these tools to accomplish the given task.

```python
agent = Agent(task='...', llm=llm, tools=tools)
```

--------------------------------

### Scheduler Output Format

Source: https://docs.openbrowser.me/examples/apps/msg-use

Example of the structured JSON output generated by the scheduler after parsing natural language.

```json
[
  {
    "contact": "Magnus",
    "original_message": "Hi",
    "composed_message": "Hi",
    "scheduled_time": "2025-06-13 18:15"
  },
  {
    "contact": "Camila", 
    "original_message": "I miss her",
    "composed_message": "I miss you ❤️",
    "scheduled_time": "2025-06-14 20:00"
  },
  {
    "contact": "sister",
    "original_message": "happy birthday message", 
    "composed_message": "Happy birthday! 🎉 Wishing you an amazing day, sis! Hope you have the best birthday ever! ❤️🎂🎈",
    "scheduled_time": "2025-06-15 09:00"
  }
]
```

--------------------------------

### Configure Qwen via DashScope

Source: https://docs.openbrowser.me/customize/supported-models

Integration for Qwen models using the DashScope compatible API. Requires the ALIBABA_CLOUD environment variable.

```python
from openbrowser import Agent, ChatOpenAI
from dotenv import load_dotenv
import os

load_dotenv()

# Get API key from https://modelstudio.console.alibabacloud.com/?tab=playground#/api-key
api_key = os.getenv('ALIBABA_CLOUD')
base_url = 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1'

llm = ChatOpenAI(model='qwen-vl-max', api_key=api_key, base_url=base_url)

agent = Agent(
    task="Your task here",
    llm=llm,
    use_vision=True
)
```

```text
ALIBABA_CLOUD=
```

--------------------------------

### Clone Repository

Source: https://docs.openbrowser.me/examples/apps/msg-use

Download the application source code and navigate to the project directory.

```bash
git clone https://github.com/billy-enrizky/openbrowser-ai.git
cd openbrowser/examples/apps/msg-use
```

--------------------------------

### Open-Ended Task Prompting

Source: https://docs.openbrowser.me/customize/agent/prompting-guide

Avoid vague instructions that lack actionable steps.

```python
task = "Go to web and make money"
```

--------------------------------

### News Article Output Format

Source: https://docs.openbrowser.me/examples/apps/news-use

Example of how extracted articles are displayed, including timestamp, sentiment indicator, and summary.

```text
[2025-09-11 02:49:21] - 🟢 - Klarna's IPO raises $1.4B, benefiting existing investors
[2025-09-11 02:54:15] - 🔴 - Tech layoffs continue as major firms cut workforce
[2025-09-11 02:59:33] - 🟡 - Federal Reserve maintains interest rates unchanged
```

--------------------------------

### Execute Browser and Data Processing Logic

Source: https://docs.openbrowser.me/customize/code-agent/basics

Example of combining JavaScript for browser interaction and Python for data processing.

```js
(function(){
  return Array.from(document.querySelectorAll('.product')).map(p => ({
    name: p.querySelector('.name').textContent,
    price: p.querySelector('.price').textContent
  }))
})()
```

```python
import pandas as pd

products = await evaluate(extract_products) # reuse other code blocks
df = pd.DataFrame(products)
df.to_csv('products.csv', index=False)
```

--------------------------------

### Initialize Laminar in Python

Source: https://docs.openbrowser.me/development/monitoring/observability

Initialize Laminar at the start of your project to enable automatic tracing of OpenBrowser and session recordings.

```python
from openbrowser import Agent, ChatGoogle
import asyncio

from lmnr import Laminar, Instruments
# this line auto-instruments OpenBrowser and any browser you use (local or remote)
Laminar.initialize(project_api_key="...", disabled_instruments={Instruments.OPENBROWSER_SESSION})

async def main():
    agent = Agent(
        task="open google, search Laminar AI",
        llm=ChatGoogle(),
    )
    await agent.run()

asyncio.run(main())
```

--------------------------------

### Platform-Specific Chrome Paths

Source: https://docs.openbrowser.me/customize/browser/real-browser

Provides the necessary paths for Chrome installations on macOS, Windows, and Linux to configure the browser connection.

```python
# macOS
executable_path='/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
user_data_dir='~/Library/Application Support/Google/Chrome'
```

```python
# Windows
executable_path='C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'
user_data_dir='%LOCALAPPDATA%\\Google\\Chrome\\User Data'
```

```python
# Linux
executable_path='/usr/bin/google-chrome'
user_data_dir='~/.config/google-chrome'
```

--------------------------------

### Configure LLM API Keys

Source: https://docs.openbrowser.me/quickstart

Add provider-specific API keys to the .env file.

```bash
# add your key to .env file
GOOGLE_API_KEY=
# Get your free Gemini API key from https://aistudio.google.com/app/u/1/apikey
```

```bash
# add your key to .env file
OPENAI_API_KEY=
```

```bash
# add your key to .env file
ANTHROPIC_API_KEY=
```

--------------------------------

### Run Agent with Lifecycle Hooks

Source: https://docs.openbrowser.me/customize/hooks

Initiates agent execution, specifying custom functions to be called at the start and end of each step.

```python
await agent.run(on_step_start=..., on_step_end=...)
```

--------------------------------

### Initialize OpenLIT Instrumentation

Source: https://docs.openbrowser.me/development/monitoring/openlit

Enable automatic instrumentation by calling openlit.init() before executing agent tasks.

```python
from openbrowser import Agent, Browser, ChatOpenAI
import asyncio
import openlit

# Initialize OpenLIT - that's it!
openlit.init()

async def main():
	browser = Browser()

	llm = ChatOpenAI(
		model="gpt-4o",
	)

	agent = Agent(
		task="Find the number trending post on Hacker news",
		llm=llm,
		browser=browser,
	)

	history = await agent.run()
	return history

if __name__ == "__main__":
	history = asyncio.run(main())
```

--------------------------------

### Define Tool Return Types

Source: https://docs.openbrowser.me/customize/tools/response

Examples of returning simple strings versus structured ActionResult objects for complex tool outputs.

```python
@tools.action('My tool')
def my_tool() -> str:
    return "Task completed successfully"

@tools.action('Advanced tool')
def advanced_tool() -> ActionResult:
    return ActionResult(
        extracted_content="Main result",
        long_term_memory="Remember this info",
        error="Something went wrong",
        is_done=True,
        success=True,
        attachments=["file.pdf"],
    )
```

--------------------------------

### Access Documentation via URL

Source: https://docs.openbrowser.me/quickstart_llm

Direct link to the OpenBrowser documentation for AI context.

```text
https://docs.openbrowser.me
```

--------------------------------

### Manage the CLI daemon process

Source: https://docs.openbrowser.me/customize/integrations/cli-daemon

Control the background daemon lifecycle, including starting, stopping, and checking the status of the browser session.

```bash
uvx openbrowser-ai daemon start     # Start daemon (auto-starts on first -c call)
uvx openbrowser-ai daemon stop      # Stop daemon and close browser
uvx openbrowser-ai daemon status    # Show PID, init state, idle timeout
uvx openbrowser-ai daemon restart   # Restart with fresh browser session
```

--------------------------------

### Sensitive Data Handling Example

Source: https://docs.openbrowser.me/customize/agent/all-parameters

Configure sensitive data handling by providing a dictionary of sensitive information. The agent will handle this data with care.

```python
from openbrowser.agent import Agent

agent = Agent(sensitive_data={"api_key": "YOUR_API_KEY"})

```

--------------------------------

### Initialize ChatBrowserUse Agent

Source: https://docs.openbrowser.me/supported-models

Use this snippet to configure the Agent with the ChatBrowserUse LLM service.

```python
from openbrowser import Agent, ChatBrowserUse

# Initialize the model
llm = ChatBrowserUse()

# Create agent with the model
agent = Agent(
    task="...", # Your task here
    llm=llm
)
```

--------------------------------

### Return Simple Tool Output

Source: https://docs.openbrowser.me/customize/tools/response

Returning a string keeps the output in the LLM context for all future steps.

```python
def simple_tool() -> str:
    return "Hello, world!"  # Keep in context for all future steps 
```

--------------------------------

### Initialize and Manage Browser Session

Source: https://docs.openbrowser.me/customize/actor/all-parameters

Use this snippet to start, manage pages, and stop a browser session. Ensure the Browser class is imported.

```python
from openbrowser import Browser

browser = Browser()
await browser.start()

# Page management
page = await browser.new_page("https://example.com")
pages = await browser.get_pages()
current = await browser.get_current_page()
await browser.close_page(page)

# To stop the browser session
await browser.stop()
```

--------------------------------

### Configure Fast LLM Models

Source: https://docs.openbrowser.me/examples/templates/fast-agent

Select high-performance LLM providers like Groq or Google Gemini Flash to reduce inference latency.

```python
# Groq - Ultra-fast inference
from openbrowser import ChatGroq
llm = ChatGroq(model='meta-llama/llama-4-maverick-17b-128e-instruct')

# Google Gemini Flash - Optimized for speed
from openbrowser import ChatGoogle
llm = ChatGoogle(model='gemini-flash-lite-latest')
```

--------------------------------

### Initialize Groq Model

Source: https://docs.openbrowser.me/supported-models

Requires GROQ_API_KEY to be set in the environment.

```python
from openbrowser import Agent, ChatGroq

llm = ChatGroq(model="meta-llama/llama-4-maverick-17b-128e-instruct")

agent = Agent(
    task="Your task here",
    llm=llm
)
```

```bash
GROQ_API_KEY=
```

--------------------------------

### Configure via Environment Variables

Source: https://docs.openbrowser.me/development/monitoring/openlit

Set OpenTelemetry configuration using standard environment variables instead of code-level initialization.

```bash
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_SERVICE_NAME="browser-automation"
export OTEL_ENVIRONMENT="production"
```

--------------------------------

### Custom Output Model Schema Example

Source: https://docs.openbrowser.me/customize/agent/all-parameters

Use this to define a Pydantic model for structured output validation. Ensure the model class is correctly specified.

```python
from openbrowser.agent import Agent
from pydantic import BaseModel

class CustomOutput(BaseModel):
    name: str
    age: int

agent = Agent(output_model_schema=CustomOutput)

```

--------------------------------

### Configure .env for Alibaba Cloud

Source: https://docs.openbrowser.me/supported-models

Environment variable file for storing Alibaba Cloud API key.

```bash
ALIBABA_CLOUD=
```

--------------------------------

### Initialize ModelScope Chat Model

Source: https://docs.openbrowser.me/supported-models

Set up the ChatOpenAI model for ModelScope's Qwen2.5-VL-72B-Instruct. Requires MODELSCOPE_API_KEY environment variable.

```python
load_dotenv()

# Get API key from https://www.modelscope.cn/docs/model-service/API-Inference/intro
api_key = os.getenv('MODELSCOPE_API_KEY')
base_url = 'https://api-inference.modelscope.cn/v1/'

llm = ChatOpenAI(model='Qwen/Qwen2.5-VL-72B-Instruct', api_key=api_key, base_url=base_url)

agent = Agent(
    task="Your task here",
    llm=llm,
    use_vision=True
)
```

--------------------------------

### Run Stress Test with OpenBrowser Agent

Source: https://docs.openbrowser.me/examples/apps/stress-tests

Automates filling out a React Native Web Form using the OpenBrowser agent. Ensure you have the necessary libraries installed.

```python
import asyncio
from openbrowser import Agent, ChatGoogle

async def run_stress_test():
    agent = Agent(
        task="Go to https://billy-enrizky.github.io/openbrowser-ai/challenges/react-native-web-form.html and fill out the form with test data",
        llm=ChatGoogle(),
    )
    await agent.run()

asyncio.run(run_stress_test())
```

--------------------------------

### Connect to Remote Browser via CDP

Source: https://docs.openbrowser.me/production

Connects to a remote Chrome instance using the Chrome DevTools Protocol. Requires starting Chrome with the --remote-debugging-port flag.

```python
from openbrowser import Agent, Browser, ChatGoogle

# Connect to existing Chrome instance
# Start Chrome with: chrome --remote-debugging-port=9222
browser = Browser(cdp_url="http://localhost:9222")

agent = Agent(
    task="your task",
    browser=browser,
    llm=ChatGoogle()
)
await agent.run()
```

--------------------------------

### Initialize Groq Chat Model

Source: https://docs.openbrowser.me/customize/supported-models

Initialize the ChatGroq model. Ensure GROQ_API_KEY is set in your environment.

```python
from openbrowser import Agent, ChatGroq

llm = ChatGroq(model="meta-llama/llama-4-maverick-17b-128e-instruct")

agent = Agent(
    task="Your task here",
    llm=llm
)
```

--------------------------------

### Docker Setup for Chrome CDP

Source: https://docs.openbrowser.me/customize/browser/remote

Dockerfile and commands to build and run a Docker container with Chrome enabled for remote debugging. This provides a consistent environment for CDP connections.

```dockerfile
FROM zenika/alpine-chrome:latest

# Expose CDP port
EXPOSE 9222

# Start Chrome with remote debugging
CMD ["chromium-browser", "--headless", "--disable-gpu", "--remote-debugging-address=0.0.0.0", "--remote-debugging-port=9222"]
```

```bash
docker build -t chrome-cdp .
docker run -p 9222:9222 chrome-cdp
```

```python
browser = Browser(cdp_url="http://localhost:9222")
```

--------------------------------

### Initialize AWS Bedrock Models

Source: https://docs.openbrowser.me/supported-models

Supports general Bedrock clients or provider-specific convenience classes. Authentication can be handled via environment variables, profiles, or IAM roles.

```python
from openbrowser import Agent, ChatAWSBedrock

# Works with any Bedrock model (Anthropic, Meta, AI21, etc.)
llm = ChatAWSBedrock(
    model="anthropic.claude-3-5-sonnet-20240620-v1:0",  # or any Bedrock model
    aws_region="us-east-1",
)

# Create agent with the model
agent = Agent(
    task="Your task here",
    llm=llm
)
```

```python
from openbrowser import Agent, ChatAnthropicBedrock

# Anthropic-specific class with Claude defaults
llm = ChatAnthropicBedrock(
    model="anthropic.claude-3-5-sonnet-20240620-v1:0",
    aws_region="us-east-1",
)

# Create agent with the model
agent = Agent(
    task="Your task here",
    llm=llm
)
```

```bash
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=us-east-1
```

--------------------------------

### Initialize OCI Generative AI Model

Source: https://docs.openbrowser.me/supported-models

Configure the ChatOCIRaw model for OCI Generative AI. Ensure your OCI configuration file is set up and the OCI Python SDK is installed.

```python
llm = ChatOCIRaw(
    model_id="ocid1.generativeaimodel.oc1.us-chicago-1.amaaaaaask7dceya...",
    service_endpoint="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com",
    compartment_id="ocid1.tenancy.oc1..aaaaaaaayeiis5uk2nuubznrekd...",
    provider="meta",  # or "cohere"
    temperature=0.7,
    max_tokens=800,
    top_p=0.9,
    auth_type="API_KEY",
    auth_profile="DEFAULT"
)

# Create agent with the model
agent = Agent(
    task="Your task here",
    llm=llm
)
```

--------------------------------

### Run Agent with Anthropic LLM

Source: https://docs.openbrowser.me/quickstart

This example demonstrates running an agent with the Anthropic LLM, using the claude-sonnet-4-0 model and a temperature of 0.0. Load environment variables via dotenv.

```python
from openbrowser import Agent, ChatAnthropic
from dotenv import load_dotenv
import asyncio

load_dotenv()

async def main():
    llm = ChatAnthropic(model='claude-sonnet-4-0', temperature=0.0)
    task = "Find the number 1 post on Show HN"
    agent = Agent(task=task, llm=llm)
    await agent.run()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Initialize Agent with LLM

Source: https://docs.openbrowser.me/customize/supported-models

Basic structure for initializing an OpenBrowser agent with a specified LLM instance.

```python
agent = Agent(
    task="Your task here",
    llm=llm
)
```

--------------------------------

### Initialize Google Gemini Model

Source: https://docs.openbrowser.me/supported-models

Requires GOOGLE_API_KEY in the environment. Note that GEMINI_API_KEY is deprecated as of 2025-05.

```python
from openbrowser import Agent, ChatGoogle
from dotenv import load_dotenv

# Read GOOGLE_API_KEY into env
load_dotenv()

# Initialize the model
llm = ChatGoogle(model='gemini-flash-latest')

# Create agent with the model
agent = Agent(
    task="Your task here",
    llm=llm
)
```

```bash
GOOGLE_API_KEY=
```

--------------------------------

### Start Chrome with Remote Debugging

Source: https://docs.openbrowser.me/customize/browser/remote

Commands to launch Chrome with the remote debugging port enabled on different operating systems. This allows external tools to connect via CDP.

```bash
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

# Windows
chrome.exe --remote-debugging-port=9222
```

--------------------------------

### Configure Custom OTLP Endpoints

Source: https://docs.openbrowser.me/development/monitoring/openlit

Use custom parameters in openlit.init() to point to specific OTLP endpoints or set application metadata.

```python
import openlit

# Configure custom OTLP endpoints
openlit.init(
	otlp_endpoint="http://localhost:4318",
	application_name="my-browser-automation",
	environment="production"
)
```

--------------------------------

### Chrome DevTools MCP Get Page State

Source: https://docs.openbrowser.me/comparison

Chrome DevTools MCP's `take_snapshot` command retrieves the full accessibility tree, providing detailed element information.

```text
uid=1_0 RootWebArea url="https://httpbin.org/forms/post"
  uid=1_1 StaticText "Customer name: "
  uid=1_2 textbox "Customer name: "
  uid=1_3 StaticText "Telephone: "
  uid=1_4 textbox "Telephone: "
  uid=1_5 StaticText "E-mail address: "
  uid=1_6 textbox "E-mail address: "
  ... (entire page tree)
```

--------------------------------

### Playwright MCP Get Page State

Source: https://docs.openbrowser.me/comparison

Playwright MCP's `browser_snapshot` returns the full accessibility tree, similar to its navigation response. This is useful for detailed analysis but can be large.

```yaml
- generic [ref=e2]:
  - paragraph [ref=e3]:
    - generic [ref=e4]:
      - text: "Customer name:"
      - textbox "Customer name:" [ref=e5]
  ... (entire page tree)
```

--------------------------------

### Chrome DevTools MCP Navigate Response

Source: https://docs.openbrowser.me/comparison

Chrome DevTools MCP provides a minimal URL confirmation for navigation. To get page details, an explicit `take_snapshot` command is required.

```text
# navigate_page response
Successfully navigated to https://httpbin.org/forms/post.
## Pages
1: https://httpbin.org/forms/post [selected]
```

--------------------------------

### Initialize OpenAI Model

Source: https://docs.openbrowser.me/supported-models

Supports any OpenAI compatible model by passing the model name. O3 is recommended for best accuracy.

```python
from openbrowser import Agent, ChatOpenAI

# Initialize the model
llm = ChatOpenAI(
    model="o3",
)

# Create agent with the model
agent = Agent(
    task="...", # Your task here
    llm=llm
)
```

```bash
OPENAI_API_KEY=
```

--------------------------------

### Interact with Browser Session

Source: https://docs.openbrowser.me/customize/hooks

Directly access the BrowserSession and CDP interface to manage browser interactions, including getting CDP sessions, tabs, current URL, and page title.

```python
agent.browser_session.agent_focus
```

```python
agent.browser_session.get_or_create_cdp_session()
```

```python
agent.browser_session.get_tabs()
```

```python
agent.browser_session.get_current_page_url()
```

```python
agent.browser_session.get_current_page_title()
```
Tokens:
Raw