# theagenticai/theagenticbench architecture

> Architecture diagram of the GitHub repository theagenticai/theagenticbench, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/theagenticai/theagenticbench
- Repository: https://github.com/theagenticai/theagenticbench

## Overview

##### Main Components
- Backend Core (agentic_bench):
- Orchestrator & Main: Central control module (orchestrator.py, main.py) that manages workflow execution.
- Agent Library: Includes pre-built agents such as the coder agent, file surfer, web surfer, and RAG agent (each in agentic_bench/agents).
- Utilities: Supporting modules for tasks like message conversion, cancellation tokens, hash calculation, and code execution (e.g., executors, initializers, markdown browser).
- Ledger: For logging or tracking tasks (ledger.py), which might play a key role in auditing and feedback loops.

- External Agent:
- AgenticBrowser: Remember it is included as a submodule and acts as an external service for web navigation, data extraction, etc.

- Frontend Application:
- Built with React/Vite (frontend/src) and Tailwind CSS.
- Contains UI components, navigation elements, and pages such as Chat, Playground, and Layout that interface with backend REST APIs as per the README’s instructions.

- Deployment & Containerization:
- Docker and Docker Compose files that allow the system to be containerized and orchestrated in a development or production environment.

##### Relationships and Data Flow
- The user interacts via the Frontend UI, which communicates with the backend agentic_bench through REST APIs (note that agentic_bench exposes its APIs, e.g., at /docs).
- The backend acts as the brain:
- The Orchestrator receives input (from an API or directly) and coordinates among various agents.
- It follows a workflow of initializing agents, task planning, selecting the next agent, executing instructions on the selected agent, and performing critiques on the results.
- Agents interact with external systems where needed; for example, the web_surfer might call the AgenticBrowser service to perform web-based tasks.
- Docker Compose is used to spin up the services, ensuring that each component (Frontend, Agentic Bench backend, Agentic Browser) runs in its respective container.

