Documentation and updated README.md for v0.7

• First solid docs version (.md only)
• Your installation guide is fully incorporated in docs/installation.md
• Updated readme.md file for v0.7
• Changelog

README.md

@@ -3,15 +3,15 @@
 [![Join our Skool Community](https://img.shields.io/badge/Skool-Join%20our%20Community-4A90E2?style=for-the-badge&logo=skool&logoColor=white)](https://www.skool.com/agent-zero) [![Join our Discord](https://img.shields.io/badge/Discord-Join%20our%20server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/B8KZKNsPpj) [![Subscribe on YouTube](https://img.shields.io/badge/YouTube-Subscribe-red?style=for-the-badge&logo=youtube&logoColor=white)](https://www.youtube.com/@AgentZeroFW) [![Connect on LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-blue?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/jan-tomasek/) [![Follow on X.com](https://img.shields.io/badge/X.com-Follow-1DA1F2?style=for-the-badge&logo=x&logoColor=white)](https://x.com/JanTomasekDev)
 
 
-[![Intro Video](/docs/res/intro_vid.jpg)](https://www.youtube.com/watch?v=C9n8zFpaV3I)
+[![Intro Video](/docs/res/new_vid.jpg)](https://www.youtube.com/watch?v=U_Gl0NPalKA)
 
 **Personal and organic AI framework**
 - Agent Zero is not a predefined agentic framework. It is designed to be dynamic, organically growing, and learning as you use it.
 - Agent Zero is fully transparent, readable, comprehensible, customizable and interactive.
 - Agent Zero uses the computer as a tool to accomplish its (your) tasks.
 
-## Now with UI:
-![UI prototype](/docs/res/ui_screen1.png)
+## Now with Responsive UI and Progress Bar:
+![Web UI](/docs/res/win_webui.gif)
 
 ## Key concepts
 1. **General-purpose assistant**
@@ -51,6 +51,8 @@
 - No coding is required, only prompting and communication skills.
 - With a solid system prompt, the framework is reliable even with small models, including precise tool usage.
 
+![Agent 1 System Load](/docs/res/ui_screen1.png)
+
 ## Keep in mind
 1. **Agent Zero can be dangerous!**
 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 built in docker container) and be careful what you wish for.
@@ -81,9 +83,15 @@ If you cannot provide all the necessary conditions or API keys, just change the
 
 ## Setup
 
-A detailed setup guide with a video can be found here: [/docs/installation](https://github.com/frdel/agent-zero/tree/main/docs/installation). Scroll down to see the readme file.
+A detailed setup guide with a video can be found in /docs/installation.md. Open the [Documentation](docs/installation.md#in-depth-guide-for-windows-and-macos).
 
-> ⚠️ **Changes to launch files since v0.6:**  
-> main.py file has been replaced with run_ui.py (webui) and run_cli.py (terminal) launch files.
-> configuration has been moved to initialize.py for both webui and terminal launch files.
+### New in version 0.7
+> - UI Revamp
+> - Auto Memory
+> - Instruments
+> - Extensions Framework
+> - Reflection
 
+> ⚠️ **Changes to launch files since v0.6:**  
+> - main.py file has been replaced with run_ui.py (webui) and run_cli.py (terminal) launch files.
+> - configuration has been moved to initialize.py for both webui and terminal launch files.

docs/README.md

@@ -0,0 +1,107 @@
+![Agent Zero Logo](res/header.png)
+# Agent Zero Documentation
+To begin with Agent Zero, follow the links below for detailed guides on various topics:
+
+- **[Installation](installation.md):** Set up Agent Zero on your system.
+- **[Quick Start](quickstart.md):** Begin using Agent Zero with practical examples.
+- **[Usage Guide](usage.md):** Explore advanced features and capabilities.
+- **[Architecture Overview](architecture.md):** Understand the internal workings of the framework.
+- **[Contributing](contribution.md):** Learn how to contribute to the Agent Zero project.
+- **[Troubleshooting and FAQ](troubleshooting.md):** Find answers to common issues and questions.
+
+## Key Features
+- **Dynamic and Organic:** Evolves from past interactions.
+- **Transparent and Customizable:** Open framework for user modifications.
+- **Computer as a Tool:** Utilize your operating system's full capabilities.
+- **Multi-Agent Cooperation:** Hierarchical structure for task management.
+- **Persistent Memory:** Remembers past interactions for continuous learning.
+- **Safe Code Execution:** Sandboxed Docker container environment for secure code execution.
+- **Interactive Terminal Interface:** Real-time observation and intervention in a command-line interface.
+- **Web UI:** User-friendly interface for managing agents.
+
+### Your experience with Agent Zero starts now!
+
+- **Join the Community:** Join the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/Z2tun2N3) community to discuss ideas, ask questions, and collaborate with other contributors.
+- **Share your Work:** Share your Agent Zero creations, workflows and discoverings on our [Show and Tell](https://github.com/frdel/agent-zero/discussions/categories/show-and-tell) area on GitHub.
+- **Report Issues:** Use the GitHub issue tracker to report bugs or suggest new features.
+
+## Table of Contents
+
+- [Welcome to the Agent Zero Documentation](#agent-zero-documentation)
+  - [Key Features](#key-features)
+    - [Start your experience with Agent Zero](#your-experience-with-agent-zero-starts-now)
+  - [Table of Contents](#table-of-contents)
+- [Installation guide for Windows, MacOS and Linux](installation.md)
+  - [Windows Quick Start](installation.md#windows-quick-start)
+  - [macOS Quick Start](installation.md#macos-quick-start)
+  - [Linux Quick Start](installation.md#linux-quick-start)
+  - [In-Depth Guide for Windows and MacOS](installation.md#in-depth-guide-for-windows-and-macos)
+    - [1. Install Conda (miniconda)](installation.md#1-install-conda-miniconda)
+    - [2. Install Docker (Docker Desktop application)](installation.md#2-install-docker-docker-desktop-application)
+    - [3. Download Agent Zero](installation.md#3-download-agent-zero)
+    - [4. Set up Conda environment](installation.md#4-set-up-conda-environment)
+    - [5. Configure Agent Zero](installation.md#5-configure-agent-zero)
+    - [6. Run Agent Zero](installation.md#6-run-agent-zero)
+    - [Choosing Your LLMs](installation.md#choosing-your-llms)
+      - [Installing and Using Ollama](installation.md#installing-and-using-ollama)
+    - [How to update Agent Zero](installation.md#how-to-update-agent-zero)
+    - [Conclusion](installation.md#conclusion)
+- [Quick Start](quickstart.md)
+  - [Launching the Web UI](quickstart.md#launching-the-web-ui)
+  - [Running a Simple Task](quickstart.md#running-a-simple-task)
+  - [Example Interaction](quickstart.md#example-interaction)
+  - [Next Steps](quickstart.md#next-steps)
+- [Architecture Overview](architecture.md)
+  - [Core Components](architecture.md#core-components)
+  - [Agent Hierarchy and Communication](architecture.md#agent-hierarchy-and-communication)
+  - [Interaction Flow](architecture.md#interaction-flow)
+  - [Memory System](architecture.md#memory-system)
+  - [Knowledge](architecture.md#knowledge)
+  - [Prompts](architecture.md#prompts)
+  - [Extensions](architecture.md#extensions)
+    - [Structure of Extensions](architecture.md#structure-of-extensions)
+    - [Types of Default Extensions](architecture.md#types-of-default-extensions)
+  - [Key Files](architecture.md#key-files)
+  - [Directory Structure](architecture.md#directory-structure)
+  - [Customization](architecture.md#customization)
+    - [Custom Prompts](architecture.md#custom-prompts)
+      - [Changing the System Prompt Folder](architecture.md#changing-the-system-prompt-folder)
+      - [Editing Prompts](architecture.md#editing-prompts)
+    - [AgentConfig](architecture.md#agentconfig)
+    - [Adding Tools](architecture.md#adding-tools)
+    - [Adding Extensions](architecture.md#adding-extensions)
+    - [Adding Instruments](architecture.md#adding-instruments)
+    - [Important Considerations](architecture.md#important-considerations)
+- [Usage Guide](usage.md)
+  - [Tool Usage](usage.md#tool-usage)
+  - [Example: Web Search and Code Execution](usage.md#example-web-search-and-code-execution)
+  - [Memory Management](usage.md#memory-management)
+  - [Multi-Agent Cooperation](usage.md#multi-agent-cooperation)
+  - [Prompt Engineering](usage.md#prompt-engineering)
+  - [Agent Behavior](usage.md#agent-behavior)
+- [Contributing to Agent Zero](contribution.md)
+  - [Getting Started](contribution.md#getting-started)
+  - [Making Changes](contribution.md#making-changes)
+  - [Submitting a Pull Request](contribution.md#submitting-a-pull-request)
+  - [Documentation Stack](contribution.md#documentation-stack)
+- [Troubleshooting and FAQ](troubleshooting.md)
+  - [Frequently Asked Questions](troubleshooting.md#frequently-asked-questions)
+  - [Troubleshooting](troubleshooting.md#troubleshooting)
+    - [Installation](troubleshooting.md#installation)
+    - [Usage](troubleshooting.md#usage)
+
+## Changelog
+
+### v0.7
+- **Hybrid Memory System**: The memory system now operates on a hybrid model where part of the memory is managed automatically by the framework while users can also manually input information.
+- **UI Revamp**
+    - The chat interface is now fully responsive, has a progress bar and supports both light and dark themes.
+- **Instruments**: Users can create custom tools (instruments) using markdown files. These instruments execute commands within the Docker container and can be used to perform various tasks, such as downloading YouTube videos or executing scripts.
+- **Extensions Framework**
+    - A new extensions framework has been introduced to keep the main agent.py file clean and maintainable. This allows for better organization of code with various subfolders for different functionalities. Files within python/extensions folders are executed in alphabetical order, streamlining processes like memory recall and solution memorization.
+- **Reflection**
+    - The framework supports advanced AI concepts like Chain of Thought and reflection through customizable prompts. Users can choose between two reflection models: dianoia-small and dianoia-xl.
+
+### ⚠️ Changes to launch files since v0.6:
+- main.py file has been replaced with run_ui.py (webui) and run_cli.py (terminal) launch files.
+- configuration has been moved to initialize.py for both webui and terminal launch files.

docs/architecture.md

@@ -0,0 +1,164 @@
+# Architecture Overview
+Agent Zero is built on a flexible and modular architecture designed for extensibility and customization. This document outlines the key components and their interactions. This simplified diagram illustrates the hierarchical relationship between agents and their interaction with tools, prompts, memory, knowledge base and instruments. 
+
+![Agent Zero Architecture](res/arch-01.svg)
+
+The user or Agent 0 is at the top of the hierarchy, delegating tasks to subordinate agents, which can further delegate to other agents.  Each agent can utilize tools and access the shared assets (prompts, memory, knowledge, extensions and instruments) to perform its tasks.
+
+## Core Components
+Agent Zero's architecture revolves around the following key components:
+
+1. **Agents:** The core actors within the framework. Agents receive instructions, reason, make decisions, and utilize tools to achieve their objectives. Agents operate within a hierarchical structure, with superior agents delegating tasks to subordinate agents.
+
+2. **Tools:** Tools are functionalities that agents can leverage. These can include anything from web search and code execution to interacting with APIs or controlling external software. Agent Zero provides a mechanism for defining and integrating both built-in and custom tools.
+
+3. **Memory:** Agents have persistent memory that stores past experiences, knowledge, and information. This memory is used to inform decision-making and improve performance over time.
+
+4. **Prompts:** Prompts guide agent behavior and communication. The system prompt defines the agent's overall role and objectives, while message prompts structure the interaction and flow of information between agents and tools.
+
+5. **Knowledge:** Knowledge refers to the user-provided information and data that agents can leverage. This can include documents, databases, or any other relevant resources. Agents can retrieve and utilize this knowledge to answer questions, make decisions, and perform RAG-augmented tasks.
+
+6. **Instruments:** Instruments provide a way to add custom functionalities to Agent Zero. They can modify agent behavior introducing new procedures, call for tools, or scripts to integrate with other systems. Instruments scripts are run inside the Docker container.
+
+7. **Extensions:** Extensions are custom components that can be added to Agent Zero to enhance its capabilities. Extensions can include new message loops, custom memory management rules, or even more.
+
+8. **Docker Container:** Agent Zero execute code commands in a Docker container, which provides isolation and security. This ensures that agents can safely and securely interact with tools and external systems.
+
+## Agent Hierarchy and Communication
+Agent Zero employs a hierarchical agent structure, where a top-level agent (often the user) can delegate tasks to subordinate agents. This hierarchy allows for the efficient breakdown of complex tasks into smaller, more manageable sub-tasks.
+
+Communication flows between agents through messages, which are structured according to the prompt templates.  These messages typically include:
+
+| Argument | Description |
+| --- | --- |
+| `Thoughts:` | The agent's internal reasoning and planning process. |
+| `Tool name:` | The specific tool used by the agent. |
+| `Responses or queries:` | Results, feedback or queries from tools or other agents. |
+
+## Interaction Flow
+A typical interaction flow within Agent Zero might look like this:
+
+![Interaction Flow](res/flow-01.svg)
+
+1.  The user provides an instruction to Agent 0.
+2.  Agent 0 initializes VectorDB and access memory as needed.
+3.  Agent 0 analyzes the instruction and formulates a plan using `thoughts` argument, possibly involving the use of tools or the creation of sub-agents.
+4.  If necessary, Agent 0 delegates sub-tasks to subordinate agents.
+5.  Agents use tools to perform actions, both providing arguments and responses or queries.
+6.  Agents communicate results and feedback back up the hierarchy.
+7.  Agent 0 provides the final response to the user.
+
+## Memory System
+The memory system is a critical component of Agent Zero, enabling the agent to learn and adapt from past interactions. It operates on a hybrid model where part of the memory is managed automatically by the framework while users can also manually input and extract information.
+- **Memory Loading**: At the start of each session, relevant memories are automatically loaded and injected into the system prompt, allowing the agent to utilize past interactions effectively.
+- **Memory Structure**: The memory is categorized into four distinct areas:
+  - **Storage and retrieval** of user-provided information (e.g., names, API keys).
+  - **Fragments**: Contains pieces of information from previous conversations, updated automatically.
+  - **Solutions**: Stores successful solutions from past interactions for future reference.
+  - **Metadata**: Each memory entry includes metadata (IDs, timestamps), enabling efficient filtering and searching based on specific criteria.
+
+## Knowledge
+- **Knowledge Base:** Wiki, books, code documentation, and other documents can be added to the knowledge base. Agent Zero uses this information to answer questions and make decisions. The `/docs` folder, containing Agent Zero's documentation, is automatically added to the knowledge base.
+- **Custom Knowledge:** Users can add custom knowledge files to the `/knowledge/custom/main` directory. Agent Zero will automatically import these files, expanding its knowledge base. Supported file formats include `.txt`, `.pdf`, `.csv`, `.html`, `.json`, and `.md`. The list of supported file formats is yet to be expanded.
+
+## Prompts
+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.  
+
+**Key Prompt Files:**
+| Prompt File | Description |
+|---|---|
+| agent.system.main.role.md | Defines the agent's overall role. |
+| agent.system.main.communication.md | Specifies how the agent should communicate. |
+| agent.system.main.solving.md | Describes the agent's approach to problem-solving. |
+| agent.system.main.tips.md | Provides additional tips or guidance to the agent. |
+| agent.system.tools.md | Organizes and calls the individual tool prompt files. |
+| agent.system.tool.*.md | Individual tool prompt files (with * as the tool name). |
+
+You can customize any of these files.  Agent Zero will use the files in your custom `prompts_subdir` if they exist, otherwise, it will fall back to the files in `prompts/default`.
+
+## Extensions
+- Extensions are a powerful feature of Agent Zero, designed to keep the main codebase clean and organized while allowing for greater flexibility and modularity. Here’s a detailed exploration of the extensions feature:
+- The extensions framework allows users to create modular components that can be integrated into the main system.
+### Structure of Extensions
+Extensions can be found in `python/extensions` directory.
+- **Folder Organization**: The extensions are stored in a designated subfolder within the Python directory. This includes various subfolders that correspond to different aspects of the agent's message loop.
+- **Execution Order**: Files within these subfolders are executed in alphabetical order, ensuring predictable behavior when multiple extensions are utilized.
+### Types of Default Extensions
+- **Message Loop Prompts**: These extensions handle the construction of system messages and maintain message history, ensuring that the agent has access to relevant context during interactions.
+- **Memory Management**: Extensions can also manage memory recall and solution memorization, allowing for dynamic updates based on user interactions.
+- **Custom Extensions**: Users can create custom extensions to add new functionalities or modify existing ones.
+
+If you believe the extension could bring value to the community, consider contributing it to the main repository by making a pull request.
+
+## Key Files
+| File | Description |
+| --- | --- |
+| `agent.py` | Contains the core logic for the `AgentConfig` class, which defines the `prompts_subdir`, rate limits for models, and more, though `AgentConfig` class must be edited through `initialize.py` file. |
+| `example.env` | Contains environment variables for configuring API keys and other settings of Agent Zero. |
+| `initialize.py` | Defines Agent Zero's core configuration, including model choices and other critical settings. This is the central point for customizing the framework's behavior. See [Choosing Your LLMs](installation.md#choosing-your-llms) for more details. |
+| `models.py` | Defines the `get_provider_chat` or `..._embedding` functions, which specifies the model provider, model name, and other parameters for adding support for new models or custom models. |
+| `requirements.txt` | Lists the dependencies used by pip to install the necessary packages when you setup Agent Zero. |
+| `run_cli.py` | Starts the Agent Zero CLI. |
+| `run_ui.py` | Starts the Agent Zero Web UI. |
+
+## Directory Structure
+| Directory | Description |
+| --- | --- |
+| `docker/` | Dockerfiles and related files for building Docker image |
+| `docs/` | Quickstart and installation guide |
+| `instruments/` | Instruments for interacting with the environment |
+| `knowledge/` | Knowledge base for storing and retrieving information |
+| `logs/` | HTML chat log files |
+| `memory/` | Memory storage for storing and retrieving information |
+| `prompts/` | System and tools prompts folders |
+| `python/` | Python code for the main system and tools |
+| `python/extensions/` | Extensions for the main system |
+| `tests/` | Unit tests for the project |
+| `tmp/` | Temporary files |
+| `webui/` | Web UI |
+| `work_dir/` | Working directory for the Agent |
+
+# Customization
+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.
+
+## Custom Prompts
+### Changing the System Prompt Folder
+1. Create a new directory inside the `prompts` directory (e.g., `prompts/my-custom-prompts`).
+2. When copying the contents of the `prompts/default` directory into your new directory, take into account that Agent Zero will merge the contents of the `default` directory with the contents of your custom directory. This means that you can copy only the files you want to modify, and the rest will be taken from the `default` directory.
+3. Modify the prompts in your custom directory as needed.
+4. In `initialize.py`, update the `prompts_subdir` parameter in `AgentConfig` to point to your custom directory:
+   ```python
+   config = AgentConfig(..., prompts_subdir="my-custom-prompts", ...)
+   ```
+
+## AgentConfig
+The `AgentConfig` class is present in both `agent.py` and `initialize.py` and provides further customization options. You must edit `AgentConfig` class through `initialize.py` file. Here are some of the key parameters you can configure:
+
+- `prompts_subdir`: Specifies the directory containing your custom prompts.  This allows you to create and manage different sets of prompts for different use cases.  (See *Prompt Customization* below).
+
+- `knowledge_subdirs`: Defines the directories where Agent Zero searches for knowledge files.
+
+- **Rate Limiting:** Control API usage and prevent rate limit errors by setting `rate_limit_seconds` and `rate_limit_requests`.
+
+- **Docker and SSH:** Configure Docker and SSH settings for code execution, if needed.
+
+## Adding Tools
+While good prompting can often achieve the desired behavior, sometimes custom tools are necessary.
+
+1. Create a new file named `agent.system.tool.$TOOL_NAME.md` inside your `prompts/$SUBDIR` directory. This file will contain the prompt for your custom tool.
+2. Open `agent.system.tools.md` and add a reference to your new tool prompt.
+3. If your tool requires specific code or external API calls, create a Python file for it in the `python/tools` directory, implementing the `Tool` base class.
+
+## Adding Extensions
+To create a new extension, follow these steps:
+1. Create a new Python file in the appropriate subfolder within the `python/extensions` directory.
+2. Implement the desired functionality within the file, following the existing structure and naming conventions, that implies following the alphabetical order of execution of the extensions in the subfolder.
+3. Your desired extension's name has to start with a number to ensure it is executed before or after an already existing extension based on your needs.
+4. Ensure that the extension is compatible with the main system and does not introduce any conflicts or errors.
+
+## Adding Instruments
+Instruments allow you to add predefined actions or workflows to Agent Zero without adding to the token count of the system prompt.
+
+1. Create a new folder with the name of your instrument (without spaces) inside `instruments/custom`.
+2. Inside this folder, create a `.md` file with the description of the instrument and a `.sh` script (or other executable) with the actual implementation. The `.md` file acts as the interface for the Agent to interact with the Instrument, and the agent will call the `.sh` with the given user arguments. The agent will parse the `.md` file, using the Instrument's name, description, and arguments described in it.
+3. The agent will automatically detect and use your custom instruments.

docs/contribution.md

@@ -0,0 +1,29 @@
+# Contributing to Agent Zero
+
+Contributions to improve Agent Zero are very welcome!  This guide outlines how to contribute code, documentation, or other improvements.
+
+## Getting Started
+
+1. **Fork the Repository:** Fork the Agent Zero repository on GitHub.
+2. **Clone Your Fork:** Clone your forked repository to your local machine.
+3. **Create a Branch:** Create a new branch for your changes. Use a descriptive name that reflects the purpose of your contribution (e.g., `fix-memory-leak`, `add-search-tool`, `improve-docs`).
+
+## Making Changes
+
+* **Code Style:** Follow the existing code style.  Agent Zero generally follows PEP 8 conventions.
+* **Testing:** Write unit tests for new features.  Agent Zero uses the `pytest` framework. Ensure your changes pass all existing and new tests.
+* **Documentation:**  Update the documentation if your changes affect user-facing functionality.  The documentation is written in Markdown.
+* **Commit Messages:**  Write clear and concise commit messages that explain the purpose of your changes.
+
+## Submitting a Pull Request
+
+1. **Push Your Branch:** Push your branch to your forked repository on GitHub.
+2. **Create a Pull Request:** Create a pull request from your branch to the appropriate branch in the main Agent Zero repository.
+   * **For new features, refactoring, or significant changes:** Target the `testing` branch.
+   * **For bug fixes and patches:** Target the `development` branch.
+3. **Provide Details:** In your pull request description, clearly explain the purpose and scope of your changes. Include relevant context, test results, and any other information that might be helpful for reviewers.
+4. **Address Feedback:**  Be responsive to feedback from the community. We love changes, but we also love to discuss them!
+
+## Documentation Stack
+
+- The documentation is built using Markdown. We appreciate your contributions and look forward to improving Agent Zero for everyone's benefit.

docs/{installation/README.md → installation.md}

@@ -1,95 +1,162 @@
-# How to install Agent Zero on Windows and MacOS
+# Installation guide for Windows, macOS and Linux
+
+[![Video](res/setup/thumb_play.png)](https://youtu.be/8H7mFsvxKYQ)
+
+The following guide provides both quick start instructions for the full installation of Agent Zero on various operating systems and in-depth guides for Windows and macOS with screenshots.
+
+## You were looking for this? [How to update Agent Zero](#how-to-update-agent-zero)
+
+<details>
+<summary><h2>Windows Quick Start</h2></summary>
+
+1. **Install Anaconda or Miniconda:** Download and install the appropriate version for your system from [here](https://docs.anaconda.com/anaconda/install/). Miniconda is recommended for a minimal installation.
+2. **Create an Environment:** Open Anaconda Navigator (or use the `conda` command), create an environment named `agent-zero`, and select Python 3.12.
+3. **Install Docker Desktop:** Download and install Docker Desktop from [here](https://www.docker.com/products/docker-desktop/).
+4. **Download Agent Zero:** Download the latest release zip from the [GitHub releases page](https://github.com/frdel/agent-zero/releases) and extract it.
+5. **Configure API Keys:** Duplicate `example.env`, rename it to `.env`, and add your API keys.
+6. **Install Requirements:** Activate your `agent-zero` environment, open a terminal in the Agent Zero directory, and run: `pip install -r requirements.txt`
+7. **Run Agent Zero (Web UI):** Execute `python run_ui.py` in your terminal.
+8. **Access the Web UI:** Open the URL displayed in your browser.
+
+</details>
+
+<details>
+<summary><h2>macOS Quick Start</h2></summary>
+
+1. **Install Miniconda:** Download the pkg installer from [here](https://docs.anaconda.com/miniconda/#miniconda-latest-installer-links) and follow the instructions.
+2. **Install Docker Desktop:** Download the dmg image from [here](https://www.docker.com/products/docker-desktop/), drag the Docker application to your Applications folder, and create a Docker Hub account.
+3. **Download Agent Zero:** Download the latest release zip from the [GitHub releases page](https://github.com/frdel/agent-zero/releases) and extract it.
+4. **Open Terminal:** Navigate to the Agent Zero directory.
+5. **Create Conda Environment:** Run: `conda create -n a0 python=3.12 -y`
+6. **Activate Environment:** Run: `conda activate a0`
+7. **Install Requirements:** Run: `pip install -r requirements.txt`
+8. **Configure API Keys:** Create a `.env` file and add your keys.
+9. **Run Agent Zero (Web UI):** Run: `python run_ui.py`
+10. **Access the Web UI:** Open the displayed URL.
+
+> ⚠️ **Important macOS Docker Configuration:** In Docker Desktop's preferences (Docker menu) go to Settings, navigate to "Advanced" and check "Allow the default Docker socket to be used (requires password)."  This allows Agent Zero to communicate with the Docker daemon.
+
+![docker socket macOS](res/setup/macsocket.png)
+
+</details>
+
+<details>
+<summary><h2>Linux Quick Start</h1></summary>
+
+1. **Install Python and Pip:** Use your distribution's package manager (e.g., `apt`, `yum`, `dnf`) to install Python 3.12 or higher and pip. On Debian/Ubuntu systems, you would typically use:
+   ```bash
+   sudo apt-get update
+   sudo apt-get install python3.12 python3-pip
+   ```
+2. **Install Miniconda:** Download the appropriate installer for your Linux distribution from [here](https://docs.anaconda.com/miniconda/#miniconda-latest-installer-links) and follow the instructions.
+3. **Install Docker:** Install Docker Desktop or Docker CE using your distribution's package manager. Make sure the Docker service is running: `sudo systemctl start docker`
+4. **Download Agent Zero:** Download the latest release zip from the [GitHub releases page](https://github.com/frdel/agent-zero/releases) and extract it.
+5. **Open Terminal and Navigate:** Open your terminal and navigate to the extracted Agent Zero folder using the `cd` command.
+6. **Create and Activate Conda Environment:**
+   ```bash
+   conda create -n a0 python=3.12 -y
+   conda activate a0
+   ```
+7. **Install Requirements:** `pip install -r requirements.txt`
+8. **Configure API Keys:** Create a `.env` file in the project root and add your API keys. You can copy the `example.env` file and rename it to `.env`.
+9. **Run Agent Zero (Web UI):** `python run_ui.py`
+10. **Access the Web UI:** Open the URL displayed in your terminal.
+
+</details>
+
+# In-Depth Guide for Windows and macOS
 - Agent Zero is not an app. It's a framework. It's made to be customized, edited, enhanced. Therefore you need to install the necessary components to run it.
-- I will provide step by step instructions along with a video for this tutorial on how to make Agent Zero work on Windows and MacOS.
-
-[![Video](thumb_play.png)](https://youtu.be/8H7mFsvxKYQ)
+- The following step by step instructions can be followed along with a video for this tutorial on how to make Agent Zero work on Windows and macOS that you find in the [top section](#installation-guide-for-windows-macos-and-linux) of the page.
 
 ## Reminders:
-1. You don't need to install Python, Conda will take care of that for you.
-2. You don't need API keys, Agent Zero can run with local models, but for this tutorial I will leave it to the default OpenAI API. Local models will be covered in another tutorial.
-3. You don't need Visual Studio Code or any other code editor, but it's easier to navigate and edit files if you have one.
-4. Docker is not mandatory, but running Agent Zero without docker is actually more complicated and can be very dangerous, so I will be showing the easier and recommended way to do it - with Docker Desktop application.
-5. Git/Github is not mandatory, you can download the framework files in browser. I will not be showing how to use Git in this tutorial.
-
+1. There's no need to install Python, Conda will manage that for you.
+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 simple video explanation for running Free and Local models is available [in this video](https://www.youtube.com/watch?v=sLMhLRHDIPY&t=80s).
+3. Visual Studio Code or any other code editor is not mandatory, but it makes it easier to navigate and edit files.
+4. Docker is not mandatory, but running Agent Zero without Docker is actually more complicated and can be very dangerous, so we will be covering the easier and recommended way - using Docker Desktop application.
+5. 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.
 
 ## 1. Install Conda (miniconda)
 - Conda is a python environment manager, it will help you keep your projects and installations separated. Full Conda has many more features, but you only need "miniconda".
 
 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".
-2. Based on your operating system, download the right installer of miniconda. For MacOS select the version with "pkg" at the end.
+2. Based on your operating system, download the right installer of miniconda. For macOS select the version with "pkg" at the end.
 
-<img src="image-1.png" alt="miniconda download win" width="500"/>
-<img src="image-5.png" alt="miniconda download macos" width="500"/>
+<img src="res/setup/image-1.png" alt="miniconda download win" width="500"/>
+<img src="res/setup/image-5.png" alt="miniconda download macos" width="500"/>
 <br><br>
 
-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.
+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.
 
-<img src="image.png" alt="miniconda install" width="200"/>
-<img src="image-2.png" alt="miniconda install" width="200"/>
-<img src="image-3.png" alt="miniconda install" width="200"/>
-<img src="image-4.png" alt="miniconda install" width="200"/>
+<img src="res/setup/image.png" alt="miniconda install" width="200"/>
+<img src="res/setup/image-2.png" alt="miniconda install" width="200"/>
+<img src="res/setup/image-3.png" alt="miniconda install" width="200"/>
+<img src="res/setup/image-4.png" alt="miniconda install" width="200"/>
 <br><br>
 
-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.
+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.
 
-<img src="image-6.png" alt="miniconda installed" height="100"/>
-<img src="image-7.png" alt="miniconda installed" height="100"/>
+<img src="res/setup/image-6.png" alt="miniconda installed" height="100"/>
+<img src="res/setup/image-7.png" alt="miniconda installed" height="100"/>
 <br><br>
 
 ## 2. Install Docker (Docker Desktop application)
 - 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.
 - Agent Zero only connects to the Docker container when it needs to execute code and commands. The frameworks itself runs on your machine.
-- Running Agent Zero without docker is possible, but more complicated and dangerous, I will not be covering that in this tutorial.
+- Running Agent Zero without Docker is possible, but more complicated and dangerous, I will not be covering that in this tutorial.
 - Docker has a desktop application with GUI for all major operating system, so I will be using that.
 
 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".
 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.
 
-<img src="image-8.png" alt="docker download" width="200"/>
+<img src="res/setup/image-8.png" alt="docker download" width="200"/>
 <br><br>
 
-3. Run the installer and go through the installattion 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.
+3. Run the installer and go through the installattion 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.
 
-<img src="image-9.png" alt="docker install" width="300"/>
-<img src="image-10.png" alt="docker install" width="300"/>
+<img src="res/setup/image-9.png" alt="docker install" width="300"/>
+<img src="res/setup/image-10.png" alt="docker install" width="300"/>
 
-<img src="image-12.png" alt="docker install" width="300"/>
+<img src="res/setup/image-12.png" alt="docker install" width="300"/>
 <br><br>
 
 
 4. Once installed, you should see Docker Desktop application on your Windows/Mac machine. 
 
-<img src="image-11.png" alt="docker installed" height="100"/>
-<img src="image-13.png" alt="docker installed" height="100"/>
+<img src="res/setup/image-11.png" alt="docker installed" height="100"/>
+<img src="res/setup/image-13.png" alt="docker installed" height="100"/>
 <br><br>
 
 5. Create account in the application.
 No need to create images or containers, the framework will do that for you. However, this requires you 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.
 
+> ⚠️ **Important macOS-only Docker Configuration:** In Docker Desktop's preferences (Docker menu) go to Settings, navigate to "Advanced" and check "Allow the default Docker socket to be used (requires password)."  This allows Agent Zero to communicate with the Docker daemon.
+
+![docker socket macOS](res/setup/macsocket.png)
+
 ## 3. Download Agent Zero
-- You can clone the Agent Zero repository (https://github.com/frdel/agent-zero) from GitHub if you know how to use git. In this tutorial I will just show how to download the files.
+- You can clone the Agent Zero repository (https://github.com/frdel/agent-zero) from GitHub if you know how to use Git. In this tutorial I will just show how to download the files.
 
 1. Go to the Agent Zero releases [here](https://github.com/frdel/agent-zero/releases).
 2. The latest release is on the top of the list, click the "Source Code (zip)" button under "Assets" to download it.
 
-<img src="image-14.png" alt="agent zero download" width="500"/>
+<img src="res/setup/image-14.png" alt="agent zero download" width="500"/>
 <br><br>
 
-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.
+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.
 
 
 ## 4. Set up Conda environment
 - Now that we have the project files and Conda, we can create **virtual Python environment** for this project, activate it and install requirements.
 
-1. Open your **"Anaconda Powershell Prompt"** application on windows or **"Terminal"** application on MacOS.
+1. Open your **"Anaconda Powershell Prompt"** application on windows or **"Terminal"** application on macOS.
 2. In the terminal, navigate to your Agent Zero folder using **"cd"** command. Replace the path with your actual Agent Zero folder path.
 ~~~
 cd C:\Users\frdel\Desktop\agent-zero
 ~~~
 You should see your folder has changed on the next terminal line.
 
-<img src="image-15.png" alt="agent zero cd" height="100"/>
-<img src="image-16.png" alt="agent zero cd" height="100"/>
+<img src="res/setup/image-15.png" alt="agent zero cd" height="100"/>
+<img src="res/setup/image-16.png" alt="agent zero cd" height="100"/>
 <br><br>
 
 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.
@@ -103,8 +170,8 @@ conda activate a0
 ~~~
 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.
 
-<img src="image-17.png" alt="conda env" height="200"/>
-<img src="image-18.png" alt="conda env" height="200"/>
+<img src="res/setup/image-17.png" alt="conda env" height="200"/>
+<img src="res/setup/image-18.png" alt="conda env" height="200"/>
 <br><br>
 
 > ⚠️ If you open a new terminal window, you will need to activate the environment with "conda activate a0" again for that window.
@@ -115,7 +182,7 @@ pip install -r requirements.txt
 ~~~
 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.
 
-<img src="image-19.png" alt="conda reqs" height="200"/>
+<img src="res/setup/image-19.png" alt="conda reqs" height="200"/>
 <br><br>
 
 ## 5. Configure Agent Zero
@@ -125,10 +192,10 @@ This might take some time. If you get any errors regarding version conflicts and
 1. Find the **"example.env"** file in your Agent Zero folder and edit the contents. I will put my OpenAI API key after **"API_KEY_OPENAI="**. If you have API keys for other service providers, add them as needed.
 2. Rename the **"example.env"** file to **".env"**. This is important, only this exact "**.env**" file name is valid.
 
-<img src="image-20.png" alt="conda reqs" height="200"/>
+<img src="res/setup/image-20.png" alt="conda reqs" height="200"/>
 <br><br>
 
-3. (Optional) Change models or setting in **"initialize.py"** file if needed.
+3. (Optional) Change models or setting in **"initialize.py"** file if needed as detailed [here](#choosing-your-llms).
 
 ## 6. Run Agent Zero
 - Setup done. It's time to test Agent Zero. Let's double check:
@@ -141,14 +208,100 @@ This might take some time. If you get any errors regarding version conflicts and
 python run_ui.py
 ~~~
 
-<img src="image-21.png" alt="run ui" height="200"/>
+<img src="res/setup/image-21.png" alt="run ui" height="110"/>
 <br><br>
 
 5. Open the URL shown in terminal in your web browser. You should see the Agent Zero interface. The first time it needs to execute code, Docker image will be downloaded and deployed, this might take some time. Be patient when seeing "Initializing docker container agent-zero-exe for safe code execution...".
 
-<img src="image-22.png" alt="run ui" width="400"/>
-<img src="image-23.png" alt="run ui" width="400"/>
+<img src="res/setup/image-22.png" alt="run ui" width="400"/>
+<img src="res/setup/image-23.png" alt="run ui" width="400"/>
 <br><br>
 
+## Choosing Your LLMs
+The `initialize.py` file is the control center for selecting the Large Language Models (LLMs) that power Agent Zero.  You can choose different LLMs for different roles:
+
+| LLM Role | Description |
+| --- | --- |
+| `chat_llm` | This is the primary LLM used for conversations and generating responses. |
+| `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. |
+| `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. |
+
+**How to Change:**
+1. Open `initialize.py`.
+2. Locate the lines where these LLMs are initialized (at the beginning of the file).
+3. Uncomment the line for the provider and model you want to use, and comment out the others.  For example, to use `gpt-4o-mini` for chat:
+   ```python
+   chat_llm = models.get_openai_chat(model_name="gpt-4o-mini", temperature=0)
+   ```
+4. Ensure only one model is uncommented for each LLM role.
+
+## Important Considerations
+
+- ⚠️ **IMPORTANT NOTICE**: Changing the `embedding_llm` will re-index all the memory and knowledge, and requires clearing the `memory` folder to avoid errors, as the embeddings can't be mixed in the vector database. Beware that this will DELETE ALL OF AGENT ZERO'S MEMORY.
+
+- Experiment with different model combinations to find the balance of performance and cost that best suits your needs. E.g., using a smaller model for `utility_llm` can save costs without significantly impacting performance.
+
+### Installing and Using Ollama (Local Models)
+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:
+
+#### First step: installation
+**On Windows:**
+
+Download Ollama from the official website and install it on your machine.
+
+<button>[Download Ollama Setup](https://ollama.com/download/OllamaSetup.exe)</button>
+
+**On macOS:**
+```
+brew install ollama
+```
+Otherwise choose macOS installer from the [official website](https://ollama.com/).
+
+**On Linux:**
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+```
+
+**Finding Model Names:**
+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).
+
+#### Second step: pulling the model
+**On Windows, macOS, and Linux:**
+```
+ollama pull <model-name>
+```
+
+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`.
+
+#### Managing your downloaded models
+Once you've downloaded some models, you might want to check which ones you have available or remove any you no longer need.
+
+- **Listing downloaded models:** 
+  To see a list of all the models you've downloaded, use the command:
+  ```
+  ollama list
+  ```
+- **Removing a model:**
+  If you need to remove a downloaded model, you can use the `ollama rm` command followed by the model name:
+  ```
+  ollama rm <model-name>
+  ```
+
+## ❗ How to update Agent Zero
+To update Agent Zero to the latest version, follow these steps:
+1. **Backup .env and initialize.py**: Before updating, make sure to save your `.env` file with all your API keys and the customizations you've made to the first part of `def_initialize` function in the `initialize.py` file to choose your LLMs (highlighted section in below figure). This is important because the update process will overwrite these files with the default versions from the repository and can save you time rewriting all your LLMs choices.
+
+![Update initialize.py](res/setup/update-initialize.png)
+
+Beware of indentations when pasting the model selection code back into the `initialize.py` file after the update.
+
+- **Using Git/GitHub:** Pull the latest version of the Agent Zero repository with Git/GitHub. The custom knowledge, solutions, memory, and other data will get ignored by Git, so you don't need to worry about losing any of your custom data. You just have to save your `.env` file before updating.
+- **Manual Update:** Alternatively, you can manually download the latest version of Agent Zero from the [releases page](https://github.com/frdel/agent-zero/releases). The only folders that you must save to retain custom data are the following: `/memory`, `/knowledge`. If you have created custom `instruments` or `prompts` you must save their dirs as well.
 
+   If you update manually, beware of new dependencies. If any changes are made to requirements.txt in the updated version, you have to execute this command inside the a0 conda env after activating it:
 
+      
+      pip install -r requirements.txt
+      
+## Conclusion
+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.  If you encounter any issues during the installation process, please consult the Troubleshooting section of this documentation or refer to the Agent Zero community for assistance.

docs/quickstart.md

@@ -0,0 +1,43 @@
+# Quick Start
+This guide provides a quick introduction to using Agent Zero. We'll cover launching the web UI, starting a new chat, and running a simple task.
+
+## Launching the Web UI
+1. Make sure you have Agent Zero installed and your environment set up correctly (refer to the [Installation guide](installation.md) if needed).
+2. Open a terminal in the Agent Zero directory and activate your conda environment (if you're using one).
+3. Run the following command:
+
+```bash
+python run_ui.py
+```
+
+4.  A message similar to this will appear in your terminal, indicating the Web UI is running:
+
+![](res/flask_link.png)
+
+5. Open your web browser and navigate to the URL shown in the terminal (usually `http://127.0.0.1:50001`). You should see the Agent Zero Web UI.
+
+![](res/ui_newchat.png)
+
+## Running a Simple Task
+Let's ask Agent Zero to tell us the current time.  Here's how:
+
+1.  Type "Download a YouTube video for me" in the chat input field and press Enter or click the send button.
+
+2. Agent Zero will process your request.  You'll see its "thoughts" and the actions it takes displayed in the UI. It will find a default already existing solution, that implies using the `code_execution_tool` to run a simple Python script to perform the task.
+
+3. The agent will then ask you for the URL of the YouTube video you want to download.
+
+## Example Interaction
+Here's an example of what you might see in the Web UI at step 3:
+![1](res/image-24.png)
+
+## Next Steps
+Now that you've run a simple task, you can experiment with more complex requests. Try asking Agent Zero to:
+
+* Perform calculations
+* Search the web for information
+* Execute shell commands
+* Explore web development tasks
+* Create or modify files
+
+The Usage Guide provides more in-depth information on using Agent Zero's various features, including prompt engineering, tool usage, and multi-agent cooperation.

docs/troubleshooting.md

@@ -0,0 +1,60 @@
+# Troubleshooting and FAQ
+This page addresses frequently asked questions (FAQ) and provides troubleshooting steps for common issues encountered while using Agent Zero.
+
+## Frequently Asked Questions
+**1. How do I set up and activate a Python virtual environment?**
+
+Use the `venv` module or `conda` (recommended).
+
+* **`venv`:**
+    ```bash
+    python -m venv .venv  # Create the environment
+    source .venv/bin/activate  # Activate (Linux/macOS)
+    .venv\Scripts\activate  # Activate (Windows)
+    ```
+* **`conda`:**
+    ```bash
+    conda create -n agent-zero python=3.12  # Create
+    conda activate agent-zero  # Activate
+    ```
+
+**2. How do I resolve `ModuleNotFoundError` errors (e.g., for `ansio`, `pyflakes`, `Flask`)?**
+
+Ensure your virtual environment is activated *before* installing requirements:
+
+```bash
+pip install -r requirements.txt
+```
+
+**3. How do I integrate models like `ollama` or `llama` with Agent Zero?**
+Refer to the [Choosing your LLMs](architecture.md#installing-and-using-ollama) section of the documentation for detailed instructions and examples for configuring different LLMs in `initialize.py`. (This assumes you'll have a dedicated documentation page for model integration).
+
+**4. How can I make Agent Zero retain memory between sessions?**
+Auto memory automatically saves and loads solutions and informations from previous sessions.
+
+**5. Where can I find more documentation or tutorials?**
+*   Join the [Agent Zero Discord community](https://discord.gg/Z2tun2N3) for support and discussions.
+
+**6. Can I run Agent Zero without API keys or for free?**
+You can experiment with locally hosted open-source LLMs like Llama.  Refer to [Choosing Your LLMs](architecture#choosing-your-llms) section for configuration instructions.  Using API-based LLMs like those from OpenAI, Google, etc., requires API keys and might incur costs.
+
+**7. How do I adjust API rate limits?**
+Modify the `rate_limit_seconds` and `rate_limit_requests` parameters in the `AgentConfig` class within `initialize.py`.
+
+**8. Can Agent Zero interact with external APIs or services (e.g., WhatsApp)?**
+Extending Agent Zero to interact with external APIs is possible by creating custom tools or solutions. Refer to the documentation on creating them. 
+
+## Troubleshooting
+
+**Installation**
+* **Dependency Conflicts:** If encountering version conflicts during installation, try creating a fresh virtual environment and reinstalling the requirements.
+* **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.
+
+**Usage**
+* **"Nothing happens" when sending a message:** This often indicates a tool execution issue, an API connection problem, or rate limiting. Check your API keys, internet connection, and ensure any required services (like Docker) are running.  Examine the logs for more details.
+
+* **Terminal commands not executing:** If using Docker for code execution, ensure the Docker container is running and properly configured.  Check SSH settings if applicable.
+
+* **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.
+
+* **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.

docs/usage.md

@@ -0,0 +1,65 @@
+# Usage Guide
+This guide explores more advanced usage scenarios for Agent Zero, building upon the basics covered in the Quick Start.
+
+![](res/memory-man.png)
+
+## Tool Usage
+Agent Zero's power comes from its ability to use tools. Here's how to leverage them effectively:
+
+* **Default Tools:** Agent Zero typically includes default tools like knowledge, webpage content, code execution, and communication.  Understand the capabilities of these tools and how to invoke them.
+* **Creating Custom Tools:**  Extend Agent Zero's functionality by creating your own custom tools. Refer to [Adding Tools](architecture.md#adding_tools) for detailed instructions.
+* **New in 0.7 ❗ | Instruments:**  Instruments are a new type of tool that allow you to create custom functions that can be called by Agent Zero.  Refer to [Adding Instruments](architecture.md#adding_instruments) for further details.
+* **Tool Arguments:**  Provide the necessary arguments to the tools.  Agent Zero expects tools to be invoked with a JSON-formatted string containing the tool name and arguments.  Refer to the Quick Start and example prompts for how to format tool calls.
+
+## Example: Web Search and Code Execution
+Let's say you want Agent Zero to find the current price of Bitcoin and then convert it to Euros. Here's a possible prompt:
+
+> Please be a professional financial analyst. Find last month Bitcoin/USD price trend and make a chart in your environment. The chart must have highlighted key points corresponding with dates of major news about cryptocurrency. Use the 'knowledge_tool' to find the price and the 'code_execution_tool' to perform the rest of the job.
+
+Agent Zero might then:
+
+1. Use the `knowledge_tool` to query a reliable source for the Bitcoin price.
+2. Extract the price from the search results.
+3. Use the `code_execution_tool` to execute a Python script that performs the conversion using the provided exchange rate.
+4. Return the final price in Euros.
+
+This example demonstrates how to combine multiple tools to achieve a simple task. By mastering prompt engineering and tool usage, you can unlock the full potential of Agent Zero to solve complex problems.
+
+## Memory Management
+* **Persistence:** Agent Zero's memory persists across sessions, allowing agents to learn from past interactions.
+* **Memory Retrieval:** Agents can access their memory to retrieve relevant information and experiences.  The `memory_tool` is used for this purpose.
+* **Knowledge Base:** You can augment the agent's knowledge by providing external knowledge files. (Link to documentation on knowledge base management).
+
+## Multi-Agent Cooperation
+One of Agent Zero's unique features is multi-agent cooperation.
+
+* **Creating Sub-Agents:** Agents can create sub-agents to delegate sub-tasks.  This helps manage complexity and distribute workload.
+* **Communication:** Agents can communicate with each other, sharing information and coordinating actions. The system prompt and message history play a key role in guiding this communication.
+* **Hierarchy:** Agent Zero uses a [hierarchical structure](architecture.md#agent-hierarchy-and-communication), with superior agents delegating tasks to subordinates.  This allows for structured problem-solving and efficient resource allocation.
+
+![](res/physics.png)
+![](res/physics-2.png)
+
+## Prompt Engineering
+Effective prompt engineering is crucial for getting the most out of Agent Zero. Here are some tips and techniques:
+
+* **Be Clear and Specific:** Clearly state your desired outcome.  The more specific you are, the better Agent Zero can understand and fulfill your request.  Avoid vague or ambiguous language.
+* **Provide Context:** If necessary, provide background information or context to help the agent understand the task better. This might include relevant details, constraints, or desired format for the response.
+* **Break Down Complex Tasks:**  For complex tasks, break them down into smaller, more manageable sub-tasks.  This makes it easier for the agent to reason through the problem and generate a solution.
+* **Iterative Refinement:** Don't expect perfect results on the first try.  Experiment with different prompts, refine your instructions based on the agent's responses, and iterate until you achieve the desired outcome.
+* **System-Level Instructions:** A custom prompts directory changes the agent's overall behavior.  You can copy the default files and modify them to give the agent specific instructions, biases, or constraints. The same goes for the tool files, that you can modify to give the agent specific instructions, biases, or constraints for each tool. See (architecture.md#prompts) for more information.
+
+## Agent Behavior
+* **System Prompt:**  The core of Agent Zero's behavior is defined in the system prompt.  Experiment with different system prompts to customize the agent's personality, biases, and reasoning approach.
+* **Prompts Directory:** The `prompts` directory contains various prompt templates used by the framework. You can modify these templates to customize the agent's communication style, instructions, and responses. See [Prompt Customization](architecture.md#custom-prompts) for more information.
+* **Creating New Tools and Instructions:** Extend Agent Zero's capabilities with custom tools and instructions. This allows you to add new features, modify existing behavior, and integrate with other systems.
+
+## Running on All Hosts
+To access the Agent Zero Web UI from other devices on your network, such as your smartphones or tablets:
+
+1.  In `run_ui.py`, add `host="0.0.0.0"` (or your private IP) to the `app.run()` command before the `port` argument (end of `run_ui.py`). The edited line of code should look like this:
+```python
+app.run(request_handler=NoRequestLoggingWSGIRequestHandler, host="0.0.0.0", port=port)
+```
+2. Access the Web UI from other devices using `http://$YOUR_PRIVATE_IP:50001`.
+> On local networks, usually 192.168.x.x or 10.0.x.x.