main README.md and latest v0.8 docs (#268)
* main README.md and latest v0.8 docs - summarization system - main README rehaul - Update README.md video - Updated imgs * main README.md and latest v0.8 docs - summarization system - main README rehaul - Update README.md video - Updated imgs
Alessandro committed
Dec 19, 2024 at 19:49 UTC
c18ea298b2d6d8ee7fdde31690a4f68963de8e35
14 files changed
+446
-308
README.md
+119
-64
@@ -1,129 +1,184 @@
1
-# Agent Zero
1
+<div align="center">
2
+
3
+
4
+
5
+# `Agent Zero`
6
7
[](https://www.skool.com/agent-zero) [](https://discord.gg/B8KZKNsPpj) [](https://www.youtube.com/@AgentZeroFW) [](https://www.linkedin.com/in/jan-tomasek/) [](https://x.com/JanTomasekDev)
8
5
-[](https://www.youtube.com/watch?v=U_Gl0NPalKA)
9
+[Installation](./docs/installation.md) •
10
+[How to update](./docs/installation.md#how-to-update-agent-zero) •
11
+[Documentation](./docs/README.md) •
12
+[Usage](./docs/usage.md)
13
+
14
+</div>
15
7
-**Personal and organic AI framework**
16
+https://github.com/user-attachments/assets/c168759d-57d8-4b43-b62a-1026afcf52e6
17
+
18
+## A personal, organic agentic framework that grows and learns with you
19
20
- Agent Zero is not a predefined agentic framework. It is designed to be dynamic, organically growing, and learning as you use it.
21
- Agent Zero is fully transparent, readable, comprehensible, customizable, and interactive.
22
- Agent Zero uses the computer as a tool to accomplish its (your) tasks.
23
13
-## Now fully Dockerized, with TTS and STT:
24
+# 💡 Key Features
25
15
-
26
+1. **General-purpose Assistant**
27
17
-## Key Concepts
28
+- Agent Zero is not pre-programmed for specific tasks (but can be). It is meant to be a general-purpose personal assistant. Give it a task, and it will gather information, execute commands and code, cooperate with other agent instances, and do its best to accomplish it.
29
+- It has a persistent memory, allowing it to memorize previous solutions, code, facts, instructions, etc., to solve tasks faster and more reliably in the future.
30
19
-1. **General-purpose Assistant**
20
- - Agent Zero is not pre-programmed for specific tasks (but can be). It is meant to be a general-purpose personal assistant. Give it a task, and it will gather information, execute commands and code, cooperate with other agent instances, and do its best to accomplish it.
21
- - It has a persistent memory, allowing it to memorize previous solutions, code, facts, instructions, etc., to solve tasks faster and more reliably in the future.
31
+
32
33
2. **Computer as a Tool**
24
- - Agent Zero uses the operating system as a tool to accomplish its tasks. It has no single-purpose tools pre-programmed. Instead, it can write its own code and use the terminal to create and use its own tools as needed.
25
- - The only default tools in its arsenal are online search, memory features, communication (with the user and other agents), and code/terminal execution. Everything else is created by the agent itself or can be extended by the user.
26
- - Tool usage functionality has been developed from scratch to be the most compatible and reliable, even with very small models.
34
28
- * **Default Tools:** Agent Zero includes tools like knowledge, webpage content, code execution, and communication.
29
- * **Creating Custom Tools:** Extend Agent Zero's functionality by creating your own custom tools.
30
- * **Instruments:** Instruments are a new type of tool that allow you to create custom functions and procedures that can be called by Agent Zero.
35
+- Agent Zero uses the operating system as a tool to accomplish its tasks. It has no single-purpose tools pre-programmed. Instead, it can write its own code and use the terminal to create and use its own tools as needed.
36
+- The only default tools in its arsenal are online search, memory features, communication (with the user and other agents), and code/terminal execution. Everything else is created by the agent itself or can be extended by the user.
37
+- Tool usage functionality has been developed from scratch to be the most compatible and reliable, even with very small models.
38
+- **Default Tools:** Agent Zero includes tools like knowledge, webpage content, code execution, and communication.
39
+- **Creating Custom Tools:** Extend Agent Zero's functionality by creating your own custom tools.
40
+- **Instruments:** Instruments are a new type of tool that allow you to create custom functions and procedures that can be called by Agent Zero.
41
42
3. **Multi-agent Cooperation**
33
- - Every agent has a superior agent giving it tasks and instructions. Every agent then reports back to its superior.
34
- - In the case of the first agent in the chain (Agent 0), the superior is the human user; the agent sees no difference.
35
- - Every agent can create its subordinate agent to help break down and solve subtasks. This helps all agents keep their context clean and focused.
43
+
44
+- Every agent has a superior agent giving it tasks and instructions. Every agent then reports back to its superior.
45
+- In the case of the first agent in the chain (Agent 0), the superior is the human user; the agent sees no difference.
46
+- Every agent can create its subordinate agent to help break down and solve subtasks. This helps all agents keep their context clean and focused.
47
+
48
+
49
+
50
51
4. **Completely Customizable and Extensible**
38
- - Almost nothing in this framework is hard-coded. Nothing is hidden. Everything can be extended or changed by the user.
39
- - The whole behavior is defined by a system prompt in the **prompts/default/agent.system.md** file. Change this prompt and change the framework dramatically.
40
- - The framework does not guide or limit the agent in any way. There are no hard-coded rails that agents have to follow.
41
- - Every prompt, every small message template sent to the agent in its communication loop can be found in the **prompts/** folder and changed.
42
- - Every default tool can be found in the **python/tools/** folder and changed or copied to create new predefined tools.
43
- - Of course, it is open-source (except for some tools like Perplexity, but that will be replaced with an open-source alternative as well in the future).
52
+
53
+- Almost nothing in this framework is hard-coded. Nothing is hidden. Everything can be extended or changed by the user.
54
+- The whole behavior is defined by a system prompt in the **prompts/default/agent.system.md** file. Change this prompt and change the framework dramatically.
55
+- The framework does not guide or limit the agent in any way. There are no hard-coded rails that agents have to follow.
56
+- Every prompt, every small message template sent to the agent in its communication loop can be found in the **prompts/** folder and changed.
57
+- Every default tool can be found in the **python/tools/** folder and changed or copied to create new predefined tools.
58
+
59
+
60
61
5. **Communication is Key**
46
- - Give your agent a proper system prompt and instructions, and it can do miracles.
47
- - Agents can communicate with their superiors and subordinates, asking questions, giving instructions, and providing guidance. Instruct your agents in the system prompt on how to communicate effectively.
48
- - The terminal interface is real-time streamed and interactive. You can stop and intervene at any point. If you see your agent heading in the wrong direction, just stop and tell it right away.
49
- - There is a lot of freedom in this framework. You can instruct your agents to regularly report back to superiors asking for permission to continue. You can instruct them to use point-scoring systems when deciding when to delegate subtasks. Superiors can double-check subordinates' results and dispute. The possibilities are endless.
62
51
-
63
+- Give your agent a proper system prompt and instructions, and it can do miracles.
64
+- Agents can communicate with their superiors and subordinates, asking questions, giving instructions, and providing guidance. Instruct your agents in the system prompt on how to communicate effectively.
65
+- The terminal interface is real-time streamed and interactive. You can stop and intervene at any point. If you see your agent heading in the wrong direction, just stop and tell it right away.
66
+- There is a lot of freedom in this framework. You can instruct your agents to regularly report back to superiors asking for permission to continue. You can instruct them to use point-scoring systems when deciding when to delegate subtasks. Superiors can double-check subordinates' results and dispute. The possibilities are endless.
67
53
-## Nice Features to Have
68
+## 🚀 Things you can build with Agent Zero
69
55
-- The new GUI output is very clean, fluid, colorful, readable, and interactive; nothing is hidden.
56
-- The same colorful output you see in the terminal is automatically saved to an HTML file in **logs/** folder for every session.
57
-- Agent output is streamed in real-time, allowing users to read along and intervene at any time.
58
-- No coding is required; only prompting and communication skills are necessary.
59
-- With a solid system prompt, the framework is reliable even with small models, including precise tool usage.
70
+- **Development Projects** - `"Create a React dashboard with real-time data visualization"`
71
61
-
72
+- **Data Analysis** - `"Analyze last quarter's NVIDIA sales data and create trend reports"`
73
63
-## Keep in Mind
74
+- **Content Creation** - `"Write a technical blog post about microservices"`
75
65
-1. **Agent Zero Can Be Dangerous!**
66
- - With proper instruction, Agent Zero is capable of many things, even potentially dangerous actions concerning your computer, data, or accounts. Always run Agent Zero in an isolated environment (like Docker) and be careful what you wish for.
76
+- **System Admin** - `"Set up a monitoring system for our web servers"`
77
68
-2. **Agent Zero Is Not Pre-programmed; It Is Prompt-based.**
69
- - The whole framework contains only a minimal amount of code and does not guide the agent in any way. Everything lies in the system prompt located in the **prompts/** folder.
78
+- **Research** - `"Gather and summarize five recent AI papers about CoT prompting"`
79
71
-3. **If You Cannot Provide the Ideal Environment, Let Your Agent Know.**
72
- - Agent Zero is made to be used in an isolated virtual environment (for safety) with some tools preinstalled and configured.
80
+# ⚙️ Installation
81
74
-[](https://www.youtube.com/watch?v=_Pionjv4hGc)
82
+Click to open a video to learn how to install Agent Zero:
83
76
-## Known Problems
84
+[](https://www.youtube.com/watch?v=cHDCCSr1YRI&t=24s)
85
78
-1. The system prompt may need improvements; contributions are welcome!
79
-2. Communication between agents via SSH within Docker containers may occasionally break; restarting might resolve issues.
80
-3. The agent may inadvertently alter its operating environment; cleaning up the **work_dir/** often fixes this.
86
+A detailed setup guide for Windows, macOS, and Linux with a video can be found in the Agent Zero Documentation at [this page](./docs/installation.md).
87
+
88
+### ⚡ Quick Start
89
+
90
+```bash
91
+# Pull and run with Docker
92
+
93
+docker pull frdel/agent-zero-run
94
+docker run -p 50001:80 frdel/agent-zero-run
95
+
96
+# Visit http://localhost:50001 to start
97
+```
98
+
99
+- Developers and contributors: download the full binaries for your system from the [releases page](https://github.com/frdel/agent-zero/releases) and then follow the instructions [provided here](./docs/installation.md#in-depth-guide-for-full-binaries-installation).
100
82
-## Ideal Environment
101
+## 🐳 Fully Dockerized, with Speech-to-Text and TTS
102
84
-- **Docker Container**: The ideal environment for running Agent Zero is within a Docker container; ensure Docker is running (e.g., Docker Desktop).
85
-- **Internet Access**: Required for online knowledge tools; adjust prompts if offline operation is preferred.
103
+
104
+
105
+- Customizable settings allow users to tailor the agent's behavior and responses to their needs.
106
+- The Web UI output is very clean, fluid, colorful, readable, and interactive; nothing is hidden.
107
+- You can load or save chats directly within the Web UI.
108
+- The same output you see in the terminal is automatically saved to an HTML file in **logs/** folder for every session.
109
110
111
89
-## Setup
112
+- Agent output is streamed in real-time, allowing users to read along and intervene at any time.
113
+- No coding is required; only prompting and communication skills are necessary.
114
+- With a solid system prompt, the framework is reliable even with small models, including precise tool usage.
115
91
-A detailed setup guide for Windows, macOS, and Linux with a video can be found in the new Agent Zero Documentation at [this page](docs/installation.md#windows-macos-and-linux-setup-guide).
116
+## 👀 Keep in Mind
117
93
-You can download full binaries for your system from the [releases page](https://github.com/frdel/agent-zero/releases).
118
+1. **Agent Zero Can Be Dangerous!**
119
95
-## Consult the Documentation
120
+- With proper instruction, Agent Zero is capable of many things, even potentially dangerous actions concerning your computer, data, or accounts. Always run Agent Zero in an isolated environment (like Docker) and be careful what you wish for.
121
97
-The documentation dives deep into the framework's features; it's an excellent starting point for new users. Click [here](docs/README.md) for more information.
122
+2. **Agent Zero Is Not Pre-programmed; It Is Prompt-based.**
123
99
-## Coming Up
124
+- The whole framework contains only a minimal amount of code and does not guide the agent in any way. Everything lies in the system prompt located in the **prompts/** folder.
125
+
126
+3. **If You Cannot Provide the Ideal Environment, Let Your Agent Know.**
127
+
128
+- Agent Zero is made to be used in an isolated virtual environment (for safety) with some tools preinstalled and configured.
129
+
130
+### 📌 Known Problems
131
+
132
+1. The system prompt may need improvements; contributions are welcome!
133
+2. The agent may inadvertently alter its operating environment; cleaning up the `work_dir` often fixes this.
134
+3. Agents might loop in multi-agentic interactions, leading to unexpected behaviors.
135
+
136
+## 📚 Read the Documentation
137
+
138
+| Page | Description |
139
+|-------|-------------|
140
+| [Installation](./docs/installation.md) | Installation, setup and configuration |
141
+| [Usage](./docs/usage.md) | Basic and advanced usage |
142
+| [Architecture](./docs/architecture.md) | System design and components |
143
+| [Contributing](./docs/contributing.md) | How to contribute |
144
+| [Troubleshooting](./docs/troubleshooting.md) | Common issues and their solutions |
145
+
146
+## 🎯 Changelog
147
+
148
+### Coming soon
149
150
- **User Interaction Refinements**
151
- **Browser Use and RAG Tools**
152
104
-### Changelog [since version 0.7]
105
-
153
> [!IMPORTANT]
154
>
108
-> **Changes to frdel/agent-zero Docker image since v0.8:**
155
+>**Changes to frdel/agent-zero Docker image since v0.7:**
156
>
110
-> - In version 0.8, the Docker image has changed to frdel/agent-zero-run using a new Dockerfile and image.
157
+> The new Docker image `frdel/agent-zero-run` provides the new unified environment.
158
+
159
+### v0.8
160
112
-#### v0.8
161
- **Docker Runtime**
162
- **New Messages History and Summarization System**
163
- **Agent Behavior Change and Management**
164
- **Text-to-Speech (TTS) and Speech-to-Text (STT)**
165
- **Settings Page in Web UI**
118
-- **SearXNG Integration Replacing Perplexity + DuckDuckGo Knowledge Tool**
166
+- **SearXNG Integration Replacing Perplexity + DuckDuckGo**
167
- **File Browser Functionality**
168
- **KaTeX Math Visualization Support**
169
- **In-chat File Attachments**
170
123
-#### v0.7
171
+### v0.7
172
+
173
- **Automatic Memory**
174
- **UI Improvements**
175
- **Instruments**
176
- **Extensions Framework**
177
- **Reflection Prompts**
178
- **Bug Fixes**
179
+
180
+## 🤝 Community and Support
181
+
182
+- [Join our Discord](https://discord.gg/B8KZKNsPpj) for live discussions or [visit our Skool Community](https://www.skool.com/agent-zero).
183
+- [Follow our YouTube channel](https://www.youtube.com/@AgentZeroFW) for hands-on explanations and tutorials
184
+- [Report Issues](https://github.com/frdel/agent-zero/issues) for bug fixes and features
docs/README.md
+3
-3
@@ -43,18 +43,18 @@ To begin with Agent Zero, follow the links below for detailed guides on various
43
- [Architecture Overview](architecture.md)
44
- [System Architecture](architecture.md#system-architecture)
45
- [Runtime Architecture](architecture.md#runtime-architecture)
46
+ - [Implementation Details](architecture.md#implementation-details)
47
- [Core Components](architecture.md#core-components)
48
- [Agents](architecture.md#1-agents)
49
- [Tools](architecture.md#2-tools)
50
- [SearXNG Integration](architecture.md#searxng-integration)
51
- [Memory System](architecture.md#3-memory-system)
52
+ - [Messages History and Summarization](archicture.md#messages-history-and-summarization)
53
- [Prompts](architecture.md#4-prompts)
54
- [Knowledge](architecture.md#5-knowledge)
55
- [Instruments](architecture.md#6-instruments)
56
- [Extensions](architecture.md#7-extensions)
55
- - [Implementation Details](architecture.md#implementation-details)
56
- - [Customization](architecture.md#customization)
57
-- [Contributing](contribution.md)
57
+ - [Contributing](contribution.md)
58
- [Getting Started](contribution.md#getting-started)
59
- [Making Changes](contribution.md#making-changes)
60
- [Submitting a Pull Request](contribution.md#submitting-a-pull-request)
docs/architecture.md
+90
-98
@@ -11,7 +11,7 @@ The user or Agent 0 is at the top of the hierarchy, delegating tasks to subordin
11
## Runtime Architecture
12
Agent Zero's runtime architecture is built around Docker containers:
13
14
-1. **Host System**:
14
+1. **Host System (your machine)**:
15
- Requires only Docker and a web browser
16
- Runs Docker Desktop or Docker Engine
17
- Handles container orchestration
@@ -35,6 +35,48 @@ This architecture ensures:
35
> page. See [Full Binaries Installation](installation.md#in-depth-guide-for-full-binaries-installation)
36
> for detailed instructions.
37
38
+## Implementation Details
39
+
40
+### Directory Structure
41
+| Directory | Description |
42
+| --- | --- |
43
+| `/docker` | Docker-related files for runtime container |
44
+| `/docs` | Documentation files and guides |
45
+| `/instruments` | Custom scripts and tools for runtime environment |
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 |
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 |
61
+
62
+### Key Files
63
+| File | Description |
64
+| --- | --- |
65
+| `.env` | Environment configuration |
66
+| `agent.py` | Core agent implementation |
67
+| `example.env` | Configuration template |
68
+| `initialize.py` | Framework initialization |
69
+| `models.py` | Model providers and configs |
70
+| `preload.py` | Pre-initialization routines |
71
+| `prepare.py` | Environment preparation |
72
+| `requirements.txt` | Python dependencies |
73
+| `run_cli.py` | CLI launcher |
74
+| `run_ui.py` | Web UI launcher |
75
+
76
+> [!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.
79
+
80
## Core Components
81
Agent Zero's architecture revolves around the following key components:
82
@@ -73,8 +115,10 @@ Agent Zero comes with a set of built-in tools designed to help agents perform ta
115
116
| Tool | Function |
117
| --- | --- |
118
+| behavior_adjustment | Agent Zero use this tool to change its behavior according to a prior request from the user.
119
| call_subordinate | Allows agents to delegate tasks to subordinate agents |
77
-| code_execution_tool | Allows agents to execute Python, Node.js, and Shell code in the terminal of the Docker container |
120
+| code_execution_tool | Allows agents to execute Python, Node.js, and Shell code in the terminal |
121
+| input | Allows agents to use the keyboard to interact with an active shell |
122
| knowledge_tool | Enables agents to retrieve information from memory, knowledge base or online external sources |
123
| response_tool | Allows agents to output a response |
124
| memory_tool | Enables agents to save, load, delete and forget information from memory |
@@ -83,7 +127,7 @@ Agent Zero comes with a set of built-in tools designed to help agents perform ta
127
#### Knowledge Tool
128
The `knowledge_tool` uses SearXNG to search the web and retrieve information. It can also search the local knowledge base and memory for relevant information. The tool returns a summary of the information, which can be used by the agent to make decisions or answer questions.
129
86
-##### SearXNG Integration
130
+#### SearXNG Integration
131
Agent Zero has integrated SearXNG as its primary search tool, replacing the previous knowledge tools (Perplexity and DuckDuckGo). This integration enhances the agent's ability to retrieve information while ensuring user privacy and customization.
132
133
- Privacy-Focused Search
@@ -101,7 +145,12 @@ In cases where SearXNG might not return satisfactory results, Agent Zero can be
145
> retrieval system.
146
147
#### Custom Tools
104
-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 in [Adding Tools](#adding-tools).
148
+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.
149
+
150
+1. Create `agent.system.tool.$TOOL_NAME.md` in `prompts/$SUBDIR`
151
+2. Add reference in `agent.system.tools.md`
152
+3. If needed, implement tool class in `python/tools` using `Tool` base class
153
+4. Follow existing patterns for consistency
154
155
> [!NOTE]
156
> Tools are always present in system prompt, so you should keep them to minimum.
@@ -119,27 +168,34 @@ The memory is categorized into four distinct areas:
168
- **Metadata**: Each memory entry includes metadata (IDs, timestamps), enabling efficient filtering and searching based on specific criteria
169
170
#### Messages History and Summarization
122
-Agent Zero implements a sophisticated message history and summarization system that helps maintain context while optimizing memory usage:
171
124
-- **Message Summaries**: Individual messages are summarized using a structured JSON format that captures key information while reducing token usage
172
+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.
173
+
174
+- **Context Extraction:** The system identifies key information from previous messages that are vital for ongoing discussions. This process mirrors how humans recall important memories, allowing less critical details to fade.
175
+- **Summarization Process:** Using natural language processing through the utility model, Agent Zero condenses the extracted information into concise summaries. By summarizing past interactions, Agent Zero can quickly recall important facts about the whole chat, leading to more appropriate responses.
176
+- **Contextual Relevance:** The summarized context is prioritized based on its relevance to the current topic, ensuring users receive the most pertinent information.
177
+
178
+**Implementation Details:**
179
+
180
+- **Message Summaries**: Individual messages are summarized using a structured format that captures key information while reducing token usage.
181
- **Dynamic Compression**: The system employs an intelligent compression strategy:
126
- - Recent messages remain in their original form for immediate context
127
- - Older messages are gradually compressed into more concise summaries
128
- - Multiple compression levels allow for efficient context window usage
129
- - Original messages are preserved separately from summaries
130
-- **Dual-Access Memory**: The system maintains two parallel streams of information:
131
- - Compressed summaries in the context window for quick reference
132
- - Original messages stored separately for detailed recall when needed
133
-- **Context Window Optimization**:
134
- - Acts as a near-infinite short-term memory for single conversations
135
- - Automatically balances detail level based on message age and importance
136
- - Maintains searchable indexes for efficient information retrieval
137
- - Dynamically adjusts compression ratios based on available space
182
+ - Recent messages remain in their original form for immediate context.
183
+ - Older messages are gradually compressed into more concise summaries.
184
+ - Multiple compression levels allow for efficient context window usage.
185
+ - Original messages are preserved separately from summaries.
186
+- **Context Window Optimization**:
187
+ - Acts as a near-infinite short-term memory for single conversations.
188
+ - Dynamically adjusts compression ratios based on available space and settings.
189
- **Bulk and Topic Summarization**:
139
- - Groups related messages into thematic chunks for better organization
140
- - Generates concise summaries of multiple messages while preserving key context
141
- - Enables efficient navigation of long conversation histories
142
- - Maintains semantic connections between related topics
190
+ - Groups related messages into thematic chunks for better organization.
191
+ - Generates concise summaries of multiple messages while preserving key context.
192
+ - Enables efficient navigation of long conversation histories.
193
+ - Maintains semantic connections between related topics.
194
+
195
+By dynamically adjusting context windows and summarizing past interactions, Agent Zero enhances both efficiency and user experience. This innovation not only reflects the framework's commitment to being dynamic and user-centric, but also draws inspiration from human cognitive processes, making AI interactions more relatable and effective. Just as humans forget trivial details, Agent Zero intelligently condenses information to enhance communication.
196
+
197
+> [!NOTE]
198
+> To maximize the effectiveness of context summarization, users should provide clear and specific instructions during interactions. This helps Agent Zero understand which details are most important to retain.
199
200
### 4. Prompts
201
The `prompts` directory contains various Markdown files that control agent behavior and communication. The most important file is `agent.system.main.md`, which acts as a central hub, referencing other prompt files.
@@ -162,6 +218,12 @@ The `prompts` directory contains various Markdown files that control agent behav
218
- **Behavior Files**: Stored in memory as `behaviour.md`, containing dynamic rules
219
- **Tool Prompts**: Organized in tool-specific files for modularity
220
221
+#### Custom Prompts
222
+1. Create directory in `prompts/` (e.g., `my-custom-prompts`)
223
+2. Copy and modify needed files from `prompts/default/`
224
+3. Agent Zero will merge your custom files with the default ones
225
+4. Select your custom prompts in the Settings page (Agent Config section)
226
+
227
#### Dynamic Behavior System
228
- **Behavior Adjustment**:
229
- Agents can modify their behavior in real-time based on user instructions
@@ -217,7 +279,12 @@ Instruments provide a way to add custom functionalities to Agent Zero without ad
279
- Can modify agent behavior by introducing new procedures
280
- Function calls or scripts to integrate with other systems
281
- Scripts are run inside the Docker Container
220
-- Implementation details in [Adding Instruments](#adding-instruments)
282
+
283
+#### Adding Instruments
284
+1. Create folder in `instruments/custom` (no spaces in name)
285
+2. Add `.md` description file for the interface
286
+3. Add `.sh` script (or other executable) for implementation
287
+4. The agent will automatically detect and use the instrument
288
289
### 7. Extensions
290
Extensions are a powerful feature of Agent Zero, designed to keep the main codebase clean and organized while allowing for greater flexibility and modularity.
@@ -232,83 +299,8 @@ Extensions can be found in `python/extensions` directory:
299
#### Types
300
- **Message Loop Prompts**: Handle system messages and history construction
301
- **Memory Management**: Handle recall and solution memorization
235
-- **Custom Extensions**: Add new functionalities (see [Adding Extensions](#adding-extensions))
236
-- **Behavior Management**: Handle dynamic behavior adjustments
302
- **System Integration**: Manage interaction with external systems
303
239
-## Implementation Details
240
-
241
-### Directory Structure
242
-| Directory | Description |
243
-| --- | --- |
244
-| `/docker` | Docker-related files for runtime container |
245
-| `/docs` | Documentation files and guides |
246
-| `/instruments` | Custom scripts and tools for runtime environment |
247
-| `/knowledge` | Knowledge base storage |
248
-| `/logs` | HTML CLI-style chat logs |
249
-| `/memory` | Persistent agent memory storage |
250
-| `/prompts` | System and tool prompts |
251
-| `/python` | Core Python codebase: |
252
-| `/api` | API endpoints and interfaces |
253
-| `/extensions` | Modular extensions |
254
-| `/helpers` | Utility functions |
255
-| `/tools` | Tool implementations |
256
-| `/tmp` | Temporary runtime data |
257
-| `/webui` | Web interface components: |
258
-| `/css` | Stylesheets |
259
-| `/js` | JavaScript modules |
260
-| `/public` | Static assets |
261
-| `/work_dir` | Working directory |
262
-
263
-### Key Files
264
-| File | Description |
265
-| --- | --- |
266
-| `.env` | Environment configuration |
267
-| `agent.py` | Core agent implementation |
268
-| `example.env` | Configuration template |
269
-| `initialize.py` | Framework initialization |
270
-| `models.py` | Model providers and configs |
271
-| `preload.py` | Pre-initialization routines |
272
-| `prepare.py` | Environment preparation |
273
-| `requirements.txt` | Python dependencies |
274
-| `run_cli.py` | CLI launcher |
275
-| `run_ui.py` | Web UI launcher |
276
-
277
-> [!NOTE]
278
-> When using the Docker runtime container, these directories are mounted
279
-> within the `/a0` volume for data persistence until the container is restarted or deleted.
280
-
281
-## Customization
282
-Agent Zero's strength lies in its flexibility. This section details how to customize various aspects of the framework, tailoring it to your specific needs and preferences.
283
-
284
-### AgentConfig
285
-The `AgentConfig` class in `initialize.py` provides various customization options:
286
-
287
-- `prompts_subdir`: Specifies the directory containing your custom prompts
288
-- `knowledge_subdirs`: Defines the directories where Agent Zero searches for knowledge files
289
-- **Rate Limiting:** Control API usage with `rate_limit_seconds` and `rate_limit_requests`
290
-- **Docker and SSH:** Configure execution environment settings
291
-
292
-### Adding Custom Components
293
-
294
-#### Custom Prompts
295
-1. Create directory in `prompts/` (e.g., `my-custom-prompts`)
296
-2. Copy and modify needed files from `prompts/default/`
297
-3. Agent Zero will merge your custom files with the default ones
298
-4. Select your custom prompts in the Settings page
299
-
300
-#### Adding Instruments
301
-1. Create folder in `instruments/custom` (no spaces in name)
302
-2. Add `.md` description file for the interface
303
-3. Add `.sh` script (or other executable) for implementation
304
-4. The agent will automatically detect and use the instrument
305
-
306
-#### Adding Tools
307
-1. Create `agent.system.tool.$TOOL_NAME.md` in `prompts/$SUBDIR`
308
-2. Add reference in `agent.system.tools.md`
309
-3. If needed, implement tool class in `python/tools` using `Tool` base class
310
-4. Follow existing patterns for consistency
311
-
304
#### Adding Extensions
305
1. Create Python file in appropriate `python/extensions` subfolder
306
2. Follow naming convention for execution order (start with number)
docs/installation.md
+17
-6
@@ -4,10 +4,22 @@
4
5
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).
6
7
-### Maybe you're looking for this? 👉[How to update Agent Zero](#how-to-update-agent-zero)
7
+### Need updates from v0.7? 👉[How to update Agent Zero](#how-to-update-agent-zero)
8
9
## Windows, macOS and Linux Setup Guide
10
11
+### Prerequisites
12
+
13
+| Component | Minimum | Recommended |
14
+|-----------|---------|-------------|
15
+| RAM | 4GB | 8GB |
16
+| Storage | 10GB | 10GB |
17
+| CPU | 2 cores | 4 cores |
18
+| Docker | Required | Required |
19
+| Internet | Optional* | Required |
20
+
21
+Note*: Offline operation requires prompt adjustments
22
+
23
1. **Install Docker Desktop:**
24
- Docker Desktop provides the runtime environment for Agent Zero, ensuring consistent behavior and security across platforms
25
- The entire framework runs within a Docker container, providing isolation and easy deployment
@@ -290,7 +302,7 @@ Agent Zero's Web UI is accessible from any device on your network through the Do
302
303
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).
304
293
-### How to update Agent Zero
305
+# How to update Agent Zero
306
307
1. **If you come from the previous version of Agent Zero (pre-0.7.1):**
308
- Your data is safely stored across various directories and files inside the Agent Zero folder.
@@ -310,19 +322,18 @@ For developers or users who need to run Agent Zero directly on their system,see
322
> Make sure to use the same embedding model you were using before, otherwise
323
> you will have to re-index all of Agent Zero's memory, therefore deleting all
324
> your custom knowledge and memory.
313
-
314
-> [!NOTE]
325
+>
326
> If you have issues loading your settings, you can try to delete the `/tmp/settings.json`
327
> file and let Agent Zero generate a new one.
328
329
2. **Update Process (Docker Desktop)**
330
- Go to Docker Desktop and stop the container from the "Containers" tab
331
- Right-click and select "Remove" to remove the container
321
-- Go to "Images" tab and remove the `frdel/agent-zero-run` image
332
+- Go to "Images" tab and remove the `frdel/agent-zero-run` image or click the three dots to pull the difference and update the Docker image.
333
334
335
325
-- Search and pull the new image
336
+- Search and pull the new image if you chose to remove it
337
- Run the new container with the same volume settings as the old one
338
339
> [!IMPORTANT]
docs/res/new_vid.jpg
Binary files a/docs/res/new_vid.jpg and b/docs/res/new_vid.jpg differ
docs/res/physics-2.png
Binary files a/docs/res/physics-2.png and b/docs/res/physics-2.png differ
docs/res/prompts.png
Binary files /dev/null and b/docs/res/prompts.png differ
docs/res/settings-page-ui.png
Binary files /dev/null and b/docs/res/settings-page-ui.png differ
docs/res/ui-screen-2.png
Binary files /dev/null and b/docs/res/ui-screen-2.png differ
docs/res/ui_chat_management.png
Binary files a/docs/res/ui_chat_management.png and b/docs/res/ui_chat_management.png differ
docs/res/web-ui.mp4
Binary files a/docs/res/web-ui.mp4 and b/docs/res/web-ui.mp4 differ
docs/troubleshooting.md
+3
-3
@@ -33,12 +33,12 @@ Extending Agent Zero to interact with external APIs is possible by creating cust
33
## Troubleshooting
34
35
**Installation**
36
-- **Docker Issues:** If Docker containers fail to start or Agent Zero can't connect to Docker, 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.
36
+- **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.
37
38
**Usage**
39
40
-- **Terminal commands not executing:** If using Docker for code execution, ensure the Docker container is running and properly configured. Check SSH settings if applicable. Check if the Docker image is updated by removing it from Docker Desktop app, and subsequently prompting Agent Zero to `run an Hello World in Python`.
40
+- **Terminal commands not executing:** Ensure the Docker container is running and properly configured. Check SSH settings if applicable. Check if the Docker image is updated by removing it from Docker Desktop app, and subsequently pulling it again.
41
42
* **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.
43
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.
\ No newline at end of file
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
knowledge/default/main/about/github_readme.md
+132
-80
@@ -1,132 +1,184 @@
1
-# Agent Zero
1
+<div align="center">
2
+
3
+
4
+
5
+### A dynamic, organic, and fully transparent open-source AI framework.
6
+
7
+[Installation](./docs/installation.md) •
8
+[How to update](./docs/installation.md#how-to-update-agent-zero) •
9
+[Documentation](./docs/README.md) •
10
+[Usage](./docs/usage.md)
11
12
[](https://www.skool.com/agent-zero) [](https://discord.gg/B8KZKNsPpj) [](https://www.youtube.com/@AgentZeroFW) [](https://www.linkedin.com/in/jan-tomasek/) [](https://x.com/JanTomasekDev)
13
14
+</div>
15
6
-[](https://www.youtube.com/watch?v=U_Gl0NPalKA)
16
+https://github.com/user-attachments/assets/c168759d-57d8-4b43-b62a-1026afcf52e6
17
+
18
+## A personal agentic framework that grows and learns with you
19
8
-**Personal and organic AI framework**
20
- Agent Zero is not a predefined agentic framework. It is designed to be dynamic, organically growing, and learning as you use it.
10
-- Agent Zero is fully transparent, readable, comprehensible, customizable and interactive.
21
+- Agent Zero is fully transparent, readable, comprehensible, customizable, and interactive.
22
- Agent Zero uses the computer as a tool to accomplish its (your) tasks.
23
13
-## Now fully Dockerized, fully UI, with TTS and STT:
14
-
24
+# 💡 Key Features
25
+
26
+1. **General-purpose Assistant**
27
16
-## Key concepts
17
-1. **General-purpose assistant**
28
- Agent Zero is not pre-programmed for specific tasks (but can be). It is meant to be a general-purpose personal assistant. Give it a task, and it will gather information, execute commands and code, cooperate with other agent instances, and do its best to accomplish it.
29
- It has a persistent memory, allowing it to memorize previous solutions, code, facts, instructions, etc., to solve tasks faster and more reliably in the future.
30
21
-2. **Computer as a tool**
31
+
32
+
33
+2. **Computer as a Tool**
34
+
35
- Agent Zero uses the operating system as a tool to accomplish its tasks. It has no single-purpose tools pre-programmed. Instead, it can write its own code and use the terminal to create and use its own tools as needed.
36
- The only default tools in its arsenal are online search, memory features, communication (with the user and other agents), and code/terminal execution. Everything else is created by the agent itself or can be extended by the user.
37
- Tool usage functionality has been developed from scratch to be the most compatible and reliable, even with very small models.
38
+- **Default Tools:** Agent Zero includes tools like knowledge, webpage content, code execution, and communication.
39
+- **Creating Custom Tools:** Extend Agent Zero's functionality by creating your own custom tools.
40
+- **Instruments:** Instruments are a new type of tool that allow you to create custom functions and procedures that can be called by Agent Zero.
41
26
-* **Default Tools:** Agent Zero includes tools like knowledge, webpage content, code execution, and communication.
27
-* **Creating Custom Tools:** Extend Agent Zero's functionality by creating your own custom tools.
28
-* **Instruments:** Instruments are a new type of tool that allow you to create custom functions and procedures that can be called by Agent Zero.
42
+3. **Multi-agent Cooperation**
43
30
-3. **Multi-agent cooperation**
44
- Every agent has a superior agent giving it tasks and instructions. Every agent then reports back to its superior.
45
- In the case of the first agent in the chain (Agent 0), the superior is the human user; the agent sees no difference.
46
- Every agent can create its subordinate agent to help break down and solve subtasks. This helps all agents keep their context clean and focused.
47
35
-4. **Completely customizable and extensible**
48
+
49
+
50
+
51
+4. **Completely Customizable and Extensible**
52
+
53
- Almost nothing in this framework is hard-coded. Nothing is hidden. Everything can be extended or changed by the user.
54
- The whole behavior is defined by a system prompt in the **prompts/default/agent.system.md** file. Change this prompt and change the framework dramatically.
55
- The framework does not guide or limit the agent in any way. There are no hard-coded rails that agents have to follow.
39
-- Every prompt, every small message template sent to the agent in its communication loop, can be found in the **prompts/** folder and changed.
56
+- Every prompt, every small message template sent to the agent in its communication loop can be found in the **prompts/** folder and changed.
57
- Every default tool can be found in the **python/tools/** folder and changed or copied to create new predefined tools.
41
-- Of course, it is open-source (except for some tools like Perplexity, but that will be replaced with an open-source alternative as well in the future).
58
43
-5. **Communication is key**
59
+
60
+
61
+5. **Communication is Key**
62
+
63
- Give your agent a proper system prompt and instructions, and it can do miracles.
64
- Agents can communicate with their superiors and subordinates, asking questions, giving instructions, and providing guidance. Instruct your agents in the system prompt on how to communicate effectively.
65
- The terminal interface is real-time streamed and interactive. You can stop and intervene at any point. If you see your agent heading in the wrong direction, just stop and tell it right away.
66
- There is a lot of freedom in this framework. You can instruct your agents to regularly report back to superiors asking for permission to continue. You can instruct them to use point-scoring systems when deciding when to delegate subtasks. Superiors can double-check subordinates' results and dispute. The possibilities are endless.
67
49
-
68
+## 🚀 Things you can build with Agent Zero
69
51
-## Nice features to have
52
-- Output is very clean, colorful, readable and interactive; nothing is hidden.
53
-- The same colorful output you see in the terminal is automatically saved to HTML file in **logs/** folder for every session.
54
-- Agent output is streamed in real-time, allowing the user to read along and intervene at any time.
55
-- No coding is required, only prompting and communication skills.
56
-- With a solid system prompt, the framework is reliable even with small models, including precise tool usage.
70
+- **Development Projects** - `"Create a React dashboard with real-time data visualization"`
71
+
72
+- **Data Analysis** - `"Analyze last quarter's NVIDIA sales data and create trend reports"`
73
+
74
+- **Content Creation** - `"Write a technical blog post about microservices"`
75
+
76
+- **System Admin** - `"Set up a monitoring system for our web servers"`
77
+
78
+- **Research** - `"Gather and summarize five recent AI papers about CoT prompting"`
79
+
80
+# ⚙️ Installation
81
+
82
+Click to open a video to learn how to install Agent Zero:
83
+
84
+[](https://www.youtube.com/watch?v=cHDCCSr1YRI&t=24s)
85
58
-
86
+A detailed setup guide for Windows, macOS, and Linux with a video can be found in the Agent Zero Documentation at [this page](./docs/installation.md).
87
60
-## Keep in mind
61
-1. **Agent Zero can be dangerous!**
62
-With proper instruction, Agent Zero is capable of many things, even potentially dangerous to your computer, data, or accounts. Always run Agent Zero in an isolated environment (like the one provided with Docker) and be careful what you wish for.
88
+### ⚡ Quick Start
89
64
-2. **Agent Zero is not pre-programmed; it is prompt-based.**
65
-The whole framework contains only a minimal amount of code and does not guide the agent in any way.
66
-Everything lies in the system prompt in the **prompts/** folder. Here you can rewrite the whole framework behavior to your needs.
67
-If your agent fails to communicate properly, use tools, reason, use memory, find answers - just instruct it better.
90
+```bash
91
+# Pull and run with Docker
92
69
-3. **If you cannot provide the ideal environment, let your agent know.**
70
-Agent Zero is made to be used in an isolated virtual environment (for safety) with some tools preinstalled and configured.
71
-If you cannot provide all the necessary conditions or API keys, just change the system prompt and tell your agent what operating system and tools are at its disposal. Nothing is hard-coded; if you do not tell your agent about a certain tool, it will not know about it and will not try to use it.
93
+docker pull frdel/agent-zero-run
94
+docker run -p 50001:80 frdel/agent-zero-run
95
73
-[](https://www.youtube.com/watch?v=_Pionjv4hGc)
96
+# Visit http://localhost:50001 to start
97
+```
98
75
-## Known problems
76
-1. The system prompt sucks. You can do better. If you do, help me please :)
77
-2. The communication between agents and terminal in Docker Container via SSH can sometimes break and stop producing outputs. Sometimes it is because the agent runs something like "server.serve_forever()" which causes the terminal to hang, sometimes a random error can occur. Restarting the agent and/or the Docker container helps.
78
-3. The agent can break his operating system. Sometimes the agent can deactivate virtual environment, uninstall packages, change config etc. Again, removing the Docker container and cleaning up the **work_dir/** is enough to fix that.
99
+- Developers and contributors: download the full binaries for your system from the [releases page](https://github.com/frdel/agent-zero/releases) and then follow the instructions [provided here](./docs/installation.md#in-depth-guide-for-full-binaries-installation).
100
80
-## Ideal environment
81
-- **Docker container**: The perfect environment to run Agent Zero is the built-in Docker container. The agent can download the image **frdel/agent-zero-exe** on its own and start the container, you only need to have Docker running (like the Docker Desktop application).
82
-- **Python**: Python has to be installed on the system to run the framework.
83
-- **Internet access**: The agent will need internet access to use its online knowledge tool and execute commands and scripts requiring a connection. If you do not need your agent to be online, you can alter its prompts in the **prompts/** folder and make it fully local.
101
+## 🐳 Fully Dockerized, with Speech-to-Text and TTS
102
+
103
+
104
+
105
+- Customizable settings allow users to tailor the agent's behavior and responses to their needs.
106
+- The Web UI output is very clean, fluid, colorful, readable, and interactive; nothing is hidden.
107
+- You can load or save chats directly within the Web UI.
108
+- The same output you see in the terminal is automatically saved to an HTML file in **logs/** folder for every session.
109
110
111
87
-## Setup
88
-A detailed setup guide for Windows, macOS and Linux with a video can be found in the new Agent Zero Documentation at [this page](docs/installation.md#windows-macos-and-linux-setup-guide).
112
+- Agent output is streamed in real-time, allowing users to read along and intervene at any time.
113
+- No coding is required; only prompting and communication skills are necessary.
114
+- With a solid system prompt, the framework is reliable even with small models, including precise tool usage.
115
90
-You can download the executable for your system from the [releases page](https://github.com/frdel/agent-zero/releases).
116
+## 👀 Keep in Mind
117
92
-## Consult the Documentation
93
-The documentation dives deep into the framework and its features. It is a good place to start if you are new to Agent Zero. Click [here](docs/README.md) to see the Documentation.
118
+1. **Agent Zero Can Be Dangerous!**
119
95
-## Coming up
96
-- **User interaction refinements**
97
-- **Browser use and RAG tools**
120
+- With proper instruction, Agent Zero is capable of many things, even potentially dangerous actions concerning your computer, data, or accounts. Always run Agent Zero in an isolated environment (like Docker) and be careful what you wish for.
121
99
-### Changelog [since version 0.7]
122
+2. **Agent Zero Is Not Pre-programmed; It Is Prompt-based.**
123
101
-#### v0.7.1
102
-- **Preinstalled binaries and bundler scripts**
103
-- **Persistent Chats** - Serialized to /tmp/chats and automatically loaded in run_ui.py on startup
104
-- **Documentation stack merged into the repository**
105
-- **Bug Fixes**
124
+- The whole framework contains only a minimal amount of code and does not guide the agent in any way. Everything lies in the system prompt located in the **prompts/** folder.
125
+
126
+3. **If You Cannot Provide the Ideal Environment, Let Your Agent Know.**
127
+
128
+- Agent Zero is made to be used in an isolated virtual environment (for safety) with some tools preinstalled and configured.
129
+
130
+### 📌 Known Problems
131
+
132
+1. The system prompt may need improvements; contributions are welcome!
133
+2. The agent may inadvertently alter its operating environment; cleaning up the `work_dir` often fixes this.
134
+3. Agents might loop in multi-agentic interactions, leading to unexpected behaviors.
135
+
136
+## 📚 Read the Documentation
137
107
-> [!NOTE]
108
-> **Changes to frdel/agent-zero Docker image since v0.8:**
109
-> - In version 0.8, the Docker image has changed to frdel/agent-zero-run using the new Dockerfile.
138
+| Page | Description |
139
+|-------|-------------|
140
+| [Installation](./docs/installation.md) | Installation, setup and configuration |
141
+| [Usage](./docs/usage.md) | Basic and advanced usage |
142
+| [Architecture](./docs/architecture.md) | System design and components |
143
+| [Contributing](./docs/contributing.md) | How to contribute |
144
+| [Troubleshooting](./docs/troubleshooting.md) | Common issues and their solutions |
145
111
-#### v0.8
112
-- **Docker runtime**
113
-- **New messages history and summarization system**
114
-- **Agent behavior change and management**
146
+## 🎯 Changelog
147
+
148
+### Coming soon
149
+
150
+- **User Interaction Refinements**
151
+- **Browser Use and RAG Tools**
152
+
153
+> [!IMPORTANT]
154
+>
155
+>**Changes to frdel/agent-zero Docker image since v0.7:**
156
+>
157
+> The new Docker image `frdel/agent-zero-run` provides the new unified environment.
158
+
159
+### v0.8
160
+
161
+- **Docker Runtime**
162
+- **New Messages History and Summarization System**
163
+- **Agent Behavior Change and Management**
164
- **Text-to-Speech (TTS) and Speech-to-Text (STT)**
116
-- **Settings page in Web UI**
117
-- **SearXNG integration replacing Perplexity + DuckDuckGo knowledge_tool**
118
-- **File browser functionality**
119
-- **KaTeX math visualization support**
120
-- **In-chat file attachments**
121
-
122
-#### v0.7
123
-- **Automatic memory**
124
-- **UI improvements**
165
+- **Settings Page in Web UI**
166
+- **SearXNG Integration Replacing Perplexity + DuckDuckGo**
167
+- **File Browser Functionality**
168
+- **KaTeX Math Visualization Support**
169
+- **In-chat File Attachments**
170
+
171
+### v0.7
172
+
173
+- **Automatic Memory**
174
+- **UI Improvements**
175
- **Instruments**
126
-- **Extensions framework**
127
-- **Reflection prompts**
128
-- **Bugfixes**
176
+- **Extensions Framework**
177
+- **Reflection Prompts**
178
+- **Bug Fixes**
179
+
180
+## 🤝 Community and Support
181
130
-> [!NOTE]
131
-> **Changes to launch files since v0.7:**
132
-> - the Docker image has been changed to frdel/agent-zero-run from the legacy installation process.
\ No newline at end of file
182
+- [Join our Discord](https://discord.gg/B8KZKNsPpj) for live discussions or [visit our Skool Community](https://www.skool.com/agent-zero).
183
+- [Follow our YouTube channel](https://www.youtube.com/@AgentZeroFW) for hands-on explanations and tutorials
184
+- [Report Issues](https://github.com/frdel/agent-zero/issues) for bug fixes and features
knowledge/default/main/about/installation.md
+82
-54
@@ -4,10 +4,22 @@
4
5
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).
6
7
-### Maybe you're looking for this? 👉[How to update Agent Zero](#how-to-update-agent-zero)
7
+### Need updates from v0.7? 👉[How to update Agent Zero](#how-to-update-agent-zero)
8
9
## Windows, macOS and Linux Setup Guide
10
11
+### Prerequisites
12
+
13
+| Component | Minimum | Recommended |
14
+|-----------|---------|-------------|
15
+| RAM | 4GB | 8GB |
16
+| Storage | 10GB | 10GB |
17
+| CPU | 2 cores | 4 cores |
18
+| Docker | Required | Required |
19
+| Internet | Optional* | Required |
20
+
21
+Note*: Offline operation requires prompt adjustments
22
+
23
1. **Install Docker Desktop:**
24
- Docker Desktop provides the runtime environment for Agent Zero, ensuring consistent behavior and security across platforms
25
- The entire framework runs within a Docker container, providing isolation and easy deployment
@@ -167,7 +179,8 @@ Agent Zero provides a comprehensive settings interface to customize various aspe
179
- **Silence Settings:** Configure silence threshold, duration, and timeout parameters for voice input
180
181
### API Keys
170
-- Configure API keys for various service providers
182
+- Configure API keys for various service providers directly within the Web UI
183
+- Click `Save` to confirm your settings
184
185
### Authentication
186
- **UI Login:** Set username for web interface access
@@ -195,7 +208,7 @@ The Settings page is the control center for selecting the Large Language Models
208
209
**How to Change:**
210
1. Open Settings page in the Web UI.
198
-2. Change the LLM for each role (Chat model, Utility model, Embedding model).
211
+2. Choose the provider for the LLM for each role (Chat model, Utility model, Embedding model) and write the model name.
212
3. Click "Save" to apply the changes.
213
214
## Important Considerations
@@ -205,6 +218,66 @@ The Settings page is the control center for selecting the Large Language Models
218
> requires clearing the `memory` folder to avoid errors, as the embeddings can't be
219
> mixed in the vector database. Note that this will DELETE ALL of Agent Zero's memory.
220
221
+## Installing and Using Ollama (Local Models)
222
+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:
223
+
224
+#### First step: installation
225
+**On Windows:**
226
+
227
+Download Ollama from the official website and install it on your machine.
228
+
229
+<button>[Download Ollama Setup](https://ollama.com/download/OllamaSetup.exe)</button>
230
+
231
+**On macOS:**
232
+```
233
+brew install ollama
234
+```
235
+Otherwise choose macOS installer from the [official website](https://ollama.com/).
236
+
237
+**On Linux:**
238
+```bash
239
+curl -fsSL https://ollama.com/install.sh | sh
240
+```
241
+
242
+**Finding Model Names:**
243
+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).
244
+
245
+#### Second step: pulling the model
246
+**On Windows, macOS, and Linux:**
247
+```
248
+ollama pull <model-name>
249
+```
250
+
251
+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`.
252
+
253
+2. A CLI message should confirm the model download on your system
254
+
255
+#### Selecting your model within Agent Zero
256
+1. Once you've downloaded your model(s), you must select it in the Settings page of the GUI.
257
+
258
+2. Within the Chat model, Utility model, or Embedding model section, choose Ollama as provider.
259
+
260
+3. Write your model code as expected by Ollama, in the format `llama3.2` or `qwen2.5:7b`
261
+
262
+4. Click `Save` to confirm your settings.
263
+
264
+
265
+
266
+#### Managing your downloaded models
267
+Once you've downloaded some models, you might want to check which ones you have available or remove any you no longer need.
268
+
269
+- **Listing downloaded models:**
270
+ To see a list of all the models you've downloaded, use the command:
271
+ ```
272
+ ollama list
273
+ ```
274
+- **Removing a model:**
275
+ If you need to remove a downloaded model, you can use the `ollama rm` command followed by the model name:
276
+ ```
277
+ ollama rm <model-name>
278
+ ```
279
+
280
+
281
- 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.
282
283
## Using Agent Zero on your mobile device
@@ -229,7 +302,7 @@ Agent Zero's Web UI is accessible from any device on your network through the Do
302
303
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).
304
232
-### How to update Agent Zero
305
+# How to update Agent Zero
306
307
1. **If you come from the previous version of Agent Zero (pre-0.7.1):**
308
- Your data is safely stored across various directories and files inside the Agent Zero folder.
@@ -249,19 +322,18 @@ For developers or users who need to run Agent Zero directly on their system,see
322
> Make sure to use the same embedding model you were using before, otherwise
323
> you will have to re-index all of Agent Zero's memory, therefore deleting all
324
> your custom knowledge and memory.
252
-
253
-> [!NOTE]
325
+>
326
> If you have issues loading your settings, you can try to delete the `/tmp/settings.json`
327
> file and let Agent Zero generate a new one.
328
329
2. **Update Process (Docker Desktop)**
330
- Go to Docker Desktop and stop the container from the "Containers" tab
331
- Right-click and select "Remove" to remove the container
260
-- Go to "Images" tab and remove the `frdel/agent-zero-run` image
332
+- Go to "Images" tab and remove the `frdel/agent-zero-run` image or click the three dots to pull the difference and update the Docker image.
333
334
335
264
-- Search and pull the new image
336
+- Search and pull the new image if you chose to remove it
337
- Run the new container with the same volume settings as the old one
338
339
> [!IMPORTANT]
@@ -290,7 +362,8 @@ For developers or users who need to run Agent Zero directly on their system,see
362
> ```
363
364
3. **Full Binaries**
293
-- Using Git/GitHub: Pull the latest version of the Agent Zero repository with. 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.
365
+- Using Git/GitHub: Pull the latest version of the Agent Zero repository.
366
+- 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.
367
368
> [!WARNING]
369
> - If you update manually, beware: save your .env file with the API keys, and look for new dependencies in requirements.txt.
@@ -493,48 +566,3 @@ After following the instructions for your specific operating system, you should
566
567
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/Z2tun2N3) community for assistance.
568
496
-## Installing and Using Ollama (Local Models)
497
-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:
498
-
499
-#### First step: installation
500
-**On Windows:**
501
-
502
-Download Ollama from the official website and install it on your machine.
503
-
504
-<button>[Download Ollama Setup](https://ollama.com/download/OllamaSetup.exe)</button>
505
-
506
-**On macOS:**
507
-```
508
-brew install ollama
509
-```
510
-Otherwise choose macOS installer from the [official website](https://ollama.com/).
511
-
512
-**On Linux:**
513
-```bash
514
-curl -fsSL https://ollama.com/install.sh | sh
515
-```
516
-
517
-**Finding Model Names:**
518
-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).
519
-
520
-#### Second step: pulling the model
521
-**On Windows, macOS, and Linux:**
522
-```
523
-ollama pull <model-name>
524
-```
525
-
526
-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`.
527
-
528
-#### Managing your downloaded models
529
-Once you've downloaded some models, you might want to check which ones you have available or remove any you no longer need.
530
-
531
-- **Listing downloaded models:**
532
- To see a list of all the models you've downloaded, use the command:
533
- ```
534
- ollama list
535
- ```
536
-- **Removing a model:**
537
- If you need to remove a downloaded model, you can use the `ollama rm` command followed by the model name:
538
- ```
539
- ollama rm <model-name>
540
- ```
\ No newline at end of file