##### Architectural Patterns and Principles
- Modular Design: The agents are separated into identifiable modules (each one handling a specific type of task), supporting the Open-Closed Principle by enabling new agent additions without major rework.
- Microservices-Like Separation (Within a Monorepo): Although all backend modules reside in a single repo, the division into distinct agents and utilities reflects a service-oriented architecture.
- Workflow Orchestration: Central orchestration logic dynamically plans and modifies workflows, which is an important pattern in modern automation systems.
- REST API Exposure: Both backend and AgenticBrowser expose REST endpoints for integrations.
- Containerization & Environment Isolation: The use of Docker ensures reproducible deployments and isolation of dependencies.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Frontend"
        FrontendUI("Frontend UI (React)"):::frontend
        Chat("Chat Page"):::frontend
        Playground("Playground Page"):::frontend
        Layout("Layout Page"):::frontend
        FrontendUI -->|"navigates"| Chat
        FrontendUI -->|"navigates"| Playground
        FrontendUI -->|"navigates"| Layout
    end

    %% API Connection from Frontend to Backend
    FrontendUI -->|"API_Request"| Orchestrator

    %% Backend Layer
    subgraph "Backend"
        %% Core Orchestration
        subgraph "Core Orchestration"
            Orchestrator("Orchestrator"):::orchestration
            Main("Main"):::orchestration
            Orchestrator ---|"initializes"| Main
        end

        %% Agent Library
        subgraph "Agent Library"
            Coder("Agent: Coder"):::agent
            FileSurfer("Agent: File Surfer"):::agent
            RAG("Agent: RAG"):::agent
            WebSurfer("Agent: Web Surfer"):::agent
        end

        %% Utilities
        subgraph "Utilities"
            MessageConversion("Message Conversion"):::utility
            Cancellation("Cancellation Tokens"):::utility
            Executors("Executors & Initializers"):::utility
            MarkdownProcessing("Markdown Processing"):::utility
            OtherUtils("Other Utilities"):::utility
        end
        
        Ledger("Ledger"):::ledger
    end

    %% External Service
    ExtAgent("AgenticBrowser Service"):::external

    %% Deployment Layer
    subgraph "Deployment"
        BackendDocker("Backend Dockerfile"):::deployment
        FrontendDocker("Frontend Dockerfile"):::deployment
        DockerCompose("Docker Compose"):::deployment
    end

    %% Backend Workflow Connections
    Orchestrator -->|"delegates"| Coder
    Orchestrator -->|"delegates"| FileSurfer
    Orchestrator -->|"delegates"| RAG
    Orchestrator -->|"delegates"| WebSurfer
    Orchestrator -->|"utilizes"| MessageConversion
    Orchestrator -->|"utilizes"| Cancellation
    Orchestrator -->|"utilizes"| Executors
    Orchestrator -->|"utilizes"| MarkdownProcessing
    Orchestrator -->|"utilizes"| OtherUtils
    Orchestrator -->|"logs_to"| Ledger

    %% External integration call from WebSurfer Agent
    WebSurfer -->|"calls"| ExtAgent

    %% Deployment connections (all components are containerized)
    DockerCompose -->|"orchestrates"| FrontendUI
    DockerCompose -->|"orchestrates"| Orchestrator
    DockerCompose -->|"orchestrates"| ExtAgent

    %% Click Events for Backend Core - Orchestrator & Main
    click Orchestrator "https://github.com/theagenticai/theagenticbench/blob/main/agentic_bench/orchestrator.py"
    click Main "https://github.com/theagenticai/theagenticbench/blob/main/agentic_bench/main.py"

    %% Click Events for Backend Core - Agent Library
    click Coder "https://github.com/theagenticai/theagenticbench/blob/main/agentic_bench/agents/coder_agent.py"
    click FileSurfer "https://github.com/theagenticai/theagenticbench/blob/main/agentic_bench/agents/file_surfer.py"
    click RAG "https://github.com/theagenticai/theagenticbench/blob/main/agentic_bench/agents/rag_agent.py"
    click WebSurfer "https://github.com/theagenticai/theagenticbench/blob/main/agentic_bench/agents/web_surfer.py"

    %% Click Events for Backend Core - Utilities
    click MessageConversion "https://github.com/theagenticai/theagenticbench/blob/main/agentic_bench/utils/convert_messages.py"
    click Cancellation "https://github.com/theagenticai/theagenticbench/blob/main/agentic_bench/utils/cancellation_token.py"
    click Executors "https://github.com/theagenticai/theagenticbench/tree/main/agentic_bench/utils/executors/"
    click MarkdownProcessing "https://github.com/theagenticai/theagenticbench/tree/main/agentic_bench/utils/markdown_browser/"
    click OtherUtils "https://github.com/theagenticai/theagenticbench/blob/main/agentic_bench/utils/message_handler.py"

    %% Click Event for Backend Core - Ledger
    click Ledger "https://github.com/theagenticai/theagenticbench/blob/main/agentic_bench/ledger.py"

    %% Click Event for External Agent
    click ExtAgent "https://github.com/theagenticai/theagenticbench/tree/main/TheAgenticBrowser"

    %% Click Events for Frontend Application
    click FrontendUI "https://github.com/theagenticai/theagenticbench/tree/main/frontend/src"
    click Chat "https://github.com/theagenticai/theagenticbench/blob/main/frontend/src/pages/Chat.tsx"
    click Playground "https://github.com/theagenticai/theagenticbench/blob/main/frontend/src/pages/Playground.tsx"
    click Layout "https://github.com/theagenticai/theagenticbench/blob/main/frontend/src/pages/Layout.tsx"

    %% Click Events for Deployment & Containerization
    click BackendDocker "https://github.com/theagenticai/theagenticbench/tree/main/agentic_bench/Dockerfile"
    click FrontendDocker "https://github.com/theagenticai/theagenticbench/tree/main/frontend/Dockerfile"
    click DockerCompose "https://github.com/theagenticai/theagenticbench/blob/main/docker-compose.yaml"

    %% Styles
    classDef frontend fill:#fcebcf,stroke:#333,stroke-width:2px;
    classDef orchestration fill:#cfe2f3,stroke:#333,stroke-width:2px;
    classDef agent fill:#d9ead3,stroke:#333,stroke-width:2px;
    classDef utility fill:#ead1dc,stroke:#333,stroke-width:2px;
    classDef ledger fill:#fff2cc,stroke:#333,stroke-width:2px;
    classDef external fill:#d0e0e3,stroke:#333,stroke-width:2px;
    classDef deployment fill:#f4cccc,stroke:#333,stroke-width:2px;
```
