# sentient-engineering/agent-q architecture

> Architecture diagram of the GitHub repository sentient-engineering/agent-q, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sentient-engineering/agent-q
- Repository: https://github.com/sentient-engineering/agent-q

## Overview

##### Project Type and Purpose
- Type: Python-based autonomous AI agent framework for web interaction (CLI tool/library).
- Purpose: Run multi-agent architectures (planner/navigator, actor/critic, MCTS-based RL, DPO finetuning) to complete tasks on the web reliably.

##### Main Architectural Components
a. Entry Point & Configuration
- `agentq/__main__.py` (CLI runner) or `server.py` (optional HTTP server)
- `agentq/config/config.py` (env loading, API keys via .env)
b. Core Orchestration Layer
- `agentq/core/orchestrator/orchestrator.py` (bootstraps and coordinates agents)
c. Agent Modules (`agentq/core/agent/…`)
- PlannerAgent, NavigatorAgent (browser navigation)
- ActorQAgent, CriticAgent (actor–critic RL)
- MCTS integration via `agentq/core/mcts/browser_mcts.py`
- Specialized agents: VisionAgent, CaptchaAgent, EvalAgent
d. Skill Library (`agentq/core/skills/…`)
- Low-level actions: open_url, get_dom, click, enter_text, screenshot, solve_captcha, etc.
e. WebDriver Interface
- `agentq/core/web_driver/playwright.py` (controls Chrome via CDP)
f. Memory & Models
- `agentq/core/memory/ltm.py` (long-term memory store)
- `agentq/core/models/models.py` (LLM wrappers)
g. Prompt Templates
- `agentq/core/prompts/prompts.py`
h. MCTS Core & Visualization
- Core MCTS engine (`agentq/core/mcts/core/mcts.py`), examples, plus visualizer client & snapshot logger
i. Utilities & Logging
- Helpers for CLI, DOM, JSON extraction, logging, tracing via Langfuse

##### Relationships & Data Flows
1. CLI (`python -m agentq`)
↓ reads
2. Configuration (.env → config.py)
↓ initializes
3. Orchestrator
↔ instantiates and sequences
- Agents
- MCTS engine (for RL tasks)
- Memory, Models, Prompts
4. An Agent (Planner/Actor/Critic/MCTS) performs decision loops:
a. Fetches prompt template → Models → produces “action plan”
b. Invokes corresponding Skill module
c. Skill calls WebDriver → Chrome → interacts with real website
d. Results (DOM, screenshot, user input) → returned to Agent
e. Memory module may store/retrieve context
f. Critic or MCTS scores the outcome → feedback → DPO pairs stored
5. Visualization & Logging (Langfuse traces via @observe decorators)

