Browser Management

Relevant source files

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

• browser_use/browser/context.py
• browser_use/controller/service.py
• browser_use/dom/service.py
• browser_use/dom/buildDomTree.js
• browser_use/agent/views.py
• README.md

The Browser Management system in browser-use provides a high-level abstraction over Playwright to enable AI agents to interact with web browsers. It manages the lifecycle of browser instances, contexts, and pages, while providing specialized tools for state extraction and element interaction.

The system is designed to transform raw web content into a structured format that LLMs can process, while also providing a robust set of actions (clicking, typing, scrolling) that the agent can execute reliably. It handles complex browser behaviors such as tab management, iframe navigation, and network stability monitoring.

Sources: README.md:1-25, browser_use/browser/context.py:1-40

Core Architecture and Session Management

Browser management is centered around the BrowserContext class, which manages a BrowserSession. This session tracks the Playwright context, the current active page, and a cached state of the browser.

Session Lifecycle

The BrowserContext supports asynchronous context management (__aenter__/__aexit__), ensuring that resources like tracing, video recordings, and cookies are properly initialized and saved upon closure.

The session initialization logic ensures that if a browser is connected via CDP or an existing Chrome instance, it reuses existing contexts rather than creating new ones.
Sources: browser_use/browser/context.py:129-210

Configuration Options

The BrowserContextConfig class defines the operational parameters for the browser environment.

Option	Type	Default	Description
cookies_file	str | None	None	Path for persistent cookie storage.
minimum_wait_page_load_time	float	0.5	Min wait before state extraction.
wait_for_network_idle_page_load_time	float	1.0	Idle time required for stability.
browser_window_size	dict	1280x1100	Default viewport dimensions.
highlight_elements	bool	True	Whether to draw overlays on elements.
viewport_expansion	int	500	Pixels beyond viewport to include in state.

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

State Extraction and DOM Processing

The system uses a combination of Python logic and injected JavaScript to extract a "clean" representation of the DOM for the AI.

The DOM Service

The DomService coordinates the execution of buildDomTree.js within the browser page. This script traverses the DOM, identifies interactive elements, and calculates their coordinates.

Interaction Filtering

Not all DOM elements are presented to the agent. The buildDomTree.js script applies specific filters:

1. Visibility: Uses getComputedStyle and offsetWidth/Height to ensure elements are not hidden.
2. Interactivity: Checks for tags like <a>, <button>, <input>, or elements with ARIA roles, tabindex, or attached click listeners.
3. Top-level Check: Uses document.elementFromPoint to verify an element isn't obscured by overlays.

Sources: browser_use/dom/buildDomTree.js:154-320

Action Execution and Navigation

Actions are executed through the Controller, which translates high-level agent commands into specific Playwright operations.

Multi-Action Flow

The controller supports executing a sequence of actions in one step. It monitors the page between actions; if the page structure changes significantly (detected by comparing path hashes), it halts the sequence to prevent errors against a stale DOM.

Key Navigation Functions

• Network Stabilization: _wait_for_stable_network filters out tracking, analytics, and streaming requests to ensure the LLM only sees the page once primary content is loaded.
• URL Whitelisting: The system checks allowed_domains before navigation and during page events to prevent the agent from leaving permitted boundaries.
• Tab Management: Supports creating, switching, and closing tabs, with the session always maintaining a reference to the current_page.

Sources: browser_use/browser/context.py:270-360, browser_use/browser/context.py:650-690

Selector Logic and Anti-Detection

To ensure high reliability, the system generates robust CSS selectors for elements identified by the LLM.

Enhanced Selectors

The _enhanced_css_selector_for_element method constructs selectors by combining:

• Standard attributes (ID, name, type).
• Accessibility labels (aria-label).
• Data attributes (data-testid, data-qa).
• Tag-specific nth-of-type logic derived from XPaths.

Sources: browser_use/browser/context.py:537-620

Anti-Detection Measures

When creating a browser context, the system injects scripts to mask Playwright's presence:

• Redefines navigator.webdriver to undefined.
• Mocks navigator.languages and navigator.plugins.
• Overwrites permissions.query to prevent detection of automation-related permission states.

Sources: browser_use/browser/context.py:237-268

Summary

Browser Management in this project provides a specialized environment where web pages are treated as structured data sources. By managing sessions, stabilizing network state, and providing an optimized DOM tree, it allows AI agents to interact with the web with human-like logic while maintaining the precision of automated testing tools.