Enterprise Autonomous Web Agent

Welcome to the Enterprise Autonomous Web Agent project. This is a robust, open-source AI agent designed to perform complex multi-step web workflows autonomously using state-of-the-art AI engineering concepts.

🌟 Core Architecture

The agent strictly follows Silicon Valley enterprise standards to ensure no hallucination, zero silent failures, and high reliability.

graph TD
    %% User Setup Phase
    subgraph "1. User Setup & Manual Authentication"
        User["Client / End User"] -->|Clones Repo| Repo["Local Codebase"]
        User -->|Runs Script| ChromeLaunch["Launch Chrome Manually (setup_profile.py)"]
        ChromeLaunch -->|User logs into websites| ChromeProfile[("Persistent ChromeProfile (Disk)")]
    end
    
    %% Core Execution Loop
    subgraph "2. Live Agent Execution Pipeline"
        RunScript["run_enterprise_agent.py"] --> FSM["Finite State Machine (FSM Gate)"]
        FSM --> Context["Context & Task Manager"]
        
        %% Browser connects to the logged-in profile
        Context --> Browser["Headless / UI Chrome (via undetected_chromedriver)"]
        ChromeProfile -.->|Loads Session Cookies| Browser
        
        Browser -->|Takes Real Snapshot / CDP| Parser["DOM Parser & Graph Generator"]
        Parser -->|Real Live Data| LLM_Adapter["Multi-Model Adapter (Live APIs)"]
        
        %% Adapter makes REAL HTTP calls
        LLM_Adapter <-->|Real API Request| Gemini["Gemini 1.5/3.1 Flash (Primary)"]
        LLM_Adapter <-->|Fallback API Request| OpenAI["OpenAI / Local Models (Fallback)"]
        
        LLM_Adapter --> Pydantic["Pydantic Validator (extra='forbid')"]
        Pydantic -- "Valid Action Schema" --> Executor["Action Executor (Click/Type)"]
        Executor --> Browser
    end

Loading

Key Highlights:

1. FSM State Gating: The agent uses a strict Finite State Machine (fsm_state.py). It forces the LLM to complete one goal (e.g., "Login") before it can move to the next (e.g., "Upload Media").
2. Persistent Chrome Profiles: We do not use insecure token or cookie injection. Users log into their browser once, and the agent uses that persistent profile via undetected_chromedriver.
3. Multi-Model Adapter: Prioritizes Gemini models for speed and cost-effectiveness, with graceful fallbacks.
4. Local Vector Database (pgvector): In case Vision models fail, the system falls back to semantic DOM filtering using local PostgreSQL and pgvector.

---

🚀 How to Run (Step-by-Step Guide)

Step 1: Install Requirements

You must have Google Chrome installed on your machine. Clone the repository and install the Python dependencies:

pip install -r requirements.txt

(Dependencies include: pydantic, langfuse, psycopg2-binary, pgvector, requests, python-dotenv)

Step 2: Setup Environment Variables

Create an .env file in the root of the project with your API key:

GEMINI_API_KEY="your_actual_gemini_api_key"

(Note: Your .env and ChromeProfile are ignored by git to protect your credentials).

Step 3: Login to Your Chrome Profile (One-time Setup)

Run the setup script to open a fresh Chrome window.

python3 setup_profile.py

Manually log into the websites you want the agent to automate (like LinkedIn, Facebook, Pinterest). When done, close the browser. Your session is permanently saved.

Step 4: Run the Live Agent

Start the execution pipeline:

python3 run_enterprise_agent.py

Watch as the AI autonomously opens your browser, loads your profile, plans its FSM states, and executes tasks step-by-step!