Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Web-UI project is a comprehensive graphical interface and orchestration layer built on top of the browser-use framework. Its primary purpose is to enable Large Language Models (LLMs) to interact with web browsers to perform complex tasks, ranging from simple navigation to multi-step information gathering and deep research.
The architecture is divided into a frontend layer (Gradio), an agentic orchestration layer (Custom Agents), and a utility layer for LLM management and configuration. It supports various providers including OpenAI, Anthropic, Google, and Ollama, and offers specialized workflows for persistent browser sessions and automated reporting.
Sources: webui.py:40-45, README.md:15-25
Core System Components
The system architecture follows a modular pattern where the UI, Agent, and Browser components are decoupled but synchronized via an execution engine.
High-Level Architecture Flow
This diagram illustrates the interaction between the user interface, the agentic logic, and the browser execution environment.
The Execution Engine coordinates the lifecycle of the browser and agent based on the provided configuration.
Sources: webui.py:75-150, src/agent/custom_agent.py:263-300
Component Descriptions
| Component | Responsibility | Relevant Files |
|---|---|---|
| Gradio WebUI | Provides the user interface for task input, configuration settings, and live browser monitoring. | webui.py |
| CustomAgent | Extends the base Agent with specialized reasoning, memory management, and structured evaluation. | src/agent/custom_agent.py |
| Deep Research | An iterative module that plans, searches, records, and generates comprehensive markdown reports. | src/utils/deep_research.py |
| CustomController | Manages the execution of actions within the browser context, including content extraction. | src/controller/custom_controller.py |
| LLM Utils | Abstracts the instantiation of various chat models (OpenAI, DeepSeek, Google, etc.). | src/utils/utils.py |
Sources: webui.py:346-600, src/agent/custom_agent.py:63-130, src/utils/deep_research.py:34-150
Agent Execution Engine
The heart of the project is the CustomAgent and its interaction loop. Unlike standard agents, the CustomAgent utilizes a specific JSON response format to track state evaluation, task progress, and future plans.
Execution Sequence
The following sequence diagram detail how a single step is executed within the CustomAgent.
Each step involves capturing the browser state, querying the LLM for a structured JSON response, and executing the resulting actions sequentially.
Sources: src/agent/custom_agent.py:197-260, src/agent/custom_prompts.py:14-50
Prompting and State Management
The system uses CustomSystemPrompt to enforce a strict JSON output format. This format includes:
- prev_action_evaluation: A self-reflection on whether the previous action succeeded.
- important_contents: Data extracted from the current page relevant to the task.
- task_progress: A summary of completed sub-tasks.
- future_plans: The list of actions remaining.
Sources: src/agent/custom_prompts.py:14-38, src/agent/custom_views.py:23-32
Deep Research Module
The Deep Research module represents a high-level workflow that automates complex information gathering through an iterative loop.
Research Workflow
The research process continues until the maximum number of iterations is reached or the agent determines no further queries are needed.
Sources: src/utils/deep_research.py:34-160
Key Functions in Deep Research
deep_research(task, llm, ...): The main entry point that manages the search loop.extract_content(browser): A specialized tool that uses Jina Reader (r.jina.ai) to convert web pages to clean markdown.generate_final_report(task, history_infos, ...): Aggregates all recorded JSON information into a publication-ready Markdown document.
Sources: src/utils/deep_research.py:61-80, src/utils/deep_research.py:233-280
Configuration and Deployment
The application supports extensive configuration through a default settings dictionary and environment variables, often managed via Docker.
Configuration Parameters
| Parameter | Default | Description |
|---|---|---|
agent_type | "custom" | Choose between original or custom agent logic. |
max_steps | 100 | The maximum iterations allowed for a single task. |
use_vision | True | Enables the agent to "see" screenshots for reasoning. |
keep_browser_open | False | Determines if the browser context persists after a task. |
headless | False | Runs the browser without a visible GUI window. |
Sources: src/utils/default_config_settings.py:7-32
Deployment via Docker
The project includes a docker-compose.yml and supervisord.conf for robust deployment. The environment is configured with Xvfb and VNC to allow remote visual monitoring of the agent's actions even when running in a headless container environment.
Sources: docker-compose.yml:10-40, supervisord.conf:1-50
Conclusion
The Web-UI architecture provides a scalable and observable framework for browser-based AI agents. By extending the core browser-use capabilities with structured memory (CustomAgent), iterative research workflows (deep_research.py), and a user-friendly management layer (webui.py), it enables both developers and end-users to automate complex web-based procedures with high degrees of reliability and transparency.