This document provides a high-level overview of Agent Zero's system architecture, showing how the major components fit together and communicate. It covers the frontend-to-backend communication flow, the agent execution model, memory systems, and external integration points.
For detailed information on specific subsystems:
Agent Zero is organized into eight major architectural layers:
| Layer | Purpose | Key Components |
|---|---|---|
| Frontend Layer | User interface and interaction | Alpine.js components, message rendering, modals |
| Communication Layer | Client-server synchronization | WebSocket push, HTTP polling fallback, REST API |
| Agent Core | Decision-making and orchestration | Agent, AgentContext, History, extensions |
| Tools & Capabilities | Agent actions and skills | Code execution, browser automation, knowledge search |
| Memory & AI | Knowledge storage and LLM calls | FAISS vector DB, memory consolidation, LiteLLM |
| External Interfaces | Third-party integrations | MCP client/server, A2A protocol, HTTP API |
| Configuration & Storage | Settings and state management | Settings system, projects, file utilities |
| Infrastructure | Deployment and runtime | Docker container, supervisord, SSH support |
Sources: [Diagram 1 from provided context], run_ui.py1-320 agent.py1-100 webui/index.html1-143
Sources: run_ui.py48-90 agent.py39-99 webui/index.js1-50 models.py292-320 python/helpers/memory.py54-90
Agent Zero implements a hybrid push/pull communication strategy to ensure reliable state synchronization between the web UI and the backend.
Sources: webui/index.js398-421 run_ui.py69-86 python/helpers/log.py1-50
| Component | File/Class | Purpose |
|---|---|---|
| WebSocket Server | socketio.AsyncServer in run_ui.py69-78 | Real-time bidirectional push |
| State Monitor | mark_dirty_for_context() in python/helpers/log.py32-39 | Tracks dirty state and triggers pushes |
| HTTP Polling | /poll endpoint in webui/index.js398-421 | Fallback mechanism (250ms cadence) |
| Snapshot Apply | applySnapshot() in webui/index.js290-396 | Unified update interface |
| Message Rendering | setMessages() in webui/js/messages.js75-111 | DOM update with process groups |
The system operates in three modes:
Sources: webui/index.js609-691 run_ui.py69-86 webui/js/messages.js75-111
The agent's decision-making loop is built around a continuous monologue() cycle that processes user messages, generates thoughts, invokes tools, and produces responses.
Sources: agent.py383-534 agent.py535-584 agent.py711-774 models.py292-464
Sources: agent.py356-425 agent.py45-203 agent.py298-317 agent.py326-342
The agent provides lifecycle hooks that extensions can tap into:
| Hook Name | Timing | Purpose |
|---|---|---|
agent_init | Agent construction | Initialize extension state |
monologue_start | Before message loop | Set up loop-level data |
message_loop_start | Each iteration start | Prepare for LLM call |
message_loop_prompts_before | Before prompt build | Modify prompt inputs |
message_loop_prompts_after | After prompt build | Edit system/history |
before_main_llm_call | Before LLM | Final intervention point |
reasoning_stream_chunk | During LLM reasoning | Process reasoning stream |
response_stream_chunk | During LLM response | Process response stream |
message_loop_end | After tool processing | Cleanup/logging |
monologue_end | After full monologue | Extract memories |
Sources: agent.py381-534 agent.py639-644 python/helpers/extension.py
Tools extend the agent's capabilities by providing actions it can perform. Each tool implements a standardized interface.
Sources: agent.py711-774 python/helpers/tool.py python/helpers/extract_tools.py
Sources: python/tools/code_execution_tool.py python/tools/skills_tool.py python/tools/knowledge_tool.py python/tools/browser_agent.py python/helpers/memory.py54-90
Code execution supports two execution modes:
| Mode | Class | Implementation | Use Case |
|---|---|---|---|
| Local | LocalInteractiveSession | python/helpers/shell_local.py | Docker/local PTY sessions |
| SSH | SSHInteractiveSession | python/helpers/shell_ssh.py | Remote execution via Paramiko |
Both implement pattern-based output detection to know when commands complete.
Sources: python/tools/code_execution_tool.py python/helpers/shell_local.py python/helpers/shell_ssh.py
Agent Zero uses a FAISS vector database for semantic memory with LLM-driven consolidation to prevent memory bloat.
Sources: python/helpers/memory.py54-260 python/extensions/message_loop_prompts_before/_20_recall_memories.py python/extensions/monologue_end/_10_memorize_memories.py
| Operation | Method | Purpose | Trigger |
|---|---|---|---|
| Recall | Memory.search() | Retrieve relevant memories | Before each LLM call |
| Memorize | Memory.memorize() | Extract new knowledge | After monologue |
| Consolidate | Memory.consolidate() | Merge similar memories | During memorization |
| Import | Memory.preload_knowledge() | Load knowledge files | Initialization |
The consolidation engine makes up to 4 LLM calls per memory to decide on actions:
Sources: python/helpers/memory.py260-489 python/helpers/memory.py489-722
Agent Zero exposes multiple protocols for external integration while also consuming external services.
Sources: run_ui.py1-320 python/helpers/mcp_server.py python/helpers/fasta2a_server.py python/helpers/mcp_handler.py
| Protocol | Path/Namespace | Authentication | Purpose |
|---|---|---|---|
| MCP Server | /mcp/sse, /mcp/message | Token | Expose agent to Claude/MCP clients |
| A2A Server | /a2a/* | Token | Agent-to-agent communication |
| External API | /api_message | API key | HTTP JSON interface |
| WebSocket | Namespaces: /, /agent_state | Session/CSRF | Real-time UI sync |
Sources: python/helpers/mcp_server.py python/helpers/fasta2a_server.py run_ui.py125-159
The MCP client (MCPConfig) consumes external MCP servers defined in settings:
Sources: python/helpers/mcp_handler.py python/helpers/settings.py636-691
Settings are managed through a centralized system with environment variable overrides and persistent storage.
Sources: python/helpers/settings.py355-428 python/helpers/settings.py605-719 python/helpers/dotenv.py
| Setting Category | Prefix | Example Keys | Purpose |
|---|---|---|---|
| Chat Model | chat_model_* | chat_model_provider, chat_model_name | Primary LLM config |
| Utility Model | util_model_* | util_model_provider, util_model_name | Background LLM tasks |
| Embedding Model | embed_model_* | embed_model_provider, embed_model_name | Vector embeddings |
| Browser Model | browser_model_* | browser_model_provider, browser_model_name | Browser automation LLM |
| Memory | memory_* | memory_recall_enabled, memory_memorize_consolidation | Memory behavior |
| MCP | mcp_* | mcp_servers, mcp_client_init_timeout | MCP configuration |
| Agent | agent_* | agent_profile, agent_memory_subdir | Agent profile |
Sources: python/helpers/settings.py512-602 initialize.py7-120
Agent Zero runs in a Docker container with multiple supervised services.
Sources: Dockerfile run_ui.py1-50 initialize.py1-200
| Process | Script/Command | Port | Purpose |
|---|---|---|---|
| Web UI | run_A0.sh | 80 | Main ASGI application |
| SearXNG | searxng service | 9000 | Meta-search engine |
| Tunnel | Tunnel daemon | 9001 | Remote HTTPS access |
| SSH | sshd | 22 | Remote shell access |
| Cron | cron | - | Scheduled tasks |
The main application uses Uvicorn with the Starlette ASGI framework to handle multiple protocols:
Sources: run_ui.py344-424 Dockerfile
Sources: webui/index.js39-127 agent.py246-296 agent.py383-534
Sources: python/extensions/message_loop_prompts_before/_20_recall_memories.py python/extensions/monologue_end/_10_memorize_memories.py python/helpers/memory.py260-722
The AgentContext class agent.py45-203 maintains per-conversation state:
| Field | Type | Purpose |
|---|---|---|
id | str | Unique context identifier |
agent0 | Agent | Root agent instance |
log | Log | Message log with updates tracking |
paused | bool | Execution pause state |
streaming_agent | Agent | Currently active agent |
task | DeferredTask | Background execution task |
type | AgentContextType | USER, TASK, or BACKGROUND |
data | dict | Context-specific data storage |
The LoopData class agent.py326-342 holds per-iteration state:
| Field | Type | Purpose |
|---|---|---|
iteration | int | Current iteration number |
system | list[str] | System prompt components |
user_message | Message | Original user message |
history_output | list[OutputMessage] | Formatted history |
extras_persistent | OrderedDict | Persistent context extras |
extras_temporary | OrderedDict | Single-iteration extras |
params_temporary | dict | Iteration parameters |
current_tool | Any | Currently executing tool |
The Log class python/helpers/log.py150-320 tracks all agent activity:
| Field | Type | Purpose |
|---|---|---|
guid | str | Unique log identifier |
logs | list[LogItem] | All log entries |
updates | list[LogItem] | Recent updates |
context | AgentContext | Parent context |
progress | str | Current progress text |
progress_active | bool | Progress animation state |
Sources: agent.py45-203 agent.py326-342 python/helpers/log.py150-320
Agent Zero's architecture is designed for extensibility, reliability, and multi-protocol integration:
The system achieves a balance between real-time responsiveness (WebSocket), reliability (polling fallback), and extensibility (hooks and plugins), making it suitable for both interactive use and programmatic integration.
Refresh this wiki