fix skills import path and gitignores
frdel committed
Feb 2, 2026 at 20:44 UTC
6ca97b7f4a3bb2e67c28593ffda5383e4db2c226
11 files changed
+662
-48
.dockerignore
+1
-4
@@ -5,16 +5,13 @@
5
# Obsolete
6
memory/**
7
instruments/**
8
+knowledge/custom/**
9
10
# Logs, tmp, usr
11
logs/*
12
tmp/*
13
usr/*
14
14
-# Knowledge directory – keep only default/
15
-knowledge/**
16
-!knowledge/default/
17
-!knowledge/default/**
15
16
# Keep .gitkeep markers anywhere
17
!**/.gitkeep
.gitignore
+4
-10
@@ -15,9 +15,10 @@
15
# Ignore all contents of the virtual environment directory
16
.venv/
17
18
-# Handle memory directory
19
-memory/**
20
-!memory/**/
18
+# obsolete folders
19
+memory/
20
+knowledge/custom/
21
+instruments/
22
23
# Handle logs directory
24
logs/*
@@ -25,15 +26,8 @@ logs/*
26
# Handle tmp and usr directory
27
tmp/*
28
usr/*
28
-!usr/skills/
29
-!usr/skills/**
29
30
# Handle knowledge directory
32
-knowledge/**
33
-!knowledge/**/
34
-# Explicitly allow the default folder in knowledge
35
-!knowledge/default/
36
-!knowledge/default/**
31
32
# Global rule to include .gitkeep files anywhere
33
!**/.gitkeep
docs/CONTRIBUTING-SKILLS.md
+8
-8
@@ -62,7 +62,7 @@ python -m python.helpers.skills_cli search "keyword"
62
63
### Manual Creation
64
65
-1. Create a folder in `usr/skills/custom/` with your skill name
65
+1. Create a folder in `usr/skills/` with your skill name
66
2. Add a `SKILL.md` file with YAML frontmatter
67
3. Optionally add supporting scripts (`.py`, `.sh`, `.js`)
68
@@ -175,8 +175,8 @@ Ask yourself:
175
python -m python.helpers.skills_cli create my-awesome-skill
176
177
# Or manually
178
-mkdir -p usr/skills/custom/my-awesome-skill
179
-touch usr/skills/custom/my-awesome-skill/SKILL.md
178
+mkdir -p usr/skills/my-awesome-skill
179
+touch usr/skills/my-awesome-skill/SKILL.md
180
```
181
182
### Step 3: Write the SKILL.md
@@ -338,12 +338,12 @@ def test_skill_has_required_fields():
338
2. **Create Your Skill:**
339
```bash
340
python -m python.helpers.skills_cli create my-skill
341
- # Edit usr/skills/custom/my-skill/SKILL.md
341
+ # Edit usr/skills/my-skill/SKILL.md
342
```
343
344
3. **Move to Default (for contribution):**
345
```bash
346
- mv usr/skills/custom/my-skill usr/skills/default/my-skill
346
+ mv usr/skills/my-skill skills/my-skill
347
```
348
349
4. **Create a Pull Request:**
@@ -433,7 +433,7 @@ my-skills-collection/
433
434
### Q: Where should I put my skills?
435
436
-**A:** During development, use `usr/skills/custom/`. For contribution, move to `usr/skills/default/`.
436
+**A:** During development, use `usr/skills/`. For contribution, move to `skills/`.
437
438
### Q: How are skills discovered?
439
@@ -441,7 +441,7 @@ my-skills-collection/
441
442
### Q: Can I use skills from other platforms?
443
444
-**A:** Yes! The SKILL.md standard is cross-platform. Skills from Claude Code, Cursor, or other compatible platforms can be copied directly to `usr/skills/custom/`.
444
+**A:** Yes! The SKILL.md standard is cross-platform. Skills from Claude Code, Cursor, or other compatible platforms can be copied directly to `usr/skills/`.
445
446
### Q: How do I update a skill?
447
@@ -455,7 +455,7 @@ my-skills-collection/
455
456
## Example Skills to Learn From
457
458
-Check out these well-structured skills in `usr/skills/default/`:
458
+Check out these well-structured skills in `skills/`:
459
460
- `brainstorming/` - Requirements exploration workflow
461
- `debugging/` - Systematic debugging methodology
docs/architecture.md
+3
-3
@@ -298,11 +298,11 @@ Your detailed instructions here...
298
#### Directory Structure
299
| Directory | Description |
300
|-----------|-------------|
301
-| `/usr/skills/default` | Default skills included with Agent Zero |
302
-| `/usr/skills/custom` | Your custom skills (create folders here) |
301
+| `/skills` | Default skills included with Agent Zero |
302
+| `/usr/skills` | Your custom skills (create folders here) |
303
304
#### Adding Skills
305
-1. Create folder in `usr/skills/custom` (e.g., `usr/skills/custom/my-skill`)
305
+1. Create folder in `usr/skills` (e.g., `usr/skills/my-skill`)
306
2. Add `SKILL.md` file with YAML frontmatter (required)
307
3. Optionally add supporting scripts (`.sh`, `.py`, etc.)
308
4. Optionally add `docs/` subfolder for additional documentation
knowledge/main/about/github_readme.md
new
+65
@@ -0,0 +1,65 @@
1
+
2
+# Agent Zero Documentation
3
+To begin with Agent Zero, follow the links below for detailed guides on various topics:
4
+
5
+- **[Installation](installation.md):** Set up (or [update](installation.md#how-to-update-agent-zero)) Agent Zero on your system.
6
+- **[Usage Guide](usage.md):** Explore GUI features and usage scenarios.
7
+- **[Architecture Overview](architecture.md):** Understand the internal workings of the framework.
8
+- **[Contributing](contribution.md):** Learn how to contribute to the Agent Zero project.
9
+- **[Troubleshooting and FAQ](troubleshooting.md):** Find answers to common issues and questions.
10
+
11
+### Your experience with Agent Zero starts now!
12
+
13
+- **Download Agent Zero:** Follow the [installation guide](installation.md) to download and run Agent Zero.
14
+- **Join the Community:** Join the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/B8KZKNsPpj) community to discuss ideas, ask questions, and collaborate with other contributors.
15
+- **Share your Work:** Share your Agent Zero creations, workflows and discoverings on our [Show and Tell](https://github.com/agent0ai/agent-zero/discussions/categories/show-and-tell) area on GitHub.
16
+- **Report Issues:** Use the [GitHub issue tracker](https://github.com/agent0ai/agent-zero/issues) to report framework-relative bugs or suggest new features.
17
+
18
+## Table of Contents
19
+
20
+- [Welcome to the Agent Zero Documentation](#agent-zero-documentation)
21
+ - [Your Experience with Agent Zero](#your-experience-with-agent-zero-starts-now)
22
+ - [Table of Contents](#table-of-contents)
23
+- [Installation Guide](installation.md)
24
+ - [Windows, macOS and Linux Setup](installation.md#windows-macos-and-linux-setup-guide)
25
+ - [Settings Configuration](installation.md#settings-configuration)
26
+ - [Choosing Your LLMs](installation.md#choosing-your-llms)
27
+ - [Installing and Using Ollama](installation.md#installing-and-using-ollama-local-models)
28
+ - [Using Agent Zero on Mobile](installation.md#using-agent-zero-on-your-mobile-device)
29
+ - [How to Update Agent Zero](installation.md#how-to-update-agent-zero)
30
+ - [Full Binaries Installation](installation.md#in-depth-guide-for-full-binaries-installation)
31
+- [Usage Guide](usage.md)
32
+ - [Basic Operations](usage.md#basic-operations)
33
+ - [Restart Framework](usage.md#restart-framework)
34
+ - [Action Buttons](usage.md#action-buttons)
35
+ - [File Attachments](usage.md#file-attachments)
36
+ - [Tool Usage](usage.md#tool-usage)
37
+ - [Example of Tools Usage](usage.md#example-of-tools-usage-web-search-and-code-execution)
38
+ - [Multi-Agent Cooperation](usage.md#multi-agent-cooperation)
39
+ - [Prompt Engineering](usage.md#prompt-engineering)
40
+ - [Voice Interface](usage.md#voice-interface)
41
+ - [Mathematical Expressions](usage.md#mathematical-expressions)
42
+ - [File Browser](usage.md#file-browser)
43
+ - [Backup & Restore](usage.md#backup--restore)
44
+- [Architecture Overview](architecture.md)
45
+ - [System Architecture](architecture.md#system-architecture)
46
+ - [Runtime Architecture](architecture.md#runtime-architecture)
47
+ - [Implementation Details](architecture.md#implementation-details)
48
+ - [Core Components](architecture.md#core-components)
49
+ - [Agents](architecture.md#1-agents)
50
+ - [Tools](architecture.md#2-tools)
51
+ - [SearXNG Integration](architecture.md#searxng-integration)
52
+ - [Memory System](architecture.md#3-memory-system)
53
+ - [Messages History and Summarization](archicture.md#messages-history-and-summarization)
54
+ - [Prompts](architecture.md#4-prompts)
55
+ - [Knowledge](architecture.md#5-knowledge)
56
+ - [Instruments](architecture.md#6-instruments)
57
+ - [Extensions](architecture.md#7-extensions)
58
+ - [Contributing](contribution.md)
59
+ - [Getting Started](contribution.md#getting-started)
60
+ - [Making Changes](contribution.md#making-changes)
61
+ - [Submitting a Pull Request](contribution.md#submitting-a-pull-request)
62
+ - [Documentation Stack](contribution.md#documentation-stack)
63
+- [Troubleshooting and FAQ](troubleshooting.md)
64
+ - [Frequently Asked Questions](troubleshooting.md#frequently-asked-questions)
65
+ - [Troubleshooting](troubleshooting.md#troubleshooting)
knowledge/main/about/installation.md
new
+554
@@ -0,0 +1,554 @@
1
+# Users installation guide for Windows, macOS and Linux
2
+
3
+Click to open a video to learn how to install Agent Zero:
4
+
5
+[](https://www.youtube.com/watch?v=w5v5Kjx51hs)
6
+
7
+The following user guide provides instructions for installing and running Agent Zero using Docker, which is the primary runtime environment for the framework. For developers and contributors, we also provide instructions for setting up the [full development environment](#in-depth-guide-for-full-binaries-installation).
8
+
9
+
10
+## Windows, macOS and Linux Setup Guide
11
+
12
+
13
+1. **Install Docker Desktop:**
14
+- Docker Desktop provides the runtime environment for Agent Zero, ensuring consistent behavior and security across platforms
15
+- The entire framework runs within a Docker container, providing isolation and easy deployment
16
+- Available as a user-friendly GUI application for all major operating systems
17
+
18
+1.1. Go to the download page of Docker Desktop [here](https://www.docker.com/products/docker-desktop/). If the link does not work, just search the web for "docker desktop download".
19
+
20
+1.2. Download the version for your operating system. For Windows users, the Intel/AMD version is the main download button.
21
+
22
+<img src="res/setup/image-8.png" alt="docker download" width="200"/>
23
+<br><br>
24
+
25
+> [!NOTE]
26
+> **Linux Users:** You can install either Docker Desktop or docker-ce (Community Edition).
27
+> For Docker Desktop, follow the instructions for your specific Linux distribution [here](https://docs.docker.com/desktop/install/linux-install/).
28
+> For docker-ce, follow the instructions [here](https://docs.docker.com/engine/install/).
29
+>
30
+> If you're using docker-ce, you'll need to add your user to the `docker` group:
31
+> ```bash
32
+> sudo usermod -aG docker $USER
33
+> ```
34
+> Log out and back in, then run:
35
+> ```bash
36
+> docker login
37
+> ```
38
+
39
+1.3. Run the installer with default settings. On macOS, drag and drop the application to your Applications folder.
40
+
41
+<img src="res/setup/image-9.png" alt="docker install" width="300"/>
42
+<img src="res/setup/image-10.png" alt="docker install" width="300"/>
43
+
44
+<img src="res/setup/image-12.png" alt="docker install" width="300"/>
45
+<br><br>
46
+
47
+1.4. Once installed, launch Docker Desktop:
48
+
49
+<img src="res/setup/image-11.png" alt="docker installed" height="100"/>
50
+<img src="res/setup/image-13.png" alt="docker installed" height="100"/>
51
+<br><br>
52
+
53
+> [!IMPORTANT]
54
+> **macOS Configuration:** In Docker Desktop's preferences (Docker menu) → Settings →
55
+> Advanced, enable "Allow the default Docker socket to be used (requires password)."
56
+
57
+
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.
62
+
63
+2.1. Pull the Agent Zero Docker image:
64
+- Search for `agent0ai/agent-zero` in Docker Desktop
65
+- Click the `Pull` button
66
+- The image will be downloaded to your machine in a few minutes
67
+
68
+
69
+
70
+> [!TIP]
71
+> Alternatively, run the following command in your terminal:
72
+>
73
+> ```bash
74
+> docker pull agent0ai/agent-zero
75
+> ```
76
+
77
+2.2. Create a data directory for persistence:
78
+- Choose or create a directory on your machine where you want to store Agent Zero's data
79
+- This can be any location you prefer (e.g., `C:/agent-zero-data` or `/home/user/agent-zero-data`)
80
+- This directory will contain all your Agent Zero files, like the legacy root folder structure:
81
+ - `/memory` - Agent's memory and learned information
82
+ - `/knowledge` - Knowledge base
83
+ - `/instruments` - Instruments and functions
84
+ - `/prompts` - Prompt files
85
+ - `/work_dir` - Working directory
86
+ - `.env` - Your API keys
87
+ - `settings.json` - Your Agent Zero settings
88
+
89
+> [!TIP]
90
+> Choose a location that's easy to access and backup. All your Agent Zero data
91
+> will be directly accessible in this directory.
92
+
93
+2.3. Run the container:
94
+- In Docker Desktop, go back to the "Images" tab
95
+- Click the `Run` button next to the `agent0ai/agent-zero` image
96
+- Open the "Optional settings" menu
97
+- Set the port to `0` in the second "Host port" field (for automatic port assignment)
98
+
99
+Optionally you can map local folders for file persistence:
100
+- Under "Volumes", configure:
101
+ - Host path: Your chosen directory (e.g., `C:\agent-zero-data`)
102
+ - Container path: `/a0`
103
+
104
+
105
+
106
+- Click the `Run` button in the "Images" tab.
107
+- The container will start and show in the "Containers" tab
108
+
109
+
110
+
111
+> [!TIP]
112
+> Alternatively, run the following command in your terminal:
113
+> ```bash
114
+> docker run -p $PORT:80 -v /path/to/your/data:/a0 agent0ai/agent-zero
115
+> ```
116
+> - Replace `$PORT` with the port you want to use (e.g., `50080`)
117
+> - Replace `/path/to/your/data` with your chosen directory path
118
+
119
+2.4. Access the Web UI:
120
+- The framework will take a few seconds to initialize and the Docker logs will look like the image below.
121
+- Find the mapped port in Docker Desktop (shown as `<PORT>:80`) or click the port right under the container ID as shown in the image below
122
+
123
+
124
+
125
+- Open `http://localhost:<PORT>` in your browser
126
+- The Web UI will open. Agent Zero is ready for configuration!
127
+
128
+
129
+
130
+> [!TIP]
131
+> You can also access the Web UI by clicking the ports right under the container ID in Docker Desktop.
132
+
133
+> [!NOTE]
134
+> After starting the container, you'll find all Agent Zero files in your chosen
135
+> directory. You can access and edit these files directly on your machine, and
136
+> the changes will be immediately reflected in the running container.
137
+
138
+3. Configure Agent Zero
139
+- Refer to the following sections for a full guide on how to configure Agent Zero.
140
+
141
+## Settings Configuration
142
+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.
143
+
144
+### Agent Configuration
145
+- **Prompts Subdirectory:** Choose the subdirectory within `/prompts` for agent behavior customization. The 'default' directory contains the standard prompts.
146
+- **Memory Subdirectory:** Select the subdirectory for agent memory storage, allowing separation between different instances.
147
+- **Knowledge Subdirectory:** Specify the location of custom knowledge files to enhance the agent's understanding.
148
+
149
+
150
+
151
+### Chat Model Settings
152
+- **Provider:** Select the chat model provider (e.g., Ollama)
153
+- **Model Name:** Choose the specific model (e.g., llama3.2)
154
+- **Temperature:** Adjust response randomness (0 for deterministic, higher values for more creative responses)
155
+- **Context Length:** Set the maximum token limit for context window
156
+- **Context Window Space:** Configure how much of the context window is dedicated to chat history
157
+
158
+
159
+
160
+### Utility Model Configuration
161
+- **Provider & Model:** Select a smaller, faster model for utility tasks like memory organization and summarization
162
+- **Temperature:** Adjust the determinism of utility responses
163
+
164
+### Embedding Model Settings
165
+- **Provider:** Choose the embedding model provider (e.g., OpenAI)
166
+- **Model Name:** Select the specific embedding model (e.g., text-embedding-3-small)
167
+
168
+### Speech to Text Options
169
+- **Model Size:** Choose the speech recognition model size
170
+- **Language Code:** Set the primary language for voice recognition
171
+- **Silence Settings:** Configure silence threshold, duration, and timeout parameters for voice input
172
+
173
+### API Keys
174
+- Configure API keys for various service providers directly within the Web UI
175
+- Click `Save` to confirm your settings
176
+
177
+### Authentication
178
+- **UI Login:** Set username for web interface access
179
+- **UI Password:** Configure password for web interface security
180
+- **Root Password:** Manage Docker container root password for SSH access
181
+
182
+
183
+
184
+### Development Settings
185
+- **RFC Parameters (local instances only):** configure URLs and ports for remote function calls between instances
186
+- **RFC Password:** Configure password for remote function calls
187
+Learn more about Remote Function Calls and their purpose [here](#7-configure-agent-zero-rfc).
188
+
189
+> [!IMPORTANT]
190
+> Always keep your API keys and passwords secure.
191
+
192
+# Choosing Your LLMs
193
+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:
194
+
195
+| LLM Role | Description |
196
+| --- | --- |
197
+| `chat_llm` | This is the primary LLM used for conversations and generating responses. |
198
+| `utility_llm` | This LLM handles internal tasks like summarizing messages, managing memory, and processing internal prompts. Using a smaller, less expensive model here can improve efficiency. |
199
+| `embedding_llm` | This LLM is responsible for generating embeddings used for memory retrieval and knowledge base lookups. Changing the `embedding_llm` will re-index all of A0's memory. |
200
+
201
+**How to Change:**
202
+1. Open Settings page in the Web UI.
203
+2. Choose the provider for the LLM for each role (Chat model, Utility model, Embedding model) and write the model name.
204
+3. Click "Save" to apply the changes.
205
+
206
+## Important Considerations
207
+
208
+> [!CAUTION]
209
+> Changing the `embedding_llm` will re-index all the memory and knowledge, and
210
+> requires clearing the `memory` folder to avoid errors, as the embeddings can't be
211
+> mixed in the vector database. Note that this will DELETE ALL of Agent Zero's memory.
212
+
213
+## Installing and Using Ollama (Local Models)
214
+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:
215
+
216
+#### First step: installation
217
+**On Windows:**
218
+
219
+Download Ollama from the official website and install it on your machine.
220
+
221
+<button>[Download Ollama Setup](https://ollama.com/download/OllamaSetup.exe)</button>
222
+
223
+**On macOS:**
224
+```
225
+brew install ollama
226
+```
227
+Otherwise choose macOS installer from the [official website](https://ollama.com/).
228
+
229
+**On Linux:**
230
+```bash
231
+curl -fsSL https://ollama.com/install.sh | sh
232
+```
233
+
234
+**Finding Model Names:**
235
+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).
236
+
237
+#### Second step: pulling the model
238
+**On Windows, macOS, and Linux:**
239
+```
240
+ollama pull <model-name>
241
+```
242
+
243
+1. Replace `<model-name>` with the name of the model you want to use. For example, to pull the Mistral Large model, you would use the command `ollama pull mistral-large`.
244
+
245
+2. A CLI message should confirm the model download on your system
246
+
247
+#### Selecting your model within Agent Zero
248
+1. Once you've downloaded your model(s), you must select it in the Settings page of the GUI.
249
+
250
+2. Within the Chat model, Utility model, or Embedding model section, choose Ollama as provider.
251
+
252
+3. Write your model code as expected by Ollama, in the format `llama3.2` or `qwen2.5:7b`
253
+
254
+4. Click `Save` to confirm your settings.
255
+
256
+
257
+
258
+#### Managing your downloaded models
259
+Once you've downloaded some models, you might want to check which ones you have available or remove any you no longer need.
260
+
261
+- **Listing downloaded models:**
262
+ To see a list of all the models you've downloaded, use the command:
263
+ ```
264
+ ollama list
265
+ ```
266
+- **Removing a model:**
267
+ If you need to remove a downloaded model, you can use the `ollama rm` command followed by the model name:
268
+ ```
269
+ ollama rm <model-name>
270
+ ```
271
+
272
+
273
+- Experiment with different model combinations to find the balance of performance and cost that best suits your needs. E.g., faster and lower latency LLMs will help, and you can also use `faiss_gpu` instead of `faiss_cpu` for the memory.
274
+
275
+## Using Agent Zero on your mobile device
276
+Agent Zero's Web UI is accessible from any device on your network through the Docker container:
277
+
278
+1. The Docker container automatically exposes the Web UI on all network interfaces
279
+2. Find the mapped port in Docker Desktop:
280
+ - Look under the container name (usually in the format `<PORT>:80`)
281
+ - For example, if you see `32771:80`, your port is `32771`
282
+3. Access the Web UI from any device using:
283
+ - Local access: `http://localhost:<PORT>`
284
+ - Network access: `http://<YOUR_COMPUTER_IP>:<PORT>`
285
+
286
+> [!TIP]
287
+> - Your computer's IP address is usually in the format `192.168.x.x` or `10.0.x.x`
288
+> - You can find your external IP address by running `ipconfig` (Windows) or `ifconfig` (Linux/Mac)
289
+> - The port is automatically assigned by Docker unless you specify one
290
+
291
+> [!NOTE]
292
+> If you're running Agent Zero directly on your system (legacy approach) instead of
293
+> using Docker, you'll need to configure the host manually in `run_ui.py` to run on all interfaces using `host="0.0.0.0"`.
294
+
295
+For developers or users who need to run Agent Zero directly on their system,see the [In-Depth Guide for Full Binaries Installation](#in-depth-guide-for-full-binaries-installation).
296
+
297
+# How to update Agent Zero
298
+
299
+1. **If you come from the previous version of Agent Zero:**
300
+- Your data is safely stored across various directories and files inside the Agent Zero folder.
301
+- To update to the new Docker runtime version, you might want to backup the following files and directories:
302
+ - `/memory` - Agent's memory
303
+ - `/knowledge` - Custom knowledge base (if you imported any custom knowledge files)
304
+ - `/instruments` - Custom instruments and functions (if you created any custom)
305
+ - `/tmp/settings.json` - Your Agent Zero settings
306
+ - `/tmp/chats/` - Your chat history
307
+- 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.
308
+- Reach for the folder where you saved your data and copy it to the new Agent Zero folder set during the installation process.
309
+- Agent Zero will automatically detect your saved data and use it across memory, knowledge, instruments, prompts and settings.
310
+
311
+> [!IMPORTANT]
312
+> 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.
313
+> The same goes for chats in `/tmp/chats/`, they might be incompatible with the new version
314
+
315
+2. **Update Process (Docker Desktop)**
316
+- Go to Docker Desktop and stop the container from the "Containers" tab
317
+- Right-click and select "Remove" to remove the container
318
+- 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.
319
+
320
+
321
+
322
+- Search and pull the new image if you chose to remove it
323
+- Run the new container with the same volume settings as the old one
324
+
325
+> [!IMPORTANT]
326
+> Make sure to use the same volume mount path when running the new
327
+> container to preserve your data. The exact path depends on where you stored
328
+> your Agent Zero data directory (the chosen directory on your machine).
329
+
330
+> [!TIP]
331
+> Alternatively, run the following commands in your terminal:
332
+>
333
+> ```bash
334
+> # Stop the current container
335
+> docker stop agent-zero
336
+>
337
+> # Remove the container (data is safe in the folder)
338
+> docker rm agent-zero
339
+>
340
+> # Remove the old image
341
+> docker rmi agent0ai/agent-zero
342
+>
343
+> # Pull the latest image
344
+> docker pull agent0ai/agent-zero
345
+>
346
+> # Run new container with the same volume mount
347
+> docker run -p $PORT:80 -v /path/to/your/data:/a0 agent0ai/agent-zero
348
+> ```
349
+
350
+3. **Full Binaries**
351
+- Using Git/GitHub: Pull the latest version of the Agent Zero repository.
352
+- The custom knowledge, solutions, memory, and other data will get ignored, so you don't need to worry about losing any of your custom data. The same goes for your .env file with all of your API keys and settings.json.
353
+
354
+> [!WARNING]
355
+> - If you update manually, beware: save your .env file with the API keys, and look for new dependencies in requirements.txt.
356
+> - If any changes are made to the requirements of the updated version, you have to execute this command inside the a0 conda env after activating it:
357
+> ```bash
358
+> pip install -r requirements.txt
359
+
360
+# In-Depth Guide for Full Binaries Installation
361
+- Agent Zero is a framework. It's made to be customized, edited, enhanced. Therefore you need to install the necessary components to run it when downloading its full binaries. This guide will help you to do so.
362
+- The following step by step instructions can be followed along with a video for this tutorial on how to make Agent Zero work with its full development environment.
363
+
364
+[](https://youtu.be/8H7mFsvxKYQ)
365
+
366
+## Reminders:
367
+1. There's no need to install Python, Conda will manage that for you.
368
+2. You don't necessarily need API keys: Agent Zero can run with local models. For this tutorial though, we will leave it to the default OpenAI API. A guide for downloading Ollama along with local models is available [here](#installing-and-using-ollama-local-models).
369
+3. Visual Studio Code or any other code editor is not mandatory, but it makes it easier to navigate and edit files.
370
+4. Git/GitHub is not mandatory, you can download the framework files through your browser. We will not be showing how to use Git in this tutorial.
371
+5. Docker is not mandatory for the full binaries installation, since the framework will run on your machine connecting to the Docker container through the Web UI RFC functionality.
372
+6. Running Agent Zero without Docker makes the process more complicated and it's thought for developers and contributors.
373
+
374
+> [!IMPORTANT]
375
+> Linux instructions are provided as general instructions for any Linux distribution. If you're using a distribution other than Debian/Ubuntu, you may need to adjust the instructions accordingly.
376
+>
377
+> For Debian/Ubuntu, just follow the macOS instructions, as they are the same.
378
+
379
+## 1. Install Conda (miniconda)
380
+- Conda is a Python environment manager, it will help you keep your projects and installations separated.
381
+- It's a lightweight version of Anaconda that includes only conda, Python, the packages they depend on, and a small number of other useful packages, including pip, zlib and a few others.
382
+
383
+1. Go to the download page of miniconda [here](https://docs.anaconda.com/miniconda/#miniconda-latest-installer-links). If the link does not work, just search the web for "miniconda download".
384
+2. Based on your operating system, download the right installer of miniconda. For macOS select the version with "pkg" at the end.
385
+
386
+<img src="res/setup/image-1.png" alt="miniconda download win" width="500"/>
387
+<img src="res/setup/image-5.png" alt="miniconda download macos" width="500"/>
388
+<br><br>
389
+
390
+3. Run the installer and go through the installation process, here you can leave everything to default and just click Next, Next... The same goes for macOS with the "pkg" graphical installer.
391
+
392
+<img src="res/setup/image.png" alt="miniconda install" width="200"/>
393
+<img src="res/setup/image-2.png" alt="miniconda install" width="200"/>
394
+<img src="res/setup/image-3.png" alt="miniconda install" width="200"/>
395
+<img src="res/setup/image-4.png" alt="miniconda install" width="200"/>
396
+<br><br>
397
+
398
+4. After the installation is complete, you should have "Anaconda Powershell Prompt" installed on your Windows machine. On macOS, when you open the Terminal application in your Applications folder and type "conda --version", you should see the version installed.
399
+
400
+<img src="res/setup/image-6.png" alt="miniconda installed" height="100"/>
401
+<img src="res/setup/image-7.png" alt="miniconda installed" height="100"/>
402
+<br><br>
403
+
404
+
405
+## 2. Download Agent Zero
406
+- You can clone the Agent Zero repository (https://github.com/agent0ai/agent-zero) from GitHub if you know how to use Git. In this tutorial I will just show how to download the files.
407
+
408
+1. Go to the Agent Zero releases [here](https://github.com/agent0ai/agent-zero/releases).
409
+2. The latest release is on the top of the list, click the "Source Code (zip)" button under "Assets" to download it.
410
+
411
+<img src="res/setup/image-14-u.png" alt="agent zero download" width="500"/>
412
+<br><br>
413
+
414
+3. Extract the downloaded archive where you want to have it. I will extract them to "agent-zero" folder on my Desktop - "C:\Users\frdel\Desktop\agent-zero" on Windows and "/Users/frdel/Desktop/agent-zero" on macOS.
415
+
416
+## 3. Set up Conda environment
417
+- Now that we have the project files and Conda, we can create **virtual Python environment** for this project, activate it and install requirements.
418
+
419
+1. Open your **"Anaconda Powershell Prompt"** application on windows or **"Terminal"** application on macOS.
420
+2. In the terminal, navigate to your Agent Zero folder using **"cd"** command. Replace the path with your actual Agent Zero folder path.
421
+~~~
422
+cd C:\Users\frdel\Desktop\agent-zero
423
+~~~
424
+You should see your folder has changed on the next terminal line.
425
+
426
+<img src="res/setup/image-15.png" alt="agent zero cd" height="100"/>
427
+<img src="res/setup/image-16.png" alt="agent zero cd" height="100"/>
428
+<br><br>
429
+
430
+3. Create Conda environment using command **"conda create"**. After **"-n"** is your environment name, you can choose your own, i will use **"a0"** - short for Agent Zero. After **"python"** is the Python version that Conda will install for you into this environment, right now, 3.12 works fine. **-y** skips confirmations.
431
+~~~
432
+conda create -n a0 python=3.12 -y
433
+~~~
434
+
435
+4. Once done, activate the new environment for this terminal window by another command:
436
+~~~
437
+conda activate a0
438
+~~~
439
+And you should see that the **(base)** on the left has changed to **(a0)**. This means that this terminal now uses the new **a0** virtual environment and all packages will be installed into this environment.
440
+
441
+<img src="res/setup/image-17.png" alt="conda env" height="200"/>
442
+<img src="res/setup/image-18.png" alt="conda env" height="200"/>
443
+<br><br>
444
+
445
+> [!IMPORTANT]
446
+> If you open a new terminal window, you will need to activate the environment with
447
+> "conda activate a0" again for that window.
448
+
449
+5. Install requirements using **"pip"**. Pip is a Python package manager. We can install all required packages from requirements.txt file using command:
450
+~~~
451
+pip install -r requirements.txt
452
+~~~
453
+This might take some time. If you get any errors regarding version conflicts and compatibility, double check that your environment is activated and that you created that environment with the correct Python version.
454
+
455
+<img src="res/setup/image-19.png" alt="conda reqs" height="200"/>
456
+<br><br>
457
+
458
+## 4. Install Docker (Docker Desktop application)
459
+Simply put, Docker is a way of running virtual computers on your machine. These are lightweight, disposable and isolated from your operating system, so it is a way to sandbox Agent Zero.
460
+- Agent Zero only connects to the Docker container when it needs to execute code and commands. The frameworks itself runs on your machine.
461
+- Docker has a desktop application with GUI for all major operating system, which is the recommended way to install it.
462
+
463
+1. Go to the download page of Docker Desktop [here](https://www.docker.com/products/docker-desktop/). If the link does not work, just search the web for "docker desktop download".
464
+2. Download the version for your operating system. Don't be tricked by the seemingly missing windows intel/amd version, it's the button itself, not in the dropdown menu.
465
+
466
+<img src="res/setup/image-8.png" alt="docker download" width="200"/>
467
+<br><br>
468
+
469
+3. Run the installer and go through the installation process. It should be even shorter than Conda installation, you can leave everything to default. On macOS, the installer is a "dmg" image, so just drag and drop the application to your Applications folder like always.
470
+
471
+<img src="res/setup/image-9.png" alt="docker install" width="300"/>
472
+<img src="res/setup/image-10.png" alt="docker install" width="300"/>
473
+
474
+<img src="res/setup/image-12.png" alt="docker install" width="300"/>
475
+<br><br>
476
+
477
+
478
+4. Once installed, you should see Docker Desktop application on your Windows/Mac machine.
479
+
480
+<img src="res/setup/image-11.png" alt="docker installed" height="100"/>
481
+<img src="res/setup/image-13.png" alt="docker installed" height="100"/>
482
+<br><br>
483
+
484
+5. Create account in the application.
485
+- It's required to be signed in to the Docker Hub, so create a free account in the Docker Desktop application, you will be prompted when the application first runs.
486
+
487
+> [!IMPORTANT]
488
+> **Important macOS-only Docker Configuration:** In Docker Desktop's preferences
489
+> (Docker menu) go to Settings, navigate to "Advanced" and check "Allow the default
490
+> Docker socket to be used (requires password)." This allows Agent Zero to
491
+> communicate with the Docker daemon.
492
+
493
+
494
+
495
+> [!NOTE]
496
+> **Linux Users:** You can install both Docker Desktop or docker-ce (Community Edition).
497
+> For Docker Desktop, follow the instructions for your specific Linux distribution [here](https://docs.docker.com/desktop/install/linux-install/).
498
+> For docker-ce, follow the instructions [here](https://docs.docker.com/engine/install/).
499
+>
500
+> If you're using docker-ce, you will need to add your user to the `docker` group to be able to run docker commands without sudo. You can do this by running the following command in your terminal: `sudo usermod -aG docker $USER`. Then log out and log back in for the changes to take effect.
501
+>
502
+> Login in the Docker CLI with `docker login` and provide your Docker Hub credentials.
503
+
504
+6. Pull the Docker image
505
+- Agent Zero needs a Docker image to be pulled from the Docker Hub to be run, even when using the full binaries.
506
+You can refer to the [installation instructions above](#windows-macos-and-linux-setup-guide) to run the Docker container and then resume from the next step. There are two differences:
507
+ - You need to map two ports instead of one:
508
+ - 55022 in the first field to run the Remote Function Call SSH
509
+ - 0 in the second field to run the Web UI in automatic port assignment
510
+ - You need to map the `/a0` volume to the location of your local Agent Zero folder.
511
+- Run the Docker container following the instructions.
512
+
513
+## 5. Run the local Agent Zero instance
514
+Run the Agent Zero with Web UI:
515
+~~~
516
+python run_ui.py
517
+~~~
518
+
519
+<img src="res/setup/image-21.png" alt="run ui" height="110"/>
520
+<br><br>
521
+
522
+- Open the URL shown in terminal in your web browser. You should see the Agent Zero interface.
523
+
524
+## 6. Configure Agent Zero
525
+Now we can configure Agent Zero - select models, settings, API Keys etc. Refer to the [Usage](usage.md#agent-configuration) guide for a full guide on how to configure Agent Zero.
526
+
527
+## 7. Configure Agent Zero RFC
528
+Agent Zero needs to be configured further to redirect some functions to the Docker container. This is crucial for development as A0 needs to run in a standardized environment to support all features.
529
+1. Go in "Settings" page in the Web UI of your local instance and go in the "Development" section.
530
+2. Set "RFC Destination URL" to `http://localhost`
531
+3. Set the two ports (HTTP and SSH) to the ones used when creating the Docker container
532
+4. Click "Save"
533
+
534
+
535
+
536
+5. Go in "Settings" page in the Web UI of your Docker instance and go in the "Development" section.
537
+
538
+
539
+
540
+6. This time the page has only the password field, set it to the same password you used when creating the Docker container.
541
+7. Click "Save"
542
+8. Use the Development environment
543
+9. Now you have the full development environment to work on Agent Zero.
544
+
545
+<img src="res/setup/image-22-1.png" alt="run ui" width="400"/>
546
+<img src="res/setup/image-23-1.png" alt="run ui" width="400"/>
547
+<br><br>
548
+
549
+
550
+### Conclusion
551
+After following the instructions for your specific operating system, you should have Agent Zero successfully installed and running. You can now start exploring the framework's capabilities and experimenting with creating your own intelligent agents.
552
+
553
+If you encounter any issues during the installation process, please consult the [Troubleshooting section](troubleshooting.md) of this documentation or refer to the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/B8KZKNsPpj) community for assistance.
554
+
python/api/skills_import.py
+1
-1
@@ -14,7 +14,7 @@ from werkzeug.utils import secure_filename
14
15
class SkillsImport(ApiHandler):
16
"""
17
- Import an external skills pack (.zip) into usr/skills/custom/<namespace>/...
17
+ Import an external skills pack (.zip) into usr/skills/<namespace>/...
18
Performs the actual import (not dry-run).
19
"""
20
python/api/skills_import_preview.py
+1
-1
@@ -14,7 +14,7 @@ from werkzeug.utils import secure_filename
14
15
class SkillsImportPreview(ApiHandler):
16
"""
17
- Preview importing an external skills pack (.zip) into usr/skills/custom/<namespace>/...
17
+ Preview importing an external skills pack (.zip) into usr/skills/<namespace>/...
18
Uses dry-run (no copying).
19
"""
20
python/helpers/skills_import.py
+1
-1
@@ -208,7 +208,7 @@ def import_skills(
208
raise ValueError("project_name is required when dest_subdir is 'project'")
209
dest_root = get_project_skills_folder(project_name)
210
else:
211
- dest_root = Path(files.get_abs_path("usr", "skills", dest_subdir))
211
+ dest_root = Path(files.get_abs_path("usr", "skills"))
212
dest_root.mkdir(parents=True, exist_ok=True)
213
214
extracted_root: Optional[Path] = None
python/tools/skills_tool.py
+20
-16
@@ -40,7 +40,9 @@ class SkillsTool(Tool):
40
if method == "read_file":
41
skill_name = str(kwargs.get("skill_name") or "").strip()
42
file_path = str(kwargs.get("file_path") or "").strip()
43
- return Response(message=self._read_file(skill_name, file_path), break_loop=False)
43
+ return Response(
44
+ message=self._read_file(skill_name, file_path), break_loop=False
45
+ )
46
47
return Response(
48
message=(
@@ -49,7 +51,9 @@ class SkillsTool(Tool):
51
),
52
break_loop=False,
53
)
52
- except Exception as e: # keep tool robust; return error instead of crashing loop
54
+ except (
55
+ Exception
56
+ ) as e: # keep tool robust; return error instead of crashing loop
57
return Response(message=f"Error in skills_tool: {e}", break_loop=False)
58
59
def _list(self) -> str:
@@ -58,10 +62,7 @@ class SkillsTool(Tool):
62
agent=self.agent,
63
)
64
if not skills:
61
- return (
62
- "No skills found. Expected SKILL.md files under: "
63
- "usr/skills/{custom,default} or project .a0proj/skills."
64
- )
65
+ return "No skills found."
66
67
# Stable output: sort by name
68
skills_sorted = sorted(skills, key=lambda s: s.name.lower())
@@ -99,17 +100,21 @@ class SkillsTool(Tool):
100
desc = desc[:200].rstrip() + "…"
101
lines.append(f"- {s.name}: {desc}")
102
lines.append("")
102
- lines.append("Tip: use skills_tool method=load skill_name=<name> to load full instructions.")
103
+ lines.append(
104
+ "Tip: use skills_tool method=load skill_name=<name> to load full instructions."
105
+ )
106
return "\n".join(lines)
107
108
def _load(self, skill_name: str) -> str:
109
107
- skill_name = skill_name.strip()
110
+ skill_name = skill_name.strip()
111
if skill_name.startswith("**") and skill_name.endswith("**"):
109
- skill_name = skill_name[2:-2] # remove markdown bold markers if used by agent
112
+ skill_name = skill_name[
113
+ 2:-2
114
+ ] # remove markdown bold markers if used by agent
115
116
if not skill_name:
112
- return "Error: 'skill_name' is required for method=load."
117
+ return "Error: 'skill_name' is required for method=load."
118
119
skill = skills_helper.find_skill(
120
skill_name,
@@ -157,7 +162,9 @@ class SkillsTool(Tool):
162
lines.append("")
163
164
if referenced_files:
160
- lines.append("Files in skill directory (use skills_tool method=read_file to open):")
165
+ lines.append(
166
+ "Files in skill directory (use skills_tool method=read_file to open):"
167
+ )
168
lines.append(referenced_files)
169
else:
170
lines.append("No additional files found in skill directory.")
@@ -206,9 +213,6 @@ class SkillsTool(Tool):
213
max_folders=100,
214
output_mode="string",
215
max_lines=300,
209
- ignore=files.read_file("conf/skill.default.gitignore")
210
- )
216
+ ignore=files.read_file("conf/skill.default.gitignore"),
217
+ )
218
return tree
212
-
213
-
214
-
skills/create-skill/SKILL.md
+4
-4
@@ -172,7 +172,7 @@ If your skill needs scripts or templates:
172
173
```bash
174
# Create directory structure
175
-mkdir -p usr/skills/custom/my-skill/{scripts,templates,docs}
175
+mkdir -p usr/skills/my-skill/{scripts,templates,docs}
176
```
177
178
## Example: Complete Skill
@@ -258,12 +258,12 @@ print(f"Took {elapsed:.4f} seconds")
258
259
1. Create skill directory:
260
```bash
261
- mkdir -p usr/skills/custom/my-skill
261
+ mkdir -p usr/skills/my-skill
262
```
263
264
2. Create SKILL.md:
265
```bash
266
- touch usr/skills/custom/my-skill/SKILL.md
266
+ touch usr/skills/my-skill/SKILL.md
267
```
268
269
3. Add content and save
@@ -277,7 +277,7 @@ To share skills with others:
277
1. Create a GitHub repository
278
2. Include the skill directory structure
279
3. Add a README with installation instructions
280
-4. Users can copy to their `usr/skills/custom/` directory
280
+4. Users can copy to their `usr/skills/` directory
281
282
## Testing Your Skill
283