# theagenticai/theagenticbrowser architecture

> Architecture diagram of the GitHub repository theagenticai/theagenticbrowser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/theagenticai/theagenticbrowser
- Repository: https://github.com/theagenticai/theagenticbrowser

## Overview

##### Project Type and Purpose
- Agentic Browser is an agent-based automation system that automates browser interactions based on natural language commands. Its purpose is to perform tasks such as web research, data extraction, e-commerce analysis, and web traversal by intelligently breaking down user requests into actionable steps using three specialized agents (Planner, Browser, and Critique).
- The README describes a feedback loop workflow where the Planner Agent formulates the task, the Browser Agent carries out action steps on web pages, and the Critique Agent validates/adjusts the execution.

##### File Structure
- Top-Level Files and Directories:
- The root includes configuration files (.env.example, config.py), Docker-related files (Dockerfile, .dockerignore), license and environment setup files.
- The “core” directory is the heart of the application – it houses:
- Agents: Located in core/agents contains separate files for browser_agent.py, critique_agent.py, and planner_agent.py.
- Server: In core/server, which contains API route definitions (api_routes.py) for exposing endpoints to trigger tasks.
- Skills: In core/skills, which encapsulate distinct functionalities like clicking actions, text entry, URL navigation, data extraction (e.g., pdf_text_extractor.py, google_search.py).
- Utils: In core/utils, where helper functions, logging, error handling, and support for DOM and UI operations are defined.
- A main entry point is available (core/main.py) to run the automation process directly.

##### Understand Key Architectural Components from the README
- Three Specialized Agents:
- Planner Agent: Responsible for decomposing user tasks.
- Browser Agent: Executes actual browser interactions.
- Critique Agent: Validates and adjusts the steps in the process.
- Additional system components include:
- Browser Manager: Likely manages browser session interactions (core/browser_manager.py).
- API Server: Exposes endpoints for executing tasks (core/server/api_routes.py).
- Skills Library: A collection of scriptable actions (in core/skills) to interface with the browser.
- Utility Modules: For logging, exception management, and integrating external APIs (e.g., OpenAI, Playwright).

a. Main Components:
- User Interface/API Entry:
- Represented by the API server (core/server) and possibly direct CLI execution (entry point: core/main.py).
- Task Decomposition Engine:
- Planner Agent (core/agents/planner_agent.py) where user commands are broken down.
- Execution Engine:
- Browser Agent (core/agents/browser_agent.py) which interacts with the browser.
- Quality and Feedback Mechanism:
- Critique Agent (core/agents/critique_agent.py) which reviews outcomes and guides further action.
- Skills Module:
- A library (core/skills) of browser action functions (e.g., click, text entry, DOM analysis).
- Browser Interaction and Management:
- Browser Manager (core/browser_manager.py) assisting with Playwright-based automation.
- Supporting Utilities:
- Logging, configuration, and helper utilities (core/utils) that support the agents’ operations.
- External Integration:
- Integration with external APIs (e.g., text model API, screenshot analysis API, Google search) as configured via the .env file and used by the agents.

b. Relationships and Interactions:
- The User’s request enters the system via an API endpoint (or directly through the main entry).
- The request is first received by the Planner Agent which analyzes and creates a plan.
- The planned actions are handed to the Browser Agent that performs browser operations (via skills modules) and uses the Browser Manager for session/driver support.
- The Critique Agent then reviews the execution (e.g., checking DOM changes, screenshots) and either approves the completion or instructs the Planner Agent to refine the task.
- A feedback loop exists among the agents ensuring the iterative improvement of tasks.

c. Important Architectural Patterns:
- Agent-based Modular Design: The clear separation between task planning (Planner Agent), task execution (Browser Agent), and quality control (Critique Agent).
- Feedback Loop: The continuous checking and refinement process among agents.
- Separation of Concerns: Distinct modules for skills, utilities, and server/API exposure.
- Configurability & Extensibility: Use of .env and modular skills makes it easier to plug additional functionalities.

