Installation guide - readme

Readme file for installation guide video

README.md

@@ -3,16 +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/intro_vid.jpg)](https://www.youtube.com/watch?v=C9n8zFpaV3I)
+[![Intro Video](/docs/res/intro_vid.jpg)](https://www.youtube.com/watch?v=C9n8zFpaV3I)
 
 **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/ui_screen1.png)
+![UI prototype](/docs/res/ui_screen1.png)
 
 ## Key concepts
 1. **General-purpose assistant**
@@ -43,7 +42,7 @@
 - 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.
 - 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.
 
-![Agent Zero](docs/splash_wide.png)
+![Agent Zero](/docs/res/splash_wide.png)
 
 ## Nice features to have
 - Output is very clean, colorful, readable and interactive; nothing is hidden.
@@ -66,7 +65,7 @@ Agent Zero is made to be used in an isolated virtual environment (for safety) wi
 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.
 
 
-[![David Ondrej video](/docs/david_vid.jpg)](https://www.youtube.com/watch?v=_Pionjv4hGc)
+[![David Ondrej video](/docs/res/david_vid.jpg)](https://www.youtube.com/watch?v=_Pionjv4hGc)
 
 ## Known problems
 1. The system prompt sucks. You can do better. If you do, help me please :)
@@ -78,49 +77,13 @@ If you cannot provide all the necessary conditions or API keys, just change the
 - **Python**: Python has to be installed on the system to run the framework.
 - **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.
 
-![Time example](docs/time_example.jpg)
+![Time example](/docs/res/time_example.jpg)
 
 ## 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.
+
 > ⚠️ **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.
 
-Update: [Guide by CheezChat for Windows](./docs/win_installation_guide.txt)
-
-1. **Required API keys:**
-- No API keys are required. Models can run locally. The only recommended API key is for https://www.perplexity.ai/ API. Perplexity is used as a convenient web search tool and has not yet been replaced by an open-source alternative in Agent Zero. If you do not have an API key for Perplexity, leave it empty in the .env file and Perplexity will not be used.
-- Chat models and embedding models can be executed locally via Ollama, LMStudio and HuggingFace or via API as well.
-
-2. **Enter your API keys if needed:**
-- You can enter your API keys into the **.env** file, which you can copy from **example.env**
-- Or you can export your API keys in the terminal session:
-~~~bash
-export API_KEY_PERPLEXITY="your-api-key-here"
-export API_KEY_OPENAI="your-api-key-here"
-~~~
-
-3. **Install dependencies with the following terminal command:**
-~~~bash
-pip install -r requirements.txt
-~~~
-
-3. **Choose your chat, utility and embeddings model and check other configuration options:**
-- In the **initialize.py** file, you can see how the chat model and embedding model are set.
-- You can choose between online models (OpenAI, Anthropic, Groq) or offline (Ollama, LMStudio, HuggingFace) for both.
-
-4. **run Docker:**
-- Easiest way is to install Docker Desktop application ([Download](https://www.docker.com/products/docker-desktop/)) and just leave it running in the background.
-- You don't need to download and build any images, it will be done automatically by the framework at runtime.
-
-## Run the program
-- Just run the **run_ui.py** file in Python:
-~~~bash
-python run_ui.py
-~~~
-- And open the URL shown in the terminal:
-
-![Flask link](docs/flask_link.png)
-
-- Or run it in debug mode in VS Code using the **debug** button in the top right corner of the editor. I have provided config files for VS Code for this purpose.
-- For the original command line interface you can run run_cli.py instead of run_ui.py

docs/installation/README.md

@@ -0,0 +1,155 @@
+# How to install Agent Zero on 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 being created. Link will be updated soon.
+![Video](thumb_play.png)
+
+## 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. 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.
+
+<img src="image-1.png" alt="miniconda download win" width="500"/>
+<img src="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.
+
+<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"/>
+<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.
+
+<img src="image-6.png" alt="miniconda installed" height="100"/>
+<img src="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.
+- 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"/>
+<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.
+
+<img src="image-9.png" alt="docker install" width="300"/>
+<img src="image-10.png" alt="docker install" width="300"/>
+
+<img src="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"/>
+<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.
+
+## 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.
+
+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"/>
+<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.
+
+
+## 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.
+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"/>
+<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.
+~~~
+conda create -n a0 python=3.12 -y
+~~~
+
+4. Once done, activate the new environment for this terminal window by another command:
+~~~
+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"/>
+<br><br>
+
+> ⚠️ If you open a new terminal window, you will need to activate the environment with "conda activate a0" again for that window.
+
+5. Install requirements using **"pip"**. Pip is a Python package manager. We can install all required packages from requirements.txt file using command:
+~~~
+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"/>
+<br><br>
+
+## 5. Configure Agent Zero
+- Now we can configure Agent Zero - select models, settings, API Keys etc.
+- I will leave the default configuration using OpenAI API and I will just provide my OpenAI API key in the **.env** file.
+
+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"/>
+<br><br>
+
+3. (Optional) Change models or setting in **"initialize.py"** file if needed.
+
+## 6. Run Agent Zero
+- Setup done. It's time to test Agent Zero. Let's double check:
+
+1. Make sure you have the **"a0"** Conda environment still active in your current terminal window. You can see that on the left of each terminal line like **(a0)** or **(base)**. If not, activate again with **"conda activate a0"** command again.
+2. Make sure your terminal is looking into the Agent Zero folder. If not, navigate to it with **"cd"** command again with your path.
+3. Run the **Docker Desktop application** you installed and just leave it running in the background. 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 sign in in the Docker Desktop application, if you haven't already.
+4. Run the Agent Zero with Web UI:
+~~~
+python run_ui.py
+~~~
+
+<img src="image-21.png" alt="run ui" height="200"/>
+<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"/>
+<br><br>
+
+
+

run_cli.py

@@ -96,10 +96,12 @@ def timeout_input(prompt, timeout=10):
 if __name__ == "__main__":
     print("Initializing framework...")
 
+    # initialize context
+    config = initialize()
+    context = AgentContext(config)
+
     # Start the key capture thread for user intervention during agent streaming
     threading.Thread(target=capture_keys, daemon=True).start()
 
-    # initialize and start the chat
-    config = initialize()
-    context = AgentContext(config)
+    #start the chat
     asyncio.run(chat(context))