How theagenticai/theagenticbrowser works
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.