d. Relevant Technologies/Frameworks:
- Python as the base platform.
- Pydantic AI Framework (as mentioned in the README) for the agent-based approach.
- Playwright (for browser automation) as inferred from the Quick Start instructions.
- Docker (using Dockerfile & .dockerignore) for containerization.
- Uvicorn & FastAPI (in core/server/api_routes.py) for exposing API endpoints.

##### Instructing the Principal Software Engineer on Diagramming
- Use clear, distinct labels for each component:
◦ “User/API Request Entry”, “Planner Agent”, “Browser Agent”, “Critique Agent”, “Skills Module”, “Browser Manager”, “Utility Services”, “External Services”.
◦ The flow of data from the API/CLI into the Planner Agent.
◦ The hand-off from the Planner Agent to the Browser Agent.
◦ The feedback from the Browser Agent to the Critique Agent and back to the Planner Agent in case of refinements.
◦ Interactions of various skills with the Browser Agent.
◦ The communication paths to external services (e.g., text API, screenshot API, Google Search).
◦ Differentiate between operational components (agents), service modules (skills, browser manager), external services, and infrastructure components (API server, configuration).
- Details such as:
◦ The containerization aspect using Docker.
◦ The external configuration dependency on the .env file.
◦ The orchestration cycle highlighted in the “Agents Workflow” section of the README.

##### Final Touches
- Component is well-labeled and that the connections show the data flow and dependencies clearly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Input"
        User["User/API Request Entry"]:::user
    end

    subgraph "API & Entry Layer"
        API["API Server"]:::api
        MainEntry["Main Entry Point"]:::entry
    end

    subgraph "Agents Layer"
        Planner["Planner Agent"]:::agent
        Browser["Browser Agent"]:::agent
        Critique["Critique Agent"]:::agent
    end

    subgraph "Service Modules"
        Skills["Skills Module"]:::service
        BrowserMgr["Browser Manager"]:::service
        Utils["Utility Modules"]:::utility
        External["External APIs/Services"]:::external
    end

    User -->|"initiates"| API
    User -->|"initiates"| MainEntry

    API -->|"triggerTask"| Planner
    MainEntry -->|"startProcess"| Planner

    Planner -->|"planDecomposition"| Browser
    Browser -->|"executeActions"| Skills
    Browser -->|"sessionManagement"| BrowserMgr
    Browser -->|"logSupport"| Utils

    Browser -->|"resultEvaluation"| Critique
    Critique -->|"feedback"| Planner
    Critique -->|"externalReview"| External

    classDef user fill:#FFDDC1,stroke:#D2691E,stroke-width:2px;
    classDef api fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef entry fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef agent fill:#FFB6C1,stroke:#B22222,stroke-width:2px;
    classDef service fill:#FFFF99,stroke:#DAA520,stroke-width:2px;
    classDef utility fill:#D3D3D3,stroke:#696969,stroke-width:2px;
    classDef external fill:#E6E6FA,stroke:#8A2BE2,stroke-width:2px;

    click Planner "https://github.com/theagenticai/theagenticbrowser/blob/main/core/agents/planner_agent.py"
    click Browser "https://github.com/theagenticai/theagenticbrowser/blob/main/core/agents/browser_agent.py"
    click Critique "https://github.com/theagenticai/theagenticbrowser/blob/main/core/agents/critique_agent.py"
    click API "https://github.com/theagenticai/theagenticbrowser/blob/main/core/server/api_routes.py"
    click Skills "https://github.com/theagenticai/theagenticbrowser/tree/main/core/skills"
    click BrowserMgr "https://github.com/theagenticai/theagenticbrowser/blob/main/core/browser_manager.py"
    click MainEntry "https://github.com/theagenticai/theagenticbrowser/blob/main/core/main.py"
    click Utils "https://github.com/theagenticai/theagenticbrowser/tree/main/core/utils"
```
