# vessl-ai/ai-agent-research architecture

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

- Interactive diagram: https://gitdiagram.com/vessl-ai/ai-agent-research
- Repository: https://github.com/vessl-ai/ai-agent-research

## Overview

##### Overall Structure
- That this is a heterogeneous collection of smaller projects (i.e. modules) focusing on different agent-based research tasks.

##### Main Components
- Individual Projects (modules):
- CrewAI Process Type Comparison (crewai-process-type)
- Agentic RAG System (agentic-rag)
- Code Agent (code-agent)
- Agentic Crawl (agentic-crawl)
- CrewAI Deep Research (crewai-deepresearch)
- Configuration Component: Shows YAML files (e.g., agents.yaml, tasks.yaml) and environment templates (.env.template) for each project.
- Core Application Logic: Represented by main source files (e.g., main.py, run.py, app.py) that drive the business logic.
- Auxiliary Tools or Agents: For instance, code-agent leverages tools for code analysis; agentic-crawl has a crawl_agent; deep research project has its own deep_research_agent.
- Presentation/Output Layer: Some projects have a “static” directory (with index.html) or produce HTML reports, indicating output rendering.
- Data/Knowledge Stores: Project files (like PDFs in agentic-rag’s knowledge folder and research result documents) show where inputs or outputs are stored.

##### Architectural Patterns and Design Principles
- Modular nature – each project is self-contained but contributes to the greater research efforts.
- Separation of concerns:
- Configuration is externalized via YAML and .env templates.
- Business logic resides in Python source files.
- Presentation/output is clearly separated (static files or generated reports).
- If applicable, note any patterns like orchestration of agents or microservice-like structures (though they are not full-blown microservices, the projects operate independently and may even interact).