##### Architectural Patterns & Principles
- Modular multi-agent pattern (separable planner, actor, critic roles)
- Pluggable “Skill” commands abstracting web interactions
- Reinforcement-style feedback loop via MCTS and DPO finetuning
- Clear separation: Orchestrator vs. Agent vs. Skill vs. WebDriver
- Configuration-driven (env, user_preferences)
- Extensibility: drop in new agents, skills, MCTS strategies

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points
    subgraph "Entry Points"
        CLI["CLI Runner"]:::core
        HTTP["HTTP Server"]:::core
    end

    %% Configuration
    subgraph "Configuration"
        CONFIG["Config Loader"]:::config
    end

    %% Orchestrator
    ORCH["Core Orchestrator"]:::core

    %% Agents Pool
    subgraph "Agent Pool"
        PLAN["Planner Agent"]:::core
        NAV["Navigator Agent"]:::core
        ACTOR["Actor Agent"]:::core
        CRITIC["Critic Agent"]:::core
        VISION["Vision Agent"]:::core
        CAPTCHA["Captcha Agent"]:::core
        EVAL["Evaluation Agent"]:::core
    end

    %% MCTS Modules
    subgraph "MCTS Framework"
        CORE_MCTS["Core MCTS Engine"]:::core
        BROWSER_MCTS["Browser-specific MCTS"]:::core
        BASE_MCTS["MCTS Base Classes"]:::core
        EXAMPLE_MCTS["MCTS Examples"]:::core
        subgraph "Visualization"
            VIZ_MAIN["Viz Entry"]:::core
            TREE_LOG["Tree Logger"]:::core
            TREE_SNAP["Tree Snapshot"]:::core
            VIZ_CLIENT["Visualizer Client"]:::core
        end
    end

    %% Skills Library
    subgraph "Skills Library"
        SKILLS["Skills Directory"]:::core
    end

    %% WebDriver & Browser
    WD["WebDriver Interface"]:::core
    BROWSER["Chrome (CDP)"]:::ext

    %% Memory, Models, Prompts
    MEM["Long-Term Memory Store"]:::core
    MODELS["Model Wrappers"]:::ext
    PROMPTS["Prompt Templates"]:::core

    %% Utilities & Logging
    subgraph "Utilities & Logging"
        UTILS["Utilities Directory"]:::config
        LOGGER["Langfuse Tracing"]:::ext
    end

    %% DPO Data Store
    DPO_DB[(DPO Data Store)]:::db

    %% Connections
    CLI -->|reads env| CONFIG
    HTTP -->|reads env| CONFIG
    CONFIG -->|init| ORCH
    ORCH -->|bootstraps| PLAN
    ORCH -->|bootstraps| NAV
    ORCH -->|bootstraps| ACTOR
    ORCH -->|bootstraps| CRITIC
    ORCH -->|bootstraps| VISION
    ORCH -->|bootstraps| CAPTCHA
    ORCH -->|bootstraps| EVAL
    ORCH -->|init| CORE_MCTS
    ORCH -->|init| MEM
    ORCH -->|init| MODELS
    ORCH -->|init| PROMPTS

    PLAN -->|fetch prompt| PROMPTS
    NAV -->|fetch prompt| PROMPTS
    ACTOR -->|fetch prompt| PROMPTS
    CRITIC -->|fetch prompt| PROMPTS
    PROMPTS -->|LLM Prompt| MODELS
    MODELS -->|LLM Response| PLAN
    PLAN -->|action plan| SKILLS
    NAV -->|action plan| SKILLS
    ACTOR -->|action plan| SKILLS
    CRITIC -->|action plan| SKILLS
    SKILLS -->|invoke| WD
    WD -->|CDP| BROWSER
    BROWSER -->|DOM/Screenshot| SKILLS
    SKILLS -->|results| PLAN
    PLAN -->|context| MEM
    MEM -->|retrieve| PLAN
    ACTOR <-->|feedback| CRITIC
    CORE_MCTS <-->|simulations| PLAN
    CORE_MCTS <-->|simulations| NAV
    CRITIC -->|DPO Pair| DPO_DB
    CORE_MCTS -->|DPO Pair| DPO_DB
    PLAN -->|trace| LOGGER
    NAV -->|trace| LOGGER
    ACTOR -->|trace| LOGGER
    CRITIC -->|observe| LOGGER
    VISION -->|trace| LOGGER
    CAPTCHA -->|trace| LOGGER
    EVAL -->|trace| LOGGER

    %% Click Events
    click CLI "https://github.com/sentient-engineering/agent-q/blob/main/agentq/__main__.py"
    click HTTP "https://github.com/sentient-engineering/agent-q/blob/main/server.py"
    click CONFIG "https://github.com/sentient-engineering/agent-q/blob/main/agentq/config/config.py"
    click ORCH "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/orchestrator/orchestrator.py"
    click PLAN "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/agent/planner_agent.py"
    click NAV "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/agent/browser_nav_agent.py"
    click ACTOR "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/agent/agentq_actor.py"
    click CRITIC "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/agent/agentq_critic.py"
    click VISION "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/agent/vision_agent.py"
    click CAPTCHA "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/agent/captcha_agent.py"
    click EVAL "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/agent/eval_agent.py"
    click BROWSER_MCTS "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/mcts/browser_mcts.py"
    click CORE_MCTS "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/mcts/core/mcts.py"
    click BASE_MCTS "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/mcts/core/base.py"
    click EXAMPLE_MCTS "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/mcts/example/grid.py"
    click VIZ_MAIN "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/mcts/visualization/__main__.py"
    click TREE_LOG "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/mcts/visualization/tree_log.py"
    click TREE_SNAP "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/mcts/visualization/tree_snapshot.py"
    click VIZ_CLIENT "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/mcts/visualization/visualizer_client.py"
    click SKILLS "https://github.com/sentient-engineering/agent-q/tree/main/agentq/core/skills/"
    click WD "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/web_driver/playwright.py"
    click MEM "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/memory/ltm.py"
    click MODELS "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/models/models.py"
    click PROMPTS "https://github.com/sentient-engineering/agent-q/blob/main/agentq/core/prompts/prompts.py"
    click UTILS "https://github.com/sentient-engineering/agent-q/tree/main/agentq/utils/"
    classDef core fill:#E3F2FD,stroke:#2196F3,stroke-width:2px;
    classDef ext fill:#E8F5E9,stroke:#4CAF50,stroke-width:2px;
    classDef config fill:#FFF3E0,stroke:#FF9800,stroke-width:2px;
    classDef db fill:#F3E5F5,stroke:#9C27B0,stroke-width:2px,stroke-dasharray: 5 5;
```
