# agent0ai/agent-zero architecture

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

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

## Overview

Agent Zero is a user-operated AI agent with a Linux workspace: users chat through the Web UI, configure a model, and ask the agent to research, create files, or work through browser and desktop tools. The map includes chat orchestration, extensibility and plugins, workspace/project support, and major documented capabilities. The README supports the user workflow and product branches; source-index references support only the listed internal links. Several capabilities are documented but their runtime wiring was not sampled, so those links are omitted.

Main entry points: [`agent.py`](https://github.com/agent0ai/agent-zero/blob/main/agent.py) (Agent runtime), [`helpers/plugins.py`](https://github.com/agent0ai/agent-zero/blob/main/helpers/plugins.py) (Plugin system), [`helpers/extension.py`](https://github.com/agent0ai/agent-zero/blob/main/helpers/extension.py) (Extension hooks), [`helpers/files.py`](https://github.com/agent0ai/agent-zero/blob/main/helpers/files.py) (File access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Chat and orchestration"]
  node_agent["Agent runtime<br/>[agent.py]"]
  node_chatstate[("Chat persistence<br/>[persist_chat.py]")]
  node_queue["Message queue<br/>[message_queue.py]"]
  node_subagents["Subagents<br/>[subagents.py]"]
end

subgraph group_framework["Runtime framework"]
  node_extensions["Extension hooks<br/>[extension.py]"]
  node_plugins["Plugin system<br/>[plugins.py]"]
  node_modules["Module loading<br/>[modules.py]"]
  node_watchdog["Watchdogs<br/>[watchdog.py]"]
  node_defer["Deferred work<br/>[defer.py]"]
  node_initialize["Initialization<br/>[initialize.py]"]
  node_runtime["Runtime config<br/>[runtime.py]"]
  node_settings[("Settings<br/>[settings.py]")]
  node_localization["Localization<br/>[localization.py]"]
  node_printing["Output formatting<br/>[print_style.py]"]
  node_strings["String utilities<br/>[strings.py]"]
end

subgraph group_workspace["Workspace and projects"]
  node_files["File access<br/>[files.py]"]
  node_projects[("Projects<br/>[projects.py]")]
  node_backup["Backup and restore<br/>[backup.py]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_browser["Browser tools<br/>[browser.py]"]
  node_desktop["Desktop tools<br/>[desktop_routes.py]"]
  node_documentquery["Document query<br/>[document_query.py]"]
  node_search["Web search<br/>[search_engine.py]"]
  node_memory["Agent memory"]
  node_integrations["External integrations"]
end

subgraph group_interfaces["User interfaces"]
  node_webui["Web UI<br/>[index.js]"]
  node_api["Chat API<br/>[message.py]"]
end

node_user(("User"))

node_user -->|"sends request"| node_webui
node_webui -.->|"starts chat"| node_agent
node_agent -->|"uses persistence"| node_chatstate
node_agent -->|"uses"| node_subagents
node_agent -->|"calls hooks"| node_extensions
node_agent -->|"uses"| node_files
node_agent -->|"uses"| node_printing
node_plugins -->|"loads hooks"| node_extensions
node_plugins -->|"uses"| node_files
node_plugins -->|"uses"| node_modules
node_plugins -->|"uses"| node_projects
node_plugins -->|"uses"| node_subagents
node_extensions -->|"discovers extensions"| node_modules
node_extensions -->|"scans files"| node_files
node_search -->|"returns results"| node_agent
node_documentquery -->|"indexes and queries"| node_agent
node_documentquery -->|"reads documents"| node_files
node_user -->|"requests browsing"| node_browser
node_user -->|"requests desktop work"| node_desktop
node_user -->|"asks about documents"| node_documentquery
node_user -->|"requests research"| node_search
node_user -->|"organizes work"| node_projects
node_user -->|"adds integrations"| node_integrations
node_user -->|"keeps backups"| node_backup

click node_webui "https://github.com/agent0ai/agent-zero/blob/main/webui/index.js"
click node_api "https://github.com/agent0ai/agent-zero/blob/main/api/message.py"
click node_agent "https://github.com/agent0ai/agent-zero/blob/main/agent.py"
click node_chatstate "https://github.com/agent0ai/agent-zero/blob/main/helpers/persist_chat.py"
click node_queue "https://github.com/agent0ai/agent-zero/blob/main/helpers/message_queue.py"
click node_subagents "https://github.com/agent0ai/agent-zero/blob/main/helpers/subagents.py"
click node_extensions "https://github.com/agent0ai/agent-zero/blob/main/helpers/extension.py"
click node_plugins "https://github.com/agent0ai/agent-zero/blob/main/helpers/plugins.py"
click node_modules "https://github.com/agent0ai/agent-zero/blob/main/helpers/modules.py"
click node_watchdog "https://github.com/agent0ai/agent-zero/blob/main/helpers/watchdog.py"
click node_defer "https://github.com/agent0ai/agent-zero/blob/main/helpers/defer.py"
click node_initialize "https://github.com/agent0ai/agent-zero/blob/main/initialize.py"
click node_runtime "https://github.com/agent0ai/agent-zero/blob/main/helpers/runtime.py"
click node_settings "https://github.com/agent0ai/agent-zero/blob/main/helpers/settings.py"
click node_localization "https://github.com/agent0ai/agent-zero/blob/main/helpers/localization.py"
click node_printing "https://github.com/agent0ai/agent-zero/blob/main/helpers/print_style.py"
click node_strings "https://github.com/agent0ai/agent-zero/blob/main/helpers/strings.py"
click node_files "https://github.com/agent0ai/agent-zero/blob/main/helpers/files.py"
click node_projects "https://github.com/agent0ai/agent-zero/blob/main/helpers/projects.py"
click node_browser "https://github.com/agent0ai/agent-zero/blob/main/plugins/_browser/tools/browser.py"
click node_desktop "https://github.com/agent0ai/agent-zero/blob/main/plugins/_desktop/helpers/desktop_routes.py"
click node_documentquery "https://github.com/agent0ai/agent-zero/blob/main/plugins/_document_query/helpers/document_query.py"
click node_search "https://github.com/agent0ai/agent-zero/blob/main/plugins/_search_engine/tools/search_engine.py"
click node_memory "https://github.com/agent0ai/agent-zero/blob/main/plugins/_memory/extensions/python/monologue_end/_50_memorize_fragments.py"
click node_integrations "https://github.com/agent0ai/agent-zero/blob/main/helpers/integration_commands.py"
click node_backup "https://github.com/agent0ai/agent-zero/blob/main/helpers/backup.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent,node_chatstate,node_queue,node_subagents,node_user toneBlue
class node_extensions,node_plugins,node_modules,node_watchdog,node_defer,node_initialize,node_runtime,node_settings,node_localization,node_printing,node_strings toneAmber
class node_files,node_projects,node_backup toneMint
class node_browser,node_desktop,node_documentquery,node_search,node_memory,node_integrations toneRose
class node_webui,node_api toneIndigo
```

## Components

### Chat and orchestration

- [Agent runtime](https://github.com/agent0ai/agent-zero/blob/main/agent.py): `agent.py`
- [Chat persistence](https://github.com/agent0ai/agent-zero/blob/main/helpers/persist_chat.py): `helpers/persist_chat.py`
- [Message queue](https://github.com/agent0ai/agent-zero/blob/main/helpers/message_queue.py): `helpers/message_queue.py`
- [Subagents](https://github.com/agent0ai/agent-zero/blob/main/helpers/subagents.py): `helpers/subagents.py`

### Runtime framework

- [Extension hooks](https://github.com/agent0ai/agent-zero/blob/main/helpers/extension.py): `helpers/extension.py`
- [Plugin system](https://github.com/agent0ai/agent-zero/blob/main/helpers/plugins.py): `helpers/plugins.py`
- [Module loading](https://github.com/agent0ai/agent-zero/blob/main/helpers/modules.py): `helpers/modules.py`
- [Watchdogs](https://github.com/agent0ai/agent-zero/blob/main/helpers/watchdog.py): `helpers/watchdog.py`
- [Deferred work](https://github.com/agent0ai/agent-zero/blob/main/helpers/defer.py): `helpers/defer.py`
- [Initialization](https://github.com/agent0ai/agent-zero/blob/main/initialize.py): `initialize.py`
- [Runtime config](https://github.com/agent0ai/agent-zero/blob/main/helpers/runtime.py): `helpers/runtime.py`
- [Settings](https://github.com/agent0ai/agent-zero/blob/main/helpers/settings.py): `helpers/settings.py`
- [Localization](https://github.com/agent0ai/agent-zero/blob/main/helpers/localization.py): `helpers/localization.py`
- [Output formatting](https://github.com/agent0ai/agent-zero/blob/main/helpers/print_style.py): `helpers/print_style.py`
- [String utilities](https://github.com/agent0ai/agent-zero/blob/main/helpers/strings.py): `helpers/strings.py`

### Workspace and projects

- [File access](https://github.com/agent0ai/agent-zero/blob/main/helpers/files.py): `helpers/files.py`
- [Projects](https://github.com/agent0ai/agent-zero/blob/main/helpers/projects.py): `helpers/projects.py`
- [Backup and restore](https://github.com/agent0ai/agent-zero/blob/main/helpers/backup.py): `helpers/backup.py`

### Agent capabilities

- [Browser tools](https://github.com/agent0ai/agent-zero/blob/main/plugins/_browser/tools/browser.py): `plugins/_browser/tools/browser.py`
- [Desktop tools](https://github.com/agent0ai/agent-zero/blob/main/plugins/_desktop/helpers/desktop_routes.py): `plugins/_desktop/helpers/desktop_routes.py`
- [Document query](https://github.com/agent0ai/agent-zero/blob/main/plugins/_document_query/helpers/document_query.py): `plugins/_document_query/helpers/document_query.py`
- [Web search](https://github.com/agent0ai/agent-zero/blob/main/plugins/_search_engine/tools/search_engine.py): `plugins/_search_engine/tools/search_engine.py`
- [Agent memory](https://github.com/agent0ai/agent-zero/blob/main/plugins/_memory/extensions/python/monologue_end/_50_memorize_fragments.py): `plugins/_memory/extensions/python/monologue_end/_50_memorize_fragments.py`
- [External integrations](https://github.com/agent0ai/agent-zero/blob/main/helpers/integration_commands.py): `helpers/integration_commands.py`

### User interfaces

- [Web UI](https://github.com/agent0ai/agent-zero/blob/main/webui/index.js): `webui/index.js`
- [Chat API](https://github.com/agent0ai/agent-zero/blob/main/api/message.py): `api/message.py`

### Other components

- **User**

## Connections

- User → Web UI: sends request (evidence: `README.md`)
- Web UI → Agent runtime: starts chat
- Agent runtime → Chat persistence: uses persistence (evidence: `helpers/fasta2a_server.py`)
- Agent runtime → Subagents: uses (evidence: `agent.py`)
- Agent runtime → Extension hooks: calls hooks (evidence: `agent.py`)
- Agent runtime → File access: uses (evidence: `agent.py`)
- Agent runtime → Output formatting: uses (evidence: `agent.py`)
- Plugin system → Extension hooks: loads hooks (evidence: `helpers/plugins.py`)
- Plugin system → File access: uses (evidence: `helpers/plugins.py`)
- Plugin system → Module loading: uses (evidence: `helpers/plugins.py`)
- Plugin system → Projects: uses (evidence: `helpers/plugins.py`)
- Plugin system → Subagents: uses (evidence: `helpers/plugins.py`)
- Extension hooks → Module loading: discovers extensions (evidence: `helpers/extension.py`)
- Extension hooks → File access: scans files (evidence: `helpers/extension.py`)
- Web search → Agent runtime: returns results (evidence: `plugins/_search_engine/tools/search_engine.py`)
- Document query → Agent runtime: indexes and queries (evidence: `plugins/_document_query/helpers/document_query.py`)
- Document query → File access: reads documents (evidence: `plugins/_document_query/helpers/document_query.py`)
- User → Browser tools: requests browsing (evidence: `README.md`)
- User → Desktop tools: requests desktop work (evidence: `README.md`)
- User → Document query: asks about documents (evidence: `README.md`)
- User → Web search: requests research (evidence: `README.md`)
- User → Projects: organizes work (evidence: `README.md`)
- User → External integrations: adds integrations (evidence: `README.md`)
- User → Backup and restore: keeps backups (evidence: `README.md`)
