Browser Use Web UI

Use Docker to run the Web UI and VNC viewer. Ensure Docker and Docker Compose are installed.

1. Clone the repository:

   git clone https://github.com/browser-use/web-ui.git
   cd web-ui

2. Configure environment: Create a .env file from the example:

   • Windows (Command Prompt): copy .env.example .env
   • macOS/Linux/Windows (PowerShell): cp .env.example .env Add your API keys to the .env file.

3. Build and run: For standard systems:

   docker compose up --build

   For ARM64 systems (e.g., Apple Silicon Macs):

   TARGETPLATFORM=linux/arm64 docker compose up --build

4. Access services:

   • Web-UI: http://localhost:7788
   • VNC Viewer: http://localhost:6080/vnc.html (Default password: youvncpassword. Change this via VNC_PASSWORD in .env).

The DeepResearchAgent supports resuming interrupted research tasks. By providing the task_id of a previous run to the run() method, the agent attempts to load the previous state (including the research plan and collected search results) from the save_dir and continues from the next pending task.

# Resuming a task with ID 'abc-123'
result = await agent.run(
    topic="The impact of quantum computing on modern cryptography",
    task_id="abc-123"
)

The BrowserUseAgent determines how it interacts with the LLM's tool-calling capabilities via the _set_tool_calling_method() internal logic. This is driven by self.settings.tool_calling_method.

If set to 'auto', the agent selects a method based on the model and library:

• ChatOpenAI or AzureChatOpenAI: Uses 'function_calling'.
• Models without native tool support: Uses 'raw'.
• ChatGoogleGenerativeAI or other libraries: Returns None (relying on default model behavior).

Users can explicitly set the tool_calling_method in their settings to override this automatic selection.

The deep research process is implemented as a state machine using Langgraph, moving through three primary nodes:

1. Planning Node (planning_node): Generates a hierarchical research plan (categories and tasks) based on the topic. It saves this plan to research_plan.md to allow for persistence and resumption.
2. Research Execution Node (research_execution_node): Iterates through the plan. For each task, it invokes the LLM, which can call tools like parallel_browser_search. Results are saved to search_info.json and the plan is updated with task statuses (pending, completed, failed).
3. Synthesis Node (synthesis_node): Once all tasks are processed, this node aggregates all search_results and uses the LLM to write a comprehensive final report, saved as report.md.

The BrowserUseAgent implements a signal handler (via SignalHandler) that allows for interactive control of a running agent using keyboard interrupts (Ctrl+C):

• Pause: Pressing Ctrl+C once triggers the pause callback, suspending the agent's execution loop.
• Resume: The agent waits for a signal to resume. Once resumed, it continues from where it left off.
• Stop: Pressing Ctrl+C a second time triggers a forced exit.

This mechanism allows developers to inspect the browser state or intervene during long-running tasks without losing the current execution history.

The DeepResearchState (a TypedDict) defines the data structure used by the Langgraph-based research workflow. It tracks the entire lifecycle of a research project, from planning to synthesis.

Core State Fields:

• task_id: Unique identifier for the research session.
• topic: The main subject of research.
• research_plan: A hierarchical list of ResearchCategoryItem (categories containing ResearchTaskItems).
• search_results: A collection of data gathered from browser tools.
• current_category_index & current_task_index_in_category: Pointers used to track progress through the hierarchical plan.
• output_dir: Path where the plan, search results, and final report are persisted.
• stop_requested: Boolean flag to signal the graph to halt execution.
• messages: The conversation history used by the LLM.

If you need to troubleshoot the container environment, you can start an interactive bash session inside the running service using Docker Compose.

docker compose run --rm -it browser-use-webui bash

The DeepResearchAgent can be extended with Model Context Protocol (MCP) tools. If mcp_server_config is provided during initialization, the agent will attempt to set up an MCP client and load its available tools into the agent's toolset alongside standard file I/O and browser tools.

# Example with MCP configuration
mcp_config = {
    # Configuration specific to your MCP server implementation
    "server_url": "http://localhost:8080",
    "api_key": "your_key"
}

agent = DeepResearchAgent(
    llm=my_llm,
    browser_config={"headless": True},
    mcp_server_config=mcp_config
)

You can bypass the LLM API key verification step by setting the SKIP_LLM_API_KEY_VERIFICATION environment variable to true or y.

Environment Variable:

• SKIP_LLM_API_KEY_VERIFICATION: Set to true, t, y, or 1 to skip verification.

export SKIP_LLM_API_KEY_VERIFICATION=true

The BrowserUseAgent can automatically generate artifacts after a run completes based on the settings provided:

1. Playwright Scripts: If settings.save_playwright_script_path is provided, the agent attempts to save the execution as a Playwright script. It can use sensitive_data_keys to mask sensitive information during this process.
2. History GIFs: If settings.generate_gif is enabled, the agent creates a GIF of the agent's history. This can be a boolean or a string specifying the output_path (e.g., 'agent_history.gif').