agent0ai · ehlowr0ld · Oct 30, 2025 · Nov 30, 2025 · Dec 24, 2025 · Dec 30, 2025
diff --git a/README.md b/README.md
@@ -6,15 +6,15 @@
     <a href="https://trendshift.io/repositories/11745" target="_blank"><img src="https://trendshift.io/api/badge/repositories/11745" alt="frdel%2Fagent-zero | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 </p>
 
-[![Agent Zero Website](https://img.shields.io/badge/Website-agent--zero.ai-0A192F?style=for-the-badge&logo=vercel&logoColor=white)](https://agent-zero.ai) [![Thanks to Sponsors](https://img.shields.io/badge/GitHub%20Sponsors-Thanks%20to%20Sponsors-FF69B4?style=for-the-badge&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/agent0ai) [![Follow on X](https://img.shields.io/badge/X-Follow-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.com/Agent0ai) [![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 Warpcast](https://img.shields.io/badge/Warpcast-Follow-5A32F3?style=for-the-badge)](https://warpcast.com/agent-zero) 
+[![Agent Zero Website](https://img.shields.io/badge/Website-agent--zero.ai-0A192F?style=for-the-badge&logo=vercel&logoColor=white)](https://agent-zero.ai) [![Thanks to Sponsors](https://img.shields.io/badge/GitHub%20Sponsors-Thanks%20to%20Sponsors-FF69B4?style=for-the-badge&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/agent0ai) [![Follow on X](https://img.shields.io/badge/X-Follow-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.com/Agent0ai) [![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 Warpcast](https://img.shields.io/badge/Warpcast-Follow-5A32F3?style=for-the-badge)](https://warpcast.com/agent-zero)
 
 
 ## Documentation:
 
 [Introduction](#a-personal-organic-agentic-framework-that-grows-and-learns-with-you) •
 [Installation](./docs/installation.md) •
 [Development](./docs/development.md) •
-[Extensibility](./docs/extensibility.md) •
+[WebSocket Infrastructure](./docs/websocket-infrastructure.md) •
 [Connectivity](./docs/connectivity.md) •
 [How to update](./docs/installation.md#how-to-update-agent-zero) •
 [Documentation](./docs/README.md) •
@@ -158,6 +158,7 @@ docker run -p 50001:80 agent0ai/agent-zero
 | [Installation](./docs/installation.md) | Installation, setup and configuration |
 | [Usage](./docs/usage.md) | Basic and advanced usage |
 | [Development](./docs/development.md) | Development and customization |
+| [WebSocket Infrastructure](./docs/websocket-infrastructure.md) | Real-time WebSocket handlers, client APIs, filtering semantics, envelopes |
 | [Extensibility](./docs/extensibility.md) | Extending Agent Zero |
 | [Connectivity](./docs/connectivity.md) | External API endpoints, MCP server connections, A2A protocol |
 | [Architecture](./docs/architecture.md) | System design and components |
@@ -265,7 +266,7 @@ docker run -p 50001:80 agent0ai/agent-zero
     - More space efficient on mobile
 - Streamable HTTP MCP servers support
 - LLM API URL added to models config for Azure, local and custom providers
-    
+
 
 ### v0.9.0 - Agent roles, backup/restore
 [Release video](https://www.youtube.com/watch?v=rMIe-TC6H-k)

diff --git a/agent.py b/agent.py
@@ -1,4 +1,4 @@
-import asyncio, random, string
+import asyncio, random, string, threading
 import nest_asyncio
 
 nest_asyncio.apply()
@@ -45,6 +45,7 @@ class AgentContextType(Enum):
 class AgentContext:
 
     _contexts: dict[str, "AgentContext"] = {}
+    _contexts_lock = threading.RLock()
     _counter: int = 0
     _notification_manager = None
 
@@ -66,10 +67,14 @@ def __init__(
     ):
         # initialize context
         self.id = id or AgentContext.generate_id()
-        existing = self._contexts.get(self.id, None)
-        if existing:
-            AgentContext.remove(self.id)
-        self._contexts[self.id] = self
+        existing = None
+        with AgentContext._contexts_lock:
+            existing = AgentContext._contexts.get(self.id, None)
+            if existing:
+                AgentContext._contexts.pop(self.id, None)
+            AgentContext._contexts[self.id] = self
+        if existing and existing.task:
+            existing.task.kill()
         if set_current:
             AgentContext.set_current(self.id)
 
@@ -94,7 +99,8 @@ def __init__(
 
     @staticmethod
     def get(id: str):
-        return AgentContext._contexts.get(id, None)
+        with AgentContext._contexts_lock:
+            return AgentContext._contexts.get(id, None)
 
     @staticmethod
     def use(id: str):
@@ -118,13 +124,15 @@ def set_current(ctxid: str):
 
     @staticmethod
     def first():
-        if not AgentContext._contexts:
-            return None
-        return list(AgentContext._contexts.values())[0]
+        with AgentContext._contexts_lock:
+            if not AgentContext._contexts:
+                return None
+            return list(AgentContext._contexts.values())[0]
 
     @staticmethod
     def all():
-        return list(AgentContext._contexts.values())
+        with AgentContext._contexts_lock:
+            return list(AgentContext._contexts.values())
 
     @staticmethod
     def generate_id():
@@ -133,8 +141,9 @@ def generate_short_id():
 
         while True:
             short_id = generate_short_id()
-            if short_id not in AgentContext._contexts:
-                return short_id
+            with AgentContext._contexts_lock:
+                if short_id not in AgentContext._contexts:
+                    return short_id
 
     @classmethod
     def get_notification_manager(cls):
@@ -146,7 +155,8 @@ def get_notification_manager(cls):
 
     @staticmethod
     def remove(id: str):
-        context = AgentContext._contexts.pop(id, None)
+        with AgentContext._contexts_lock:
+            context = AgentContext._contexts.pop(id, None)
         if context and context.task:
             context.task.kill()
         return context

diff --git a/docs/README.md b/docs/README.md
@@ -6,6 +6,7 @@ To begin with Agent Zero, follow the links below for detailed guides on various
 - **[Usage Guide](usage.md):** Explore GUI features and usage scenarios.
 - **[Development](development.md):** Set up a development environment for Agent Zero.
 - **[Extensibility](extensibility.md):** Learn how to create custom extensions for Agent Zero.
+- **[WebSocket Infrastructure](websocket-infrastructure.md):** Build real-time features with bidirectional handlers and client APIs.
 - **[Connectivity](connectivity.md):** Learn how to connect to Agent Zero from other applications.
 - **[Architecture Overview](architecture.md):** Understand the internal workings of the framework.
 - **[Contributing](contribution.md):** Learn how to contribute to the Agent Zero project.
@@ -58,7 +59,8 @@ To begin with Agent Zero, follow the links below for detailed guides on various
     - [Knowledge](architecture.md#5-knowledge)
     - [Instruments](architecture.md#6-instruments)
     - [Extensions](architecture.md#7-extensions)
-  - [Contributing](contribution.md)
+- [WebSocket Infrastructure](websocket-infrastructure.md)
+- [Development](development.md)
   - [Getting Started](contribution.md#getting-started)
   - [Making Changes](contribution.md#making-changes)
   - [Submitting a Pull Request](contribution.md#submitting-a-pull-request)

diff --git a/docs/contribution.md b/docs/contribution.md
@@ -6,6 +6,7 @@ Contributions to improve Agent Zero are very welcome!  This guide outlines how t
 
 - See [development](development.md) for instructions on how to set up a development environment.
 - See [extensibility](extensibility.md) for instructions on how to create custom extensions.
+- See [websocket infrastructure](websocket-infrastructure.md) for guidance on building real-time handlers and client integrations.
 
 1. **Fork the Repository:** Fork the Agent Zero repository on GitHub.
 2. **Clone Your Fork:** Clone your forked repository to your local machine.
@@ -27,4 +28,4 @@ Contributions to improve Agent Zero are very welcome!  This guide outlines how t
 
 ## Documentation Stack
 
-- The documentation is built using Markdown. We appreciate your contributions even if you don't know Markdown, and look forward to improve Agent Zero for everyone's benefit.
+- The documentation is built using Markdown. We appreciate your contributions even if you don't know Markdown, and look forward to improve Agent Zero for everyone's benefit.
diff --git a/docs/development.md b/docs/development.md
@@ -68,7 +68,7 @@ Now when you select one of the python files in the project, you should see prope
 ```bash
 pip install -r requirements.txt
 playwright install chromium
-``` 
+```
 These will install all the python packages and browser binaries for playwright (browser agent).
 Errors in the code editor caused by missing packages should now be gone. If not, try reloading the window.
 
@@ -81,7 +81,9 @@ It will not be able to do code execution and few other features requiring the Do
 
 ![VS Code debugging](res/dev/devinst-6.png)
 
-The framework will run at the default port 5000. If you open `http://localhost:5000` in your browser and see `ERR_EMPTY_RESPONSE`, don't panic, you may need to select another port like I did for some reason. If you need to change the defaut port, you can add `"--port=5555"` to the args in the `.vscode/launch.json` file or you can create a `.env` file in the root directory and set the `WEB_UI_PORT` variable to the desired port.
+The framework will run at the default port 5000. If you open `http://localhost:5000` in your browser and see `ERR_EMPTY_RESPONSE`, don't panic, you may need to select another port like I did for some reason. If you need to change the default port, you can add `"--port=5555"` to the args in the `.vscode/launch.json` file or you can create a `.env` file in the root directory and set the `WEB_UI_PORT` variable to the desired port.
+
+You can also set the bind host via `"--host=0.0.0.0"` (or `WEB_UI_HOST=0.0.0.0`).
 
 It may take a while the first time. You should see output like the screenshot below. The RFC error is ok for now as we did not yet connect our local development to another instance in docker.
 ![First run](res/dev/devinst-7.png)
@@ -147,6 +149,7 @@ You're now ready to contribute to Agent Zero, create custom extensions, or modif
 
 ## Next steps
 - See [extensibility](extensibility.md) for instructions on how to create custom extensions.
+- See [websocket infrastructure](websocket-infrastructure.md) for real-time handler patterns, client APIs, and troubleshooting tips.
 - See [contribution](contribution.md) for instructions on how to contribute to the framework.
 
 ## Configuration via Environment Variables
@@ -167,4 +170,4 @@ These environment variables automatically override the hardcoded defaults in `ge
 - You can use the `DockerfileLocal` to build your docker image.
 - Navigate to your project root in the terminal and run `docker build -f DockerfileLocal -t agent-zero-local --build-arg CACHE_DATE=$(date +%Y-%m-%d:%H:%M:%S) .`
 - The `CACHE_DATE` argument is optional, it is used to cache most of the build process and only rebuild the last steps when the files or dependencies change.
-- See `docker/run/build.txt` for more build command examples.
+- See `docker/run/build.txt` for more build command examples.
diff --git a/docs/installation.md b/docs/installation.md
@@ -10,7 +10,7 @@ The following user guide provides instructions for installing and running Agent
 ## Windows, macOS and Linux Setup Guide
 
 
-1. **Install Docker Desktop:** 
+1. **Install Docker Desktop:**
 - Docker Desktop provides the runtime environment for Agent Zero, ensuring consistent behavior and security across platforms
 - The entire framework runs within a Docker container, providing isolation and easy deployment
 - Available as a user-friendly GUI application for all major operating systems
@@ -23,8 +23,8 @@ The following user guide provides instructions for installing and running Agent
 <br><br>
 
 > [!NOTE]
-> **Linux Users:** You can install either Docker Desktop or docker-ce (Community Edition). 
-> For Docker Desktop, follow the instructions for your specific Linux distribution [here](https://docs.docker.com/desktop/install/linux-install/). 
+> **Linux Users:** You can install either Docker Desktop or docker-ce (Community Edition).
+> For Docker Desktop, follow the instructions for your specific Linux distribution [here](https://docs.docker.com/desktop/install/linux-install/).
 > For docker-ce, follow the instructions [here](https://docs.docker.com/engine/install/).
 >
 > If you're using docker-ce, you'll need to add your user to the `docker` group:
@@ -44,14 +44,14 @@ The following user guide provides instructions for installing and running Agent
 <img src="res/setup/image-12.png" alt="docker install" width="300"/>
 <br><br>
 
-1.4. Once installed, launch Docker Desktop: 
+1.4. Once installed, launch Docker Desktop:
 
 <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>
 
 > [!NOTE]
-> **MacOS Configuration:** In Docker Desktop's preferences (Docker menu) → Settings → 
+> **MacOS Configuration:** In Docker Desktop's preferences (Docker menu) → Settings →
 > Advanced, enable "Allow the default Docker socket to be used (requires password)."
 
 ![docker socket macOS](res/setup/macsocket.png)
@@ -189,8 +189,8 @@ Optionally you can map local folders for file persistence:
 > You can also access the Web UI by clicking the ports right under the container ID in Docker Desktop.
 
 > [!NOTE]
-> After starting the container, you'll find all Agent Zero files in your chosen 
-> directory. You can access and edit these files directly on your machine, and 
+> After starting the container, you'll find all Agent Zero files in your chosen
+> directory. You can access and edit these files directly on your machine, and
 > the changes will be immediately reflected in the running container.
 
 3. Configure Agent Zero
@@ -306,7 +306,7 @@ ollama pull <model-name>
 2. A CLI message should confirm the model download on your system
 
 #### Selecting your model within Agent Zero
-1. Once you've downloaded your model(s), you must select it in the Settings page of the GUI. 
+1. Once you've downloaded your model(s), you must select it in the Settings page of the GUI.
 
 2. Within the Chat model, Utility model, or Embedding model section, choose Ollama as provider.
 
@@ -321,7 +321,7 @@ ollama pull <model-name>
 #### 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:** 
+- **Listing downloaded models:**
   To see a list of all the models you've downloaded, use the command:
   ```
   ollama list
@@ -356,8 +356,10 @@ Agent Zero's Web UI is accessible from any device on your network through the Do
 > - The port is automatically assigned by Docker unless you specify one
 
 > [!NOTE]
-> If you're running Agent Zero directly on your system (legacy approach) instead of 
-> using Docker, you'll need to configure the host manually in `run_ui.py` to run on all interfaces using `host="0.0.0.0"`.
+> If you're running Agent Zero directly on your system (legacy approach) instead of
+> using Docker, configure the bind address/ports via flags or environment variables:
+> - Use `--host 0.0.0.0` (or set `WEB_UI_HOST=0.0.0.0` in `.env`) to listen on all interfaces.
+> - Use `--port <PORT>` (or `WEB_UI_PORT`) to pick the HTTP port.
 
 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).
 
@@ -418,9 +420,8 @@ For developers or users who need to run Agent Zero directly on their system,see
 > docker run -p $PORT:80 -v /path/to/your/data:/a0 agent0ai/agent-zero
 > ```
 
-      
+
 ### 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. 
+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](troubleshooting.md) of this documentation or refer to the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/B8KZKNsPpj) community for assistance.
-
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -4,22 +4,25 @@ This guide provides a quick introduction to using Agent Zero. We'll cover launch
 ## 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:
+3. Run one of the following commands:
 
 ```bash
 python run_ui.py
 ```
 
-4.  A message similar to this will appear in your terminal, indicating the Web UI is running:
+Notes:
+- HTTP binds to `--host/--port` (or `WEB_UI_HOST`/`WEB_UI_PORT`, default port 5000).
+
+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.
+5. Open your web browser and navigate to the URL shown in the terminal (usually `http://127.0.0.1:5000`). You should see the Agent Zero Web UI.
 
 ![New Chat](res/ui_newchat1.png)
 
 > [!TIP]
-> As you can see, the Web UI has four distinct buttons for easy chat management: 
+> As you can see, the Web UI has four distinct buttons for easy chat management:
 > `New Chat`, `Reset Chat`, `Save Chat`, and `Load Chat`.
 > Chats can be saved and loaded individually in `json` format and are stored in the
 > `/tmp/chats` directory.
@@ -49,6 +52,6 @@ Now that you've run a simple task, you can experiment with more complex requests
 * Create or modify files
 
 > [!TIP]
-> The [Usage Guide](usage.md) provides more in-depth information on using Agent 
-> Zero's various features, including prompt engineering, tool usage, and multi-agent 
-> cooperation.
+> The [Usage Guide](usage.md) provides more in-depth information on using Agent
+> Zero's various features, including prompt engineering, tool usage, and multi-agent
+> cooperation.
diff --git a/docs/usage.md b/docs/usage.md
@@ -102,6 +102,9 @@ Agent Zero's power comes from its ability to use [tools](architecture.md#tools).
 
 - **Understand Tools:** Agent Zero includes default tools like knowledge (powered by SearXNG), code execution, and communication. Understand the capabilities of these tools and how to invoke them.
 
+### Real-Time WebSocket Features
+- Use WebSockets when you need bidirectional, low-latency updates. The [WebSocket Infrastructure guide](websocket-infrastructure.md) explains the backend handler framework, client API, filtering semantics, and common producer/consumer patterns.
+
 ## Example of Tools Usage: Web Search and Code Execution
 Let's say you want Agent Zero to perform some financial analysis tasks. Here's a possible prompt: