# Where to Find Detailed Architectural Explanations for Agent Zero: A Complete Developer's Guide

> Discover detailed architectural explanations for Agent Zero in the official repository. Explore the hierarchical agent system and seven core components for developers.

- Repository: [Agent Zero/agent-zero](https://github.com/agent0ai/agent-zero)
- Tags: architecture
- Published: 2026-02-23

---

**The most comprehensive architectural documentation for Agent Zero is located in [`docs/developer/architecture.md`](https://github.com/agent0ai/agent-zero/blob/main/docs/developer/architecture.md), which details the hierarchical agent system, Docker runtime, and seven core component pillars.**

Agent Zero is an open-source autonomous agent framework designed for hierarchical task delegation and extensible tool use. If you are looking for detailed architectural explanations for Agent Zero, the project provides extensive documentation within the repository itself, alongside well-structured source code that implements a seven-pillar component system. This guide maps the official documentation to specific implementation files so you can navigate from high-level concepts to concrete code.

## Primary Architecture Documentation Location

The definitive architectural explanation resides in **[`docs/developer/architecture.md`](https://github.com/agent0ai/agent-zero/blob/main/docs/developer/architecture.md)**. This document provides a comprehensive overview organized into four major sections: System Architecture, Runtime Architecture, Core Components, and detailed subsystem breakdowns. Each section contains deep dives into specific implementation areas, with direct links to relevant source files.

The documentation explains how Agent Zero implements a **hierarchical agent system** where a top-level user context delegates tasks to subordinate agents, all running within a Docker-based runtime environment that ensures dependency isolation and cross-platform consistency.

## Core Architectural Components

Agent Zero is built upon seven core pillars, each implemented as a distinct subsystem with clear responsibilities and interfaces.

### Agents

The **`Agent`** class in [`agent.py`](https://github.com/agent0ai/agent-zero/blob/main/agent.py) implements the central message loop, hierarchical delegation, and tool orchestration. This class manages the conversation state, processes incoming messages, and coordinates with subordinate agents through the `AgentContext` system. The architecture supports nested agent hierarchies where parent agents can spawn child agents to handle specific subtasks.

### Tools

Built-in tools reside in **`python/tools/`** and inherit from the abstract **`Tool`** base class defined in [`python/helpers/tool.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/tool.py). The framework includes tools for code execution (`code_execution_tool`), web search (`search_engine`), and hierarchical delegation (`call_subordinate`). Each tool implements a standard interface that allows the agent to discover capabilities and execute them with typed parameters.

### Memory System

The hybrid memory implementation in **[`python/helpers/memory.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/memory.py)** combines persistent JSON storage with vector embeddings. This dual-mode system stores conversation fragments, solutions, and metadata in a structured format while enabling semantic retrieval through vector similarity search. The memory system integrates with the agent's context to provide long-term persistence across sessions.

### Prompts

System prompts are assembled from markdown files located in **`prompts/`**, with [`agent.system.main.md`](https://github.com/agent0ai/agent-zero/blob/main/agent.system.main.md) serving as the primary template. The prompt architecture uses a hierarchical composition system where the main prompt imports specialized sub-prompts for specific tools and capabilities. This modular approach allows developers to customize agent behavior by modifying markdown files without changing Python code.

### Knowledge

Knowledge bases are imported from **`/knowledge`** and made searchable through the Knowledge Tool. The architecture supports multiple knowledge formats and provides a unified query interface that agents can use to retrieve domain-specific information during task execution.

### Skills

Skills follow the open SKILL.md standard and are stored in **`/usr/skills`** or **`/skills`**. These reusable capability modules extend agent functionality through well-defined interfaces, allowing the community to share and import pre-built skill sets.

### Extensions

The plug-in system in **`python/extensions/`** enables custom behavior injection at well-defined extension points. The extension architecture uses decorators to register callbacks for events such as response streaming and tool execution, allowing developers to modify core behavior without forking the codebase.

## Key Source Files and Implementation Details

Understanding Agent Zero's architecture requires familiarity with these critical files:

| File | Role |
|------|------|
| [`docs/developer/architecture.md`](https://github.com/agent0ai/agent-zero/blob/main/docs/developer/architecture.md) | Authoritative architecture description and high-level system overview |
| [`agent.py`](https://github.com/agent0ai/agent-zero/blob/main/agent.py) | Core `Agent` class, message loop, and tool orchestration |
| [`initialize.py`](https://github.com/agent0ai/agent-zero/blob/main/initialize.py) | Framework bootstrap that sets up Docker runtime and loads settings |
| [`models.py`](https://github.com/agent0ai/agent-zero/blob/main/models.py) | Model configuration structures and factory helpers |
| [`python/helpers/tool.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/tool.py) | Abstract `Tool` base class used by all built-in tools |
| `python/tools/*.py` | Implementations of built-in tools (search, code execution, memory, etc.) |
| [`python/helpers/extension.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/extension.py) | Extension-point registration and dispatch system |
| [`prompts/agent.system.main.md`](https://github.com/agent0ai/agent-zero/blob/main/prompts/agent.system.main.md) | Main system prompt that composes sub-prompts |
| [`python/helpers/memory.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/memory.py) | Hybrid memory implementation (vector store + JSON) |
| [`python/helpers/mcp_handler.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/mcp_handler.py) | MCP (Model-Context-Protocol) client for remote model servers |

## Practical Code Examples

### Initializing a Top-Level Agent Session

This example demonstrates how the Docker container entry point initializes the hierarchical agent system using `AgentConfig` and `AgentContext`:

```python
from agent import Agent, AgentContext, AgentConfig
import models

# Configure model providers (defined in models.py)

config = AgentConfig(
    chat_model=models.ModelConfig(provider="openai", name="gpt-4o"),
    utility_model=models.ModelConfig(provider="openai", name="gpt-4o-mini"),
    embeddings_model=models.ModelConfig(provider="openai", name="text-embedding-3-large"),
    browser_model=models.ModelConfig(provider="openai", name="gpt-4o-mini"),
    mcp_servers="localhost:5000",
    profile="default"
)

# Create the top-level "User" context

top_ctx = AgentContext(config=config, name="User")

# Initiate conversation

top_ctx.communicate(
    msg=AgentContext.UserMessage(message="Explain the difference between recursion and iteration.")
)

```

*Relevant source:* [`agent.py`](https://github.com/agent0ai/agent-zero/blob/main/agent.py) (Agent initialization, `AgentContext.communicate`) – [link](https://github.com/agent0ai/agent-zero/blob/main/agent.py)

### Executing a Built-in Tool

This snippet shows how the agent framework processes tool requests. The LLM emits a tool call, which `process_tools` routes to the appropriate implementation in `python/tools/`:

```python
from agent import AgentContext
from python.helpers.tool import ToolResult

# Access the current running context

ctx = AgentContext.current()

# The LLM generates a request like:

# {"tool_name":"search_engine","tool_args":{"query":"latest Python 3.12 features"}}

# process_tools parses this and invokes the tool.

# Implementation resides in python/tools/search_engine.py

```

*Tool implementation:* [`python/tools/search_engine.py`](https://github.com/agent0ai/agent-zero/blob/main/python/tools/search_engine.py) – [link](https://github.com/agent0ai/agent-zero/blob/main/python/tools/search_engine.py)

### Registering a Custom Extension

Extensions allow you to inject behavior at specific points in the agent lifecycle without modifying core files:

```python

# File: python/extensions/99_custom_logger.py

from python.helpers.extension import register_extension

@register_extension("response_stream")
async def log_response(agent, loop_data, stream_data):
    # Log every chunk the LLM streams back

    agent.context.log.log(
        type="info",
        heading="LLM response chunk",
        content=stream_data["chunk"]
    )

```

*Extension system:* [`python/helpers/extension.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/extension.py) – [link](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/extension.py)

## Summary

- **Primary Documentation:** The authoritative architectural explanation for Agent Zero is located in [`docs/developer/architecture.md`](https://github.com/agent0ai/agent-zero/blob/main/docs/developer/architecture.md), which provides comprehensive coverage of the system's design philosophy and component interactions.

- **Seven Core Pillars:** The architecture is organized around Agents, Tools, Memory System, Prompts, Knowledge, Skills, and Extensions—each implemented as distinct, modular subsystems with clear interfaces.

- **Hierarchical Design:** The system implements a parent-child agent hierarchy managed through `AgentContext` in [`agent.py`](https://github.com/agent0ai/agent-zero/blob/main/agent.py), enabling complex task delegation and coordination.

- **Extension Points:** The framework supports custom behavior injection via the extension system in [`python/helpers/extension.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/extension.py), allowing developers to modify functionality without forking the codebase.

- **Docker-Based Runtime:** The architecture assumes containerized execution through the Docker setup in `/docker`, ensuring consistent environments across development and production.

## Frequently Asked Questions

### Where is the main architecture documentation for Agent Zero located?

The primary architectural documentation is located at [`docs/developer/architecture.md`](https://github.com/agent0ai/agent-zero/blob/main/docs/developer/architecture.md) in the repository root. This file contains the authoritative explanation of the system's high-level design, including the hierarchical agent structure, Docker runtime model, and detailed breakdowns of all seven core components. The document is organized into sections covering System Architecture, Runtime Architecture, and Core Components, with direct links to relevant source files.

### What are the seven core pillars of Agent Zero's architecture?

Agent Zero's architecture is built upon seven core pillars: **Agents** (the message loop and delegation logic in [`agent.py`](https://github.com/agent0ai/agent-zero/blob/main/agent.py)), **Tools** (executable capabilities in `python/tools/`), **Memory System** (hybrid JSON and vector storage in [`python/helpers/memory.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/memory.py)), **Prompts** (modular markdown templates in `prompts/`), **Knowledge** (searchable domain data in `/knowledge`), **Skills** (reusable capability modules in `/skills`), and **Extensions** (plugin system in `python/extensions/`). Each pillar operates as an independent subsystem with defined interfaces for integration.

### How does Agent Zero handle tool execution and orchestration?

Tool execution is orchestrated through the `Agent` class in [`agent.py`](https://github.com/agent0ai/agent-zero/blob/main/agent.py), which processes LLM-generated tool requests and dispatches them to concrete implementations in `python/tools/`. Each tool inherits from the abstract `Tool` base class defined in [`python/helpers/tool.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/tool.py), ensuring consistent interfaces for parameter validation and execution. The system supports built-in tools like `code_execution_tool`, `search_engine`, and `call_subordinate`, with the agent managing the full lifecycle from request parsing to result integration.

### Can I extend Agent Zero without modifying the core codebase?

Yes, Agent Zero provides a comprehensive extension system that allows you to inject custom behavior at well-defined extension points without forking or modifying core files. The extension framework in [`python/helpers/extension.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/extension.py) uses Python decorators to register callbacks for events such as `response_stream`, tool execution, and agent initialization. You can place custom extension files in `python/extensions/` (e.g., [`99_custom_logger.py`](https://github.com/agent0ai/agent-zero/blob/main/99_custom_logger.py)), and the framework will automatically load and execute your code at the appropriate lifecycle stages, enabling modifications to logging, response processing, and tool behavior.