##### Specific Inclusions
- Each module should have a visible “Configuration Layer” where environment variables and YAML settings are read.
- The “Application Layer” in each should clearly show which file (like main.py or run.py) triggers the logic.
- For agent execution, show components like:
- Retrieval-Augmented Generation in agentic-rag: illustrate two paths for PDFSearchTool and CrewDoclingSource, complete with document ingestion.
- Code Analysis Agent in code-agent: include an element that processes source code and outputs HTML reports.
- Process Comparison in crewai-process-type: denote performance comparison between sequential and hierarchical orchestrations.
- Data flow from the input (e.g., PDFs, source code) through processing agents.
- Outputs being generated (reports in HTML or result text files).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Top-level node
    AR["AI Agent Research"]:::system

    %% CrewAI Process Type Comparison Module
    subgraph "CrewAI Process Type Comparison"
        c1["Configuration: .env.template"]:::config
        c2["Core Logic: main.py"]:::core
        c3["Output: research_results_20250215_195508.txt"]:::output
        c1 -->|"readsConfig"| c2
        c2 -->|"generates"| c3
    end

    %% Agentic RAG System Module
    subgraph "Agentic RAG System"
        r1["Core Logic: main.py"]:::core
        r2["Knowledge Store: knowledge/ PDFs"]:::output
        r3["Output: research_result_docling_20250217_135344.txt"]:::output
        r4["Output: research_result_pdfsearch_20250217_135225.txt"]:::output
        r2 -->|"ingestion"| r1
        r1 -->|"generates"| r3
        r1 -->|"generates"| r4
    end

    %% Code Agent Module
    subgraph "Code Agent"
        ca1["Configuration: .env.template"]:::config
        ca2["Core Logic: main.py"]:::core
        ca3["Output: output/ HTML reports"]:::output
        ca1 -->|"readsConfig"| ca2
        ca2 -->|"generates"| ca3
    end

    %% Agentic Crawl Module
    subgraph "Agentic Crawl"
        ac1["Configuration: config & .env.template"]:::config
        ac2["Core Logic: src/ (app.py, run.py, main.py)"]:::core
        ac3["Tool: crawl_agent.py"]:::core
        ac4["Tool: crew_handler.py"]:::core
        ac5["Tool: custom_tool.py"]:::core
        ac6["Output: static/index.html"]:::output
        ac1 -->|"readsConfig"| ac2
        ac2 -->|"orchestrates"| ac3
        ac2 -->|"orchestrates"| ac4
        ac2 -->|"orchestrates"| ac5
        ac3 -->|"produces"| ac6
        ac4 -->|"produces"| ac6
        ac5 -->|"produces"| ac6
    end

    %% CrewAI Deep Research Module
    subgraph "CrewAI Deep Research"
        dr1["Configuration: src/config/ YAML"]:::config
        dr2["Configuration: .env.example"]:::config
        dr3["Core Logic: app.py, deep_research_agent.py, run.py"]:::core
        dr4["Output: static/index.html"]:::output
        dr1 -->|"readsConfig"| dr3
        dr2 -->|"readsConfig"| dr3
        dr3 -->|"generates"| dr4
    end

    %% Linking top-level to modules (using their configuration nodes as entry points)
    AR -->|"init"| c1
    AR -->|"init"| r1
    AR -->|"init"| ca1
    AR -->|"init"| ac1
    AR -->|"init"| dr1

    %% Click Events for CrewAI Process Type Comparison
    click c1 "https://github.com/vessl-ai/ai-agent-research/blob/main/crewai-process-type/.env.template"
    click c2 "https://github.com/vessl-ai/ai-agent-research/blob/main/crewai-process-type/main.py"
    click c3 "https://github.com/vessl-ai/ai-agent-research/blob/main/crewai-process-type/research_results_20250215_195508.txt"

    %% Click Events for Agentic RAG System
    click r1 "https://github.com/vessl-ai/ai-agent-research/blob/main/agentic-rag/main.py"
    click r2 "https://github.com/vessl-ai/ai-agent-research/tree/main/agentic-rag/knowledge/"
    click r3 "https://github.com/vessl-ai/ai-agent-research/blob/main/agentic-rag/research_result_docling_20250217_135344.txt"
    click r4 "https://github.com/vessl-ai/ai-agent-research/blob/main/agentic-rag/research_result_pdfsearch_20250217_135225.txt"

    %% Click Events for Code Agent
    click ca1 "https://github.com/vessl-ai/ai-agent-research/blob/main/code-agent/.env.template"
    click ca2 "https://github.com/vessl-ai/ai-agent-research/blob/main/code-agent/main.py"
    click ca3 "https://github.com/vessl-ai/ai-agent-research/tree/main/code-agent/output/"

    %% Click Events for Agentic Crawl
    click ac1 "https://github.com/vessl-ai/ai-agent-research/tree/main/agentic-crawl/config/"
    click ac2 "https://github.com/vessl-ai/ai-agent-research/tree/main/agentic-crawl/src/"
    click ac3 "https://github.com/vessl-ai/ai-agent-research/blob/main/agentic-crawl/src/crawl_agent.py"
    click ac4 "https://github.com/vessl-ai/ai-agent-research/blob/main/agentic-crawl/src/crew_handler.py"
    click ac5 "https://github.com/vessl-ai/ai-agent-research/blob/main/agentic-crawl/tools/custom_tool.py"
    click ac6 "https://github.com/vessl-ai/ai-agent-research/blob/main/agentic-crawl/src/static/index.html"

    %% Click Events for CrewAI Deep Research
    click dr1 "https://github.com/vessl-ai/ai-agent-research/tree/main/crewai-deepresearch/src/config/"
    click dr2 "https://github.com/vessl-ai/ai-agent-research/blob/main/crewai-deepresearch/.env.example"
    click dr3 "https://github.com/vessl-ai/ai-agent-research/blob/main/crewai-deepresearch/src/app.py"
    click dr4 "https://github.com/vessl-ai/ai-agent-research/blob/main/crewai-deepresearch/src/static/index.html"

    %% Styles
    classDef system fill:#E0E0E0,stroke:#000,stroke-width:2px;
    classDef config fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef core fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef output fill:#FFDAB9,stroke:#333,stroke-width:2px;
```
