This page provides a high-level introduction to Agent Zero, its core capabilities, and system architecture. It is intended for developers and technical users who want to understand what Agent Zero is and how its components fit together.
For installation instructions, see Getting Started. For detailed architectural information, see Architecture Overview. For understanding fundamental concepts, see Key Concepts.
Sources: README.md1-167 knowledge/main/about/github_readme.md1-167
Agent Zero is a personal, organic agentic framework designed to be dynamic, transparent, and fully customizable. Unlike predefined agentic systems, Agent Zero grows and learns as you use it, adapting to your needs through persistent memory and continuous learning.
The framework is built on three core principles:
| Principle | Description |
|---|---|
| Dynamic Growth | Not pre-programmed for specific tasks; evolves organically through use and memory |
| Full Transparency | Readable, comprehensible codebase with no hidden logic or black boxes |
| Computer as Tool | Uses the operating system itself as the primary tool, writing code and executing commands as needed |
Agent Zero operates as a general-purpose personal assistant capable of:
Sources: README.md42-48 README.md72-86
Agent Zero is not pre-programmed for specific tasks. It functions as a general-purpose personal assistant that can tackle arbitrary problems by breaking them down, gathering information, executing code, and coordinating with other agent instances.
The system includes persistent memory implemented with FAISS vector databases, allowing it to memorize:
Sources: README.md72-76
Rather than relying on pre-built single-purpose tools, Agent Zero uses the operating system as its primary tool. It can write and execute code dynamically to create functionality as needed.
Default Tools:
Extensibility:
Sources: README.md79-86
Agent Zero implements a hierarchical multi-agent system where every agent has a superior providing instructions and subordinates helping with subtasks.
Hierarchy Characteristics:
Sources: README.md88-93
Agent Zero's behavior is defined entirely through configuration files and extensions rather than hard-coded logic.
Customization Points:
| Component | Location | Purpose |
|---|---|---|
| System Prompts | prompts/default/agent.system.md | Defines agent behavior and guidelines |
| Message Templates | prompts/ | All agent communication templates |
| Tools | python/tools/ | Core and custom tool implementations |
| Extensions | python/extensions/ | Lifecycle hooks for injecting functionality |
| Settings | usr/settings.json | Runtime configuration and API keys |
The framework provides no hard-coded rails - agent behavior is entirely prompt-driven and extensible.
Sources: README.md96-103
Agent Zero emphasizes clear communication between all participants:
The communication layer uses dual-mode synchronization:
Sources: README.md107-112
This diagram shows the primary code entities and their relationships. Key classes like Agent, AgentContext, Log, and Tool form the execution backbone, while the Memory system handles persistent learning.
Sources: High-level diagrams provided, README.md1-167
This diagram traces a typical message through the system, showing how run_ui.py orchestrates communication, the Agent.monologue() loop processes requests, tools are executed, and StateMonitor synchronizes UI updates.
Sources: High-level diagrams provided, run_ui.py python/helpers/agent.py python/helpers/state_monitor.py
The following table summarizes Agent Zero's major subsystems and links to their detailed documentation:
| Component | Description | Documentation |
|---|---|---|
| Agent System | Core execution engine implementing the monologue loop, tool orchestration, and multi-agent hierarchy | Core Agent System |
| Tools | Extensible tool system including code execution, knowledge search, browser automation, and scheduler | Tools and Capabilities |
| Memory | FAISS-based vector database for persistent learning, knowledge storage, and similarity search | Memory and Learning |
| Skills | SKILL.md standard for portable agent capabilities compatible with Claude Code, Cursor, and other tools | Skills System |
| Extensions | Lifecycle hooks for injecting functionality at system prompt, loop start, prompt preparation, and loop end | Prompts and Extensions |
| Configuration | Settings management with priority-based loading from JSON, environment variables, and model provider definitions | Configuration and Settings |
| Projects | Isolated workspaces with dedicated memory, knowledge, secrets, and custom instructions | Projects |
| Scheduler | Background task automation with cron-based scheduling, ad-hoc triggers, and planned execution | Task Scheduler |
| MCP Integration | Model Context Protocol client for connecting to external tool servers (local stdio and remote HTTP) | MCP Integration |
| Web UI | Alpine.js-based reactive interface with WebSocket push and polling fallback for real-time updates | Web User Interface |
Sources: README.md70-141 Table of contents structure
Pull and run Agent Zero with Docker:
Visit http://localhost:50001 to access the Web UI.
Sources: README.md60-67
For detailed platform-specific installation instructions covering Docker Desktop setup on Windows, macOS, and Linux, see Getting Started.
For production VPS deployment with reverse proxy and SSL, see the installation documentation.
For local development setup without Docker, see the development setup guide.
Sources: README.md50-56 docs/setup/installation.md1-586
After installation, configure Agent Zero through the Settings UI:
Settings can also be configured via A0_SET_* environment variables for automated deployments.
Sources: docs/setup/installation.md228-375
Once configured, explore Agent Zero's capabilities:
Sources: README.md152-166
Agent Zero excels at tasks requiring code execution, research, and automation:
| Use Case | Description |
|---|---|
| Financial Analysis | "Find last month's Bitcoin/USD price trend, correlate with major cryptocurrency news events, generate annotated chart with highlighted key dates" |
| Excel Automation | "Scan incoming directory for financial spreadsheets, validate and clean data, consolidate from multiple sources, generate executive reports with flagged anomalies" |
| API Integration | "Use this Google Gemini API snippet to generate product images, remember the integration for future use" - agent learns and stores the solution |
| Server Monitoring | "Check server status every 30 minutes: CPU usage, disk space, memory. Alert if metrics exceed thresholds" - scheduled task with credentials |
| Multi-Client Isolation | Separate projects for each client with isolated memory, custom instructions, and dedicated secrets |
Sources: README.md114-124
Agent Zero is capable of executing arbitrary code and terminal commands on your system. Always run Agent Zero in an isolated environment (Docker container recommended) and carefully review requests before execution.
The entire framework is guided by prompt files in the prompts/ directory. Agent behavior, tool instructions, and communication templates are all defined through these prompts, making the system highly customizable but requiring careful prompt engineering.
Agent Zero requires:
Sources: README.md141-149
Sources: README.md388-392
Refresh this wiki
This wiki was recently refreshed. Please wait 1 day to refresh again.