Custom Browser Implementation
Relevant source files
The following files were used as context for generating this wiki page:
The Custom Browser Implementation in the web-ui project provides an enhanced wrapper around the standard Playwright-based browser sessions. Its primary purpose is to allow AI agents to utilize existing user browser profiles, enabling access to authenticated sessions (like logged-in accounts) without manual re-authentication. This implementation supports both transient and persistent sessions, high-definition recording, and customized Chromium arguments for specialized research tasks.
Sources: README.md:27-31, src/utils/deep_research.py:44-58
Core Architecture and Initialization
The system utilizes CustomBrowser, a subclass of the base Browser class, to manage the lifecycle of the browser instance. It primarily interfaces with Playwright to launch Chromium with specific configurations. A key feature is the ability to point the browser to a local Chrome executable and user data directory via environment variables CHROME_PATH and CHROME_USER_DATA.
Browser Configuration Workflow
When the system initializes a custom browser, it evaluates whether to use a local installation or a managed Playwright instance. If a local browser is specified, it constructs a list of Chromium arguments, including the --user-data-dir to maintain state across sessions.
The diagram above shows the decision logic for selecting between a managed browser and a user-provided browser profile.
Sources: src/utils/deep_research.py:44-58, webui.py:228-245
Persistent Sessions and Context Management
The implementation supports persistent browser sessions, where the browser window can remain open between different AI tasks. This is managed through global variables in the WebUI and specific flags in the configuration.
Global State Persistence
The system maintains global references to ensure that a single browser context can be reused across multiple agent runs if keep_browser_open is enabled.
| Variable | Description | Source |
|---|---|---|
_global_browser | Stores the active CustomBrowser or Browser instance. | webui.py:43 |
_global_browser_context | Stores the active BrowserContext for the session. | webui.py:44 |
CHROME_PERSISTENT_SESSION | Environment variable to toggle persistence. | README.md:143 |
Context Configuration
Contexts are created with specific window dimensions and recording settings. For "Deep Research" tasks, the system automatically sets the max_query_num to 1 when using a custom browser to ensure stability within a shared profile.
Sources: webui.py:260-271, src/utils/deep_research.py:48-50
Integration with AI Agents
The CustomAgent class is designed to interact specifically with these browser contexts. It utilizes CustomSystemPrompt and CustomAgentMessagePrompt to communicate the state of the browser, including interactive elements and visual context, back to the Large Language Model (LLM).
Agent-Browser Interaction Flow
This sequence illustrates the loop of the agent observing the state through the custom context and executing actions via Playwright.
Sources: src/agent/custom_agent.py:270-305, src/agent/custom_prompts.py:87-130
Configuration and Environment Variables
The custom browser behavior is highly dependent on environment configuration. Users can define these in a .env file to customize the execution environment.
| Variable | Type | Default | Description |
|---|---|---|---|
CHROME_PATH | Path | None | Absolute path to the Chrome/Chromium executable. |
CHROME_USER_DATA | Path | None | Path to the browser profile directory. |
HEADLESS | Boolean | False | Whether to run the browser without a visible GUI. |
DISABLE_SECURITY | Boolean | True | Disables web security for easier interaction. |
Sources: README.md:120-130, webui.py:229-234
Implementation Snippet: Initialization in Deep Research
The following code demonstrates how the CustomBrowser is instantiated within the research module, handling both own-browser logic and Chromium arguments.
# From src/utils/deep_research.py:53-65
browser = CustomBrowser(
config=BrowserConfig(
headless=kwargs.get("headless", False),
disable_security=kwargs.get("disable_security", True),
chrome_instance_path=chrome_path,
extra_chromium_args=extra_chromium_args,
)
)
browser_context = await browser.new_context()
Summary
The Custom Browser Implementation provides a bridge between standard AI automation and personalized user environments. By wrapping Playwright's Browser and Context classes, the system enables persistent sessions and the use of local browser profiles, which are critical for tasks requiring authentication or continuity. This architecture allows the CustomAgent to operate with high fidelity, leveraging existing browser state to complete complex web-based workflows.