These examples are intentionally short and high signal so tool-call shape guidance
can live in knowledge without bloating the default prompt stack.
## 1) Namespaced tool (`text_editor`) vs non-namespaced tool (`code_execution_tool`)
- `text_editor` requires method in `tool_name`:
- `text_editor:read`
- `text_editor:write`
- `text_editor:patch`
- `code_execution_tool` uses a plain tool name plus behavior in `tool_args.runtime`.
### Example A: read file lines with namespaced tool
```json
{
"tool_name": "text_editor:read",
"tool_args": {
"path": "/workspace/agent-zero/README.md",
"line_from": 1,
"line_to": 60
}
}
```
### Example B: run shell command with `code_execution_tool`
```json
{
"tool_name": "code_execution_tool",
"tool_args": {
"runtime": "terminal",
"session": 0,
"reset": false,
"code": "pwd"
}
}
```
### Example C: poll ongoing terminal output
```json
{
"tool_name": "code_execution_tool",
"tool_args": {
"runtime": "output",
"session": 0
}
}
```
## 2) Memory tools use plain names and structured args
```json
{
"tool_name": "memory_load",
"tool_args": {
"query": "tool argument format",
"limit": 3,
"threshold": 0.7
}
}
```
## 3) Subordinate tool booleans are JSON booleans
```json
{
"tool_name": "call_subordinate",
"tool_args": {
"profile": "",
"message": "Review this patch for edge cases.",
"reset": true
}
}
```
Use these examples as structure references only. Adapt arguments to the current task.”Œtype”ŒDocument”uŒ__pydantic_extra__”NŒ__pydantic_fields_set__”�”(hhh�Œ__pydantic_private__”NubŒ
The utility model handles high-volume, lower-stakes operations and can be a cheaper/faster model than the chat model. Browser automation is exposed as the direct `browser` tool; the main agent decides when to call it. Changing the embedding model invalidates the existing vector index - the entire knowledge base is re-indexed automatically.
## Model Providers
Providers are defined in `conf/model_providers.yaml`. All chat and embedding providers go through LiteLLM, which normalizes the API interface. Supported chat providers (as of v0.9.8):
- Agent Zero API (a0_venice) - hosted service with no API key required for basic use
- Anthropic, OpenAI, OpenRouter, Google (Gemini), Groq, Mistral AI
- DeepSeek, xAI, Moonshot AI, Sambanova, CometAPI, Z.AI, Inception AI
- Venice.ai, AWS Bedrock, Azure OpenAI
- GitHub Copilot, HuggingFace
- Ollama, LM Studio (local models)
- Other OpenAI-compatible endpoints (custom `api_base`)
| `_example` | Minimal example for building custom profiles |
Custom profiles go in `usr/agents/<profile>/` to survive framework updates.
## Plugin System
Plugins are discovered from `plugins/` (framework plugins) and `usr/plugins/` (user plugins). Each plugin requires a `plugin.yaml` with at minimum: `name`, `description`, `version`.
### Activation
- **Global activation**: enabled/disabled for all contexts via the Plugins settings panel
- **Scoped activation**: enabled/disabled per project or per agent profile via the plugin Switch modal
- Activation state stored as `.toggle-1` (ON) and `.toggle-0` (OFF) files in the plugin's config dir
### Built-in Framework Plugins
| Plugin | Purpose |
|--------|---------|
| `_memory` | Memory and knowledge pipeline, recall, consolidation |
| `_code_execution` | Terminal and code execution tool |
Any setting can be set via environment variable using the `A0_SET_` prefix. This is the primary mechanism for automated deployment and container configuration.
}”(hh2h}”(hh,hhhh-hh,hh.hˆhNhh2hh/uhX×These can be set in the `.env` file at the project root or passed as Docker `-e` flags during container creation.
| `agent_temperature` | LLM temperature for the chat model |
Settings are stored in `usr/settings.json` and managed through the Settings page in the web UI. The settings page also provides: API key management (multiple keys per provider with round-robin), backup/restore, external services (tunnels, MCP, A2A), and memory management.”h!h"uh#Nh$�”(hhh�h&NubŒ
The agent can write and execute code in any language available in the Docker container. The execution environment is a Kali Linux container with two Python runtimes:
The agent installs packages into the execution runtime (`/opt/venv`) via `pip install`. Packages needed by the framework itself must target `/opt/venv-a0`.
Supported runtimes for code execution: Python, Node.js, Bash/shell. Other languages (Go, Rust, PHP, etc.) can be used if the compiler/runtime is installed in the container.
Code runs in the terminal with real-time output streaming. Long-running processes, background jobs, and interactive sessions are supported. The agent can pause and resume code execution and interact with running processes.
Skills are structured markdown files that provide contextual expertise for specific tasks. When a skill is relevant to the current task, it is loaded into the agent's context and followed as a set of instructions. Skills are discovered from:
Skills follow the open SKILL.md standard, making them portable across tools that support it. The agent executes skill instructions using `code_execution_tool` or `skills_tool`.
When a project is active, the agent's file operations, memory, and knowledge are scoped to that project. Projects prevent context bleed between separate work streams.
The agent has automatic access to its knowledge base via similarity search. Knowledge is indexed from `knowledge/` (framework-level) and `usr/knowledge/<subdir>/` (user-level). The agent does not need to explicitly query knowledge - relevant content is surfaced automatically with memory recall. The `knowledge_tool` can also be called explicitly for targeted lookups.
The `document_query_tool` can load and query arbitrary documents (local files or URLs) using a separate RAG pipeline. Unlike the knowledge base (which is pre-indexed), this tool indexes documents on demand with a configurable chunk size. Useful for analyzing large documents, codebases, or external content without polluting the persistent knowledge store.
The agent can schedule tasks to run at specified times or intervals using the scheduler tool. Scheduled tasks run in the background with their own agent instances. Tasks are managed via the Scheduler UI in the web interface.
- **Model capability ceiling**: tool usage quality and reasoning depth are bounded by the underlying LLM. Small models may struggle with complex multi-step tool use.
}”(hhKh}”(hŒ0/a0/knowledge/main/about/setup-and-deployment.md”hhhŒsetup-and-deployment.md”hhPhŒmd”hˆhNhhKhŒ2026-05-03 06:12:53”uhXh# Agent Zero - Setup and Deployment
Map `/a0/usr` to a host directory for persistence:
```bash
docker run -p 50001:80 -v /path/on/host:/a0/usr agent0ai/agent-zero
```
Contents of `/a0/usr/`:
- `settings.json` - all configuration including API keys and model settings
- `memory/` - FAISS vector indexes and knowledge import state
- `knowledge/` - user-added knowledge files
- `agents/` - custom agent profiles
- `plugins/` - user plugins
- `projects/` - project workspaces
- `work/` - default working directory for agent file output
## Configuration After Start
On first run, open Settings (gear icon) and configure:
1. **API Keys** - add at least one provider API key under the relevant provider section
2. **Chat Model** - select provider and model name for the primary LLM
3. **Utility Model** - select a cheaper/faster model for internal tasks
4. **Embedding Model** - select embedding provider and model (required for memory and knowledge)
Settings are saved to `usr/settings.json` immediately on change.
## Updating Agent Zero
The recommended update process is to use Self Update:
1. Open **Settings UI → Update** tab
2. Open **Self Update**
3. Wait for the update checker to see if you have the latest version or if there's an available update
You'll also be prompted through the UI when a new A0 version is released. Note that backups are automatically managed internally during the self-update process.
### Updating from Pre-v0.9.8
If upgrading from v0.9.8 or earlier, the architecture has significantly changed. You must use the new install scripts and manually migrate your data:
1. Backup your existing `usr/` directory.
2. Run the Quick Install script (`curl -fsSL https://bash.agent-zero.ai | bash` for macOS/Linux or `irm https://ps.agent-zero.ai | iex` for Windows).
3. Copy your backed-up `usr/` contents into the new installation's `a0/usr/` directory to preserve your settings, memory, and plugins.
## Remote Access
### Flare Tunnel (recommended for external access)
This generates a public HTTPS URL without requiring firewall changes or a static IP. Set a username and password before creating the tunnel to enable authentication.
### Local Network
Access from other devices on the same network using the host machine's IP:
`http://<host-ip>:<mapped-port>`
### Microsoft Dev Tunnels
Supported as an alternative to Flare for users in Microsoft environments. Configure under External Services in Settings.
## Mobile Access
Agent Zero is a Progressive Web App (PWA). On mobile, open the web UI URL in a browser, then add to home screen for an app-like experience. Works with both local network and tunnel URLs.
Agent Zero is an open-source, general-purpose agentic framework. It is not pre-programmed for specific tasks and has no fixed capability set beyond the basics. Its defining characteristic is that it grows and adapts as it is used - accumulating knowledge, solutions, and behaviors through persistent memory and user customization.
The framework has been created by Jan Tomášek and is maintained by the Agent Zero dev team and the community. Source code lives at github.com/agent0ai/agent-zero.
## Core Design Principles
**No hard-coding.** Almost nothing in the framework is fixed in source code. Agent behavior, tool definitions, message templates, and response patterns are all controlled by files in the `prompts/` directory. Changing the prompts changes the agent - fundamentally if needed.
**Transparency.** Every prompt, every message template, every tool implementation is readable and editable. There are no hidden instructions or black-box behaviors. The agent can be fully audited.
**Computer as a tool.** Agent Zero does not have a library of pre-built skill functions. Instead, it uses the operating system directly - writing code, running terminal commands, and creating tools on demand. The terminal is the primary interface to everything.
**Organic growth.** The agent accumulates knowledge through experience. Facts, solutions, discovered patterns, and useful code are stored in memory and recalled in future conversations. The agent becomes more effective at tasks it has done before.
**Prompt-driven behavior.** The `prompts/` directory is the control plane. System prompts, tool instructions, framework messages, and utility AI prompts are all there. The agent's behavior is as good as its prompts.
Agent Zero treats the human user as its top-level superior in the agent hierarchy. The user is functionally indistinguishable from a superior agent - they give tasks, receive reports, and can intervene at any time. The agent is not a chatbot that answers questions; it is an executor that solves tasks using whatever means are available to it.
The framework is a personal tool, not a service. It runs locally (or on user-controlled infrastructure) and has access to the user's files, credentials, and systems as configured. This makes it powerful and requires the user to understand what they are delegating.”h!h"uh#Nh$�”(hhh�h&NubŒ
Each agent runs a continuous monologue loop. On each cycle the agent receives its current context (system prompt + message history), produces a JSON response (thoughts, headline, tool name, tool args), and the framework executes the named tool. The tool result is appended to history and the loop continues until the agent calls `response` to deliver a final answer to its superior.
The loop handles: message history management, context window limits (via summarization), memory recall injection, intervention from superiors, and error recovery (misformat retries, tool-not-found handling).
Each WebSocket session connects to one `AgentContext`. Multiple concurrent chats run in separate contexts. The framework is initialized in `initialize.py` and the server entry point is `run_ui.py`.
System prompts are assembled from fragment files on each loop iteration. The main system prompt is `prompts/agent.system.main.md`, which includes sub-prompts via `{{ include "filename.md" }}` directives. Agent profiles (in `agents/<profile>/prompts/`) can override individual fragments. This means a subordinate with the `developer` profile gets a different role and communication section while sharing the same tool list and solving workflow as the base agent.
Prompt fragments are in `prompts/`. Plugin system prompts are in `plugins/<plugin>/prompts/`. The assembled system prompt is dynamic - it changes based on profile, active project, loaded tools, recalled memories, and injected extras.
The hierarchy is a tree with the human user at the root. Each node is an agent instance running in its own context. A superior calls `call_subordinate` with a message and optional profile name; this creates a new `AgentContext` and runs the subordinate agent's loop until it returns a response.
Agent 0 is always the top-level agent whose superior is the user. When Agent 0 delegates a task to a subordinate, that subordinate can itself delegate further. There is no enforced depth limit. Agents share the same tool system but each has its own isolated context and history.
Subordinates can be given specific prompt profiles (`developer`, `researcher`, or any custom profile in `agents/`). Profiles change the role, communication style, and available instructions without changing the underlying framework.
## Memory and Knowledge Pipeline
### Knowledge (vector DB, read-only)
Knowledge files (in `knowledge/` and `usr/knowledge/`) are loaded when a memory DB is initialized (normally at the start of the first monologue in a chat), embedded, and stored in a FAISS vector index per memory subdir. Files are tracked by checksum; only changed files are re-indexed. Supported formats: `.md`, `.txt`, `.pdf`, `.csv`, `.html`, `.json`.
The memory areas are:
- `main` - general knowledge and facts (files in knowledge root or `main/` subdir)
- `fragments` - partial or supplementary knowledge
- `solutions` - known solutions to problems
### Recall (automatic, per conversation turn)
The `RecallMemories` extension runs every N loop iterations (configurable). It queries the vector store using either the raw conversation or a utility-LLM-generated search query. Results from `main` and `fragments` areas plus `solutions` are injected into `loop_data.extras_persistent`, which gets rendered into the system prompt via `agent.context.extras.md` template.”h!h"uh#Nh$�”(hhh�h&NubŒ
nhXQkidmdT”h
)�”}”(h
}”(hhsh}”(hhmhhhhnhhmhhohˆhNhhshhpuhXóThe agent sees recalled memories as a section in its system prompt labeled "Memories on the topic". The agent is instructed not to over-rely on them.
### Agent memory (read-write, via memorize tool)
The agent can explicitly save facts, solutions, and code snippets using the `memorize` tool. These are stored in the same FAISS index under the `main` or `solutions` area and recalled in future conversations. Memory can also be consolidated (summarized) and managed through the Memory Dashboard in the web UI.
## Tool System
Tools are Python classes in `python/tools/` that inherit from `Tool`. Each tool implements an `execute()` async method. Tools are discovered at startup and registered in the agent's tool list (rendered into the system prompt as `{{tools}}`). The agent names a tool in its JSON response; the framework finds and calls it.
The plugin system (`python/helpers/plugins.py`) discovers plugins from `plugins/` and `usr/plugins/`. Each plugin has a `plugin.yaml` manifest declaring name, version, and settings. Plugins can contribute: API handlers, tools, WebUI components, extensions, and hooks. User plugins in `usr/plugins/` are never overwritten by framework updates. The agent has skills to create, manage, debug, review and contribute plugins to the Plugin Index repository (https://github.com/agent0ai/a0-plugins)
## Frontend Architecture
The web UI is built with Alpine.js and ES module components. The main shell is `webui/index.html`. Components are in `webui/components/`. Frontend state is managed via Alpine stores defined with `createStore` from `/js/AlpineStore.js`.
Real-time communication uses Socket.io WebSockets via a unified `/ws` namespace. WebSocket handlers (WsHandler subclasses) are in `api/ws_*.py`. The connection manager is in `helpers/ws_manager.py`. API handlers are in `api/`, each deriving from `ApiHandler` in `helpers/api.py`.”h!h"uh#Nh$�”(hhh�h&NubŒ
pDhjySQv7D”h
)�”}”(h
}”(hhzh}”(hŒ fragments”hŒ2026-05-03 06:15:22”hhzuhX„{'thoughts': ['The error is an authentication error, which means we need to provide the necessary credentials for the chat model provider.', 'We should check with the OpenRouter provider to see if they have an alternative solution, such as using their own API key or credentials.', "The user's message is still unclear, but we can try to provide more information about the error and ask for clarification."], 'headline': 'Error handling and alternative solutions', 'tool_name': 'response', 'tool_args': {'text': "Sorry to hear that you're experiencing an error. Can you please provide more information about the error? *waiting for 1 minute*"}}”h!h"uh#Nh$�”(hhh�h&NubŒ
y1hRuaG0YY”ahhƒŒ_consolidation_similarity”Œnumpy.core.multiarray”Œscalar”“”Œnumpy”Œdtype”“”Œf8”‰ˆ‡”R”(KŒ<”NNNJÿÿÿÿJÿÿÿÿKt”bCÐÉæ?”†”R”uhX˜# Problem The chat model provider is `a0_venice`, and the API key for the Agent Zero API is not available. We should check with the OpenRouter provider to see if they have an alternative solution.
# Solution
1. Check with the OpenRouter provider to see if they have an alternative solution for authentication.
2. If no alternative solution is available, wait for a duration or timestamp before proceeding.”h!h"uh#Nh$�”(hhh�h&NubŒ
KIvt3bU98z”h
)�”}”(h
}”(Œid”h Œmetadata”}”(Œarea”Œ solutions”Œ timestamp”Œ2026-05-03 06:25:40”h¤h Œ_consolidation_similarity”h’h˜Cðv~æ?”†”R”uŒpage_content”X�# Problem
User sends a message that's misformatted and requires JSON message formatting instructions.
# Solution
1. The user sends a malformed JSON message, indicating that the formatting instructions should be provided in a specific format.
2. The user is instructed to follow system prompt instructions on JSON message formatting precisely, suggesting the need for clear and concise instructions.”Œtype”h uh#Nh$�”(h¤h¯h¥�h&NubŒ
