# frdel/agent-zero architecture

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

- Interactive diagram: https://gitdiagram.com/frdel/agent-zero
- Repository: https://github.com/frdel/agent-zero

## Overview

##### Project type & purpose
- Agent Zero is a full-stack, prompt-based “organic” AI assistant framework.
- It provides both a CLI interface (run_cli.py) and a rich Web UI (webui/) backed by a Python API server (python/api, run_ui.py).
- It’s intended to run containerized (docker/run) and integrates with external services (LLM APIs, SearxNG search, optional vector DB, TTS/STT).

##### High-level architectural layers
A. Presentation Layer
- CLI client (run_cli.py)
- Web UI client (static files in webui/, index.html/css/js)
B. API Layer
- Python HTTP server (run_ui.py or run_cli.py for CLI mode)
- Endpoints under python/api/*.py (message, health, upload, settings, etc.)
C. Core Agent Engine
- agent.py orchestrator
- initialize.py, preload.py, prepare.py (startup tasks)
- python/extensions (message loop hooks, reflection, system-prompt injection)
- python/tools (built-in tool plugins: code execution, browser, knowledge, memory, etc.)
- python/helpers (utility modules: LLM calls, file I/O, shell helpers, search clients, vector_db, RAG, etc.)
- prompts/ (all system- and user-prompt templates, tool instructions)
D. Data & Persistence
- memory/ (persistent agent memory)
- knowledge/ (RAG knowledge bases)
- logs/ (chat session transcripts in HTML)
- example.env, settings.yaml (configuration)
E. External Services & Tools
- LLM provider APIs (OpenAI, etc.)
- SearxNG search engine (container mounted at docker/run/fs/etc/searxng)
- Optional vector DB (e.g., Chroma via python/helpers/vector_db)
- Browser automation (Playwright/Chromium via python/helpers/browser & lib/browser/*.js)
- Local shell / code execution (python/helpers/shell_local, code_execution_tool)
- TTS/STT (python/helpers/whisper)
F. Container Orchestration
- docker/run/docker-compose.yml
- Dockerfiles (Dockerfile, DockerfileKali)
- Mounted filesystem layout under docker/run/fs (configs, init scripts, installer scripts)

##### Component relationships & data flows
- User → CLI or Web UI → HTTP/WebSocket → Python API
- API handlers call Core Agent Engine (agent.py)
- Agent Engine uses:
- Prompt templates (prompts/)
- Tools (python/tools/) via helper wrappers (python/helpers/tool.py)
- Extensions to hook before/after message loops
- LLM calls for generation (python/helpers/call_llm.py)
- Memory & RAG: load/save context (python/helpers/memory, vector_db)
- File system operations (logs/, memory/, knowledge/)
- External search via SearxNG (python/helpers/searxng)
- Browser automation (lib/browser/*.js + python/helpers/browser_use)
- Results flow back up: Engine → API → UI or CLI → User
- Docker Compose wires up:
- Python application container
- SearxNG service container
- Optional additional services (vector DB)

##### Architectural patterns & design principles
- Layered architecture (Presentation → API → Business → Data → External)
- Plugin/module pattern for “tools” and “extensions” (easy to extend)
- Prompt-driven behavior: everything guided by prompt templates in prompts/
- Multi-agent hierarchy: parent agent spawns subordinate agents for subtasks
- Containerized, reproducible environment (Docker + Docker Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User((User))

    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["CLI Client\n(run_cli.py)"]
        WebUI["Web UI Client\n(webui/)"]
    end

    %% API Layer
    subgraph "API Layer"
        HTTP["HTTP Server\n(run_ui.py)"]
        Endpoints["REST/WebSocket Endpoints\n(python/api/)"]
    end

    %% Core Agent Engine
    subgraph "Core Agent Engine"
        Orchestrator["Orchestrator\n(agent.py)"]
        Initialize["initialize.py"]
        Preload["preload.py"]
        Prepare["prepare.py"]
        Extensions["Extensions\n(python/extensions/)"]
        Tools["Tool Plugins\n(python/tools/)"]
        Helpers["Helper Utilities\n(python/helpers/)"]
        Prompts["Prompt Templates\n(prompts/)"]
    end

    %% Data & Persistence
    subgraph "Data & Persistence"
        Memory["Agent Memory\n(memory/)"]
        Knowledge["Knowledge Bases\n(knowledge/)"]
        Logs["Chat Logs\n(logs/)"]
        Env["Env Config\n(example.env)"]
        SXSettings["SearxNG Settings\n(docker/run/fs/etc/searxng/settings.yml)"]
    end

    %% External Services
    subgraph "External Services"
        LLM["LLM Provider APIs"]
        Searx["SearxNG Search\n(docker/run/fs/etc/searxng/)"]
        Vector["Vector DB Helper\n(python/helpers/vector_db.py)"]
        Browser["Browser Automation\n(lib/browser/ + python/helpers/browser_use.py)"]
        Shell["Shell & Code Execution\n(python/helpers/shell_local.py)"]
        TTS["TTS/STT\n(python/helpers/whisper.py)"]
    end

    %% Docker Compose Environment
    subgraph "Docker Compose Environment"
        Compose["docker-compose.yml"]
        Dockerfile["Dockerfiles\n(Dockerfile, DockerfileKali)"]
        MountFS["Mounted FS\n(docker/run/fs/)"]
    end

    %% Connections
    User --> CLI
    User --> WebUI
    CLI --> HTTP
    WebUI --> HTTP
    HTTP --> Endpoints
    Endpoints --> Orchestrator
    HTTP --> Orchestrator
    Orchestrator --> Initialize
    Orchestrator --> Preload
    Orchestrator --> Prepare
    Orchestrator --> Prompts
    Orchestrator --> Extensions
    Orchestrator --> Tools
    Orchestrator --> Helpers
    Orchestrator --> Memory
    Orchestrator --> Knowledge
    Orchestrator --> Logs
    Extensions --> Helpers
    Tools --> Helpers
    Helpers --> LLM
    Helpers --> Searx
    Helpers --> Vector
    Helpers --> Browser
    Helpers --> Shell
    Helpers --> TTS
    Orchestrator --> LLM

    %% Click Events
    click CLI "https://github.com/frdel/agent-zero/blob/main/run_cli.py"
    click WebUI "https://github.com/frdel/agent-zero/tree/main/webui/"
    click HTTP "https://github.com/frdel/agent-zero/blob/main/run_ui.py"
    click Endpoints "https://github.com/frdel/agent-zero/tree/main/python/api/"
    click Orchestrator "https://github.com/frdel/agent-zero/blob/main/agent.py"
    click Initialize "https://github.com/frdel/agent-zero/blob/main/initialize.py"
    click Preload "https://github.com/frdel/agent-zero/blob/main/preload.py"
    click Prepare "https://github.com/frdel/agent-zero/blob/main/prepare.py"
    click Extensions "https://github.com/frdel/agent-zero/tree/main/python/extensions/"
    click Tools "https://github.com/frdel/agent-zero/tree/main/python/tools/"
    click Helpers "https://github.com/frdel/agent-zero/tree/main/python/helpers/"
    click Prompts "https://github.com/frdel/agent-zero/tree/main/prompts/"
    click Memory "https://github.com/frdel/agent-zero/tree/main/memory/"
    click Knowledge "https://github.com/frdel/agent-zero/tree/main/knowledge/"
    click Logs "https://github.com/frdel/agent-zero/tree/main/logs/"
    click Env "https://github.com/frdel/agent-zero/blob/main/example.env"
    click SXSettings "https://github.com/frdel/agent-zero/blob/main/docker/run/fs/etc/searxng/settings.yml"
    click Searx "https://github.com/frdel/agent-zero/tree/main/docker/run/fs/etc/searxng/"
    click Vector "https://github.com/frdel/agent-zero/blob/main/python/helpers/vector_db.py"
    click Browser "https://github.com/frdel/agent-zero/tree/main/lib/browser/"
    click Shell "https://github.com/frdel/agent-zero/blob/main/python/helpers/shell_local.py"
    click TTS "https://github.com/frdel/agent-zero/blob/main/python/helpers/whisper.py"
    click Compose "https://github.com/frdel/agent-zero/blob/main/docker/run/docker-compose.yml"
    click Dockerfile "https://github.com/frdel/agent-zero/tree/main/docker/run/Dockerfile"

    %% Styles
    classDef presentation fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef api fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef engine fill:#98FB98,stroke:#000,stroke-width:1px;
    classDef tools fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef data fill:#DDA0DD,stroke:#000,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef docker stroke-dasharray:5 5,stroke:#666,fill:none;
    class CLI,WebUI presentation
    class HTTP,Endpoints api
    class Orchestrator,Initialize,Preload,Prepare,Prompts,Extensions engine
    class Tools,Helpers tools
    class Memory,Knowledge,Logs,Env,SXSettings data
    class LLM,Searx,Vector,Browser,Shell,TTS external
    class Compose,Dockerfile,MountFS docker
```
