How sentient-engineering/agent-q works
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