update docs for v0.9.8
Update docs for Docker-first quickstart and MCP client config + skills
Alessandro committed
Dec 29, 2025 at 15:12 UTC
55bf0e4ed9a4241121a5dbc074d0c9cfa54da7d3
11 files changed
+335
-153
docs/README.md
+21
-1
@@ -2,6 +2,7 @@
2
# Agent Zero Documentation
3
To begin with Agent Zero, follow the links below for detailed guides on various topics:
4
5
+- **[Quickstart](quickstart.md):** Launch the UI and run a first task.
6
- **[Installation](installation.md):** Set up (or [update](installation.md#how-to-update-agent-zero)) Agent Zero on your system.
7
- **[Usage Guide](usage.md):** Explore GUI features and usage scenarios.
8
- **[Development](development.md):** Set up a development environment for Agent Zero.
@@ -9,8 +10,15 @@ To begin with Agent Zero, follow the links below for detailed guides on various
10
- **[WebSocket Infrastructure](websocket-infrastructure.md):** Build real-time features with bidirectional handlers and client APIs.
11
- **[Connectivity](connectivity.md):** Learn how to connect to Agent Zero from other applications.
12
- **[Architecture Overview](architecture.md):** Understand the internal workings of the framework.
13
+- **[Extensibility](extensibility.md):** Learn how to create custom extensions, tools, instruments, and prompts.
14
+- **[Connectivity](connectivity.md):** Learn how to connect to Agent Zero from other applications.
15
+- **[MCP Setup](mcp_setup.md):** Configure Agent Zero as an MCP client for external tools.
16
+- **[Notifications](notifications.md):** Use the notification system in the UI and backend.
17
+- **[Tunnel](tunnel.md):** Expose your instance securely with Cloudflare tunnels.
18
+- **[Development](development.md):** Set up a development environment for Agent Zero.
19
- **[Contributing](contribution.md):** Learn how to contribute to the Agent Zero project.
20
- **[Troubleshooting and FAQ](troubleshooting.md):** Find answers to common issues and questions.
21
+- **[Design Specs](designs/):** Technical specifications for larger features.
22
23
### Your experience with Agent Zero starts now!
24
@@ -32,6 +40,7 @@ To begin with Agent Zero, follow the links below for detailed guides on various
40
- [Using Agent Zero on Mobile](installation.md#using-agent-zero-on-your-mobile-device)
41
- [How to Update Agent Zero](installation.md#how-to-update-agent-zero)
42
- [Full Binaries Installation](installation.md#in-depth-guide-for-full-binaries-installation)
43
+- [Quickstart](quickstart.md)
44
- [Usage Guide](usage.md)
45
- [Basic Operations](usage.md#basic-operations)
46
- [Restart Framework](usage.md#restart-framework)
@@ -40,7 +49,10 @@ To begin with Agent Zero, follow the links below for detailed guides on various
49
- [Tool Usage](usage.md#tool-usage)
50
- [Example of Tools Usage](usage.md#example-of-tools-usage-web-search-and-code-execution)
51
- [Multi-Agent Cooperation](usage.md#multi-agent-cooperation)
52
+ - [Projects](usage.md#projects)
53
+ - [Tasks & Scheduling](usage.md#tasks--scheduling)
54
- [Prompt Engineering](usage.md#prompt-engineering)
55
+ - [Secrets & Variables](usage.md#secrets--variables)
56
- [Voice Interface](usage.md#voice-interface)
57
- [Mathematical Expressions](usage.md#mathematical-expressions)
58
- [File Browser](usage.md#file-browser)
@@ -54,7 +66,7 @@ To begin with Agent Zero, follow the links below for detailed guides on various
66
- [Tools](architecture.md#2-tools)
67
- [SearXNG Integration](architecture.md#searxng-integration)
68
- [Memory System](architecture.md#3-memory-system)
57
- - [Messages History and Summarization](archicture.md#messages-history-and-summarization)
69
+ - [Messages History and Summarization](architecture.md#messages-history-and-summarization)
70
- [Prompts](architecture.md#4-prompts)
71
- [Knowledge](architecture.md#5-knowledge)
72
- [Skills](architecture.md#6-skills)
@@ -68,3 +80,11 @@ To begin with Agent Zero, follow the links below for detailed guides on various
80
- [Troubleshooting and FAQ](troubleshooting.md)
81
- [Frequently Asked Questions](troubleshooting.md#frequently-asked-questions)
82
- [Troubleshooting](troubleshooting.md#troubleshooting)
83
+- [Connectivity](connectivity.md)
84
+- [MCP Setup](mcp_setup.md)
85
+- [Notifications](notifications.md)
86
+- [Tunnel](tunnel.md)
87
+- [Development](development.md)
88
+- [Extensibility](extensibility.md)
89
+- [Contributing](contribution.md)
90
+- [Design Specs](designs/)
docs/architecture.md
+41
-31
@@ -32,8 +32,7 @@ This architecture ensures:
32
> [!NOTE]
33
> The legacy approach of running Agent Zero directly on the host system (using Python, Conda, etc.)
34
> is still possible but requires Remote Function Calling (RFC) configuration through the Settings
35
-> page. See [Full Binaries Installation](installation.md#in-depth-guide-for-full-binaries-installation)
36
-> for detailed instructions.
35
+> page. See the [development guide](development.md) for detailed instructions.
36
37
## Implementation Details
38
@@ -43,39 +42,43 @@ This architecture ensures:
42
| `/docker` | Docker-related files for runtime container |
43
| `/docs` | Documentation files and guides |
44
| `/usr/skills` | Skills using the open SKILL.md standard (contextual expertise) |
45
+| `/agents` | Agent profiles (prompts, tools, extensions per profile) |
46
| `/knowledge` | Knowledge base storage |
47
| `/logs` | HTML CLI-style chat logs |
48
| `/memory` | Persistent agent memory storage |
49
-| `/prompts` | System and tool prompts |
50
-| `/python` | Core Python codebase: |
51
-| `/api` | API endpoints and interfaces |
52
-| `/extensions` | Modular extensions |
53
-| `/helpers` | Utility functions |
54
-| `/tools` | Tool implementations |
49
+| `/prompts` | Default system and tool prompt templates |
50
+| `/python` | Core Python codebase |
51
+| `/python/api` | API endpoints and interfaces |
52
+| `/python/extensions` | Modular extensions |
53
+| `/python/helpers` | Utility functions |
54
+| `/python/tools` | Tool implementations |
55
| `/tmp` | Temporary runtime data |
56
-| `/webui` | Web interface components: |
57
-| `/css` | Stylesheets |
58
-| `/js` | JavaScript modules |
59
-| `/public` | Static assets |
60
-| `/work_dir` | Working directory |
56
+| `/tmp/chats` | Saved chat history (JSON) |
57
+| `/tmp/secrets.env` | Secrets store (not always included in backups) |
58
+| `/usr/projects` | Project workspaces and `.a0proj` metadata |
59
+| `/webui` | Web interface components |
60
+| `/webui/css` | Stylesheets |
61
+| `/webui/js` | JavaScript modules |
62
+| `/webui/public` | Static assets |
63
+| `/work_dir` | Working directory (inside Docker: `/a0/work_dir`) |
64
65
### Key Files
66
| File | Description |
67
| --- | --- |
65
-| `.env` | Environment configuration |
68
+| `tmp/settings.json` | Main runtime settings (written by the Settings UI) |
69
+| `tmp/secrets.env` | Secrets store (managed via Settings -> Secrets) |
70
+| `conf/model_providers.yaml` | Model provider defaults and settings |
71
| `agent.py` | Core agent implementation |
67
-| `example.env` | Configuration template |
72
| `initialize.py` | Framework initialization |
73
| `models.py` | Model providers and configs |
74
| `preload.py` | Pre-initialization routines |
75
| `prepare.py` | Environment preparation |
76
| `requirements.txt` | Python dependencies |
73
-| `run_cli.py` | CLI launcher |
77
| `run_ui.py` | Web UI launcher |
78
+| `run_tunnel.py` | Tunnel launcher |
79
80
> [!NOTE]
77
-> When using the Docker runtime container, these directories are mounted
78
-> within the `/a0` volume for data persistence until the container is restarted or deleted.
81
+> In the Docker runtime, the framework lives under `/a0` inside the container. Data persists as long as the container exists. For upgrades, prefer **Backup & Restore** instead of mapping the full `/a0` directory.
82
83
## Core Components
84
Agent Zero's architecture revolves around the following key components:
@@ -140,10 +143,10 @@ In cases where SearXNG might not return satisfactory results, Agent Zero can be
143
> retrieval system.
144
145
#### Custom Tools
143
-Users can create custom tools to extend Agent Zero's capabilities. Custom tools can be integrated into the framework by defining a tool specification, which includes the tool's prompt to be placed in `/prompts/$FOLDERNAME/agent.system.tool.$TOOLNAME.md`, as detailed below.
146
+Users can create custom tools to extend Agent Zero's capabilities. Custom tools can be integrated into the framework by defining a tool specification, which includes the tool's prompt. Place these prompt overrides in your agent profile:
147
145
-1. Create `agent.system.tool.$TOOL_NAME.md` in `prompts/$SUBDIR`
146
-2. Add reference in `agent.system.tools.md`
148
+1. Create `agent.system.tool.$TOOL_NAME.md` in `agents/<agent_profile>/prompts/` (or in `prompts/` for global defaults)
149
+2. Add the reference in `agent.system.tools.md` within the same prompt scope
150
3. If needed, implement tool class in `python/tools` using `Tool` base class
151
4. Follow existing patterns for consistency
152
@@ -162,6 +165,14 @@ The memory is categorized into four distinct areas:
165
- **Solutions**: Stores successful solutions from past interactions for future reference
166
- **Metadata**: Each memory entry includes metadata (IDs, timestamps), enabling efficient filtering and searching based on specific criteria
167
168
+#### Embeddings and Utility Model
169
+- Embeddings are generated locally using a small default model (tiny disk footprint).
170
+- The **utility model** handles summarization and memory extraction; it must be capable enough to distinguish durable knowledge from noise.
171
+
172
+#### Memory Management Best Practices
173
+- After important sessions, ask the agent to **“memorize learning opportunities from the current session.”**
174
+- For long-running workflows, **distill durable knowledge into prompts** rather than relying exclusively on memory.
175
+
176
#### Messages History and Summarization
177
178
Agent Zero employs a sophisticated message history and summarization system to maintain context effectively while optimizing memory usage. This system dynamically manages the information flow, ensuring relevant details are readily available while efficiently handling the constraints of context windows.
@@ -208,16 +219,16 @@ The `prompts` directory contains various Markdown files that control agent behav
219
| agent.system.tool.*.md | Individual tool prompt files |
220
221
#### Prompt Organization
211
-- **Default Prompts**: Located in `prompts/default/`, serve as the base configuration
212
-- **Custom Prompts**: Can be placed in custom subdirectories (e.g., `prompts/my-custom/`)
222
+- **Default Prompts**: Located in `prompts/`, serve as the base configuration
223
+- **Custom Prompts (v0.9.7+)**: Place overrides in `agents/<agent_profile>/prompts/`
224
- **Behavior Files**: Stored in memory as `behaviour.md`, containing dynamic rules
225
- **Tool Prompts**: Organized in tool-specific files for modularity
226
216
-#### Custom Prompts
217
-1. Create directory in `prompts/` (e.g., `my-custom-prompts`)
218
-2. Copy and modify needed files from `prompts/default/`
219
-3. Agent Zero will merge your custom files with the default ones
220
-4. Select your custom prompts in the Settings page (Agent Config section)
227
+#### Custom Prompts (Post v0.9.7)
228
+1. Create or select an agent profile under `agents/<agent_profile>/`
229
+2. Add only the prompt files you want to override in `agents/<agent_profile>/prompts/`
230
+3. Agent Zero merges these overrides with the default prompts automatically
231
+4. Select the **Agent Profile** in Settings to activate the overrides
232
233
#### Dynamic Behavior System
234
- **Behavior Adjustment**:
@@ -245,8 +256,7 @@ The `prompts` directory contains various Markdown files that control agent behav
256
- Maintains separation between core functionality and behavioral rules
257
258
> [!NOTE]
248
-> You can customize any of these files. Agent Zero will use the files in your custom `prompts_subdir`
249
-> if they exist, otherwise, it will fall back to the files in `prompts/default`.
259
+> You can customize any of these files. Agent Zero will use files in `agents/<agent_profile>/prompts/` when present, and fall back to `prompts/` for everything else.
260
261
> [!TIP]
262
> The behavior system allows for dynamic adjustments without modifying the base prompt files.
@@ -338,4 +348,4 @@ Extensions can be found in `python/extensions` directory:
348
349
> [!NOTE]
350
> Consider contributing valuable custom components to the main repository.
341
-> See [Contributing](contribution.md) for more information.
\ No newline at end of file
351
+> See [Contributing](contribution.md) for more information.
docs/connectivity.md
+11
@@ -604,6 +604,9 @@ It provides two endpoint types:
604
- **SSE (`/mcp/sse`):** For clients that support Server-Sent Events.
605
- **Streamable HTTP (`/mcp/http/`):** For clients that use streamable HTTP requests.
606
607
+> [!NOTE]
608
+> This section describes **Agent Zero as an MCP server**. To configure Agent Zero as an MCP **client** (consuming external tools), see [MCP Setup](mcp_setup.md).
609
+
610
### Example MCP Server Configuration
611
612
Below is an example of a `mcp.json` configuration file that a client could use to connect to the Agent Zero MCP server.
@@ -676,3 +679,11 @@ When a project is specified:
679
- All A2A conversations will run in the context of that project
680
- The agent will have access to project-specific resources, instructions, and knowledge
681
- This enables project-isolated agent-to-agent communication
682
+
683
+### Practical Use Cases
684
+- Connect two Agent Zero instances for long-running, isolated workflows
685
+- Delegate specialized tasks to a dedicated agent instance
686
+- Maintain strict context separation between agents
687
+
688
+> [!TIP]
689
+> If you need tool access rather than chat delegation, use MCP instead of A2A. See [MCP Setup](mcp_setup.md).
docs/development.md
+3
@@ -134,6 +134,9 @@ My Dockerized instance:
134
My VS Code instance:
135
136
137
+## RFC Notes (Host IDE + Docker Execution)
138
+Agent Zero runs code inside the container by default. If you are running the framework locally in your IDE but want tools (like code execution) to run in Docker, configure RFC in **Settings -> Development** and point it to a running Agent Zero container. This routes execution through SSH/RFC to the container while keeping the UI and agent loop on your host.
139
+
140
141
# 🎉 Congratulations! 🚀
142
docs/extensibility.md
+19
@@ -99,6 +99,18 @@ When a tool is called, it goes through the following lifecycle:
99
3. `execute` method (main functionality)
100
4. `after_execution` method
101
102
+### Instruments
103
+Instruments are reusable scripts and procedures stored on disk and indexed in memory. They are **not** always present in the system prompt, making them lighter-weight than tools for specialized workflows.
104
+
105
+- **When to use tools:** core capabilities you want always available in the prompt
106
+- **When to use instruments:** repeatable scripts or procedures that can be recalled on demand
107
+
108
+#### Creating Instruments
109
+1. Create a folder in `instruments/custom/` (no spaces in name)
110
+2. Add a `.md` description file explaining inputs/outputs
111
+3. Add a script (`.sh`, `.py`, etc.) with the implementation
112
+4. Restart or reload so the agent indexes the instrument
113
+
114
### API Endpoints
115
API endpoints expose Agent Zero functionality to external systems or the user interface. They are modular and can be extended or replaced.
116
@@ -120,6 +132,9 @@ Prompts are located in:
132
- Default prompts: `/prompts/`
133
- Agent-specific prompts: `/agents/{agent_profile}/prompts/`
134
135
+> [!NOTE]
136
+> Since v0.9.7, custom prompts should be placed under `agents/<agent_profile>/prompts/` instead of a shared `prompts` subdirectory.
137
+
138
#### Prompt Features
139
Agent Zero's prompt system supports several powerful features:
140
@@ -244,6 +259,8 @@ In this example:
259
260
Projects provide isolated workspaces for individual chats, keeping prompts, memory, knowledge, files, and secrets scoped to a specific use case.
261
262
+Projects are ideal for multi-client or multi-domain work because each project can have **its own agent/subagents and context windows**, preventing context mixing. They are especially powerful when combined with the Tasks scheduler.
263
+
264
### Project Location and Structure
265
266
- Projects are located under `/a0/usr/projects/`
@@ -294,6 +311,8 @@ Projects are the recommended way to create specialized workflows in Agent Zero w
311
- Keep passwords and other secrets scoped to a single workspace
312
- Run multiple independent flows side by side under the same Agent Zero installation
313
314
+See [Usage → Tasks & Scheduling](usage.md#tasks--scheduling) for how to pair projects with scheduled tasks.
315
+
316
## Best Practices
317
- Keep extensions focused on a single responsibility
318
- Use the appropriate extension point for your functionality
docs/installation.md
+94
-68
@@ -58,7 +58,7 @@ The following user guide provides instructions for installing and running Agent
58
59
2. **Run Agent Zero:**
60
61
-- Note: Agent Zero also offers a Hacking Edition based on Kali linux with modified prompts for cybersecurity tasks. The setup is the same as the regular version, just use the agent0ai/agent-zero:hacking image instead of agent0ai/agent-zero.
61
+- Note: The Hacker profile is included in the main image. After launch, choose the **hacker** agent profile in Settings if you want the security-focused prompts and tooling.
62
63
2.1. Pull the Agent Zero Docker image:
64
- Search for `agent0ai/agent-zero` in Docker Desktop
@@ -74,22 +74,21 @@ The following user guide provides instructions for installing and running Agent
74
> docker pull agent0ai/agent-zero
75
> ```
76
77
-2.2. OPTIONAL - Create a data directory for persistence:
77
+2.2. OPTIONAL - Map specific folders for persistence:
78
79
> [!CAUTION]
80
-> Preferred way of persisting Agent Zero data is to use the backup and restore feature.
81
-> By mapping the whole `/a0` directory to a local directory, you will run into problems when upgrading Agent Zero to a newer version.
80
+> The recommended persistence and upgrade workflow is to use **Settings → Backup & Restore**.
81
+> Do **not** map the entire `/a0` directory: it contains the application code and can break upgrades.
82
83
- Choose or create a directory on your machine where you want to store Agent Zero's data
84
- This can be any location you prefer (e.g., `C:/agent-zero-data` or `/home/user/agent-zero-data`)
85
- You can map individual subfolders of `/a0` to a local directory or the full `/a0` directory (not recommended).
86
- This directory will contain all your Agent Zero files, like the legacy root folder structure:
87
- - `/agents` - Specialized agents with their prompts and tools
88
- - `/memory` - Agent's memory and learned information
89
- - `/knowledge` - Knowledge base
90
- - `/usr/skills` - Skills using the open SKILL.md standard
91
- - `/prompts` - Prompt files
92
- - `.env` - Your API keys
87
+ - `/a0/agents` - Specialized agents with their prompts and tools
88
+ - `/a0/memory` or `/a0/knowledge` if you explicitly want to persist those between restarts
89
+ - `/a0/knowledge` - Knowledge base
90
+ - `/a0/usr/projects` - Project workspaces
91
+ - `/a0/usr/skills` - Skills using the open SKILL.md standard
92
- `/tmp/settings.json` - Your Agent Zero settings
93
94
> [!TIP]
@@ -146,7 +145,7 @@ docker run -p 50080:80 \
145
- In Docker Desktop, go back to the "Images" tab
146
- Click the `Run` button next to the `agent0ai/agent-zero` image
147
- Open the "Optional settings" menu
149
-- Set the web port (80) to desired host port number in the second "Host port" field or set to `0` for automatic port assignment
148
+- **Ensure at least one host port is mapped to container port `80`** (set host port to `0` for automatic assignment)
149
150
Optionally you can map local folders for file persistence:
151
> [!CAUTION]
@@ -169,10 +168,10 @@ Optionally you can map local folders for file persistence:
168
> [!TIP]
169
> Alternatively, run the following command in your terminal:
170
> ```bash
172
-> docker run -p $PORT:80 -v /path/to/your/data:/a0 agent0ai/agent-zero
171
+> docker run -p 0:80 -v /path/to/your/work_dir:/a0/work_dir agent0ai/agent-zero
172
> ```
174
-> - Replace `$PORT` with the port you want to use (e.g., `50080`)
175
-> - Replace `/path/to/your/data` with your chosen directory path
173
+> - Replace `0` with a fixed port if you prefer (e.g., `50080:80`)
174
+> - Map only the folders you need (e.g., `/a0/work_dir`, `/a0/usr/projects`), not the entire `/a0` directory
175
176
2.4. Access the Web UI:
177
- The framework will take a few seconds to initialize and the Docker logs will look like the image below.
@@ -200,10 +199,13 @@ Optionally you can map local folders for file persistence:
199
Agent Zero provides a comprehensive settings interface to customize various aspects of its functionality. Access the settings by clicking the "Settings"button with a gear icon in the sidebar.
200
201
### Agent Configuration
203
-- **Prompts Subdirectory:** Choose the subdirectory within `/prompts` for agent behavior customization. The 'default' directory contains the standard prompts.
202
+- **Agent Profile:** Select the agent profile (e.g., `agent0`, `hacker`, `researcher`). Profiles can override prompts, tools, and extensions.
203
- **Memory Subdirectory:** Select the subdirectory for agent memory storage, allowing separation between different instances.
204
- **Knowledge Subdirectory:** Specify the location of custom knowledge files to enhance the agent's understanding.
205
206
+> [!NOTE]
207
+> Since v0.9.7, custom prompts belong in `/a0/agents/<agent_name>/prompts/` rather than a shared `/prompts` folder. See the [Extensibility guide](extensibility.md#prompts) for details.
208
+
209
210
211
### Chat Model Settings
@@ -215,14 +217,26 @@ Agent Zero provides a comprehensive settings interface to customize various aspe
217
218
219
220
+> [!IMPORTANT]
221
+> **Model naming is provider-specific.** Use `gpt-4.1` for OpenAI, but use `openai/gpt-4.1` for OpenRouter. If you see “Invalid model ID,” verify the provider and naming format.
222
+
223
+> [!TIP]
224
+> **Context window tuning:** Set the total context window size first (for example, 100k), then adjust the chat history portion as a fraction of that total. A large fraction on a very large context window can still be enormous.
225
+
226
### Utility Model Configuration
219
-- **Provider & Model:** Select a smaller, faster model for utility tasks like memory organization and summarization
227
+- **Provider & Model:** Select a model for utility tasks like memory organization and summarization
228
- **Temperature:** Adjust the determinism of utility responses
229
230
+> [!NOTE]
231
+> Utility models need to be strong enough to extract and consolidate memory reliably. Very small models (e.g., 4B) often fail at this; 70B-class models or high-quality cloud “flash/mini” models work best.
232
+
233
### Embedding Model Settings
234
- **Provider:** Choose the embedding model provider (e.g., OpenAI)
235
- **Model Name:** Select the specific embedding model (e.g., text-embedding-3-small)
236
237
+> [!NOTE]
238
+> Agent Zero uses a local embedding model by default (tiny footprint), but you can switch to OpenAI embeddings like `text-embedding-3-small` or `text-embedding-3-large` if preferred.
239
+
240
### Speech to Text Options
241
- **Model Size:** Choose the speech recognition model size
242
- **Language Code:** Set the primary language for voice recognition
@@ -232,6 +246,12 @@ Agent Zero provides a comprehensive settings interface to customize various aspe
246
- Configure API keys for various service providers directly within the Web UI
247
- Click `Save` to confirm your settings
248
249
+> [!NOTE]
250
+> **OpenAI API vs Plus subscription:** A ChatGPT Plus subscription does not include API credits. You must provide a separate API key for OpenAI usage in Agent Zero.
251
+
252
+> [!TIP]
253
+> For OpenAI-compatible providers (e.g., custom gateways or Z.AI/GLM), add the API key under **External Services → Other OpenAI-compatible API keys**, then select **OpenAI Compatible** as the provider in model settings.
254
+
255
> [!CAUTION]
256
> **GitHub Copilot Provider:** When using the GitHub Copilot provider, after selecting the model and entering your first prompt, the OAuth login procedure will begin. You'll find the authentication code and link in the output logs. Complete the authentication process by following the provided link and entering the code, then you may continue using Agent Zero.
257
@@ -250,11 +270,14 @@ Agent Zero provides a comprehensive settings interface to customize various aspe
270
### Development Settings
271
- **RFC Parameters (local instances only):** configure URLs and ports for remote function calls between instances
272
- **RFC Password:** Configure password for remote function calls
253
-Learn more about Remote Function Calls and their purpose [here](#7-configure-agent-zero-rfc).
273
+Learn more about Remote Function Calls in the [Development guide](development.md#step-6-configure-ssh-and-rfc-connection).
274
275
> [!IMPORTANT]
276
> Always keep your API keys and passwords secure.
277
278
+> [!NOTE]
279
+> On Windows host installs (non-Docker), you must use RFC to run shell code on the host system. The Docker runtime handles this automatically.
280
+
281
# Choosing Your LLMs
282
The Settings page is the control center for selecting the Large Language Models (LLMs) that power Agent Zero. You can choose different LLMs for different roles:
283
@@ -270,6 +293,36 @@ The Settings page is the control center for selecting the Large Language Models
293
3. Click "Save" to apply the changes.
294
295
## Important Considerations
296
+### Model Naming by Provider
297
+Use the naming format required by your selected provider:
298
+
299
+| Provider | Model Name Format | Example |
300
+| --- | --- | --- |
301
+| OpenAI | Model name only | `gpt-4.1` |
302
+| OpenRouter | Provider prefix required | `openai/gpt-4.1` |
303
+| Venice AI | Model name with optional parameters | `qwen3-235b:disable_thinking=true` |
304
+| Ollama | Model name only | `llama3.2` |
305
+
306
+> [!IMPORTANT]
307
+> Remove `openai/` when using the native OpenAI provider. That prefix is only for OpenRouter.
308
+
309
+> [!TIP]
310
+> Venice model parameters can be appended directly to the model name, for example:
311
+> `qwen3-235b:disable_thinking=true&include_venice_system_prompt=false`
312
+
313
+### Context Window & Memory Split
314
+- Set the **total context window** (e.g., 100k) first.
315
+- Then tune the **chat history portion** as a fraction of that total.
316
+- Extremely large totals can make even small fractions very large; adjust thoughtfully.
317
+
318
+### Utility Model Guidance
319
+- Utility models handle summarization and memory extraction.
320
+- Very small models (≈4B) usually fail at reliable memory extraction.
321
+- Aim for ~70B class models or strong cloud “flash/mini” models for better results.
322
+
323
+### Reasoning/Thinking Models
324
+- Reasoning can increase cost and latency. Some models perform better **without** reasoning.
325
+- If a model supports it, disable reasoning via provider-specific parameters (e.g., Venice `disable_thinking=true`).
326
327
## Installing and Using Ollama (Local Models)
328
If you're interested in Ollama, which is a powerful tool that allows you to run various large language models locally, here's how to install and use it:
@@ -293,7 +346,7 @@ curl -fsSL https://ollama.com/install.sh | sh
346
```
347
348
**Finding Model Names:**
296
-Visit the [Ollama model library](https://ollama.com/library) for a list of available models and their corresponding names. The format is usually `provider/model-name` (or just `model-name` in some cases).
349
+Visit the [Ollama model library](https://ollama.com/library) for a list of available models and their corresponding names. Ollama models are referenced by **model name only** (for example, `llama3.2`).
350
351
#### Second step: pulling the model
352
**On Windows, macOS, and Linux:**
@@ -318,6 +371,9 @@ ollama pull <model-name>
371
372
373
374
+> [!NOTE]
375
+> If Agent Zero runs in Docker and Ollama runs on the host, ensure port **11434** is reachable from the container. If both services are in the same Docker network, you can use `http://<container_name>:11434` instead of `host.docker.internal`.
376
+
377
#### Managing your downloaded models
378
Once you've downloaded some models, you might want to check which ones you have available or remove any you no longer need.
379
@@ -366,59 +422,29 @@ For developers or users who need to run Agent Zero directly on their system,see
422
# How to update Agent Zero
423
424
> [!NOTE]
369
-> Since v0.9, Agent Zero has a Backup and Restore feature, so you don't need to backup the files manually.
370
-> In Settings, Backup and Restore tab will guide you through the process.
371
-
372
-1. **If you come from the previous version of Agent Zero:**
373
-- Your data is safely stored across various directories and files inside the Agent Zero folder.
374
-- To update to the new Docker runtime version, you might want to backup the following files and directories:
375
- - `/memory` - Agent's memory
376
- - `/knowledge` - Custom knowledge base (if you imported any custom knowledge files)
377
- - `/usr/skills` - Custom skills using SKILL.md format (if you created any)
378
- - `/tmp/settings.json` - Your Agent Zero settings
379
- - `/tmp/chats/` - Your chat history
380
-- Once you have saved these files and directories, you can proceed with the Docker runtime [installation instructions above](#windows-macos-and-linux-setup-guide) setup guide.
381
-- Reach for the folder where you saved your data and copy it to the new Agent Zero folder set during the installation process.
382
-- Agent Zero will automatically detect your saved data and use it across memory, knowledge, skills, prompts and settings.
383
-
384
-> [!IMPORTANT]
385
-> If you have issues loading your settings, you can try to delete the `/tmp/settings.json` file and let Agent Zero generate a new one.
386
-> The same goes for chats in `/tmp/chats/`, they might be incompatible with the new version
387
-
388
-2. **Update Process (Docker Desktop)**
389
-- Go to Docker Desktop and stop the container from the "Containers" tab
390
-- Right-click and select "Remove" to remove the container
391
-- Go to "Images" tab and remove the `agent0ai/agent-zero` image or click the three dots to pull the difference and update the Docker image.
392
-
393
-
425
+> Since v0.9, Agent Zero includes a Backup & Restore workflow in the Settings UI. This is the **safest** way to upgrade Docker instances.
426
395
-- Search and pull the new image if you chose to remove it
396
-- Run the new container with the same volume settings as the old one
397
-
398
-> [!IMPORTANT]
399
-> Make sure to use the same volume mount path when running the new
400
-> container to preserve your data. The exact path depends on where you stored
401
-> your Agent Zero data directory (the chosen directory on your machine).
427
+## Recommended Update Process (Docker)
428
+1. **Keep the old container running** and note its port.
429
+2. **Pull the new image** (`agent0ai/agent-zero:latest`).
430
+3. **Start a new container** on a different host port.
431
+4. In the **old** instance, open **Settings → Backup & Restore** and create a backup.
432
+5. In the **new** instance, restore that backup from the same panel.
433
+6. **Manually copy secrets** from `/a0/tmp/secrets.env` if you rely on them (secrets are not always included in backups).
434
435
> [!TIP]
404
-> Alternatively, run the following commands in your terminal:
405
->
406
-> ```bash
407
-> # Stop the current container
408
-> docker stop agent-zero
409
->
410
-> # Remove the container (data is safe in the folder)
411
-> docker rm agent-zero
412
->
413
-> # Remove the old image
414
-> docker rmi agent0ai/agent-zero
415
->
416
-> # Pull the latest image
417
-> docker pull agent0ai/agent-zero
418
->
419
-> # Run new container with the same volume mount
420
-> docker run -p $PORT:80 -v /path/to/your/data:/a0 agent0ai/agent-zero
421
-> ```
436
+> If the new instance fails to load settings, remove `/a0/tmp/settings.json` and restart to regenerate defaults.
437
+
438
+## Manual Migration (Legacy or Non-Docker)
439
+If you are migrating from older, non-Docker setups, copy these directories into your new instance:
440
+- `/a0/memory` (agent memories)
441
+- `/a0/knowledge` (custom knowledge)
442
+- `/a0/instruments` (custom instruments)
443
+- `/a0/tmp/settings.json` (settings)
444
+- `/a0/tmp/chats/` (chat history)
445
+- `/a0/tmp/secrets.env` (secrets)
446
+
447
+Then proceed with the Docker installation steps above.
448
449
450
### Conclusion
docs/mcp_setup.md
+43
-11
@@ -1,7 +1,10 @@
1
-# Agent Zero: MCP Server Integration Guide
1
+# Agent Zero: MCP Client Integration Guide
2
3
This guide explains how to configure and utilize external tool providers through the Model Context Protocol (MCP) with Agent Zero. This allows Agent Zero to leverage tools hosted by separate local or remote MCP-compliant servers.
4
5
+> [!NOTE]
6
+> This guide covers Agent Zero as an MCP **client**. To expose Agent Zero as an MCP **server**, see [Connectivity → MCP Server](connectivity.md#mcp-server-connectivity).
7
+
8
## What are MCP Servers?
9
10
MCP servers are external processes or services that expose a set of tools that Agent Zero can use. Agent Zero acts as an MCP *client*, consuming tools made available by these servers. The integration supports three main types of MCP servers:
@@ -16,11 +19,31 @@ Agent Zero discovers and integrates MCP tools dynamically:
19
20
1. **Configuration**: You define the MCP servers Agent Zero should connect to in its configuration. The primary way to do this is through the Agent Zero settings UI.
21
2. **Saving Settings**: When you save your settings via the UI, Agent Zero updates the `tmp/settings.json` file, specifically the `"mcp_servers"` key.
19
-3. **Automatic Installation (on Restart)**: After saving your settings and restarting Agent Zero, the system will attempt to automatically install any MCP server packages defined with `command: "npx"` and the `--package` argument in their configuration (this process is managed by `initialize.py`). You can monitor the application logs (e.g., Docker logs) for details on this installation attempt.
22
+3. **Server Startup**: Agent Zero initializes configured MCP servers (stdio servers) or connects to them (remote servers). For `npx`/`uvx` based servers, the first run may download packages.
23
4. **Tool Discovery**: Upon initialization (or when settings are updated), Agent Zero connects to each configured and enabled MCP server and queries it for the list of available tools, their descriptions, and expected parameters.
21
-5. **Dynamic Prompting**: The information about these discovered tools is then dynamically injected into the agent's system prompt. A placeholder like `{{tools}}` in a system prompt template (e.g., `prompts/default/agent.system.mcp_tools.md`) is replaced with a formatted list of all available MCP tools. This allows the agent's underlying Language Model (LLM) to know which external tools it can request.
24
+5. **Dynamic Prompting**: The information about these discovered tools is then dynamically injected into the agent's system prompt. A placeholder like `{{tools}}` in a system prompt template (e.g., `prompts/agent.system.mcp_tools.md`) is replaced with a formatted list of all available MCP tools. This allows the agent's underlying Language Model (LLM) to know which external tools it can request.
25
6. **Tool Invocation**: When the LLM decides to use an MCP tool, Agent Zero's `process_tools` method (handled by `mcp_handler.py`) identifies it as an MCP tool and routes the request to the appropriate `MCPConfig` helper, which then communicates with the designated MCP server to execute the tool.
26
27
+## Recommended MCP Servers
28
+Community-tested MCP servers include:
29
+
30
+- **Browser OS MCP** (browser automation)
31
+- **Chrome DevTools MCP** (browser automation)
32
+- **Playwright MCP** (browser automation)
33
+- **n8n MCP** (workflow automation)
34
+- **Gmail MCP** (email workflows)
35
+
36
+> [!TIP]
37
+> The built-in browser agent can be unreliable; MCP-based browser tools are the recommended alternative.
38
+
39
+## Docker Networking Notes
40
+If Agent Zero runs in Docker and your MCP server runs on the host:
41
+
42
+- Use `host.docker.internal` when available (macOS/Windows).
43
+- On Linux, run the MCP server in the same Docker network and reference it by container name.
44
+
45
+If your MCP server is remote, use its HTTPS URL in the configuration.
46
+
47
## Configuration
48
49
### Configuration File & Method
@@ -35,20 +58,29 @@ When you input and save your MCP server details in the UI, these settings are wr
58
59
Within `tmp/settings.json`, the MCP servers are defined under the `"mcp_servers"` key.
60
38
-* **Value Type**: The value for `"mcp_servers"` must be a **JSON formatted string**. This string itself contains an **array** of server configuration objects.
39
-* **Default Value**: If `tmp/settings.json` does not exist, or if it exists but does not contain the `"mcp_servers"` key, Agent Zero will use a default value of `""` (an empty string), meaning no MCP servers are configured.
61
+* **Value Type**: The value for `"mcp_servers"` must be a **JSON formatted string**. The string itself contains either:
62
+ * A JSON object containing `"mcpServers"` (recommended, matches the Settings UI)
63
+ * A JSON array of server configuration objects
64
+* **Default Value**: An empty config (for example, `{"mcpServers": {}}`).
65
* **Manual Editing (Advanced)**: While UI configuration is recommended, you can also manually edit `tmp/settings.json`. If you do, ensure the `"mcp_servers"` value is a valid JSON string, with internal quotes properly escaped.
66
42
-**Example `mcp_servers` string in `tmp/settings.json`:**
67
+**Example `mcp_servers` configuration (recommended format):**
68
69
```json
70
{
46
- // ... other settings ...
47
- "mcp_servers": "[{'name': 'sequential-thinking','command': 'npx','args': ['--yes', '--package', '@modelcontextprotocol/server-sequential-thinking', 'mcp-server-sequential-thinking']}, {'name': 'brave-search', 'command': 'npx', 'args': ['--yes', '--package', '@modelcontextprotocol/server-brave-search', 'mcp-server-brave-search'], 'env': {'BRAVE_API_KEY': 'YOUR_BRAVE_KEY_HERE'}}, {'name': 'fetch', 'command': 'npx', 'args': ['--yes', '--package', '@tokenizin/mcp-npx-fetch', 'mcp-npx-fetch', '--ignore-robots-txt', '--user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36']}]",
48
- // ... other settings ...
71
+ "mcpServers": {
72
+ "sqlite": {
73
+ "command": "uvx",
74
+ "args": ["mcp-server-sqlite", "--db-path", "/root/db.sqlite"]
75
+ },
76
+ "deep-wiki": {
77
+ "description": "Use this MCP to analyze GitHub repositories",
78
+ "url": "https://mcp.deepwiki.com/sse"
79
+ }
80
+ }
81
}
82
```
51
-*Note: In the actual `settings.json` file, the entire value for `mcp_servers` is a single string, with backslashes escaping the quotes within the array structure.*
83
+*Note: In `tmp/settings.json`, the entire value of `"mcp_servers"` is stored as a single string. The Settings UI handles escaping automatically.*
84
85
* **Updating**: As mentioned, the recommended way to set or update this value is through Agent Zero's settings UI.
86
* **For Existing `settings.json` Files (After an Upgrade)**: If you have an existing `tmp/settings.json` from a version of Agent Zero prior to MCP server support, the `"mcp_servers"` key will likely be missing. To add this key:
@@ -58,7 +90,7 @@ Within `tmp/settings.json`, the MCP servers are defined under the `"mcp_servers"
90
91
### MCP Server Configuration Structure
92
61
-Here are templates for configuring individual servers within the `mcp_servers` JSON array string:
93
+Here are templates for configuring individual servers within the `mcp_servers` configuration:
94
95
**1. Local Stdio Server**
96
docs/notifications.md
+3
@@ -2,6 +2,9 @@
2
3
Quick guide for using the notification system in Agent Zero.
4
5
+> [!TIP]
6
+> Notifications pair well with scheduled tasks. See [Tasks & Scheduling](usage.md#tasks--scheduling) for automation patterns.
7
+
8
## Backend Usage
9
10
Use `AgentNotification` helper methods anywhere in your Python code:
docs/quickstart.md
+12
-15
@@ -1,13 +1,11 @@
1
# Quick Start
2
-This guide provides a quick introduction to using Agent Zero. We'll cover launching the web UI, starting a new chat, and running a simple task.
2
+This guide provides a quick introduction to using Agent Zero. We'll cover launching the Web UI, starting a new chat, and running a simple task.
3
4
-## Launching the Web UI
5
-1. Make sure you have Agent Zero installed and your environment set up correctly (refer to the [Installation guide](installation.md) if needed).
6
-2. Open a terminal in the Agent Zero directory and activate your conda environment (if you're using one).
7
-3. Run one of the following commands:
4
+## Launching the Web UI (Docker)
5
+1. Pull the latest image:
6
7
```bash
10
-python run_ui.py
8
+docker pull agent0ai/agent-zero:latest
9
```
10
11
Notes:
@@ -15,7 +13,9 @@ Notes:
13
14
4. A message similar to this will appear in your terminal, indicating the Web UI is running:
15
18
-
16
+```bash
17
+docker run -p 0:80 agent0ai/agent-zero:latest
18
+```
19
20
5. Open your web browser and navigate to the URL shown in the terminal (usually `http://127.0.0.1:5000`). You should see the Agent Zero Web UI.
21
@@ -32,14 +32,13 @@ Notes:
32
## Running a Simple Task
33
Let's ask Agent Zero to download a YouTube video. Here's how:
34
35
-1. Type "Download a YouTube video for me" in the chat input field and press Enter or click the send button.
36
-
37
-2. Agent Zero will process your request. You'll see its "thoughts" and the actions it takes displayed in the UI. It will find a default already existing solution, that implies using the `code_execution_tool` to run a simple Python script to perform the task.
38
-
39
-3. The agent will then ask you for the URL of the YouTube video you want to download.
35
+1. Type "Download a YouTube video for me" in the chat input field and press Enter or click the send button.
36
+2. Agent Zero will process your request. You'll see its thoughts and tool calls in the UI.
37
+3. The agent will ask you for the URL of the YouTube video you want to download.
38
39
## Example Interaction
40
Here's an example of what you might see in the Web UI at step 3:
41
+
42
43
44
## Next Steps
@@ -52,6 +51,4 @@ Now that you've run a simple task, you can experiment with more complex requests
51
* Create or modify files
52
53
> [!TIP]
55
-> The [Usage Guide](usage.md) provides more in-depth information on using Agent
56
-> Zero's various features, including prompt engineering, tool usage, and multi-agent
57
-> cooperation.
54
+> The [Usage Guide](usage.md) provides more in-depth information on tools, projects, tasks, and backup/restore.
docs/troubleshooting.md
+34
-17
@@ -3,37 +3,54 @@ This page addresses frequently asked questions (FAQ) and provides troubleshootin
3
4
## Frequently Asked Questions
5
**1. How do I ask Agent Zero to work directly on my files or dirs?**
6
-- Place the files/dirs in the `work_dir` directory. Agent Zero will be able to perform tasks on them. The `work_dir` directory is located in the root directory of the Docker Container.
6
+- Place the files/dirs in `/a0/work_dir`. Agent Zero will be able to perform tasks on them.
7
8
**2. When I input something in the chat, nothing happens. What's wrong?**
9
-- Check if you have set up API keys in the Settings page. If not, the application will not be able to communicate with the endpoints it needs to run LLMs and to perform tasks.
9
+- Check if you have set up API keys in the Settings page. If not, the application cannot call LLM providers.
10
11
-**3. How do I integrate open-source models with Agent Zero?**
12
-Refer to the [Choosing your LLMs](installation.md#installing-and-using-ollama-local-models) section of the documentation for detailed instructions and examples for configuring different LLMs. Local models can be run using Ollama or LM Studio.
11
+**3. I get “Invalid model ID.” What does that mean?**
12
+- Verify the **provider** and **model naming**. For example, `openai/gpt-4.1` is correct for OpenRouter, but **incorrect** for the native OpenAI provider.
13
+
14
+**4. Does ChatGPT Plus include API access?**
15
+- No. ChatGPT Plus does not include API credits. You must provide an OpenAI API key in Settings.
16
+
17
+**5. Where is chat history stored?**
18
+- Chat history lives at `/a0/tmp/chats/` inside the container.
19
+
20
+**6. How do I integrate open-source models with Agent Zero?**
21
+Refer to the [Choosing your LLMs](installation.md#installing-and-using-ollama-local-models) section for configuring local models (Ollama, LM Studio, etc.).
22
23
> [!TIP]
15
-> Some LLM providers offer free usage of their APIs, for example Groq, Mistral, SambaNova or CometAPI.
24
+> Some LLM providers offer free usage tiers, for example Groq, Mistral, SambaNova, or CometAPI.
25
+
26
+**7. How can I make Agent Zero retain memory between sessions?**
27
+Use **Settings → Backup & Restore** and avoid mapping the entire `/a0` directory. See [How to update Agent Zero](installation.md#how-to-update-agent-zero).
28
+
29
+**8. My browser agent fails or is unreliable. What now?**
30
+The built-in browser agent is currently unstable on some systems. Use MCP alternatives such as Browser OS, Chrome DevTools, or Playwright. See [MCP Setup](mcp_setup.md).
31
17
-**6. How can I make Agent Zero retain memory between sessions?**
18
-Refer to the [How to update Agent Zero](installation.md#how-to-update-agent-zero) section of the documentation for instructions on how to update Agent Zero while retaining memory and data.
32
+**9. My secrets disappeared after a backup restore.**
33
+Secrets are stored in `/a0/tmp/secrets.env` and are not always included in backup archives. Copy them manually.
34
20
-**7. Where can I find more documentation or tutorials?**
21
-- Join the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/B8KZKNsPpj) community for support and discussions.
35
+**10. Where can I find more documentation or tutorials?**
36
+- Join the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/B8KZKNsPpj) community.
37
23
-**8. How do I adjust API rate limits?**
24
-Modify the `rate_limit_seconds` and `rate_limit_requests` parameters in the `AgentConfig` class within `initialize.py`.
38
+**11. How do I adjust API rate limits?**
39
+Use the model rate limit fields in Settings (Chat/Utility/Embedding model sections) to set request/input/output limits. These map to the model config limits (for example `limit_requests`, `limit_input`, `limit_output`).
40
26
-**9. My code_execution_tool doesn't work, what's wrong?**
27
-- Ensure you have Docker installed and running. If using Docker Desktop on macOS, grant it access to your project files in Docker Desktop's settings. Check the [Installation guide](installation.md#4-install-docker-docker-desktop-application) for more details.
28
-- Verify that the Docker image is updated.
41
+**12. My `code_execution_tool` doesn't work, what's wrong?**
42
+- Ensure Docker is installed and running.
43
+- On macOS, grant Docker Desktop access to your project files.
44
+- Verify that the Docker image is updated.
45
30
-**10. Can Agent Zero interact with external APIs or services (e.g., WhatsApp)?**
31
-Extending Agent Zero to interact with external APIs is possible by creating custom tools or solutions. Refer to the documentation on creating them.
46
+**13. Can Agent Zero interact with external APIs or services (e.g., WhatsApp)?**
47
+Yes, by creating custom tools or using MCP servers. See [Extensibility](extensibility.md) and [MCP Setup](mcp_setup.md).
48
49
## Troubleshooting
50
51
**Installation**
52
- **Docker Issues:** If Docker containers fail to start, consult the Docker documentation and verify your Docker installation and configuration. On macOS, ensure you've granted Docker access to your project files in Docker Desktop's settings as described in the [Installation guide](installation.md#4-install-docker-docker-desktop-application). Verify that the Docker image is updated.
53
+- **Web UI not reachable:** Ensure at least one host port is mapped to container port `80`. If you used `0:80`, check the assigned port in Docker Desktop.
54
55
**Usage**
56
@@ -41,4 +58,4 @@ Extending Agent Zero to interact with external APIs is possible by creating cust
58
59
* **Error Messages:** Pay close attention to the error messages displayed in the Web UI or terminal. They often provide valuable clues for diagnosing the issue. Refer to the specific error message in online searches or community forums for potential solutions.
60
44
-* **Performance Issues:** If Agent Zero is slow or unresponsive, it might be due to resource limitations, network latency, or the complexity of your prompts and tasks, especially when using local models.
\ No newline at end of file
61
+* **Performance Issues:** If Agent Zero is slow or unresponsive, it might be due to resource limitations, network latency, or the complexity of your prompts and tasks, especially when using local models.
docs/usage.md
+54
-10
@@ -34,7 +34,7 @@ Located beneath the chat input box, Agent Zero provides a set of action buttons
34
#### Knowledge and File Management
35
* **Import Knowledge:** Import external files into the agent's knowledge base
36
- Supports `.txt`, `.pdf`, `.csv`, `.html`, `.json`, and `.md` formats
37
- - Files are stored in `\knowledge\custom\main`
37
+ - Files are stored in `/a0/knowledge/custom/main`
38
- Success message confirms successful import
39
- See [knowledge](architecture.md#knowledge) for more details
40
@@ -58,6 +58,7 @@ Located beneath the chat input box, Agent Zero provides a set of action buttons
58
Access the chat history in JSON format
59
- View the conversation as processed by the LLM
60
- Useful for debugging and understanding agent behavior
61
+ - Files are stored under `/a0/tmp/chats/` inside the container
62
63
64
@@ -102,17 +103,23 @@ Agent Zero's power comes from its ability to use [tools](architecture.md#tools).
103
104
- **Understand Tools:** Agent Zero includes default tools like knowledge (powered by SearXNG), code execution, and communication. Understand the capabilities of these tools and how to invoke them.
105
105
-### Real-Time WebSocket Features
106
-- Use WebSockets when you need bidirectional, low-latency updates. The [WebSocket Infrastructure guide](websocket-infrastructure.md) explains the backend handler framework, client API, filtering semantics, and common producer/consumer patterns.
106
+### Browser Agent Status & MCP Alternatives
107
+The built-in browser agent currently has dependency issues on some systems. If web automation is critical, prefer MCP-based browser tools instead:
108
+
109
+- **Browser OS MCP**
110
+- **Chrome DevTools MCP**
111
+- **Playwright MCP**
112
+
113
+See [MCP Setup](mcp_setup.md) for configuration guidance and recommended servers.
114
115
## Example of Tools Usage: Web Search and Code Execution
116
Let's say you want Agent Zero to perform some financial analysis tasks. Here's a possible prompt:
117
111
-> Please be a professional financial analyst. Find last month Bitcoin/ USD price trend and make a chart in your environment. The chart must have highlighted key points corresponding with dates of major news about cryptocurrency. Use the 'search_engine' and 'document_query_tool' to find the price and the news, and the 'code_execution_tool' to perform the rest of the job.
118
+> Please be a professional financial analyst. Find last month Bitcoin/ USD price trend and make a chart in your environment. The chart must have highlighted key points corresponding with dates of major news about cryptocurrency. Use the `search_engine` and `document_query` tools to find the price and the news, and the `code_execution_tool` to perform the rest of the job.
119
120
Agent Zero might then:
121
115
-1. Use the `search_engine` and `document_query_tool` to query a reliable source for the Bitcoin price and for the news about cryptocurrency as prompted.
122
+1. Use the `search_engine` and `document_query` tools to query a reliable source for the Bitcoin price and for the news about cryptocurrency as prompted.
123
2. Extract the price from the search results and save the news, extracting their dates and possible impact on the price.
124
3. Use the `code_execution_tool` to execute a Python script that performs the graph creation and key points highlighting, using the extracted data and the news dates as inputs.
125
4. Save the final chart on disk inside the container and provide a link to it with the `response_tool`.
@@ -132,6 +139,25 @@ One of Agent Zero's unique features is multi-agent cooperation.
139
140
141
142
+## Projects
143
+Projects create isolated workspaces with their own context, instructions, memory, and secrets. This prevents context bleed between unrelated tasks or clients.
144
+
145
+- Project files live under `/a0/usr/projects/<project_name>/`
146
+- Project instructions are automatically injected from `.a0proj/instructions/`
147
+- Project memory and knowledge are stored separately from global memory
148
+
149
+See [Projects in Extensibility](extensibility.md#projects) for structure details and file locations.
150
+
151
+## Tasks & Scheduling
152
+Tasks allow Agent Zero to spawn scheduled or on-demand work in separate contexts.
153
+
154
+- **Schedule from UI:** Settings → Tasks Scheduler can run a task at a specified time.
155
+- **Schedule from chat:** ask the agent to create a task for a future time.
156
+- **Dedicated context:** each task runs in its own chat context, which pairs well with Projects.
157
+
158
+> [!TIP]
159
+> Combine **Projects + Tasks + Notifications** for recurring, scoped workflows (e.g., daily inbox summaries). See [Notifications](notifications.md) for alerts.
160
+
161
## Prompt Engineering
162
Effective prompt engineering is crucial for getting the most out of Agent Zero. Here are some tips and techniques:
163
@@ -140,6 +166,20 @@ Effective prompt engineering is crucial for getting the most out of Agent Zero.
166
* **Break Down Complex Tasks:** For complex tasks, break them down into smaller, more manageable sub-tasks. This makes it easier for the agent to reason through the problem and generate a solution.
167
* **Iterative Refinement:** Don't expect perfect results on the first try. Experiment with different prompts, refine your instructions based on the agent's responses, and iterate until you achieve the desired outcome. To achieve a full-stack, web-app development task, for example, you might need to iterate for a few hours for 100% success.
168
169
+## Secrets & Variables
170
+Use the Settings → **Secrets** and **Variables** fields to store credentials and non-sensitive configuration values.
171
+
172
+- **Secrets** (sensitive): API keys, passwords, tokens
173
+- **Variables** (non-sensitive): URLs, usernames, flags
174
+
175
+You can reference these values in prompts by name. For example, store `MY_GMAIL` as a secret and instruct the agent to use it when prompted.
176
+
177
+> [!IMPORTANT]
178
+> Secrets are stored in `/a0/tmp/secrets.env`. Keep a manual copy if you rely on backups, as secrets are not always preserved by Backup & Restore.
179
+
180
+> [!NOTE]
181
+> Project-scoped secrets and variables (when using Projects) live under `/a0/usr/projects/<project_name>/.a0proj/` (`secrets.env`, `variables.env`).
182
+
183
## Voice Interface
184
Agent Zero provides both Text-to-Speech (TTS) and Speech-to-Text (STT) capabilities for natural voice interaction:
185
@@ -192,7 +232,7 @@ Configure STT settings in the Settings page:
232
> ensuring that no data is transmitted to external servers or OpenAI APIs. This
233
> enhances user privacy while maintaining functionality.
234
195
-
235
+## Mathematical Expressions
236
* **Complex Mathematics:** Supports full KaTeX syntax for:
237
- Fractions, exponents, and roots
238
- Matrices and arrays
@@ -227,7 +267,7 @@ Agent Zero provides a powerful file browser interface for managing your workspac
267
- Current path always visible for context
268
269
> [!NOTE]
230
-> The files browser allows the user to go in the Agent Zero root folder if you click the `Up` button, but the working directory of Agents will always be `/work_dir`
270
+> The file browser lets you navigate the Agent Zero filesystem. For file-based work, keep your working files in `/a0/work_dir` (or inside a Project workspace).
271
>
272
- **File Operations**:
273
- Create new files and directories
@@ -252,7 +292,7 @@ Agent Zero provides a comprehensive backup and restore system to protect your da
292
Access the backup functionality through the Settings interface:
293
294
1. Click the **Settings** button in the sidebar
255
-2. Navigate to the **Backup** tab
295
+2. Navigate to the **Backup & Restore** tab
296
3. Click **Create Backup** to start the backup process
297
298
#### What Gets Backed Up
@@ -265,6 +305,9 @@ By default, Agent Zero backs up your most important data:
305
* **Custom Skills**: Any skills you've added or modified (SKILL.md format)
306
* **Uploaded Files**: Documents and files you've worked with
307
308
+> [!NOTE]
309
+> Chat history is stored at `/a0/tmp/chats/` inside the container.
310
+
311
#### Customizing Backup Content
312
Before creating a backup, you can customize what to include:
313
@@ -284,12 +327,13 @@ Before creating a backup, you can customize what to include:
327
328
> [!NOTE]
329
> Backup creation may take a few minutes depending on the amount of data. You'll see progress updates during the process.
330
+> Secrets stored in `/a0/tmp/secrets.env` are not always included in backup archives. Keep a manual copy if you rely on secrets.
331
332
### Restoring from Backup
333
The restore process allows you to recover your Agent Zero setup from a previous backup:
334
335
#### Starting a Restore
292
-1. Navigate to **Settings** → **Backup** tab
336
+1. Navigate to **Settings** → **Backup & Restore** tab
337
2. Click **Restore from Backup**
338
3. Upload your backup ZIP file
339
@@ -330,7 +374,7 @@ Optionally clean up existing files before restoring:
374
* **Test Restores**: Occasionally test restoring backups to ensure they work
375
376
#### Security Considerations
333
-* **API Keys**: Backups include your API keys and sensitive configuration
377
+* **Secrets**: Backups do **not** reliably include `/a0/tmp/secrets.env`. Copy it manually when migrating.
378
* **Secure Storage**: Store backup files securely and don't share them
379
* **Clean Systems**: When restoring on new systems, verify all configurations
380