How frdel/agent-zero works
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)