Introduction & Quick Start

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• browser_use/browser/context.py
• browser_use/controller/service.py
• browser_use/agent/prompts.py
• pyproject.toml
• browser_use/agent/message_manager/service.py

Browser-use is a Python-based library designed to connect AI agents with web browsers, enabling automated interaction with websites through Large Language Models (LLMs). It provides a structured interface for agents to analyze webpage elements, execute complex sequences of actions, and maintain state across browser sessions. The system abstracts away the complexities of DOM manipulation and browser control by leveraging Playwright and LangChain to provide a high-level API for browser automation.

Sources: README.md:1-24, pyproject.toml:1-30

Core Architecture

The browser-use architecture consists of several key components working in orchestration: the Agent, the Controller, and the BrowserContext. The Agent serves as the high-level orchestrator that manages the task loop, while the Controller registers and executes specific browser actions. The BrowserContext manages the underlying Playwright session, providing anti-detection measures and state extraction capabilities.

System Workflow Diagram

This diagram illustrates the flow of information from the user's task through the AI Agent to the actual browser interaction.

Installation & Environment Setup

Browser-use requires Python version 3.11 or higher. The setup process involves installing the library via pip and configuring the necessary browser drivers through Playwright.

Step	Command	Description
1	pip install browser-use	Installs the core library and dependencies including LangChain and Pydantic.
2	playwright install	Downloads the necessary browser binaries (Chromium, Firefox, WebKit).
3	.env configuration	Define OPENAI_API_KEY or other provider keys for LLM access.

Sources: README.md:28-60, pyproject.toml:10-15

Quick Start Implementation

A basic implementation requires an LLM instance (e.g., GPT-4o) and an Agent initialized with a specific task.

from langchain_openai import ChatOpenAI
from browser_use import Agent
import asyncio

async def main():
    agent = Agent(
        task="Search for 'browser-use' on Reddit and return the first comment.",
        llm=ChatOpenAI(model="gpt-4o"),
    )
    result = await agent.run()
    print(result)

asyncio.run(main())

Sources: README.md:40-55

Browser & Context Configuration

The BrowserContext manages the session lifecycle and provides extensive configuration options for security, performance, and interaction behavior.

Configuration Parameters

The BrowserContextConfig class defines how the browser behaves during a session.

Parameter	Type	Default	Description
wait_between_actions	float	1.0	Delay in seconds between sequential actions in a single step.
disable_security	bool	False	Disables browser security features (CSP, HTTPS errors).
highlight_elements	bool	True	Visually highlights the elements the AI is interacting with.
browser_window_size	dict	1280x1100	Initial viewport dimensions.
allowed_domains	list	None	Optional whitelist for restricted navigation.

Sources: browser_use/browser/context.py:46-115

Anti-Detection Measures

To prevent bot detection, the BrowserContext injects initialization scripts that modify standard browser properties. These include:

• Masking the navigator.webdriver property.
• Mocking navigator.languages and navigator.plugins.
• Overriding window.chrome and permission query behaviors.

Sources: browser_use/browser/context.py:205-245

Controller and Action Registry

The Controller acts as a bridge between the AI's intent and browser execution. It maintains a registry of available actions that the LLM can call.

Execution Sequence

The following sequence diagram shows how an action is processed by the Controller.

Default Supported Actions

By default, the Controller registers various navigation and interaction functions:

• Navigation: search_google, go_to_url, go_back, open_tab.
• Interaction: click_element, input_text, scroll_down, send_keys.
• Extraction: extract_content, get_dropdown_options.

Sources: browser_use/controller/service.py:50-180

State and Prompting

The MessageManager and SystemPrompt classes define how the AI perceives the browser state. The state is represented as a structured BrowserState object containing:

• URL & Tabs: Information on all open pages.
• Interactive Elements: A simplified DOM tree where elements are assigned unique indices (e.g., [33]<button>).
• Visual Context: Base64 encoded screenshots (if vision is enabled).

Sources: browser_use/agent/prompts.py:15-100, browser_use/agent/message_manager/service.py:170-200

Important Rules for Agents

The system prompt enforces strict operational constraints on the agent:

1. Response Format: Must always be valid JSON containing current_state and action sequence.
2. Action Sequencing: Multiple actions can be executed per step, but the sequence is interrupted if the page changes.
3. Task Completion: The done action must be used only when the ultimate user goal is met.

Sources: browser_use/agent/prompts.py:25-85

Conclusion

Browser-use provides a robust framework for building browser-aware AI agents. By combining automated state extraction with a flexible action registry and anti-detection capabilities, it allows developers to focus on high-level task logic rather than low-level browser automation scripts. The library's reliance on structured JSON communication and standardized DOM representation ensures compatibility across various LLM providers.