diff --git a/README.md b/README.md index c4fd3d280..b79da447a 100644 --- a/README.md +++ b/README.md @@ -12,12 +12,9 @@ ## Documentation: [Introduction](#a-personal-organic-agentic-framework-that-grows-and-learns-with-you) • -[Installation](./docs/getting-started/installation.md) • -[Development](./docs/development/setup.md) • -[WebSocket Infrastructure](./docs/advanced/websockets.md) • -[Connectivity](./docs/advanced/connectivity.md) • -[How to update](./docs/getting-started/installation.md#how-to-update-agent-zero) • -[Documentation](./docs/README.md) • +[Installation](./docs/setup/installation.md) • +[How to update](./docs/setup/installation.md#how-to-update-agent-zero)
+[Development Setup](./docs/setup/dev-setup.md) • [Usage](./docs/guides/usage.md) Or see DeepWiki generated documentation: @@ -29,8 +26,12 @@ Or see DeepWiki generated documentation:
-> ### 🚨 **PROJECTS!** 🚨 -> Agent Zero now supports **Projects** – isolated workspaces with their own prompts, files, memory, and secrets, so you can create dedicated setups for each use case without mixing contexts. +> ### 🚨 **AGENT ZERO SKILLS** 🚨 +> Agent Zero Instruments become **Skills** - portable, structured agent capabilities using the open `SKILL.md` standard (compatible with Claude Code, Codex and more). +> +> **Plus:** Git-based Projects with authentication for public/private repositories - clone codebases directly into isolated workspaces. +> +> See [Usage Guide](./docs/guides/usage.md) and [Projects Tutorial](./docs/guides/projects.md) to get started.
@@ -46,6 +47,26 @@ Or see DeepWiki generated documentation: - Agent Zero is fully transparent, readable, comprehensible, customizable, and interactive. - Agent Zero uses the computer as a tool to accomplish its (your) tasks. +# ⚙️ Installation + +Click to open a video to learn how to install Agent Zero: + +[![Easy Installation guide](/docs/res/easy_ins_vid.png)](https://www.youtube.com/watch?v=w5v5Kjx51hs) + +A detailed setup guide for Windows, macOS, and Linux with a video can be found in the Agent Zero Documentation at [this page](./docs/setup/installation.md). + +### ⚡ Quick Start + +```bash +# Pull and run with Docker + +docker pull agent0ai/agent-zero +docker run -p 50001:80 agent0ai/agent-zero + +# Visit http://localhost:50001 to start +``` + + # 💡 Key Features 1. **General-purpose Assistant** @@ -53,7 +74,7 @@ Or see DeepWiki generated documentation: - Agent Zero is not pre-programmed for specific tasks (but can be). It is meant to be a general-purpose personal assistant. Give it a task, and it will gather information, execute commands and code, cooperate with other agent instances, and do its best to accomplish it. - It has a persistent memory, allowing it to memorize previous solutions, code, facts, instructions, etc., to solve tasks faster and more reliably in the future. -![Agent 0 Working](/docs/res/ui-screen-2.png) +![Agent 0 Working](/docs/res/ui_screen2.png) 2. **Computer as a Tool** @@ -70,8 +91,7 @@ Or see DeepWiki generated documentation: - In the case of the first agent in the chain (Agent 0), the superior is the human user; the agent sees no difference. - Every agent can create its subordinate agent to help break down and solve subtasks. This helps all agents keep their context clean and focused. -![Multi-agent](docs/res/physics.png) -![Multi-agent 2](docs/res/physics-2.png) +![Multi-agent](docs/res/usage/multi-agent.png) 4. **Completely Customizable and Extensible** @@ -82,7 +102,7 @@ Or see DeepWiki generated documentation: - Every default tool can be found in the **python/tools/** folder and changed or copied to create new predefined tools. - **Automated configuration** via `A0_SET_` environment variables for deployment automation and easy setup. -![Prompts](/docs/res/prompts.png) +![Prompts](/docs/res/profiles.png) 5. **Communication is Key** @@ -91,41 +111,21 @@ Or see DeepWiki generated documentation: - 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. -## 🚀 Things you can build with Agent Zero +## 🚀 Real-world use cases -- **Development Projects** - `"Create a React dashboard with real-time data visualization"` +- **Financial Analysis & Charting** - `"Find last month's Bitcoin/USD price trend, correlate with major cryptocurrency news events, generate annotated chart with highlighted key dates"` -- **Data Analysis** - `"Analyze last quarter's NVIDIA sales data and create trend reports"` +- **Excel Automation Pipeline** - `"Scan incoming directory for financial spreadsheets, validate and clean data, consolidate from multiple sources, generate executive reports with flagged anomalies"` -- **Content Creation** - `"Write a technical blog post about microservices"` +- **API Integration Without Code** - `"Use this Google Gemini API snippet to generate product images, remember the integration for future use"` - agent learns and stores the solution in memory -- **System Admin** - `"Set up a monitoring system for our web servers"` +- **Automated Server Monitoring** - `"Check server status every 30 minutes: CPU usage, disk space, memory. Alert if metrics exceed thresholds"` (scheduled task with project-scoped credentials) -- **Research** - `"Gather and summarize five recent AI papers about CoT prompting"` - - -# ⚙️ Installation - -Click to open a video to learn how to install Agent Zero: - -[![Easy Installation guide](/docs/res/easy_ins_vid.png)](https://www.youtube.com/watch?v=w5v5Kjx51hs) - -A detailed setup guide for Windows, macOS, and Linux with a video can be found in the Agent Zero Documentation at [this page](./docs/getting-started/installation.md). - -### ⚡ Quick Start - -```bash -# Pull and run with Docker - -docker pull agent0ai/agent-zero -docker run -p 50001:80 agent0ai/agent-zero - -# Visit http://localhost:50001 to start -``` +- **Multi-Client Project Isolation** - Separate projects for each client with isolated memory, custom instructions, and dedicated secrets - prevents context bleed across sensitive work ## 🐳 Fully Dockerized, with Speech-to-Text and TTS -![Settings](docs/res/settings-page-ui.png) +![Settings](docs/res/settings-page-ui1.png) - Customizable settings allow users to tailor the agent's behavior and responses to their needs. - The Web UI output is very clean, fluid, colorful, readable, and interactive; nothing is hidden. @@ -153,14 +153,15 @@ docker run -p 50001:80 agent0ai/agent-zero | Page | Description | |-------|-------------| -| [Installation](./docs/getting-started/installation.md) | Installation, setup and configuration | +| [Installation](./docs/setup/installation.md) | Installation, setup and configuration | | [Usage](./docs/guides/usage.md) | Basic and advanced usage | -| [Development](./docs/development/setup.md) | Development and customization | -| [WebSocket Infrastructure](./docs/advanced/websockets.md) | Real-time WebSocket handlers, client APIs, filtering semantics, envelopes | -| [Extensibility](./docs/development/extensibility.md) | Extending Agent Zero | -| [Connectivity](./docs/advanced/connectivity.md) | External API endpoints, MCP server connections, A2A protocol | -| [Architecture](./docs/advanced/architecture.md) | System design and components | -| [Contributing](./docs/development/contribution.md) | How to contribute | +| [Guides](./docs/guides/) | Step-by-step guides: Usage, Projects, API Integration, MCP Setup, A2A Setup | +| [Development Setup](./docs/setup/dev-setup.md) | Development and customization | +| [WebSocket Infrastructure](./docs/developer/websockets.md) | Real-time WebSocket handlers, client APIs, filtering semantics, envelopes | +| [Extensions](./docs/developer/extensions.md) | Extending Agent Zero | +| [Connectivity](./docs/developer/connectivity.md) | External API endpoints, MCP server connections, A2A protocol | +| [Architecture](./docs/developer/architecture.md) | System design and components | +| [Contributing](./docs/guides/contribution.md) | How to contribute | | [Troubleshooting](./docs/guides/troubleshooting.md) | Common issues and their solutions | diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..55dcaf965 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,120 @@ +![Agent Zero Logo](res/header.png) +# Agent Zero Documentation + +Welcome to the Agent Zero documentation hub. Whether you're getting started or diving deep into the framework, you'll find comprehensive guides below. + +## Quick Start + +- **[Quickstart Guide](quickstart.md):** Get up and running in 5 minutes with Agent Zero. +- **[Installation Guide](setup/installation.md):** Detailed setup instructions for all platforms (or [update your installation](setup/installation.md#how-to-update-agent-zero)). +- **[VPS Deployment](setup/vps-deployment.md):** Deploy Agent Zero on a remote server. +- **[Development Setup](setup/dev-setup.md):** Set up a local development environment. + +## User Guides + +- **[Usage Guide](guides/usage.md):** Comprehensive guide to Agent Zero's features and capabilities. +- **[Projects Tutorial](guides/projects.md):** Learn to create isolated workspaces with dedicated context and memory. +- **[API Integration](guides/api-integration.md):** Add external APIs without writing code. +- **[MCP Setup](guides/mcp-setup.md):** Configure Model Context Protocol servers. +- **[A2A Setup](guides/a2a-setup.md):** Enable agent-to-agent communication. +- **[Troubleshooting](guides/troubleshooting.md):** Solutions to common issues and FAQs. + +## Developer Documentation + +- **[Architecture Overview](developer/architecture.md):** Understand Agent Zero's internal structure and components. +- **[Extensions](developer/extensions.md):** Create custom extensions to extend functionality. +- **[Connectivity](developer/connectivity.md):** Connect to Agent Zero from external applications. +- **[WebSockets](developer/websockets.md):** Real-time communication infrastructure. +- **[MCP Configuration](developer/mcp-configuration.md):** Advanced MCP server configuration. +- **[Notifications](developer/notifications.md):** Notification system architecture and setup. +- **[Contributing Skills](developer/contributing-skills.md):** Create and share agent skills. +- **[Contributing Guide](guides/contribution.md):** Contribute to the Agent Zero project. + +## Community & Support + +- **Join the Community:** Connect with other users on [Discord](https://discord.gg/B8KZKNsPpj) to discuss ideas, ask questions, and collaborate. +- **Share Your Work:** Show off your Agent Zero creations and workflows in the [Show and Tell](https://github.com/agent0ai/agent-zero/discussions/categories/show-and-tell) area. +- **Report Issues:** Use the [GitHub issue tracker](https://github.com/agent0ai/agent-zero/issues) to report bugs or suggest features. +- **Follow Updates:** Subscribe to the [YouTube channel](https://www.youtube.com/@AgentZeroFW) for tutorials and release videos. + +--- + +## Table of Contents + +- [Quick Start](#quick-start) + - [Quickstart Guide](quickstart.md) + - [Installation Guide](setup/installation.md) + - [Step 1: Install Docker Desktop](setup/installation.md#step-1-install-docker-desktop) + - [Windows Installation](setup/installation.md#-windows-installation) + - [macOS Installation](setup/installation.md#-macos-installation) + - [Linux Installation](setup/installation.md#-linux-installation) + - [Step 2: Run Agent Zero](setup/installation.md#step-2-run-agent-zero) + - [Pull Docker Image](setup/installation.md#21-pull-the-agent-zero-docker-image) + - [Map Folders for Persistence](setup/installation.md#22-optional-map-folders-for-persistence) + - [Run the Container](setup/installation.md#23-run-the-container) + - [Access the Web UI](setup/installation.md#24-access-the-web-ui) + - [Step 3: Configure Agent Zero](setup/installation.md#step-3-configure-agent-zero) + - [Settings Configuration](setup/installation.md#settings-configuration) + - [Agent Configuration](setup/installation.md#agent-configuration) + - [Chat Model Settings](setup/installation.md#chat-model-settings) + - [API Keys](setup/installation.md#api-keys) + - [Authentication](setup/installation.md#authentication) + - [Choosing Your LLMs](setup/installation.md#choosing-your-llms) + - [Installing Ollama (Local Models)](setup/installation.md#installing-and-using-ollama-local-models) + - [Using on Mobile Devices](setup/installation.md#using-agent-zero-on-your-mobile-device) + - [How to Update Agent Zero](setup/installation.md#how-to-update-agent-zero) + - [VPS Deployment](setup/vps-deployment.md) + - [Development Setup](setup/dev-setup.md) + +- [User Guides](#user-guides) + - [Usage Guide](guides/usage.md) + - [Basic Operations](guides/usage.md#basic-operations) + - [Tool Usage](guides/usage.md#tool-usage) + - [Projects](guides/usage.md#projects) + - [What Projects Provide](guides/usage.md#what-projects-provide) + - [Creating Projects](guides/usage.md#creating-projects) + - [Project Configuration](guides/usage.md#project-configuration) + - [Activating Projects](guides/usage.md#activating-projects) + - [Common Use Cases](guides/usage.md#common-use-cases) + - [Tasks & Scheduling](guides/usage.md#tasks--scheduling) + - [Task Types](guides/usage.md#task-types) + - [Creating Tasks](guides/usage.md#creating-tasks) + - [Task Configuration](guides/usage.md#task-configuration) + - [Integration with Projects](guides/usage.md#integration-with-projects) + - [Secrets & Variables](guides/usage.md#secrets--variables) + - [Remote Access via Tunneling](guides/usage.md#remote-access-via-tunneling) + - [Voice Interface](guides/usage.md#voice-interface) + - [Memory Management](guides/usage.md#memory-management) + - [Backup & Restore](guides/usage.md#backup--restore) + - [Projects Tutorial](guides/projects.md) + - [API Integration](guides/api-integration.md) + - [MCP Setup](guides/mcp-setup.md) + - [A2A Setup](guides/a2a-setup.md) + - [Troubleshooting](guides/troubleshooting.md) + +- [Developer Documentation](#developer-documentation) + - [Architecture Overview](developer/architecture.md) + - [System Architecture](developer/architecture.md#system-architecture) + - [Runtime Architecture](developer/architecture.md#runtime-architecture) + - [Implementation Details](developer/architecture.md#implementation-details) + - [Core Components](developer/architecture.md#core-components) + - [Agents](developer/architecture.md#1-agents) + - [Tools](developer/architecture.md#2-tools) + - [Memory System](developer/architecture.md#3-memory-system) + - [Prompts](developer/architecture.md#4-prompts) + - [Knowledge](developer/architecture.md#5-knowledge) + - [Skills](developer/architecture.md#6-skills) + - [Extensions](developer/architecture.md#7-extensions) + - [Extensions](developer/extensions.md) + - [Connectivity](developer/connectivity.md) + - [WebSockets](developer/websockets.md) + - [MCP Configuration](developer/mcp-configuration.md) + - [Notifications](developer/notifications.md) + - [Contributing Skills](developer/contributing-skills.md) + - [Contributing Guide](guides/contribution.md) + +--- + +### Your journey with Agent Zero starts now! + +Ready to dive in? Start with the [Quickstart Guide](quickstart.md) for the fastest path to your first chat, or follow the [Installation Guide](setup/installation.md) for a detailed setup walkthrough. diff --git a/docs/advanced/tunneling.md b/docs/advanced/tunneling.md deleted file mode 100644 index aa7de020a..000000000 --- a/docs/advanced/tunneling.md +++ /dev/null @@ -1,57 +0,0 @@ -# Agent Zero Tunnel Feature - -The tunnel feature in Agent Zero allows you to expose your local Agent Zero instance to the internet using Flaredantic tunnels. This makes it possible to share your Agent Zero instance with others without requiring them to install and run Agent Zero themselves. - -## How It Works - -Agent Zero uses the [Flaredantic](https://pypi.org/project/flaredantic/) library to create secure tunnels to expose your local instance to the internet. These tunnels: - -- Are secure (HTTPS) -- Don't require any configuration -- Generate unique URLs for each session -- Can be regenerated on demand - -## Using the Tunnel Feature - -1. Open the settings and navigate to the "External Services" tab -2. Click on "Flare Tunnel" in the navigation menu -3. Click the "Create Tunnel" button to generate a new tunnel -4. Once created, the tunnel URL will be displayed and can be copied to share with others -5. The tunnel URL will remain active until you stop the tunnel or close the Agent Zero application - -## Security Considerations - -When sharing your Agent Zero instance via a tunnel: - -- Anyone with the URL can access your Agent Zero instance -- No additional authentication is added beyond what your Agent Zero instance already has -- Consider setting up authentication if you're sharing sensitive information -- The tunnel exposes your local Agent Zero instance, not your entire system - -## Troubleshooting - -If you encounter issues with the tunnel feature: - -1. Check your internet connection -2. Try refreshing the tunnel URL -3. Restart Agent Zero -4. Check the console logs for any error messages - -## Adding Authentication - -To add basic authentication to your Agent Zero instance when using tunnels, you can set the following environment variables: - -``` -AUTH_LOGIN=your_username -AUTH_PASSWORD=your_password -``` - -Alternatively, you can configure the username and password directly in the settings: - -1. Open the settings modal in the Agent Zero UI -2. Navigate to the "External Services" tab -3. Find the "Authentication" section -4. Enter your desired username and password in the "UI Login" and "UI Password" fields -5. Click the "Save" button to apply the changes - -This will require users to enter these credentials when accessing your tunneled Agent Zero instance. When attempting to create a tunnel without authentication configured, Agent Zero will display a security warning. \ No newline at end of file diff --git a/docs/advanced/architecture.md b/docs/developer/architecture.md similarity index 96% rename from docs/advanced/architecture.md rename to docs/developer/architecture.md index f8f735a81..82a91281b 100644 --- a/docs/advanced/architecture.md +++ b/docs/developer/architecture.md @@ -2,9 +2,6 @@ Agent Zero is built on a flexible and modular architecture designed for extensibility and customization. This section outlines the key components and the interactions between them. ## System Architecture -This simplified diagram illustrates the hierarchical relationship between agents and their interaction with tools, extensions, skills, prompts, memory and knowledge base. - -![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 skills) to perform its tasks. @@ -60,7 +57,6 @@ This architecture ensures: | `/webui/css` | Stylesheets | | `/webui/js` | JavaScript modules | | `/webui/public` | Static assets | -| `/work_dir` | Working directory (inside Docker: `/a0/work_dir`) | ### Key Files | File | Description | @@ -75,7 +71,6 @@ This architecture ensures: | `prepare.py` | Environment preparation | | `requirements.txt` | Python dependencies | | `run_ui.py` | Web UI launcher | -| `run_tunnel.py` | Tunnel launcher | > [!NOTE] > In the Docker runtime, the framework lives under `/a0` inside the container. Data persists as long as the container exists. For upgrades, prefer **Backup & Restore** instead of mapping the full `/a0` directory. @@ -100,8 +95,6 @@ Communication flows between agents through messages, which are structured accord #### 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 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 @@ -145,7 +138,7 @@ In cases where SearXNG might not return satisfactory results, Agent Zero can be #### Custom Tools Users can create custom tools to extend Agent Zero's capabilities. Custom tools can be integrated into the framework by defining a tool specification, which includes the tool's prompt. Place these prompt overrides in your agent profile: -1. Create `agent.system.tool.$TOOL_NAME.md` in `agents//prompts/` (or in `prompts/` for global defaults) +1. Create `agent.system.tool.$TOOL_NAME.md` in `agents//prompts/` 2. Add the reference in `agent.system.tools.md` within the same prompt scope 3. If needed, implement tool class in `python/tools` using `Tool` base class 4. Follow existing patterns for consistency @@ -225,7 +218,7 @@ The `prompts` directory contains various Markdown files that control agent behav - **Tool Prompts**: Organized in tool-specific files for modularity #### Custom Prompts (Post v0.9.7) -1. Create or select an agent profile under `agents//` +1. Create or clone an existing agent profile under `agents//` 2. Add only the prompt files you want to override in `agents//prompts/` 3. Agent Zero merges these overrides with the default prompts automatically 4. Select the **Agent Profile** in Settings to activate the overrides @@ -247,8 +240,6 @@ The `prompts` directory contains various Markdown files that control agent behav 3. New rules are merged with existing ruleset 4. Updated behavior is immediately applied -![Behavior Adjustment](res/ui-behavior-change-chat.png) - - **Integration with System Prompt**: - Behavior rules are injected at the start of the system prompt - Rules are formatted in a structured markdown format @@ -348,4 +339,4 @@ Extensions can be found in `python/extensions` directory: > [!NOTE] > Consider contributing valuable custom components to the main repository. -> See [Contributing](contribution.md) for more information. +> See [Contributing](../guides/contribution.md) for more information. diff --git a/docs/advanced/connectivity.md b/docs/developer/connectivity.md similarity index 99% rename from docs/advanced/connectivity.md rename to docs/developer/connectivity.md index 9b702af87..ba9e4e9c5 100644 --- a/docs/advanced/connectivity.md +++ b/docs/developer/connectivity.md @@ -605,7 +605,7 @@ It provides two endpoint types: - **Streamable HTTP (`/mcp/http/`):** For clients that use streamable HTTP requests. > [!NOTE] -> This section describes **Agent Zero as an MCP server**. To configure Agent Zero as an MCP **client** (consuming external tools), see [MCP Setup](mcp_setup.md). +> This section describes **Agent Zero as an MCP server**. To configure Agent Zero as an MCP **client** (consuming external tools), see [MCP Setup](../guides/mcp-setup.md). ### Example MCP Server Configuration @@ -686,4 +686,4 @@ When a project is specified: - Maintain strict context separation between agents > [!TIP] -> If you need tool access rather than chat delegation, use MCP instead of A2A. See [MCP Setup](mcp_setup.md). +> If you need tool access rather than chat delegation, use MCP instead of A2A. See [MCP Setup](../guides/mcp-setup.md). diff --git a/docs/development/contributing-skills.md b/docs/developer/contributing-skills.md similarity index 82% rename from docs/development/contributing-skills.md rename to docs/developer/contributing-skills.md index 4dba0dc8a..97b8a8c4a 100644 --- a/docs/development/contributing-skills.md +++ b/docs/developer/contributing-skills.md @@ -2,17 +2,6 @@ Welcome to the Agent Zero Skills ecosystem! This guide will help you create, test, and share skills with the community. -## Table of Contents - -- [What is a Skill?](#what-is-a-skill) -- [Quick Start](#quick-start) -- [SKILL.md Standard](#skillmd-standard) -- [Creating Your First Skill](#creating-your-first-skill) -- [Best Practices](#best-practices) -- [Testing Skills](#testing-skills) -- [Sharing Skills](#sharing-skills) -- [Community Guidelines](#community-guidelines) - --- ## What is a Skill? @@ -301,28 +290,6 @@ One skill = one expertise area. If your skill is getting too long, split it: 3. **Verify Instructions:** Follow your own instructions manually to ensure they work. -### Automated Testing - -Create a test file `test_skill.py` in your skill folder: - -```python -"""Tests for my-awesome-skill""" -import pytest -from python.helpers.skills import SkillManager - -def test_skill_loads(): - manager = SkillManager() - skill = manager.get_skill("my-awesome-skill") - assert skill is not None - assert skill.name == "my-awesome-skill" - -def test_skill_has_required_fields(): - manager = SkillManager() - skill = manager.get_skill("my-awesome-skill") - assert skill.description - assert len(skill.description) > 20 -``` - --- ## Sharing Skills @@ -399,34 +366,6 @@ my-skills-collection/ - Respect licenses of any code you include - Don't include proprietary or copyrighted content -### Code of Conduct - -- Be respectful in all interactions -- Provide constructive feedback -- Help newcomers learn -- Report issues responsibly - ---- - -## Resources - -### Official Documentation - -- [Agent Zero Documentation](./README.md) -- [Architecture Guide](./architecture.md) -- [Skills System](./architecture.md#skills-system) - -### Community - -- [GitHub Issues](https://github.com/agent0ai/agent-zero/issues) -- [Discussions](https://github.com/agent0ai/agent-zero/discussions) - -### External Resources - -- [Skills Marketplace](https://skillsmp.com) -- [Awesome Agent Skills](https://github.com/skillmatic-ai/awesome-agent-skills) -- [Anthropic Skills Repository](https://github.com/anthropics/skills) - --- ## FAQ @@ -453,16 +392,4 @@ my-skills-collection/ --- -## Example Skills to Learn From - -Check out these well-structured skills in `skills/`: - -- `brainstorming/` - Requirements exploration workflow -- `debugging/` - Systematic debugging methodology -- `tdd/` - Test-driven development process -- `code-review/` - Comprehensive review checklist -- `create-skill/` - Meta-skill for creating new skills - ---- - Happy skill building! 🚀 diff --git a/docs/development/extensibility.md b/docs/developer/extensions.md similarity index 95% rename from docs/development/extensibility.md rename to docs/developer/extensions.md index 66fb0c9c6..dfccbb90b 100644 --- a/docs/development/extensibility.md +++ b/docs/developer/extensions.md @@ -1,4 +1,4 @@ -# Extensibility framework in Agent Zero +# Extensions Framework > [!NOTE] > Agent Zero is built with extensibility in mind. It provides a framework for creating custom extensions, agents, skills, and tools that can be used to enhance the functionality of the framework. @@ -99,18 +99,6 @@ When a tool is called, it goes through the following lifecycle: 3. `execute` method (main functionality) 4. `after_execution` method -### Instruments -Instruments are reusable scripts and procedures stored on disk and indexed in memory. They are **not** always present in the system prompt, making them lighter-weight than tools for specialized workflows. - -- **When to use tools:** core capabilities you want always available in the prompt -- **When to use instruments:** repeatable scripts or procedures that can be recalled on demand - -#### Creating Instruments -1. Create a folder in `instruments/custom/` (no spaces in name) -2. Add a `.md` description file explaining inputs/outputs -3. Add a script (`.sh`, `.py`, etc.) with the implementation -4. Restart or reload so the agent indexes the instrument - ### API Endpoints API endpoints expose Agent Zero functionality to external systems or the user interface. They are modular and can be extended or replaced. diff --git a/docs/developer/mcp-configuration.md b/docs/developer/mcp-configuration.md new file mode 100644 index 000000000..b56044238 --- /dev/null +++ b/docs/developer/mcp-configuration.md @@ -0,0 +1,404 @@ +# Advanced MCP Configuration + +This guide provides comprehensive technical details for configuring and utilizing external tool providers through the Model Context Protocol (MCP) with Agent Zero. This allows Agent Zero to leverage tools hosted by separate local or remote MCP-compliant servers. + +> [!NOTE] +> For a quick start guide on adding MCP servers through the UI, see [MCP Setup](../guides/mcp-setup.md). + +> [!NOTE] +> This guide covers Agent Zero as an MCP **client**. To expose Agent Zero as an MCP **server**, see [Connectivity → MCP Server](connectivity.md#mcp-server-connectivity). + +## MCP Server Types + +Agent Zero supports three main types of MCP servers: + +1. **Local Stdio Servers**: Local executables that Agent Zero communicates with via standard input/output (stdio). +2. **Remote SSE Servers**: Network-accessible servers that use Server-Sent Events (SSE), usually over HTTP/S. +3. **Remote Streaming HTTP Servers**: Servers using the streamable HTTP transport protocol for MCP communication. + +## How Agent Zero Consumes MCP Tools + +Agent Zero discovers and integrates MCP tools dynamically through the following process: + +1. **Configuration**: MCP servers are defined in the Agent Zero configuration, primarily through the Settings UI. +2. **Saving Settings**: When saved via the UI, Agent Zero updates `usr/settings.json`, specifically the `"mcp_servers"` key. +3. **Server Startup**: Agent Zero initializes configured MCP servers (stdio) or connects to them (remote). For `npx`/`uvx` based servers, the first run downloads packages. +4. **Tool Discovery**: Upon initialization, Agent Zero connects to each enabled MCP server and queries for available tools, descriptions, and parameters. +5. **Dynamic Prompting**: Tool information is injected into the agent's system prompt. The `{{tools}}` placeholder in templates (e.g., `prompts/agent.system.mcp_tools.md`) is replaced with the formatted tool list. +6. **Tool Invocation**: When the LLM requests an MCP tool, Agent Zero's `process_tools` method (`mcp_handler.py`) routes the request to the appropriate MCP server. + +## Configuration File Structure + +### Settings Location + +MCP server configurations are stored in: +- `usr/settings.json` (primary storage) + +### The `mcp_servers` Setting + +Within `usr/settings.json`, MCP servers are defined under the `"mcp_servers"` key: + +- **Value Type**: JSON formatted string containing: + - A JSON object with `"mcpServers"` (recommended, matches UI) + - Or a JSON array of server configurations +- **Default Value**: Empty config (`{"mcpServers": {}}`) +- **Manual Editing**: While UI configuration is recommended, manual editing is possible. Ensure proper JSON string formatting with escaped quotes. + +### Recommended Configuration Format + +```json +{ + "mcpServers": { + "sqlite": { + "command": "uvx", + "args": ["mcp-server-sqlite", "--db-path", "/root/db.sqlite"] + }, + "deep-wiki": { + "description": "Use this MCP to analyze GitHub repositories", + "url": "https://mcp.deepwiki.com/sse" + } + } +} +``` + +> [!NOTE] +> In `usr/settings.json`, the entire `"mcp_servers"` value is stored as a single string. The Settings UI handles escaping automatically. + +### Upgrading Existing Installations + +For existing `settings.json` files without MCP support: + +1. Ensure you're running a version with MCP support +2. Open the settings UI +3. Save settings (even without changes) +4. This writes the complete settings structure including `"mcp_servers": ""` +5. Configure servers via UI or careful manual editing + +## Server Configuration Templates + +### 1. Local Stdio Server + +```json +{ + "name": "My Local Tool Server", + "description": "Optional: A brief description of this server.", + "type": "stdio", + "command": "python", + "args": ["path/to/your/mcp_stdio_script.py", "--some-arg"], + "env": { + "PYTHONPATH": "/path/to/custom/libs:.", + "ANOTHER_VAR": "value" + }, + "encoding": "utf-8", + "encoding_error_handler": "strict", + "disabled": false +} +``` + +**Configuration Fields:** +- `type`: Optional, auto-detected. Can be `"stdio"`, `"sse"`, or streaming variants +- `command`: **Required**. The executable to run +- `args`: Optional list of command arguments +- `env`: Optional environment variables for the process +- `encoding`: Optional, default `"utf-8"` +- `encoding_error_handler`: Optional, can be `"strict"`, `"ignore"`, or `"replace"` + +### 2. Remote SSE Server + +```json +{ + "name": "My Remote API Tools", + "description": "Optional: Description of the remote SSE server.", + "type": "sse", + "url": "https://api.example.com/mcp-sse-endpoint", + "headers": { + "Authorization": "Bearer YOUR_API_KEY_OR_TOKEN", + "X-Custom-Header": "some_value" + }, + "timeout": 5.0, + "sse_read_timeout": 300.0, + "disabled": false +} +``` + +**Configuration Fields:** +- `url`: **Required**. Full URL for the SSE endpoint +- `headers`: Optional HTTP headers for authentication/custom headers +- `timeout`: Optional connection timeout in seconds (default: 5.0) +- `sse_read_timeout`: Optional read timeout for SSE stream (default: 300.0) + +### 3. Remote Streaming HTTP Server + +```json +{ + "name": "My Streaming HTTP Tools", + "description": "Optional: Description of the remote streaming HTTP server.", + "type": "streaming-http", + "url": "https://api.example.com/mcp-http-endpoint", + "headers": { + "Authorization": "Bearer YOUR_API_KEY_OR_TOKEN", + "X-Custom-Header": "some_value" + }, + "timeout": 5.0, + "sse_read_timeout": 300.0, + "disabled": false +} +``` + +**Streaming HTTP Variants:** +Type can be: `"http-stream"`, `"streaming-http"`, `"streamable-http"`, or `"http-streaming"` + +### Example in settings.json + +```json +{ + "mcp_servers": "[{'name': 'MyPythonTools', 'command': 'python3', 'args': ['mcp_scripts/my_server.py'], 'disabled': false}, {'name': 'ExternalAPI', 'url': 'https://data.example.com/mcp', 'headers': {'X-Auth-Token': 'supersecret'}, 'disabled': false}]" +} +``` + +## Key Configuration Fields + +### Common Fields + +- **`name`**: Unique server identifier. Used to prefix tools (e.g., `server_name.tool_name`). Normalized internally (lowercase, spaces/hyphens → underscores) +- **`type`**: Optional explicit type. Auto-detected if omitted based on `command` (stdio) or `url` (defaults to sse) +- **`disabled`**: Boolean. Set `true` to ignore this server without removing configuration +- **`description`**: Optional human-readable description + +### Type-Specific Required Fields + +- **Stdio servers**: Require `command` +- **Remote servers**: Require `url` + +## Docker Networking Considerations + +### Agent Zero in Docker, MCP Server on Host + +**macOS/Windows:** +```json +{ + "url": "http://host.docker.internal:PORT/endpoint" +} +``` + +**Linux:** +- Run MCP server in the same Docker network +- Reference by container name: `http://container_name:PORT/endpoint` + +### Remote MCP Servers + +Use standard HTTPS URLs: +```json +{ + "url": "https://api.example.com/mcp-endpoint" +} +``` + +## Using MCP Tools + +### Tool Naming Convention + +MCP tools are prefixed with the normalized server name: + +- Server name: `"sequential-thinking"` +- Tool name from server: `"run_chain"` +- Final tool name in Agent Zero: `sequential_thinking.run_chain` + +### Agent Interaction + +Instruct the agent to use MCP tools directly: + +``` +"Agent, use the sequential_thinking.run_chain tool with the following input..." +``` + +The LLM formulates the appropriate JSON request automatically. + +### Execution Flow + +1. `process_tools` method receives tool request +2. `mcp_handler.py` checks if tool name exists in `MCPConfig` +3. If found: delegates to corresponding MCP server +4. If not found: attempts to find built-in tool with that name + +This prioritization allows MCP tools to extend or override built-in functionality. + +## Troubleshooting + +### Server Not Connecting + +**Check status in UI:** +- Settings → MCP/A2A → External MCP Servers +- Green indicator = connected +- Red indicator = connection failed + +**Common issues:** +- Wrong URL or port +- Missing authentication headers +- Network/firewall blocking connection +- Server not running + +### Tools Not Appearing + +**Verification steps:** +1. Confirm server shows as connected (green status) +2. Check server exposes tools (count shown in UI) +3. Verify tool names match server documentation +4. For `npx`/`uvx` servers, first run downloads packages (may take time) + +### Encoding Issues (Stdio Servers) + +Adjust encoding settings: +```json +{ + "encoding": "utf-8", + "encoding_error_handler": "replace" +} +``` + +Error handler options: +- `"strict"`: Fail on encoding errors (default) +- `"ignore"`: Skip problematic characters +- `"replace"`: Replace with placeholder character + +## Security Considerations + +### API Keys and Secrets + +Store sensitive data securely: +- Use environment variables when possible +- Avoid committing secrets to version control +- Use header-based authentication for remote servers + +### Network Security + +- Use HTTPS for remote MCP servers +- Validate SSL certificates (default behavior) +- Restrict network access to trusted servers only + +### Local Stdio Servers + +- Only run trusted executables +- Review server code before execution +- Use environment isolation when possible + +## Performance Optimization + +### Connection Timeouts + +Adjust for network conditions: +```json +{ + "timeout": 10.0, // Initial connection + "sse_read_timeout": 600.0 // Long-running operations +} +``` + +### Server Pooling + +For high-frequency tool usage: +- Agent Zero maintains persistent connections to remote servers +- Stdio servers are kept alive between tool calls +- Reduces overhead for repeated operations + +## Advanced Examples + +### Multi-Server Configuration + +```json +{ + "mcpServers": { + "browser": { + "command": "npx", + "args": ["-y", "chrome-devtools-mcp@latest"] + }, + "database": { + "command": "uvx", + "args": ["mcp-server-sqlite", "--db-path", "/data/app.db"] + }, + "external-api": { + "url": "https://api.example.com/mcp", + "headers": { + "Authorization": "Bearer token123" + } + }, + "backup-api": { + "url": "https://backup.example.com/mcp", + "disabled": true + } + } +} +``` + +### Custom Environment Variables + +```json +{ + "mcpServers": { + "python-tools": { + "command": "python3", + "args": ["/opt/tools/mcp_server.py"], + "env": { + "PYTHONPATH": "/opt/libs:/usr/local/lib/python3.9", + "API_KEY": "secret_key", + "DEBUG": "true" + } + } + } +} +``` + +## Integration Patterns + +### Tool Composition + +Combine multiple MCP servers for complex workflows: +1. Browser MCP for data extraction +2. Database MCP for storage +3. Workflow MCP for orchestration + +Agent Zero can chain these tools automatically based on task requirements. + +### Fallback Configuration + +```json +{ + "mcpServers": { + "primary-service": { + "url": "https://primary.example.com/mcp" + }, + "fallback-service": { + "url": "https://fallback.example.com/mcp", + "disabled": true + } + } +} +``` + +Enable fallback manually when primary service is unavailable. + +## Development and Testing + +### Testing MCP Configurations + +1. Add server with `disabled: false` +2. Save and check connection status +3. Test individual tools via agent prompts +4. Monitor logs for errors +5. Adjust configuration as needed + +### Creating Custom MCP Servers + +For developing custom MCP servers: +- Follow MCP protocol specifications +- Implement stdio or HTTP transport +- Provide clear tool descriptions +- Test with Agent Zero before production + +See [MCP Protocol Documentation](https://modelcontextprotocol.io) for implementation details. + +## Related Documentation + +- [MCP Setup](../guides/mcp-setup.md) - Quick start guide +- [Connectivity: MCP Server](connectivity.md#mcp-server-connectivity) - Exposing Agent Zero as MCP server +- [Advanced: Extensions](extensions.md) - Custom tools and extensions diff --git a/docs/advanced/notifications.md b/docs/developer/notifications.md similarity index 100% rename from docs/advanced/notifications.md rename to docs/developer/notifications.md diff --git a/docs/advanced/websockets.md b/docs/developer/websockets.md similarity index 99% rename from docs/advanced/websockets.md rename to docs/developer/websockets.md index 24a11ae95..d2f44e775 100644 --- a/docs/advanced/websockets.md +++ b/docs/developer/websockets.md @@ -1,9 +1,5 @@ # WebSocket Infrastructure Guide -**Audience**: Backend and frontend developers building real-time features on Agent Zero -**Updated**: 2026-01-02 -**Related Specs**: `specs/003-websocket-event-handlers/*` - This guide consolidates everything you need to design, implement, and troubleshoot Agent Zero WebSocket flows. It complements the feature specification by describing day-to-day developer tasks, showing how backend handlers and frontend clients cooperate, and documenting practical patterns for producers and consumers on both sides of the connection. --- diff --git a/docs/development/designs/backup-specification-backend.md b/docs/development/designs/backup-specification-backend.md deleted file mode 100644 index aa03857c8..000000000 --- a/docs/development/designs/backup-specification-backend.md +++ /dev/null @@ -1,1708 +0,0 @@ -# Agent Zero Backup/Restore Backend Specification - -## Overview -This specification defines the backend implementation for Agent Zero's backup and restore functionality, providing users with the ability to backup and restore their Agent Zero configurations, data, and custom files using glob pattern-based selection. The backup functionality is implemented as a dedicated "backup" tab in the settings interface for easy access and organization. - -## Core Requirements - -### Backup Flow -1. User configures backup paths using glob patterns in settings modal -2. Backend creates zip archive with selected files and metadata -3. Archive is provided as download to user - -### Restore Flow -1. User uploads backup archive in settings modal -2. Backend extracts and validates metadata -3. User confirms file list and destination paths -4. Backend restores files to specified locations - -## Backend Architecture - -### 1. Settings Integration - -#### Settings Schema Extension -Add backup/restore section with dedicated tab to `python/helpers/settings.py`: - -**Integration Notes:** -- Leverages existing settings button handler pattern (follows MCP servers example) -- Integrates with Agent Zero's established error handling and toast notification system -- Uses existing file operation helpers with RFC support for development mode compatibility - -```python -# Add to SettingsSection in convert_out() function -backup_section: SettingsSection = { - "id": "backup_restore", - "title": "Backup & Restore", - "description": "Backup and restore Agent Zero data and configurations using glob pattern-based file selection.", - "fields": [ - { - "id": "backup_create", - "title": "Create Backup", - "description": "Create a backup archive of selected files and configurations using customizable patterns.", - "type": "button", - "value": "Create Backup", - }, - { - "id": "backup_restore", - "title": "Restore from Backup", - "description": "Restore files and configurations from a backup archive with pattern-based selection.", - "type": "button", - "value": "Restore Backup", - } - ], - "tab": "backup", # Dedicated backup tab for clean organization -} -``` - -#### Default Backup Configuration -The backup system now uses **resolved absolute filesystem paths** instead of placeholders, ensuring compatibility across different deployment environments (Docker containers, direct host installations, different users). - -```python -def _get_default_patterns(self) -> str: - """Get default backup patterns with resolved absolute paths""" - # Ensure paths don't have double slashes - agent_root = self.agent_zero_root.rstrip('/') - user_home = self.user_home.rstrip('/') - - return f"""# Agent Zero Knowledge (excluding defaults) -{agent_root}/knowledge/** -!{agent_root}/knowledge/default/** - -# Agent Zero Instruments (excluding defaults) -{agent_root}/instruments/** -!{agent_root}/instruments/default/** - -# Memory (excluding embeddings cache) -{agent_root}/memory/** -!{agent_root}/memory/embeddings/** - -# Configuration and Settings (CRITICAL) -{agent_root}/.env -{agent_root}/tmp/settings.json -{agent_root}/tmp/chats/** -{agent_root}/tmp/tasks/** -{agent_root}/tmp/uploads/** - -# User Home Directory (excluding hidden files by default) -{user_home}/** -!{user_home}/.*/** -!{user_home}/.*""" -``` - -**Example Resolved Patterns** (varies by environment): -``` -# Docker container environment -/a0/knowledge/** -!/a0/knowledge/default/** -/root/** -!/root/.*/** -!/root/.* - -# Host environment -/home/rafael/a0/data/knowledge/** -!/home/rafael/a0/data/knowledge/default/** -/home/rafael/** -!/home/rafael/.*/** -!/home/rafael/.* -``` - -> **⚠️ CRITICAL FILE NOTICE**: The `{agent_root}/.env` file contains essential configuration including API keys, model settings, and runtime parameters. This file is **REQUIRED** for Agent Zero to function properly and should always be included in backups alongside `settings.json`. Without this file, restored Agent Zero instances will not have access to configured language models or external services. - -### 2. API Endpoints - -#### 2.1 Backup Test Endpoint -**File**: `python/api/backup_test.py` - -```python -from python.helpers.api import ApiHandler -from flask import Request, Response -from python.helpers.backup import BackupService -import json - -class BackupTest(ApiHandler): - """Test backup patterns and return matched files""" - - @classmethod - def requires_auth(cls) -> bool: - return True - - @classmethod - def requires_loopback(cls) -> bool: - return True - - async def process(self, input: dict, request: Request) -> dict | Response: - patterns = input.get("patterns", "") - include_hidden = input.get("include_hidden", False) - max_files = input.get("max_files", 1000) # Limit for preview - - try: - backup_service = BackupService() - matched_files = await backup_service.test_patterns( - patterns=patterns, - include_hidden=include_hidden, - max_files=max_files - ) - - return { - "success": True, - "files": matched_files, - "total_count": len(matched_files), - "truncated": len(matched_files) >= max_files - } - - except Exception as e: - return { - "success": False, - "error": str(e) - } -``` - -#### 2.2 Backup Create Endpoint -**File**: `python/api/backup_create.py` - -```python -from python.helpers.api import ApiHandler -from flask import Request, Response, send_file -from python.helpers.backup import BackupService -import tempfile -import os - -class BackupCreate(ApiHandler): - """Create backup archive and provide download""" - - @classmethod - def requires_auth(cls) -> bool: - return True - - @classmethod - def requires_loopback(cls) -> bool: - return True - - async def process(self, input: dict, request: Request) -> dict | Response: - patterns = input.get("patterns", "") - include_hidden = input.get("include_hidden", False) - backup_name = input.get("backup_name", "agent-zero-backup") - - try: - backup_service = BackupService() - zip_path = await backup_service.create_backup( - patterns=patterns, - include_hidden=include_hidden, - backup_name=backup_name - ) - - # Return file for download - return send_file( - zip_path, - as_attachment=True, - download_name=f"{backup_name}.zip", - mimetype='application/zip' - ) - - except Exception as e: - return { - "success": False, - "error": str(e) - } -``` - -#### 2.3 Backup Restore Endpoint -**File**: `python/api/backup_restore.py` - -```python -from python.helpers.api import ApiHandler -from flask import Request, Response -from python.helpers.backup import BackupService -from werkzeug.datastructures import FileStorage - -class BackupRestore(ApiHandler): - """Restore files from backup archive""" - - @classmethod - def requires_auth(cls) -> bool: - return True - - @classmethod - def requires_loopback(cls) -> bool: - return True - - async def process(self, input: dict, request: Request) -> dict | Response: - # Handle file upload - if 'backup_file' not in request.files: - return {"success": False, "error": "No backup file provided"} - - backup_file: FileStorage = request.files['backup_file'] - if backup_file.filename == '': - return {"success": False, "error": "No file selected"} - - # Get restore configuration - restore_patterns = input.get("restore_patterns", "") - overwrite_policy = input.get("overwrite_policy", "overwrite") # overwrite, skip, backup - - try: - backup_service = BackupService() - result = await backup_service.restore_backup( - backup_file=backup_file, - restore_patterns=restore_patterns, - overwrite_policy=overwrite_policy - ) - - return { - "success": True, - "restored_files": result["restored_files"], - "skipped_files": result["skipped_files"], - "errors": result["errors"] - } - - except Exception as e: - return { - "success": False, - "error": str(e) - } -``` - -#### 2.4 Backup Restore Preview Endpoint -**File**: `python/api/backup_restore_preview.py` - -```python -from python.helpers.api import ApiHandler -from flask import Request, Response -from python.helpers.backup import BackupService -from werkzeug.datastructures import FileStorage - -class BackupRestorePreview(ApiHandler): - """Preview files that would be restored based on patterns""" - - @classmethod - def requires_auth(cls) -> bool: - return True - - @classmethod - def requires_loopback(cls) -> bool: - return True - - async def process(self, input: dict, request: Request) -> dict | Response: - # Handle file upload - if 'backup_file' not in request.files: - return {"success": False, "error": "No backup file provided"} - - backup_file: FileStorage = request.files['backup_file'] - if backup_file.filename == '': - return {"success": False, "error": "No file selected"} - - restore_patterns = input.get("restore_patterns", "") - - try: - backup_service = BackupService() - preview_result = await backup_service.preview_restore( - backup_file=backup_file, - restore_patterns=restore_patterns - ) - - return { - "success": True, - "files": preview_result["files"], - "total_count": preview_result["total_count"], - "skipped_count": preview_result["skipped_count"] - } - - except Exception as e: - return { - "success": False, - "error": str(e) - } -``` - -#### 2.5 Backup File Preview Grouped Endpoint -**File**: `python/api/backup_preview_grouped.py` - -```python -from python.helpers.api import ApiHandler -from flask import Request, Response -from python.helpers.backup import BackupService - -class BackupPreviewGrouped(ApiHandler): - """Get grouped file preview with smart directory organization""" - - @classmethod - def requires_auth(cls) -> bool: - return True - - @classmethod - def requires_loopback(cls) -> bool: - return True - - async def process(self, input: dict, request: Request) -> dict | Response: - patterns = input.get("patterns", "") - include_hidden = input.get("include_hidden", False) - max_depth = input.get("max_depth", 3) - search_filter = input.get("search_filter", "") - - try: - backup_service = BackupService() - grouped_preview = await backup_service.get_grouped_file_preview( - patterns=patterns, - include_hidden=include_hidden, - max_depth=max_depth, - search_filter=search_filter - ) - - return { - "success": True, - "groups": grouped_preview["groups"], - "stats": grouped_preview["stats"], - "total_files": grouped_preview["total_files"], - "total_size": grouped_preview["total_size"] - } - - except Exception as e: - return { - "success": False, - "error": str(e) - } -``` - -#### 2.6 Backup Progress Stream Endpoint -**File**: `python/api/backup_progress_stream.py` - -```python -from python.helpers.api import ApiHandler -from flask import Request, Response, stream_template -from python.helpers.backup import BackupService -import json - -class BackupProgressStream(ApiHandler): - """Stream real-time backup progress""" - - @classmethod - def requires_auth(cls) -> bool: - return True - - @classmethod - def requires_loopback(cls) -> bool: - return True - - async def process(self, input: dict, request: Request) -> dict | Response: - patterns = input.get("patterns", "") - include_hidden = input.get("include_hidden", False) - backup_name = input.get("backup_name", "agent-zero-backup") - - def generate_progress(): - try: - backup_service = BackupService() - - # Generator function for streaming progress - for progress_data in backup_service.create_backup_with_progress( - patterns=patterns, - include_hidden=include_hidden, - backup_name=backup_name - ): - yield f"data: {json.dumps(progress_data)}\n\n" - - except Exception as e: - yield f"data: {json.dumps({'error': str(e), 'completed': True})}\n\n" - - return Response( - generate_progress(), - content_type='text/event-stream', - headers={ - 'Cache-Control': 'no-cache', - 'Connection': 'keep-alive' - } - ) -``` - -#### 2.7 Backup Inspect Endpoint -**File**: `python/api/backup_inspect.py` - -```python -from python.helpers.api import ApiHandler -from flask import Request, Response -from python.helpers.backup import BackupService -from werkzeug.datastructures import FileStorage - -class BackupInspect(ApiHandler): - """Inspect backup archive and return metadata""" - - @classmethod - def requires_auth(cls) -> bool: - return True - - @classmethod - def requires_loopback(cls) -> bool: - return True - - async def process(self, input: dict, request: Request) -> dict | Response: - # Handle file upload - if 'backup_file' not in request.files: - return {"success": False, "error": "No backup file provided"} - - backup_file: FileStorage = request.files['backup_file'] - if backup_file.filename == '': - return {"success": False, "error": "No file selected"} - - try: - backup_service = BackupService() - metadata = await backup_service.inspect_backup(backup_file) - - return { - "success": True, - "metadata": metadata, - "files": metadata.get("files", []), - "include_patterns": metadata.get("include_patterns", []), # Array of include patterns - "exclude_patterns": metadata.get("exclude_patterns", []), # Array of exclude patterns - "default_patterns": metadata.get("backup_config", {}).get("default_patterns", ""), - "agent_zero_version": metadata.get("agent_zero_version", "unknown"), - "timestamp": metadata.get("timestamp", ""), - "backup_name": metadata.get("backup_name", ""), - "total_files": metadata.get("total_files", len(metadata.get("files", []))), - "backup_size": metadata.get("backup_size", 0), - "include_hidden": metadata.get("include_hidden", False) - } - - except Exception as e: - return { - "success": False, - "error": str(e) - } -``` - -### 3. Backup Service Implementation - -#### Core Service Class -**File**: `python/helpers/backup.py` - -**RFC Integration Notes:** -The BackupService leverages Agent Zero's existing file operation helpers which already support RFC (Remote Function Call) routing for development mode. This ensures seamless operation whether running in direct mode or with container isolation. - -```python -import zipfile -import json -import os -import tempfile -import datetime -from typing import List, Dict, Any, Optional -from pathspec import PathSpec -from pathspec.patterns import GitWildMatchPattern -from python.helpers import files, runtime, git -import shutil - -class BackupService: - """Core backup and restore service for Agent Zero""" - - def __init__(self): - self.agent_zero_version = self._get_agent_zero_version() - self.agent_zero_root = files.get_abs_path("") # Resolved Agent Zero root - self.user_home = os.path.expanduser("~") # Current user's home directory - - def _get_default_patterns(self) -> str: - """Get default backup patterns from specification""" - return DEFAULT_BACKUP_PATTERNS - - def _get_agent_zero_version(self) -> str: - """Get current Agent Zero version""" - try: - # Get version from git info (same as run_ui.py) - gitinfo = git.get_git_info() - return gitinfo.get("version", "development") - except: - return "unknown" - - def _resolve_path(self, pattern_path: str) -> str: - """Resolve pattern path to absolute system path (now patterns are already absolute)""" - return pattern_path - - def _unresolve_path(self, abs_path: str) -> str: - """Convert absolute path back to pattern path (now patterns are already absolute)""" - return abs_path - - def _parse_patterns(self, patterns: str) -> tuple[list[str], list[str]]: - """Parse patterns string into include and exclude pattern arrays""" - include_patterns = [] - exclude_patterns = [] - - for line in patterns.split('\n'): - line = line.strip() - if not line or line.startswith('#'): - continue - - if line.startswith('!'): - # Exclude pattern - exclude_patterns.append(line[1:]) # Remove the '!' prefix - else: - # Include pattern - include_patterns.append(line) - - return include_patterns, exclude_patterns - - def _patterns_to_string(self, include_patterns: list[str], exclude_patterns: list[str]) -> str: - """Convert pattern arrays back to patterns string for pathspec processing""" - patterns = [] - - # Add include patterns - for pattern in include_patterns: - patterns.append(pattern) - - # Add exclude patterns with '!' prefix - for pattern in exclude_patterns: - patterns.append(f"!{pattern}") - - return '\n'.join(patterns) - - async def _get_system_info(self) -> Dict[str, Any]: - """Collect system information for metadata""" - import platform - import psutil - - try: - return { - "platform": platform.platform(), - "system": platform.system(), - "release": platform.release(), - "version": platform.version(), - "machine": platform.machine(), - "processor": platform.processor(), - "architecture": platform.architecture()[0], - "hostname": platform.node(), - "python_version": platform.python_version(), - "cpu_count": str(psutil.cpu_count()), - "memory_total": str(psutil.virtual_memory().total), - "disk_usage": str(psutil.disk_usage('/').total if os.path.exists('/') else 0) - } - except Exception as e: - return {"error": f"Failed to collect system info: {str(e)}"} - - async def _get_environment_info(self) -> Dict[str, Any]: - """Collect environment information for metadata""" - try: - return { - "user": os.environ.get("USER", "unknown"), - "home": os.environ.get("HOME", "unknown"), - "shell": os.environ.get("SHELL", "unknown"), - "path": os.environ.get("PATH", "")[:200] + "..." if len(os.environ.get("PATH", "")) > 200 else os.environ.get("PATH", ""), - "timezone": str(datetime.datetime.now().astimezone().tzinfo), - "working_directory": os.getcwd(), - "agent_zero_root": files.get_abs_path(""), - "runtime_mode": "development" if runtime.is_development() else "production" - } - except Exception as e: - return {"error": f"Failed to collect environment info: {str(e)}"} - - async def _get_backup_author(self) -> str: - """Get backup author/system identifier""" - try: - import getpass - username = getpass.getuser() - hostname = platform.node() - return f"{username}@{hostname}" - except: - return "unknown" - - async def _calculate_file_checksums(self, matched_files: List[Dict[str, Any]]) -> Dict[str, str]: - """Calculate SHA-256 checksums for files""" - import hashlib - - checksums = {} - for file_info in matched_files: - try: - real_path = file_info["real_path"] - if os.path.exists(real_path) and os.path.isfile(real_path): - hash_sha256 = hashlib.sha256() - with open(real_path, "rb") as f: - for chunk in iter(lambda: f.read(4096), b""): - hash_sha256.update(chunk) - checksums[real_path] = hash_sha256.hexdigest() - except Exception: - checksums[file_info["real_path"]] = "error" - - return checksums - - async def _count_directories(self, matched_files: List[Dict[str, Any]]) -> int: - """Count unique directories in file list""" - directories = set() - for file_info in matched_files: - dir_path = os.path.dirname(file_info["path"]) - if dir_path: - directories.add(dir_path) - return len(directories) - - def _calculate_backup_checksum(self, zip_path: str) -> str: - """Calculate checksum of the entire backup file""" - import hashlib - - try: - hash_sha256 = hashlib.sha256() - with open(zip_path, "rb") as f: - for chunk in iter(lambda: f.read(4096), b""): - hash_sha256.update(chunk) - return hash_sha256.hexdigest() - except Exception: - return "error" - - async def test_patterns(self, patterns: str, include_hidden: bool = False, max_files: int = 1000) -> List[Dict[str, Any]]: - """Test backup patterns and return list of matched files""" - - # Parse patterns using pathspec - pattern_lines = [line.strip() for line in patterns.split('\n') if line.strip() and not line.strip().startswith('#')] - - if not pattern_lines: - return [] - - matched_files = [] - processed_count = 0 - - try: - spec = PathSpec.from_lines(GitWildMatchPattern, pattern_lines) - - # Walk through base directories - for base_pattern_path, base_real_path in self.base_paths.items(): - if not os.path.exists(base_real_path): - continue - - for root, dirs, files_list in os.walk(base_real_path): - # Filter hidden directories if not included - if not include_hidden: - dirs[:] = [d for d in dirs if not d.startswith('.')] - - for file in files_list: - if processed_count >= max_files: - break - - # Skip hidden files if not included - if not include_hidden and file.startswith('.'): - continue - - file_path = os.path.join(root, file) - pattern_path = self._unresolve_path(file_path) - - # Remove leading slash for pathspec matching - relative_path = pattern_path.lstrip('/') - - if spec.match_file(relative_path): - try: - stat = os.stat(file_path) - matched_files.append({ - "path": pattern_path, - "real_path": file_path, - "size": stat.st_size, - "modified": datetime.datetime.fromtimestamp(stat.st_mtime).isoformat(), - "type": "file" - }) - processed_count += 1 - except (OSError, IOError): - # Skip files we can't access - continue - - if processed_count >= max_files: - break - - if processed_count >= max_files: - break - - except Exception as e: - raise Exception(f"Error processing patterns: {str(e)}") - - return matched_files - - async def create_backup(self, patterns: str, include_hidden: bool = False, backup_name: str = "agent-zero-backup") -> str: - """Create backup archive with selected files""" - - # Get matched files - matched_files = await self.test_patterns(patterns, include_hidden, max_files=10000) - - if not matched_files: - raise Exception("No files matched the backup patterns") - - # Create temporary zip file - temp_dir = tempfile.mkdtemp() - zip_path = os.path.join(temp_dir, f"{backup_name}.zip") - - try: - with zipfile.ZipFile(zip_path, 'w', zipfile.ZIP_DEFLATED) as zipf: - # Calculate file checksums for integrity verification - file_checksums = await self._calculate_file_checksums(matched_files) - - # Add comprehensive metadata - this is the control file for backup/restore - include_patterns, exclude_patterns = self._parse_patterns(patterns) - - metadata = { - # Basic backup information - "agent_zero_version": self.agent_zero_version, - "timestamp": datetime.datetime.now().isoformat(), - "backup_name": backup_name, - "include_hidden": include_hidden, - - # Pattern arrays for granular control during restore - "include_patterns": include_patterns, # Array of include patterns - "exclude_patterns": exclude_patterns, # Array of exclude patterns - - # System and environment information - "system_info": await self._get_system_info(), - "environment_info": await self._get_environment_info(), - "backup_author": await self._get_backup_author(), - - # Backup configuration - "backup_config": { - "default_patterns": self._get_default_patterns(), - "include_hidden": include_hidden, - "compression_level": 6, - "integrity_check": True - }, - - # File information with checksums - "files": [ - { - "path": f["path"], - "size": f["size"], - "modified": f["modified"], - "checksum": file_checksums.get(f["real_path"], ""), - "type": "file" - } - for f in matched_files - ], - - # Statistics - "total_files": len(matched_files), - "backup_size": sum(f["size"] for f in matched_files), - "directory_count": await self._count_directories(matched_files), - - # Integrity verification - "backup_checksum": "", # Will be calculated after backup creation - "verification_method": "sha256" - } - - zipf.writestr("metadata.json", json.dumps(metadata, indent=2)) - - # Add files - for file_info in matched_files: - real_path = file_info["real_path"] - archive_path = file_info["path"].lstrip('/') - - try: - if os.path.exists(real_path) and os.path.isfile(real_path): - zipf.write(real_path, archive_path) - except (OSError, IOError) as e: - # Log error but continue with other files - print(f"Warning: Could not backup file {real_path}: {e}") - continue - - return zip_path - - except Exception as e: - # Cleanup on error - if os.path.exists(zip_path): - os.remove(zip_path) - raise Exception(f"Error creating backup: {str(e)}") - - async def inspect_backup(self, backup_file) -> Dict[str, Any]: - """Inspect backup archive and return metadata""" - - # Save uploaded file temporarily - temp_dir = tempfile.mkdtemp() - temp_file = os.path.join(temp_dir, "backup.zip") - - try: - backup_file.save(temp_file) - - with zipfile.ZipFile(temp_file, 'r') as zipf: - # Read metadata - if "metadata.json" not in zipf.namelist(): - raise Exception("Invalid backup file: missing metadata.json") - - metadata_content = zipf.read("metadata.json").decode('utf-8') - metadata = json.loads(metadata_content) - - # Add file list from archive - files_in_archive = [name for name in zipf.namelist() if name != "metadata.json"] - metadata["files_in_archive"] = files_in_archive - - return metadata - - except zipfile.BadZipFile: - raise Exception("Invalid backup file: not a valid zip archive") - except json.JSONDecodeError: - raise Exception("Invalid backup file: corrupted metadata") - finally: - # Cleanup - if os.path.exists(temp_file): - os.remove(temp_file) - if os.path.exists(temp_dir): - os.rmdir(temp_dir) - - async def get_grouped_file_preview(self, patterns: str, include_hidden: bool = False, max_depth: int = 3, search_filter: str = "") -> Dict[str, Any]: - """Get files organized in smart groups with depth limitation""" - - # Get all matched files - all_files = await self.test_patterns(patterns, include_hidden, max_files=10000) - - # Apply search filter if provided - if search_filter.strip(): - search_lower = search_filter.lower() - all_files = [f for f in all_files if search_lower in f["path"].lower()] - - # Group files by directory structure - groups = {} - total_size = 0 - - for file_info in all_files: - path = file_info["path"] - total_size += file_info["size"] - - # Split path and limit depth - path_parts = path.strip('/').split('/') - - # Limit to max_depth for grouping - if len(path_parts) > max_depth: - group_path = '/' + '/'.join(path_parts[:max_depth]) - is_truncated = True - else: - group_path = '/' + '/'.join(path_parts[:-1]) if len(path_parts) > 1 else '/' - is_truncated = False - - if group_path not in groups: - groups[group_path] = { - "path": group_path, - "files": [], - "file_count": 0, - "total_size": 0, - "is_truncated": False, - "subdirectories": set() - } - - groups[group_path]["files"].append(file_info) - groups[group_path]["file_count"] += 1 - groups[group_path]["total_size"] += file_info["size"] - groups[group_path]["is_truncated"] = groups[group_path]["is_truncated"] or is_truncated - - # Track subdirectories for truncated groups - if is_truncated and len(path_parts) > max_depth: - next_dir = path_parts[max_depth] - groups[group_path]["subdirectories"].add(next_dir) - - # Convert groups to sorted list and add display info - sorted_groups = [] - for group_path, group_info in sorted(groups.items()): - group_info["subdirectories"] = sorted(list(group_info["subdirectories"])) - - # Limit displayed files for UI performance - if len(group_info["files"]) > 50: - group_info["displayed_files"] = group_info["files"][:50] - group_info["additional_files"] = len(group_info["files"]) - 50 - else: - group_info["displayed_files"] = group_info["files"] - group_info["additional_files"] = 0 - - sorted_groups.append(group_info) - - return { - "groups": sorted_groups, - "stats": { - "total_groups": len(sorted_groups), - "total_files": len(all_files), - "total_size": total_size, - "search_applied": bool(search_filter.strip()), - "max_depth": max_depth - }, - "total_files": len(all_files), - "total_size": total_size - } - - def create_backup_with_progress(self, patterns: str, include_hidden: bool = False, backup_name: str = "agent-zero-backup"): - """Generator that yields backup progress for streaming""" - - try: - # Step 1: Get matched files - yield { - "stage": "discovery", - "message": "Scanning files...", - "progress": 0, - "completed": False - } - - import asyncio - matched_files = asyncio.run(self.test_patterns(patterns, include_hidden, max_files=10000)) - - if not matched_files: - yield { - "stage": "error", - "message": "No files matched the backup patterns", - "progress": 0, - "completed": True, - "error": True - } - return - - total_files = len(matched_files) - - yield { - "stage": "discovery", - "message": f"Found {total_files} files to backup", - "progress": 10, - "completed": False, - "total_files": total_files - } - - # Step 2: Calculate checksums - yield { - "stage": "checksums", - "message": "Calculating file checksums...", - "progress": 15, - "completed": False - } - - file_checksums = asyncio.run(self._calculate_file_checksums(matched_files)) - - # Step 3: Create backup - temp_dir = tempfile.mkdtemp() - zip_path = os.path.join(temp_dir, f"{backup_name}.zip") - - yield { - "stage": "backup", - "message": "Creating backup archive...", - "progress": 20, - "completed": False - } - - with zipfile.ZipFile(zip_path, 'w', zipfile.ZIP_DEFLATED) as zipf: - # Create and add metadata first - metadata = { - "agent_zero_version": self.agent_zero_version, - "timestamp": datetime.datetime.now().isoformat(), - "backup_name": backup_name, - "backup_patterns": patterns, - "include_hidden": include_hidden, - "system_info": asyncio.run(self._get_system_info()), - "environment_info": asyncio.run(self._get_environment_info()), - "backup_author": asyncio.run(self._get_backup_author()), - "backup_config": { - "default_patterns": self._get_default_patterns(), - "custom_patterns": patterns, - "include_hidden": include_hidden, - "compression_level": 6, - "integrity_check": True - }, - "files": [ - { - "path": f["path"], - "size": f["size"], - "modified": f["modified"], - "checksum": file_checksums.get(f["real_path"], ""), - "type": "file" - } - for f in matched_files - ], - "total_files": len(matched_files), - "backup_size": sum(f["size"] for f in matched_files), - "directory_count": asyncio.run(self._count_directories(matched_files)), - "backup_checksum": "", - "verification_method": "sha256" - } - - zipf.writestr("metadata.json", json.dumps(metadata, indent=2)) - - # Add files with progress updates - for i, file_info in enumerate(matched_files): - real_path = file_info["real_path"] - archive_path = file_info["path"].lstrip('/') - - try: - if os.path.exists(real_path) and os.path.isfile(real_path): - zipf.write(real_path, archive_path) - - # Yield progress every 10 files or at key milestones - if i % 10 == 0 or i == total_files - 1: - progress = 20 + (i + 1) / total_files * 70 # 20-90% - yield { - "stage": "backup", - "message": f"Adding file: {file_info['path']}", - "progress": int(progress), - "completed": False, - "current_file": i + 1, - "total_files": total_files, - "file_path": file_info["path"] - } - except Exception as e: - yield { - "stage": "warning", - "message": f"Failed to backup file: {file_info['path']} - {str(e)}", - "progress": int(20 + (i + 1) / total_files * 70), - "completed": False, - "warning": True - } - - # Step 4: Calculate final checksum - yield { - "stage": "finalization", - "message": "Calculating backup checksum...", - "progress": 95, - "completed": False - } - - backup_checksum = self._calculate_backup_checksum(zip_path) - - # Step 5: Complete - yield { - "stage": "completed", - "message": "Backup created successfully", - "progress": 100, - "completed": True, - "success": True, - "backup_path": zip_path, - "backup_checksum": backup_checksum, - "total_files": total_files, - "backup_size": os.path.getsize(zip_path) - } - - except Exception as e: - yield { - "stage": "error", - "message": f"Backup failed: {str(e)}", - "progress": 0, - "completed": True, - "error": True - } - - async def restore_backup(self, backup_file, restore_patterns: str, overwrite_policy: str = "overwrite") -> Dict[str, Any]: - """Restore files from backup archive""" - - # Save uploaded file temporarily - temp_dir = tempfile.mkdtemp() - temp_file = os.path.join(temp_dir, "backup.zip") - - restored_files = [] - skipped_files = [] - errors = [] - - try: - backup_file.save(temp_file) - - # Parse restore patterns if provided - if restore_patterns.strip(): - pattern_lines = [line.strip() for line in restore_patterns.split('\n') - if line.strip() and not line.strip().startswith('#')] - spec = PathSpec.from_lines(GitWildMatchPattern, pattern_lines) if pattern_lines else None - else: - spec = None - - with zipfile.ZipFile(temp_file, 'r') as zipf: - # Read metadata - if "metadata.json" in zipf.namelist(): - metadata_content = zipf.read("metadata.json").decode('utf-8') - metadata = json.loads(metadata_content) - - # Process each file in archive - for archive_path in zipf.namelist(): - if archive_path == "metadata.json": - continue - - # Check if file matches restore patterns - if spec and not spec.match_file(archive_path): - skipped_files.append({ - "path": archive_path, - "reason": "not_matched_by_pattern" - }) - continue - - # Determine target path - target_path = self._resolve_path("/" + archive_path) - - try: - # Handle overwrite policy - if os.path.exists(target_path): - if overwrite_policy == "skip": - skipped_files.append({ - "path": archive_path, - "reason": "file_exists_skip_policy" - }) - continue - elif overwrite_policy == "backup": - backup_path = f"{target_path}.backup.{datetime.datetime.now().strftime('%Y%m%d_%H%M%S')}" - shutil.move(target_path, backup_path) - - # Create target directory if needed - target_dir = os.path.dirname(target_path) - os.makedirs(target_dir, exist_ok=True) - - # Extract file - with zipf.open(archive_path) as source, open(target_path, 'wb') as target: - shutil.copyfileobj(source, target) - - restored_files.append({ - "archive_path": archive_path, - "target_path": target_path, - "status": "restored" - }) - - except Exception as e: - errors.append({ - "path": archive_path, - "error": str(e) - }) - - return { - "restored_files": restored_files, - "skipped_files": skipped_files, - "errors": errors - } - - except Exception as e: - raise Exception(f"Error restoring backup: {str(e)}") - finally: - # Cleanup - if os.path.exists(temp_file): - os.remove(temp_file) - if os.path.exists(temp_dir): - os.rmdir(temp_dir) - - async def preview_restore(self, backup_file, restore_patterns: str) -> Dict[str, Any]: - """Preview which files would be restored based on patterns""" - - # Save uploaded file temporarily - temp_dir = tempfile.mkdtemp() - temp_file = os.path.join(temp_dir, "backup.zip") - - files_to_restore = [] - skipped_files = [] - - try: - backup_file.save(temp_file) - - # Parse restore patterns if provided - if restore_patterns.strip(): - pattern_lines = [line.strip() for line in restore_patterns.split('\n') - if line.strip() and not line.strip().startswith('#')] - spec = PathSpec.from_lines(GitWildMatchPattern, pattern_lines) if pattern_lines else None - else: - spec = None - - with zipfile.ZipFile(temp_file, 'r') as zipf: - # Read metadata for context - metadata = {} - if "metadata.json" in zipf.namelist(): - metadata_content = zipf.read("metadata.json").decode('utf-8') - metadata = json.loads(metadata_content) - - # Process each file in archive - for archive_path in zipf.namelist(): - if archive_path == "metadata.json": - continue - - # Check if file matches restore patterns - if spec: - if spec.match_file(archive_path): - files_to_restore.append({ - "path": archive_path, - "target_path": self._resolve_path("/" + archive_path), - "action": "restore" - }) - else: - skipped_files.append({ - "path": archive_path, - "reason": "not_matched_by_pattern" - }) - else: - # No patterns specified, restore all files - files_to_restore.append({ - "path": archive_path, - "target_path": self._resolve_path("/" + archive_path), - "action": "restore" - }) - - return { - "files": files_to_restore, - "skipped_files": skipped_files, - "total_count": len(files_to_restore), - "skipped_count": len(skipped_files) - } - - except Exception as e: - raise Exception(f"Error previewing restore: {str(e)}") - finally: - # Cleanup - if os.path.exists(temp_file): - os.remove(temp_file) - if os.path.exists(temp_dir): - os.rmdir(temp_dir) -``` - -### 4. Dependencies - -#### Required Python Packages -Add to `requirements.txt`: -``` -pathspec>=0.10.0 # For gitignore-style pattern matching -psutil>=5.8.0 # For system information collection -``` - -#### Agent Zero Internal Dependencies -The backup system requires these Agent Zero helper modules: -- `python.helpers.git` - For version detection using git.get_git_info() (consistent with run_ui.py) -- `python.helpers.files` - For file operations and path resolution -- `python.helpers.runtime` - For development/production mode detection - -#### Installation Command -```bash -pip install pathspec psutil -``` - -### 5. Error Handling - -#### Integration with Agent Zero Error System -The backup system integrates with Agent Zero's existing error handling infrastructure: - -```python -from python.helpers.errors import format_error -from python.helpers.print_style import PrintStyle - -# Follow Agent Zero's error handling patterns -try: - result = await backup_operation() - return {"success": True, "data": result} -except Exception as e: - error_message = format_error(e) - PrintStyle.error(f"Backup error: {error_message}") - return {"success": False, "error": error_message} -``` - -#### Common Error Scenarios -1. **Invalid Patterns**: Malformed glob patterns -2. **Permission Errors**: Files/directories not accessible -3. **Disk Space**: Insufficient space for backup creation -4. **Invalid Archives**: Corrupted or invalid backup files -5. **Path Conflicts**: Files outside allowed directories - -#### Error Response Format -```python -{ - "success": False, - "error": "Human-readable error message", - "error_code": "BACKUP_PATTERN_INVALID", # Optional machine-readable code - "details": { # Optional additional details - "invalid_patterns": ["pattern1", "pattern2"], - "suggestion": "Check pattern syntax" - } -} -``` - -### 6. Security Considerations - -#### Path Security -- Validate all paths to prevent directory traversal attacks -- Restrict backups to predefined base directories (/a0, /root) -- Sanitize file names in archives -- Implement file size limits for uploads/downloads - -#### Authentication -- All endpoints require authentication (`requires_auth = True`) -- All endpoints require loopback (`requires_loopback = True`) -- No API key access for security - -#### File System Protection -- Read-only access to system directories outside allowed paths -- Size limits for backup archives -- Timeout limits for backup operations -- Temporary file cleanup - -### 7. Performance Considerations - -#### File Processing -- Limit number of files in test/preview operations (max_files parameter) -- Stream file processing for large archives -- Implement progress tracking for large operations -- Use temporary directories for staging - -#### Memory Management -- Stream zip file creation to avoid memory issues -- Process files individually rather than loading all in memory -- Clean up temporary files promptly -- Implement timeout limits for long operations - -### 8. Configuration - -#### Default Configuration -```python -BACKUP_CONFIG = { - "max_files_preview": 1000, - "max_backup_size": 1024 * 1024 * 1024, # 1GB - "max_upload_size": 1024 * 1024 * 1024, # 1GB - "operation_timeout": 300, # 5 minutes - "temp_cleanup_interval": 3600, # 1 hour - "allowed_base_paths": ["/a0", "/root"] -} -``` - -#### Future Integration Opportunities -**Task Scheduler Integration:** -Agent Zero's existing task scheduler could be extended to support automated backups: - -```python -# Potential future enhancement - scheduled backups -{ - "name": "auto_backup_daily", - "type": "scheduled", - "schedule": "0 2 * * *", # Daily at 2 AM - "tool_name": "backup_create", - "tool_args": { - "patterns": "default_patterns", - "backup_name": "auto_backup_{date}" - } -} -``` - -## Enhanced Metadata Structure and Restore Workflow - -### Version Detection Implementation -The backup system uses the same version detection method as Agent Zero's main UI: - -```python -def _get_agent_zero_version(self) -> str: - """Get current Agent Zero version""" - try: - # Get version from git info (same as run_ui.py) - gitinfo = git.get_git_info() - return gitinfo.get("version", "development") - except: - return "unknown" -``` - -This ensures consistency between the backup metadata and the main application version reporting. - -### Metadata.json Format -The backup archive includes a comprehensive `metadata.json` file with the following structure: - -```json -{ - "agent_zero_version": "version", - "timestamp": "ISO datetime", - "backup_name": "user-defined name", - "include_hidden": boolean, - - "include_patterns": [ - "/a0/knowledge/**", - "/a0/instruments/**", - "/a0/memory/**", - "/a0/.env", - "/a0/tmp/settings.json" - ], - "exclude_patterns": [ - "/a0/knowledge/default/**", - "/a0/instruments/default/**", - "/a0/memory/embeddings/**" - ], - - "system_info": { /* platform, architecture, etc. */ }, - "environment_info": { /* user, timezone, paths, etc. */ }, - "backup_author": "user@hostname", - "backup_config": { - "default_patterns": "system defaults", - "include_hidden": boolean, - "compression_level": 6, - "integrity_check": true - }, - - "files": [ /* file list with checksums */ ], - "total_files": count, - "backup_size": bytes, - "backup_checksum": "sha256" -} -``` - -### Restore Workflow -1. **Upload Archive**: User uploads backup.zip file -2. **Load Metadata**: System extracts and parses metadata.json -3. **Display Metadata**: Complete metadata.json shown in ACE JSON editor -4. **User Editing**: User can modify include_patterns and exclude_patterns arrays directly -5. **Preview Changes**: System shows which files will be restored based on current metadata -6. **Execute Restore**: Files restored according to final metadata configuration - -### JSON Metadata Editing Benefits -- **Single Source of Truth**: metadata.json is the authoritative configuration -- **Direct Editing**: Users edit JSON arrays directly in ACE editor -- **Full Control**: Access to all metadata properties, not just patterns -- **Validation**: JSON syntax validation and array structure validation -- **Transparency**: Users see exactly what will be used for restore - -## Comprehensive Enhancement Summary - -### Enhanced Metadata Structure -The backup metadata has been significantly enhanced to include: -- **System Information**: Platform, architecture, Python version, CPU count, memory, disk usage -- **Environment Details**: User, timezone, working directory, runtime mode, Agent Zero root path -- **Backup Author**: System identifier (user@hostname) for backup tracking -- **File Checksums**: SHA-256 hashes for all backed up files for integrity verification -- **Backup Statistics**: Total files, directories, sizes with verification methods -- **Compatibility Data**: Agent Zero version and environment for restoration validation - -### Smart File Management -- **Grouped File Preview**: Organize files by directory structure with depth limitation (max 3 levels) -- **Smart Grouping**: Show directory hierarchies with expandable file counts -- **Search and Filter**: Real-time filtering by file name or path fragments -- **Performance Optimization**: Limit preview files (1000 max) and displayed files (50 per group) for UI responsiveness - -### Real-time Progress Streaming -- **Server-Sent Events**: Live backup progress updates via `/backup_progress_stream` endpoint -- **Multi-stage Progress**: Discovery → Checksums → Backup → Finalization with percentage tracking -- **File-by-file Updates**: Real-time display of current file being processed -- **Error Handling**: Graceful error reporting and warning collection during backup process - -### Advanced API Endpoints -1. **`/backup_preview_grouped`**: Get smart file groupings with depth control and search -2. **`/backup_progress_stream`**: Stream real-time backup progress via SSE -3. **`/backup_restore_preview`**: Preview restore operations with pattern filtering -4. **Enhanced `/backup_inspect`**: Return comprehensive metadata with system information - -### System Information Collection -- **Platform Detection**: OS, architecture, Python version, hostname -- **Resource Information**: CPU count, memory, disk usage via psutil (converted to strings for JSON consistency) -- **Environment Capture**: User, timezone, paths, runtime mode -- **Version Integration**: Uses git.get_git_info() for consistent version detection with main application -- **Integrity Verification**: SHA-256 checksums for individual files and complete backup - -### Security and Reliability Enhancements -- **Integrity Verification**: File-level and backup-level checksum validation -- **Comprehensive Logging**: Detailed progress tracking and error collection -- **Path Security**: Enhanced validation with system information context -- **Backup Validation**: Version compatibility checking and environment verification - -This enhanced backend specification provides a production-ready, comprehensive backup and restore system with advanced metadata tracking, real-time progress monitoring, and intelligent file management capabilities, all while maintaining Agent Zero's architectural patterns and security standards. - -### Implementation Status Updates - -#### ✅ COMPLETED: Core BackupService Implementation -- **Git Version Integration**: Updated to use `git.get_git_info()` consistent with `run_ui.py` -- **Type Safety**: Fixed psutil return values to be strings for JSON metadata consistency -- **Code Quality**: All linting errors resolved, proper import structure -- **Testing Verified**: BackupService initializes correctly and detects Agent Zero root paths -- **Dependencies Added**: pathspec>=0.10.0 for pattern matching, psutil>=5.8.0 for system info -- **Git Helper Integration**: Uses python.helpers.git.get_git_info() for version detection consistency - -#### Next Implementation Phase: API Endpoints -Ready to implement the 8 API endpoints: -1. `backup_test.py` - Pattern testing and file preview -2. `backup_create.py` - Archive creation and download -3. `backup_restore.py` - File restoration from archive -4. `backup_inspect.py` - Archive metadata inspection -5. `backup_get_defaults.py` - Fetch default patterns -6. `backup_restore_preview.py` - Preview restore patterns -7. `backup_preview_grouped.py` - Smart directory grouping -8. `backup_progress_stream.py` - Real-time progress streaming - -## Implementation Cleanup and Final Status - -### ✅ **COMPLETED CLEANUP (December 2024)** - -#### **Removed Unused Components:** -- ❌ **`backup_download.py`** - Functionality moved to `backup_create` (direct download) -- ❌ **`backup_progress_stream.py`** - Not implemented in frontend, overengineered -- ❌ **`_calculate_file_checksums()` method** - Dead code, checksums not properly used -- ❌ **`_calculate_backup_checksum()` method** - Dead code, never called -- ❌ **`hashlib` import** - No longer needed after checksum removal - -#### **Simplified BackupService:** -- ✅ **Removed checksum calculation** - Was calculated but not properly used, overcomplicating the code -- ✅ **Streamlined metadata** - Removed unused integrity verification fields -- ✅ **Fixed `_count_directories()` method** - Had return statement in wrong place -- ✅ **Cleaner error handling** - Removed unnecessary warning outputs - -#### **Enhanced Hidden File Logic:** -The most critical fix was implementing proper explicit pattern handling: - -```python -# NEW: Enhanced hidden file logic -def _get_explicit_patterns(self, include_patterns: List[str]) -> set[str]: - """Extract explicit (non-wildcard) patterns that should always be included""" - explicit_patterns = set() - - for pattern in include_patterns: - # If pattern doesn't contain wildcards, it's explicit - if '*' not in pattern and '?' not in pattern: - # Remove leading slash for comparison - explicit_patterns.add(pattern.lstrip('/')) - - # Also add parent directories as explicit (so hidden dirs can be traversed) - path_parts = pattern.lstrip('/').split('/') - for i in range(1, len(path_parts)): - parent_path = '/'.join(path_parts[:i]) - explicit_patterns.add(parent_path) - - return explicit_patterns - -# FIXED: Hidden file filtering now respects explicit patterns -if not include_hidden and file.startswith('.'): - if not self._is_explicitly_included(pattern_path, explicit_patterns): - continue # Only exclude hidden files discovered via wildcards -``` - -#### **Final API Endpoint Set (6 endpoints):** -1. ✅ **`backup_get_defaults`** - Get default metadata configuration -2. ✅ **`backup_test`** - Test patterns and preview files (dry run) -3. ✅ **`backup_preview_grouped`** - Get grouped file preview for UI -4. ✅ **`backup_create`** - Create and download backup archive -5. ✅ **`backup_inspect`** - Inspect uploaded backup metadata -6. ✅ **`backup_restore_preview`** - Preview restore operation -7. ✅ **`backup_restore`** - Execute restore operation - -### **Critical Issue Fixed: Hidden Files** - -**Problem:** When `include_hidden=false`, the system was excluding ALL hidden files, even when they were explicitly specified in patterns like `/a0/.env`. - -**Solution:** Implemented explicit pattern detection that distinguishes between: -- **Explicit patterns** (like `/a0/.env`) - Always included regardless of `include_hidden` setting -- **Wildcard discoveries** (like `/a0/*`) - Respect the `include_hidden` setting - -**Result:** Critical files like `.env` are now properly backed up when explicitly specified, ensuring Agent Zero configurations are preserved. - -### **Implementation Status: ✅ PRODUCTION READY** - -The backup system is now: -- **Simplified**: Removed unnecessary complexity and dead code -- **Reliable**: Fixed critical hidden file handling -- **Efficient**: No unnecessary checksum calculations -- **Clean**: Proper error handling and type safety -- **Complete**: Full backup and restore functionality working - -**Key Benefits of Cleanup:** -- ✅ **Simpler maintenance** - Less code to maintain and debug -- ✅ **Better performance** - No unnecessary checksum calculations -- ✅ **Correct behavior** - Hidden files now work as expected -- ✅ **Cleaner API** - Only endpoints that are actually used -- ✅ **Better reliability** - Removed complex features that weren't properly implemented - -The Agent Zero backup system is now production-ready and battle-tested! 🚀 - -## ✅ **FINAL STATUS: ACE EDITOR STATE GUARANTEE COMPLETED (December 2024)** - -### **Goal Achievement Verification** - -The primary goal has been successfully achieved: **All metadata.json operations in GUI use the ACE editor state, not original archive metadata, giving users complete control to edit and execute exactly what's defined in the editor.** - -#### **✅ Archive metadata.json Usage** (MINIMAL - only technical requirements): -```python -# ONLY used for: -# 1. Initial ACE editor preload (backup_inspect API) -original_backup_metadata = json.loads(metadata_content) -metadata["include_patterns"] = original_backup_metadata.get("include_patterns", []) -metadata["exclude_patterns"] = original_backup_metadata.get("exclude_patterns", []) - -# 2. Path translation for cross-system compatibility -environment_info = original_backup_metadata.get("environment_info", {}) -backed_up_agent_root = environment_info.get("agent_zero_root", "") -``` - -#### **✅ ACE editor metadata Usage** (EVERYTHING ELSE): -```python -# Used for ALL user-controllable operations: -backup_metadata = user_edited_metadata if user_edited_metadata else original_backup_metadata - -# 1. File pattern matching for restore -restore_include_patterns = backup_metadata.get("include_patterns", []) -restore_exclude_patterns = backup_metadata.get("exclude_patterns", []) - -# 2. Clean before restore operations -files_to_delete = await self._find_files_to_clean_with_user_metadata(backup_metadata, original_backup_metadata) - -# 3. All user preferences and settings -include_hidden = backup_metadata.get("include_hidden", False) -``` - -### **Implementation Architecture** - -#### **Hybrid Approach - Perfect Balance:** -- **✅ User Control**: ACE editor content drives all restore operations -- **✅ Technical Compatibility**: Original metadata enables cross-system path translation -- **✅ Complete Transparency**: Users see and control exactly what will be executed -- **✅ System Intelligence**: Automatic path translation preserves functionality - -#### **API Layer Integration:** -```python -# Both preview and restore APIs follow same pattern: -class BackupRestorePreview(ApiHandler): - async def process(self, input: dict, request: Request) -> dict | Response: - # Get user-edited metadata from ACE editor - metadata = json.loads(metadata_json) - - # Pass user metadata to service layer - result = await backup_service.preview_restore( - backup_file=backup_file, - restore_include_patterns=metadata.get("include_patterns", []), - restore_exclude_patterns=metadata.get("exclude_patterns", []), - user_edited_metadata=metadata # ← ACE editor content - ) -``` - -#### **Service Layer Implementation:** -```python -# Service methods intelligently use both metadata sources: -async def preview_restore(self, user_edited_metadata: Optional[Dict[str, Any]] = None): - # Read original metadata from archive - original_backup_metadata = json.loads(metadata_content) - - # Use ACE editor metadata for operations - backup_metadata = user_edited_metadata if user_edited_metadata else original_backup_metadata - - # User metadata drives pattern matching - files_to_restore = await self._process_with_user_patterns(backup_metadata) - - # Original metadata enables path translation - target_path = self._translate_restore_path(archive_path, original_backup_metadata) -``` - -### **Dead Code Cleanup Results** - -#### **✅ Removed Unused Method:** -- **`_find_files_to_clean()` method** (39 lines) - Replaced by `_find_files_to_clean_with_user_metadata()` -- **Functionality**: Was using original archive metadata instead of user-edited metadata -- **Replacement**: New method properly uses ACE editor content for clean operations - -#### **✅ Method Comparison:** -```python -# OLD (REMOVED): Used original archive metadata -async def _find_files_to_clean(self, backup_metadata: Dict[str, Any]): - original_include_patterns = backup_metadata.get("include_patterns", []) # ← Archive metadata - # ... 39 lines of implementation - -# NEW (ACTIVE): Uses ACE editor metadata -async def _find_files_to_clean_with_user_metadata(self, user_metadata: Dict[str, Any], original_metadata: Dict[str, Any]): - user_include_patterns = user_metadata.get("include_patterns", []) # ← ACE editor metadata - # Translation only uses original_metadata for environment_info -``` - -### **User Experience Flow** - -1. **Upload Archive** → Original metadata.json extracted -2. **ACE Editor Preload** → Original patterns shown as starting point -3. **User Editing** → Complete freedom to modify patterns, settings -4. **Preview Operation** → Uses current ACE editor content -5. **Execute Restore** → Uses final ACE editor content -6. **Path Translation** → Automatic system compatibility (transparent to user) - -### **Technical Benefits Achieved** - -#### **✅ Complete User Control:** -- Users can edit any pattern in the ACE editor -- Changes immediately reflected in preview operations -- Execute button runs exactly what's shown in editor -- No hidden operations using different metadata - -#### **✅ Cross-System Compatibility:** -- Path translation preserves technical functionality -- Users don't need to manually adjust paths -- Works seamlessly between different Agent Zero installations -- Maintains backup portability across environments - -#### **✅ Clean Architecture:** -- Single source of truth: ACE editor content -- Clear separation of concerns: user control vs technical requirements -- Eliminated dead code and simplified maintenance -- Consistent behavior between preview and execution - -### **Final Status: ✅ PRODUCTION READY** - -The Agent Zero backup system now provides: -- **✅ Complete user control** via ACE editor state -- **✅ Cross-system compatibility** through intelligent path translation -- **✅ Clean, maintainable code** with dead code eliminated -- **✅ Transparent operations** with full user visibility -- **✅ Production reliability** with comprehensive error handling - -**The backup system perfectly balances user control with technical functionality!** 🎯 diff --git a/docs/development/designs/backup-specification-frontend.md b/docs/development/designs/backup-specification-frontend.md deleted file mode 100644 index 26dd93c6d..000000000 --- a/docs/development/designs/backup-specification-frontend.md +++ /dev/null @@ -1,1663 +0,0 @@ -# Agent Zero Backup/Restore Frontend Specification - -## Overview -This specification defines the frontend implementation for Agent Zero's backup and restore functionality, providing an intuitive user interface with a dedicated "backup" tab in the settings system and following established Alpine.js patterns. The backup functionality gets its own tab for better organization and user experience. - -## Frontend Architecture - -### 1. Settings Integration - -#### Settings Modal Enhancement -Update `webui/js/settings.js` to handle backup/restore button clicks in the dedicated backup tab: - -```javascript -// Add to handleFieldButton method (following MCP servers pattern) -async handleFieldButton(field) { - console.log(`Button clicked: ${field.id}`); - - if (field.id === "mcp_servers_config") { - openModal("settings/mcp/client/mcp-servers.html"); - } else if (field.id === "backup_create") { - openModal("settings/backup/backup.html"); - } else if (field.id === "backup_restore") { - openModal("settings/backup/restore.html"); - } -} -``` - -### 2. Component Structure - -#### Directory Structure -``` -webui/components/settings/backup/ -├── backup.html # Backup creation modal -├── restore.html # Restore modal -└── backup-store.js # Shared store for both modals -``` - -**Note**: The backup functionality is accessed through a dedicated "backup" tab in the settings interface, providing users with easy access to backup and restore operations without cluttering other settings areas. - -#### Enhanced Metadata Structure -The backup system uses a comprehensive `metadata.json` file that includes: -- **Pattern Arrays**: Separate `include_patterns[]` and `exclude_patterns[]` for granular control -- **System Information**: Platform, environment, and version details -- **Direct JSON Editing**: Users edit the metadata.json directly in ACE JSON editor -- **Single Source of Truth**: No pattern string conversions, metadata.json is authoritative - -### 3. Backup Modal Component - -#### File: `webui/components/settings/backup/backup.html` -```html - - - Create Backup - - - -
- -
- - - - -``` - -### 4. Restore Modal Component - -#### File: `webui/components/settings/backup/restore.html` -```html - - - Restore Backup - - - -
- -
- - - - -``` - -### 5. Store Implementation - -#### File: `webui/components/settings/backup/backup-store.js` -```javascript -import { createStore } from "/js/AlpineStore.js"; - -// ⚠️ CRITICAL: The .env file contains API keys and essential configuration. -// This file is REQUIRED for Agent Zero to function and must be backed up. -// Note: Patterns now use resolved absolute paths (e.g., /home/user/a0/data/.env) - -const model = { - // State - mode: 'backup', // 'backup' or 'restore' - loading: false, - loadingMessage: '', - error: '', - - // File operations log (shared between backup and restore) - fileOperationsLog: '', - - // Backup state - backupMetadataConfig: null, - includeHidden: false, - previewStats: { total: 0, truncated: false }, - backupEditor: null, - - // Enhanced file preview state - previewMode: 'grouped', // 'grouped' or 'flat' - previewFiles: [], - previewGroups: [], - filteredPreviewFiles: [], - fileSearchFilter: '', - expandedGroups: new Set(), - - // Progress state - progressData: null, - progressEventSource: null, - - // Restore state - backupFile: null, - backupMetadata: null, - restorePatterns: '', - overwritePolicy: 'overwrite', - restoreEditor: null, - restoreResult: null, - - // Initialization - async initBackup() { - this.mode = 'backup'; - this.resetState(); - await this.initBackupEditor(); - await this.updatePreview(); - }, - - async initRestore() { - this.mode = 'restore'; - this.resetState(); - await this.initRestoreEditor(); - }, - - resetState() { - this.loading = false; - this.error = ''; - this.backupFile = null; - this.backupMetadata = null; - this.restoreResult = null; - this.fileOperationsLog = ''; - }, - - // File operations logging - addFileOperation(message) { - const timestamp = new Date().toLocaleTimeString(); - this.fileOperationsLog += `[${timestamp}] ${message}\n`; - - // Auto-scroll to bottom - this.$nextTick(() => { - const textarea = document.getElementById(this.mode === 'backup' ? 'backup-file-list' : 'restore-file-list'); - if (textarea) { - textarea.scrollTop = textarea.scrollHeight; - } - }); - }, - - clearFileOperations() { - this.fileOperationsLog = ''; - }, - - // Cleanup method for modal close - onClose() { - this.resetState(); - if (this.backupEditor) { - this.backupEditor.destroy(); - this.backupEditor = null; - } - if (this.restoreEditor) { - this.restoreEditor.destroy(); - this.restoreEditor = null; - } - }, - - // Get default backup metadata with resolved patterns from backend - async getDefaultBackupMetadata() { - const timestamp = new Date().toISOString(); - - try { - // Get resolved default patterns from backend - const response = await sendJsonData("backup_get_defaults", {}); - - if (response.success) { - // Use patterns from backend with resolved absolute paths - const include_patterns = response.default_patterns.include_patterns; - const exclude_patterns = response.default_patterns.exclude_patterns; - - return { - backup_name: `agent-zero-backup-${timestamp.slice(0, 10)}`, - include_hidden: false, - include_patterns: include_patterns, - exclude_patterns: exclude_patterns, - backup_config: { - compression_level: 6, - integrity_check: true - } - }; - } - } catch (error) { - console.warn("Failed to get default patterns from backend, using fallback"); - } - - // Fallback patterns (will be overridden by backend on first use) - return { - backup_name: `agent-zero-backup-${timestamp.slice(0, 10)}`, - include_hidden: false, - include_patterns: [ - // These will be replaced with resolved absolute paths by backend - "# Loading default patterns from backend..." - ], - exclude_patterns: [], - backup_config: { - compression_level: 6, - integrity_check: true - } - }; - }, - - // Editor Management - Following Agent Zero ACE editor patterns - async initBackupEditor() { - const container = document.getElementById("backup-metadata-editor"); - if (container) { - const editor = ace.edit("backup-metadata-editor"); - - const dark = localStorage.getItem("darkMode"); - if (dark != "false") { - editor.setTheme("ace/theme/github_dark"); - } else { - editor.setTheme("ace/theme/tomorrow"); - } - - editor.session.setMode("ace/mode/json"); - - // Initialize with default backup metadata - const defaultMetadata = this.getDefaultBackupMetadata(); - editor.setValue(JSON.stringify(defaultMetadata, null, 2)); - editor.clearSelection(); - - // Auto-update preview on changes (debounced) - let timeout; - editor.on('change', () => { - clearTimeout(timeout); - timeout = setTimeout(() => { - this.updatePreview(); - }, 1000); - }); - - this.backupEditor = editor; - } - }, - - async initRestoreEditor() { - const container = document.getElementById("restore-metadata-editor"); - if (container) { - const editor = ace.edit("restore-metadata-editor"); - - const dark = localStorage.getItem("darkMode"); - if (dark != "false") { - editor.setTheme("ace/theme/github_dark"); - } else { - editor.setTheme("ace/theme/tomorrow"); - } - - editor.session.setMode("ace/mode/json"); - editor.setValue('{}'); - editor.clearSelection(); - - // Auto-validate JSON on changes - editor.on('change', () => { - this.validateRestoreMetadata(); - }); - - this.restoreEditor = editor; - } - }, - - // ACE Editor utility methods - Following MCP servers pattern - // Unified editor value getter (following MCP servers pattern) - getEditorValue() { - const editor = this.mode === 'backup' ? this.backupEditor : this.restoreEditor; - return editor ? editor.getValue() : '{}'; - }, - - // Unified JSON formatting (following MCP servers pattern) - formatJson() { - const editor = this.mode === 'backup' ? this.backupEditor : this.restoreEditor; - if (!editor) return; - - try { - const currentContent = editor.getValue(); - const parsed = JSON.parse(currentContent); - const formatted = JSON.stringify(parsed, null, 2); - - editor.setValue(formatted); - editor.clearSelection(); - editor.navigateFileStart(); - } catch (error) { - console.error("Failed to format JSON:", error); - this.error = "Invalid JSON: " + error.message; - } - }, - - // Enhanced File Preview Operations - async updatePreview() { - try { - const metadataText = this.getEditorValue(); - const metadata = JSON.parse(metadataText); - - if (!metadata.include_patterns || metadata.include_patterns.length === 0) { - this.previewStats = { total: 0, truncated: false }; - this.previewFiles = []; - this.previewGroups = []; - return; - } - - // Convert patterns arrays back to string format for API - const patternsString = this.convertPatternsToString(metadata.include_patterns, metadata.exclude_patterns); - - // Get grouped preview for better UX - const response = await sendJsonData("backup_preview_grouped", { - patterns: patternsString, - include_hidden: metadata.include_hidden || false, - max_depth: 3, - search_filter: this.fileSearchFilter - }); - - if (response.success) { - this.previewGroups = response.groups; - this.previewStats = response.stats; - - // Flatten groups for flat view - this.previewFiles = []; - response.groups.forEach(group => { - this.previewFiles.push(...group.files); - }); - - this.applyFileSearch(); - } else { - this.error = response.error; - } - } catch (error) { - this.error = `Preview error: ${error.message}`; - } - }, - - // Convert pattern arrays to string format for backend API - convertPatternsToString(includePatterns, excludePatterns) { - const patterns = []; - - // Add include patterns - if (includePatterns) { - patterns.push(...includePatterns); - } - - // Add exclude patterns with '!' prefix - if (excludePatterns) { - excludePatterns.forEach(pattern => { - patterns.push(`!${pattern}`); - }); - } - - return patterns.join('\n'); - }, - - // Validation for backup metadata - validateBackupMetadata() { - try { - const metadataText = this.getEditorValue(); - const metadata = JSON.parse(metadataText); - - // Validate required fields - if (!Array.isArray(metadata.include_patterns)) { - throw new Error('include_patterns must be an array'); - } - if (!Array.isArray(metadata.exclude_patterns)) { - throw new Error('exclude_patterns must be an array'); - } - if (!metadata.backup_name || typeof metadata.backup_name !== 'string') { - throw new Error('backup_name must be a non-empty string'); - } - - this.backupMetadataConfig = metadata; - this.error = ''; - return true; - } catch (error) { - this.error = `Invalid backup metadata: ${error.message}`; - return false; - } - }, - - // File Preview UI Management - initFilePreview() { - this.fileSearchFilter = ''; - this.expandedGroups.clear(); - this.previewMode = localStorage.getItem('backupPreviewMode') || 'grouped'; - }, - - togglePreviewMode() { - this.previewMode = this.previewMode === 'grouped' ? 'flat' : 'grouped'; - localStorage.setItem('backupPreviewMode', this.previewMode); - }, - - toggleGroup(groupPath) { - if (this.expandedGroups.has(groupPath)) { - this.expandedGroups.delete(groupPath); - } else { - this.expandedGroups.add(groupPath); - } - }, - - isGroupExpanded(groupPath) { - return this.expandedGroups.has(groupPath); - }, - - debounceFileSearch() { - clearTimeout(this.searchTimeout); - this.searchTimeout = setTimeout(() => { - this.applyFileSearch(); - }, 300); - }, - - clearFileSearch() { - this.fileSearchFilter = ''; - this.applyFileSearch(); - }, - - applyFileSearch() { - if (!this.fileSearchFilter.trim()) { - this.filteredPreviewFiles = this.previewFiles; - } else { - const search = this.fileSearchFilter.toLowerCase(); - this.filteredPreviewFiles = this.previewFiles.filter(file => - file.path.toLowerCase().includes(search) - ); - } - }, - - async exportFileList() { - const fileList = this.previewFiles.map(f => f.path).join('\n'); - const blob = new Blob([fileList], { type: 'text/plain' }); - const url = URL.createObjectURL(blob); - const a = document.createElement('a'); - a.href = url; - a.download = 'backup-file-list.txt'; - a.click(); - URL.revokeObjectURL(url); - }, - - async copyFileListToClipboard() { - const fileList = this.previewFiles.map(f => f.path).join('\n'); - try { - await navigator.clipboard.writeText(fileList); - toast('File list copied to clipboard', 'success'); - } catch (error) { - toast('Failed to copy to clipboard', 'error'); - } - }, - - async showFilePreview() { - // Validate backup metadata first - if (!this.validateBackupMetadata()) { - return; - } - - try { - this.loading = true; - this.loadingMessage = 'Generating file preview...'; - - const metadata = this.backupMetadataConfig; - const patternsString = this.convertPatternsToString(metadata.include_patterns, metadata.exclude_patterns); - - const response = await sendJsonData("backup_test", { - patterns: patternsString, - include_hidden: metadata.include_hidden || false, - max_files: 1000 - }); - - if (response.success) { - // Store preview data for file preview modal - this.previewFiles = response.files; - openModal('backup/file-preview.html'); - } else { - this.error = response.error; - } - } catch (error) { - this.error = `Preview error: ${error.message}`; - } finally { - this.loading = false; - } - }, - - // Real-time Backup with Progress Streaming - async createBackup() { - // Validate backup metadata first - if (!this.validateBackupMetadata()) { - return; - } - - try { - this.loading = true; - this.error = ''; - this.clearFileOperations(); - this.addFileOperation('Starting backup creation...'); - - const metadata = this.backupMetadataConfig; - const patternsString = this.convertPatternsToString(metadata.include_patterns, metadata.exclude_patterns); - - // Start real-time progress streaming - const eventSource = new EventSource(`/backup_progress_stream?` + new URLSearchParams({ - patterns: patternsString, - include_hidden: metadata.include_hidden || false, - backup_name: metadata.backup_name - })); - - this.progressEventSource = eventSource; - - eventSource.onmessage = (event) => { - const data = JSON.parse(event.data); - - // Log file operations - if (data.file_path) { - this.addFileOperation(`Adding: ${data.file_path}`); - } else if (data.message) { - this.addFileOperation(data.message); - } - - if (data.completed) { - eventSource.close(); - this.progressEventSource = null; - - if (data.success) { - this.addFileOperation(`Backup completed successfully: ${data.total_files} files, ${this.formatFileSize(data.backup_size)}`); - // Download the completed backup - this.downloadBackup(data.backup_path, metadata.backup_name); - toast('Backup created successfully', 'success'); - } else if (data.error) { - this.error = data.message || 'Backup creation failed'; - this.addFileOperation(`Error: ${this.error}`); - } - - this.loading = false; - } else { - this.loadingMessage = data.message || 'Processing...'; - } - }; - - eventSource.onerror = (error) => { - eventSource.close(); - this.progressEventSource = null; - this.loading = false; - this.error = 'Connection error during backup creation'; - this.addFileOperation(`Error: ${this.error}`); - }; - - } catch (error) { - this.error = `Backup error: ${error.message}`; - this.addFileOperation(`Error: ${error.message}`); - this.loading = false; - } - }, - - async downloadBackup(backupPath, backupName) { - try { - const response = await fetch('/backup_download', { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ backup_path: backupPath }) - }); - - if (response.ok) { - const blob = await response.blob(); - const url = globalThis.URL.createObjectURL(blob); - const a = document.createElement('a'); - a.href = url; - a.download = `${backupName}.zip`; - a.click(); - globalThis.URL.revokeObjectURL(url); - } - } catch (error) { - console.error('Download error:', error); - } - }, - - cancelBackup() { - if (this.progressEventSource) { - this.progressEventSource.close(); - this.progressEventSource = null; - } - this.loading = false; - this.progressData = null; - }, - - resetToDefaults() { - const defaultMetadata = this.getDefaultBackupMetadata(); - if (this.backupEditor) { - this.backupEditor.setValue(JSON.stringify(defaultMetadata, null, 2)); - this.backupEditor.clearSelection(); - } - this.updatePreview(); - }, - - // Dry run functionality - async dryRun() { - if (this.mode === 'backup') { - await this.dryRunBackup(); - } else if (this.mode === 'restore') { - await this.dryRunRestore(); - } - }, - - async dryRunBackup() { - // Validate backup metadata first - if (!this.validateBackupMetadata()) { - return; - } - - try { - this.loading = true; - this.loadingMessage = 'Performing dry run...'; - this.clearFileOperations(); - this.addFileOperation('Starting backup dry run...'); - - const metadata = this.backupMetadataConfig; - const patternsString = this.convertPatternsToString(metadata.include_patterns, metadata.exclude_patterns); - - const response = await sendJsonData("backup_test", { - patterns: patternsString, - include_hidden: metadata.include_hidden || false, - max_files: 10000 - }); - - if (response.success) { - this.addFileOperation(`Found ${response.files.length} files that would be backed up:`); - response.files.forEach((file, index) => { - this.addFileOperation(`${index + 1}. ${file.path} (${this.formatFileSize(file.size)})`); - }); - this.addFileOperation(`\nTotal: ${response.files.length} files, ${this.formatFileSize(response.files.reduce((sum, f) => sum + f.size, 0))}`); - this.addFileOperation('Dry run completed successfully.'); - } else { - this.error = response.error; - this.addFileOperation(`Error: ${response.error}`); - } - } catch (error) { - this.error = `Dry run error: ${error.message}`; - this.addFileOperation(`Error: ${error.message}`); - } finally { - this.loading = false; - } - }, - - async dryRunRestore() { - if (!this.backupFile) { - this.error = 'Please select a backup file first'; - return; - } - - try { - this.loading = true; - this.loadingMessage = 'Performing restore dry run...'; - this.clearFileOperations(); - this.addFileOperation('Starting restore dry run...'); - - const formData = new FormData(); - formData.append('backup_file', this.backupFile); - formData.append('restore_patterns', this.getEditorValue()); - - const response = await fetch('/backup_restore_preview', { - method: 'POST', - body: formData - }); - - const result = await response.json(); - - if (result.success) { - this.addFileOperation(`Found ${result.files.length} files that would be restored:`); - result.files.forEach((file, index) => { - this.addFileOperation(`${index + 1}. ${file.path} -> ${file.target_path}`); - }); - if (result.skipped_files && result.skipped_files.length > 0) { - this.addFileOperation(`\nSkipped ${result.skipped_files.length} files:`); - result.skipped_files.forEach((file, index) => { - this.addFileOperation(`${index + 1}. ${file.path} (${file.reason})`); - }); - } - this.addFileOperation(`\nTotal: ${result.files.length} files to restore, ${result.skipped_files?.length || 0} skipped`); - this.addFileOperation('Dry run completed successfully.'); - } else { - this.error = result.error; - this.addFileOperation(`Error: ${result.error}`); - } - } catch (error) { - this.error = `Dry run error: ${error.message}`; - this.addFileOperation(`Error: ${error.message}`); - } finally { - this.loading = false; - } - }, - - // Enhanced Restore Operations with Metadata Display - async handleFileUpload(event) { - const file = event.target.files[0]; - if (!file) return; - - this.backupFile = file; - this.error = ''; - this.restoreResult = null; - - try { - this.loading = true; - this.loadingMessage = 'Inspecting backup archive...'; - - const formData = new FormData(); - formData.append('backup_file', file); - - const response = await fetch('/backup_inspect', { - method: 'POST', - body: formData - }); - - const result = await response.json(); - - if (result.success) { - this.backupMetadata = result.metadata; - - // Load complete metadata for JSON editing - this.restoreMetadata = JSON.parse(JSON.stringify(result.metadata)); // Deep copy - - // Initialize restore editor with complete metadata JSON - if (this.restoreEditor) { - this.restoreEditor.setValue(JSON.stringify(this.restoreMetadata, null, 2)); - this.restoreEditor.clearSelection(); - } - - // Validate backup compatibility - this.validateBackupCompatibility(); - } else { - this.error = result.error; - this.backupMetadata = null; - } - } catch (error) { - this.error = `Inspection error: ${error.message}`; - this.backupMetadata = null; - } finally { - this.loading = false; - } - }, - - validateBackupCompatibility() { - if (!this.backupMetadata) return; - - const warnings = []; - - // Check Agent Zero version compatibility - // Note: Both backup and current versions are obtained via git.get_git_info() - const backupVersion = this.backupMetadata.agent_zero_version; - const currentVersion = "current"; // Retrieved from git.get_git_info() on backend - - if (backupVersion !== currentVersion && backupVersion !== "development") { - warnings.push(`Backup created with Agent Zero ${backupVersion}, current version is ${currentVersion}`); - } - - // Check backup age - const backupDate = new Date(this.backupMetadata.timestamp); - const daysSinceBackup = (Date.now() - backupDate) / (1000 * 60 * 60 * 24); - - if (daysSinceBackup > 30) { - warnings.push(`Backup is ${Math.floor(daysSinceBackup)} days old`); - } - - // Check system compatibility - const systemInfo = this.backupMetadata.system_info; - if (systemInfo && systemInfo.system) { - // Could add platform-specific warnings here - } - - if (warnings.length > 0) { - toast(`Compatibility warnings: ${warnings.join(', ')}`, 'warning'); - } - }, - - async performRestore() { - if (!this.backupFile) { - this.error = 'Please select a backup file'; - return; - } - - try { - this.loading = true; - this.loadingMessage = 'Restoring files...'; - this.error = ''; - this.clearFileOperations(); - this.addFileOperation('Starting file restoration...'); - - const formData = new FormData(); - formData.append('backup_file', this.backupFile); - formData.append('restore_patterns', this.getEditorValue()); - formData.append('overwrite_policy', this.overwritePolicy); - - const response = await fetch('/backup_restore', { - method: 'POST', - body: formData - }); - - const result = await response.json(); - - if (result.success) { - // Log restored files - this.addFileOperation(`Successfully restored ${result.restored_files.length} files:`); - result.restored_files.forEach((file, index) => { - this.addFileOperation(`${index + 1}. ${file.archive_path} -> ${file.target_path}`); - }); - - // Log skipped files - if (result.skipped_files && result.skipped_files.length > 0) { - this.addFileOperation(`\nSkipped ${result.skipped_files.length} files:`); - result.skipped_files.forEach((file, index) => { - this.addFileOperation(`${index + 1}. ${file.path} (${file.reason})`); - }); - } - - // Log errors - if (result.errors && result.errors.length > 0) { - this.addFileOperation(`\nErrors during restoration:`); - result.errors.forEach((error, index) => { - this.addFileOperation(`${index + 1}. ${error.path}: ${error.error}`); - }); - } - - this.addFileOperation(`\nRestore completed: ${result.restored_files.length} restored, ${result.skipped_files?.length || 0} skipped, ${result.errors?.length || 0} errors`); - this.restoreResult = result; - toast('Restore completed successfully', 'success'); - } else { - this.error = result.error; - this.addFileOperation(`Error: ${result.error}`); - } - } catch (error) { - this.error = `Restore error: ${error.message}`; - this.addFileOperation(`Error: ${error.message}`); - } finally { - this.loading = false; - } - }, - - // JSON Metadata Utilities - validateRestoreMetadata() { - try { - const metadataText = this.getEditorValue(); - const metadata = JSON.parse(metadataText); - - // Validate required fields - if (!Array.isArray(metadata.include_patterns)) { - throw new Error('include_patterns must be an array'); - } - if (!Array.isArray(metadata.exclude_patterns)) { - throw new Error('exclude_patterns must be an array'); - } - - this.restoreMetadata = metadata; - this.error = ''; - return true; - } catch (error) { - this.error = `Invalid JSON metadata: ${error.message}`; - return false; - } - }, - - getCurrentRestoreMetadata() { - if (this.validateRestoreMetadata()) { - return this.restoreMetadata; - } - return null; - }, - - // Restore Operations - Metadata Control - resetToOriginalMetadata() { - if (this.backupMetadata) { - this.restoreMetadata = JSON.parse(JSON.stringify(this.backupMetadata)); // Deep copy - - if (this.restoreEditor) { - this.restoreEditor.setValue(JSON.stringify(this.restoreMetadata, null, 2)); - this.restoreEditor.clearSelection(); - } - } - }, - - loadDefaultPatterns() { - if (this.backupMetadata && this.backupMetadata.backup_config?.default_patterns) { - // Parse default patterns and update current metadata - const defaultPatterns = this.backupMetadata.backup_config.default_patterns; - // This would need to be implemented based on how default patterns are structured - // For now, just reset to original metadata - this.resetToOriginalMetadata(); - } - }, - - async showRestorePreview() { - if (!this.backupFile || !this.restorePatterns.trim()) { - this.error = 'Please select a backup file and specify restore patterns'; - return; - } - - try { - this.loading = true; - this.loadingMessage = 'Generating restore preview...'; - - const formData = new FormData(); - formData.append('backup_file', this.backupFile); - formData.append('restore_patterns', this.getEditorValue()); - - const response = await fetch('/backup_restore_preview', { - method: 'POST', - body: formData - }); - - const result = await response.json(); - - if (result.success) { - this.previewFiles = result.files; - openModal('backup/file-preview.html'); - } else { - this.error = result.error; - } - } catch (error) { - this.error = `Preview error: ${error.message}`; - } finally { - this.loading = false; - } - }, - - // Utility - formatTimestamp(timestamp) { - if (!timestamp) return 'Unknown'; - return new Date(timestamp).toLocaleString(); - }, - - formatFileSize(bytes) { - if (!bytes) return '0 B'; - const sizes = ['B', 'KB', 'MB', 'GB']; - const i = Math.floor(Math.log(bytes) / Math.log(1024)); - return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${sizes[i]}`; - }, - - formatDate(dateString) { - if (!dateString) return 'Unknown'; - return new Date(dateString).toLocaleDateString(); - }, - - // Enhanced Metadata Management - toggleMetadataView() { - this.showDetailedMetadata = !this.showDetailedMetadata; - localStorage.setItem('backupShowDetailedMetadata', this.showDetailedMetadata); - }, - - async exportMetadata() { - if (!this.backupMetadata) return; - - const metadataJson = JSON.stringify(this.backupMetadata, null, 2); - const blob = new Blob([metadataJson], { type: 'application/json' }); - const url = URL.createObjectURL(blob); - const a = document.createElement('a'); - a.href = url; - a.download = 'backup-metadata.json'; - a.click(); - URL.revokeObjectURL(url); - }, - - // Progress Log Management - initProgressLog() { - this.progressLog = []; - this.progressLogId = 0; - }, - - addProgressLogEntry(message, type = 'info') { - if (!this.progressLog) this.progressLog = []; - - this.progressLog.push({ - id: this.progressLogId++, - time: new Date().toLocaleTimeString(), - message: message, - type: type - }); - - // Keep log size manageable - if (this.progressLog.length > 100) { - this.progressLog = this.progressLog.slice(-50); - } - - // Auto-scroll to bottom - this.$nextTick(() => { - const logElement = document.getElementById('backup-progress-log'); - if (logElement) { - logElement.scrollTop = logElement.scrollHeight; - } - }); - }, - - clearProgressLog() { - this.progressLog = []; - }, - - // Watch for progress data changes to update log - watchProgressData() { - this.$watch('progressData', (newData) => { - if (newData && newData.message) { - const type = newData.error ? 'error' : newData.warning ? 'warning' : newData.success ? 'success' : 'info'; - this.addProgressLogEntry(newData.message, type); - } - }); - } -}; - -const store = createStore("backupStore", model); -export { store }; -``` - -### 6. Integration Requirements - -#### Settings Tab Integration -The backup functionality is integrated as a dedicated "backup" tab in the settings system, providing: -- **Dedicated Tab**: Clean separation from other settings categories -- **Easy Access**: Users can quickly find backup/restore functionality -- **Organized Interface**: Backup operations don't clutter developer or other tabs - -#### Settings Button Handler -Update settings field button handling to open backup/restore modals when respective buttons are clicked in the backup tab. - -**Integration with existing `handleFieldButton()` method:** -```javascript -// In webui/js/settings.js - add to existing handleFieldButton method -async handleFieldButton(field) { - console.log(`Button clicked: ${field.id}`); - - if (field.id === "mcp_servers_config") { - openModal("settings/mcp/client/mcp-servers.html"); - } else if (field.id === "backup_create") { - openModal("settings/backup/backup.html"); - } else if (field.id === "backup_restore") { - openModal("settings/backup/restore.html"); - } -} -``` - -#### Modal System Integration -Use existing `openModal()` and `closeModal()` functions from the global modal system (`webui/js/modals.js`). - -#### Toast Notifications -Use existing Agent Zero toast system for consistent user feedback: -```javascript -// Use established toast patterns -globalThis.toast("Backup created successfully", "success"); -globalThis.toast("Restore completed", "success"); -globalThis.toast("Error creating backup", "error"); -``` - -#### ACE Editor Integration -The backup system follows Agent Zero's established ACE editor patterns **exactly** as implemented in MCP servers: - -**Theme Detection (identical to MCP servers):** -```javascript -// Exact pattern from webui/components/settings/mcp/client/mcp-servers-store.js -const container = document.getElementById("backup-metadata-editor"); -if (container) { - const editor = ace.edit("backup-metadata-editor"); - - const dark = localStorage.getItem("darkMode"); - if (dark != "false") { - editor.setTheme("ace/theme/github_dark"); - } else { - editor.setTheme("ace/theme/tomorrow"); - } - - editor.session.setMode("ace/mode/json"); - editor.setValue(JSON.stringify(defaultMetadata, null, 2)); - editor.clearSelection(); - this.backupEditor = editor; -} -``` - -**Cleanup Pattern (following MCP servers):** -```javascript -onClose() { - if (this.backupEditor) { - this.backupEditor.destroy(); - this.backupEditor = null; - } - // Additional cleanup... -} -``` - -#### API Integration Patterns -The backup system uses Agent Zero's existing API communication methods for consistency: - -**Standard API Calls (using global sendJsonData):** -```javascript -// Use existing global sendJsonData function (from webui/index.js) -const response = await sendJsonData("backup_test", { - patterns: patternsString, - include_hidden: metadata.include_hidden || false, - max_files: 1000 -}); - -// Error handling follows Agent Zero patterns -if (response.success) { - this.previewFiles = response.files; -} else { - this.error = response.error; -} -``` - -**File Upload API Calls:** -```javascript -// For endpoints that handle file uploads (restore operations) -const formData = new FormData(); -formData.append('backup_file', this.backupFile); -formData.append('restore_patterns', this.getEditorValue()); - -const response = await fetch('/backup_restore', { - method: 'POST', - body: formData -}); - -const result = await response.json(); -``` - -**Server-Sent Events (progress streaming):** -```javascript -// Real-time progress updates using EventSource -const eventSource = new EventSource('/backup_progress_stream?' + new URLSearchParams({ - patterns: patternsString, - backup_name: metadata.backup_name -})); - -eventSource.onmessage = (event) => { - const data = JSON.parse(event.data); - this.loadingMessage = data.message; - // Handle progress updates... -}; -``` - -#### Utility Function Integration -The backup system can leverage existing Agent Zero utility functions for consistency: - -**File Size Formatting:** -```javascript -// Check if Agent Zero has existing file size utilities -// If not available, implement following Agent Zero's style patterns -formatFileSize(bytes) { - if (!bytes) return '0 B'; - const sizes = ['B', 'KB', 'MB', 'GB']; - const i = Math.floor(Math.log(bytes) / Math.log(1024)); - return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${sizes[i]}`; -} -``` - -**Time Formatting (following existing patterns):** -```javascript -// Use existing localization helpers if available -formatTimestamp(timestamp) { - if (!timestamp) return 'Unknown'; - return new Date(timestamp).toLocaleString(); -} -``` - -**Error Handling Integration:** -```javascript -// Use existing error handling patterns -try { - const result = await backupOperation(); - globalThis.toast("Operation completed successfully", "success"); -} catch (error) { - console.error('Backup error:', error); - globalThis.toast(`Error: ${error.message}`, "error"); -} -``` - -### 8. Styling Guidelines - -#### CSS Variables -Use existing CSS variables for consistent theming: -- `--c-bg-primary`, `--c-bg-secondary` -- `--c-text-primary`, `--c-text-secondary` -- `--c-border`, `--c-error`, `--c-success-bg` - -#### Responsive Design -Ensure modals work on mobile devices with appropriate responsive breakpoints. - -#### Accessibility -- Proper ARIA labels for form elements -- Keyboard navigation support -- Screen reader compatibility - -### 9. Error Handling - -#### User-Friendly Messages -- Clear error messages for common scenarios -- Loading states with descriptive messages -- Success feedback with action confirmation - -#### Validation -- Client-side validation for file types -- Pattern syntax validation -- File size limits - -## Comprehensive Enhancement Summary - -### Enhanced File Preview System -- **Smart Directory Grouping**: Files organized by directory structure with 3-level depth limitation -- **Dual View Modes**: Toggle between grouped directory view and flat file list -- **Real-time Search**: Debounced search filtering by file name or path fragments -- **Expandable Groups**: Collapsible directory groups with file count badges and size indicators -- **Performance Optimization**: Limited display (50 files per group) with "show more" indicators -- **Export Capabilities**: Export file lists to text files or copy to clipboard - -### Real-time Progress Visualization -- **Live Progress Streaming**: Server-Sent Events for real-time backup/restore progress updates -- **Multi-stage Progress Bar**: Visual progress indicator with percentage and stage information -- **File-by-file Display**: Current file being processed with count progress (X/Y files) -- **Live Progress Log**: Scrollable, auto-updating log with timestamped entries -- **Progress Control**: Cancel operation capability with cleanup handling -- **Status Categorization**: Color-coded progress entries (info, warning, error, success) - -### Comprehensive Metadata Display -- **Enhanced Backup Information**: Basic info grid with creation date, author, version, file count, size, and checksum -- **Expandable Detailed View**: Collapsible sections for system info, environment details, and backup configuration -- **System Information Display**: Platform, architecture, Python version, hostname from backup metadata -- **Environment Context**: User, timezone, runtime mode, working directory information -- **Compatibility Validation**: Automatic compatibility checking with warnings for version mismatches and old backups -- **Metadata Export**: Export complete metadata.json for external analysis - -### Consistent UI Standards -- **Standardized Scrollable Areas**: All file lists and progress logs use consistent max-height (350px) with scroll -- **Monospace Font Usage**: File paths displayed in monospace for improved readability -- **Responsive Design**: Mobile-friendly layouts with proper breakpoints -- **Theme Integration**: Full CSS variable support for dark/light mode compatibility -- **Loading States**: Comprehensive loading indicators with descriptive messages - -### Advanced User Experience Features -- **Search and Filter**: Real-time file filtering with search term highlighting -- **Pattern Control Buttons**: "Reset to Original", "Load Defaults", "Preview Files" for pattern management -- **File Selection Preview**: Comprehensive file preview before backup/restore operations -- **Progress Cancellation**: User-controlled operation cancellation with proper cleanup -- **Error Recovery**: Clear error messages with suggested fixes and recovery options -- **State Persistence**: Remember user preferences (view mode, expanded groups, etc.) - -### Alpine.js Architecture Enhancements -- **Enhanced Store Management**: Extended backup store with grouped preview, progress tracking, and metadata handling -- **Event-driven Updates**: Real-time UI updates via Server-Sent Events integration -- **State Synchronization**: Proper Alpine.js reactive state management for complex UI interactions -- **Memory Management**: Cleanup of event sources, intervals, and large data structures -- **Performance Optimization**: Debounced search, efficient list rendering, and scroll management - -### Integration Features -- **Settings Modal Integration**: Seamless integration with existing Agent Zero settings system -- **Toast Notifications**: Success/error feedback using existing notification system -- **Modal System**: Proper integration with Agent Zero's modal management -- **API Layer**: Consistent API communication patterns following Agent Zero conventions -- **Error Handling**: Unified error handling and user feedback mechanisms - -### Accessibility and Usability -- **Keyboard Navigation**: Full keyboard support for all interactive elements -- **Screen Reader Support**: Proper ARIA labels and semantic HTML structure -- **Copy-to-Clipboard**: Quick clipboard operations for file lists and metadata -- **Export Options**: Multiple export formats for file manifests and metadata -- **Visual Feedback**: Clear visual indicators for loading, success, error, and warning states - -## Enhanced Restore Workflow with Pattern Editing - -### Metadata-Driven Restore Process -1. **Upload Archive**: User uploads backup.zip file in restore modal -2. **Parse Metadata**: System extracts and loads complete metadata.json -3. **Display JSON**: Complete metadata.json shown in ACE JSON editor -4. **Direct Editing**: User can modify include_patterns, exclude_patterns, and other settings directly -5. **JSON Validation**: Real-time validation of JSON syntax and structure -6. **Preview Changes**: User can preview which files will be restored based on current metadata -7. **Execute Restore**: Files restored according to final metadata configuration - -### JSON Metadata Editing Benefits -- **Single Source of Truth**: metadata.json is the authoritative configuration -- **Direct Control**: Users edit the exact JSON that will be used for restore -- **Full Access**: Modify any metadata property, not just patterns -- **Real-time Validation**: JSON syntax and structure validation as you type -- **Transparency**: See exactly what configuration will be applied - -### Enhanced User Experience -- **Intelligent Defaults**: Complete metadata automatically loaded from backup -- **JSON Editor**: Professional ACE editor with syntax highlighting and validation -- **Real-time Preview**: See exactly which files will be restored before proceeding -- **Immediate Feedback**: JSON validation and error highlighting as you edit - -This enhanced frontend specification delivers a professional-grade user interface with sophisticated file management, real-time progress monitoring, and comprehensive metadata visualization, all organized within a dedicated backup tab for optimal user experience. The implementation maintains perfect integration with Agent Zero's existing UI architecture and follows established Alpine.js patterns. - -### Implementation Status: ✅ COMPLETED & PRODUCTION READY - -### **Final Implementation State (December 2024)** - -#### **✅ COMPLETED Components:** - -**1. Settings Integration** ✅ -- **Backup Tab**: Dedicated "Backup & Restore" tab in settings interface -- **Button Handlers**: Integrated with existing `handleFieldButton()` method -- **Modal System**: Uses existing Agent Zero modal management -- **Toast Notifications**: Consistent error/success feedback - -**2. Alpine.js Components** ✅ -- **Backup Modal**: `webui/components/settings/backup/backup.html` -- **Restore Modal**: `webui/components/settings/backup/restore.html` -- **Backup Store**: `webui/components/settings/backup/backup-store.js` -- **Theme Integration**: Full dark/light mode support with CSS variables - -**3. Core Functionality** ✅ -- **JSON Metadata Editing**: ACE editor with syntax highlighting and validation -- **File Preview**: Grouped directory view with search and filtering -- **Real-time Operations**: Live backup creation and restore progress -- **Error Handling**: Comprehensive validation and user feedback -- **Progress Monitoring**: File-by-file progress tracking and logging - -**4. User Experience Features** ✅ -- **Drag & Drop**: File upload for restore operations -- **Search & Filter**: Real-time file filtering by name/path -- **Export Options**: File lists and metadata export -- **State Persistence**: Remember user preferences and expanded groups -- **Responsive Design**: Mobile-friendly layouts with proper breakpoints - -#### **✅ Backend Integration:** - -**API Endpoints Used:** -1. **`/backup_get_defaults`** - Get default patterns with resolved absolute paths -2. **`/backup_test`** - Pattern testing and dry run functionality -3. **`/backup_preview_grouped`** - Smart file grouping for UI display -4. **`/backup_create`** - Create and download backup archives -5. **`/backup_inspect`** - Extract metadata from uploaded archives -6. **`/backup_restore_preview`** - Preview restore operations -7. **`/backup_restore`** - Execute file restoration - -**Communication Patterns:** -- **Standard API**: Uses global `sendJsonData()` for consistency -- **File Upload**: FormData for archive uploads with proper validation -- **Error Handling**: Follows Agent Zero error formatting and toast patterns -- **Progress Updates**: Real-time file operation logging and status updates - -#### **✅ Key Technical Achievements:** - -**Enhanced Metadata Management:** -- **Direct JSON Editing**: Users edit metadata.json directly in ACE editor -- **Pattern Arrays**: Separate include_patterns/exclude_patterns for granular control -- **Real-time Validation**: JSON syntax checking and structure validation -- **System Information**: Complete backup context with platform/environment details - -**Advanced File Operations:** -- **Smart Grouping**: Directory-based organization with depth limitation -- **Hidden File Support**: Proper explicit vs wildcard pattern handling -- **Search & Filter**: Debounced search with real-time results -- **Export Capabilities**: File lists and metadata export functionality - -**Professional UI/UX:** -- **Consistent Styling**: Follows Agent Zero design patterns and CSS variables -- **Loading States**: Comprehensive progress indicators and status messages -- **Error Recovery**: Clear error messages with suggested fixes -- **Accessibility**: Keyboard navigation and screen reader support - -#### **✅ Frontend Architecture Benefits:** - -**Alpine.js Integration:** -- **Store Pattern**: Uses proven `createStore()` pattern from MCP servers -- **Component Lifecycle**: Proper initialization and cleanup following Agent Zero patterns -- **Reactive State**: Real-time UI updates with Alpine's reactivity system -- **Event Handling**: Leverages Alpine's declarative event system - -**Code Reuse:** -- **ACE Editor Setup**: Identical theme detection and configuration as MCP servers -- **Modal Management**: Uses existing Agent Zero modal and overlay systems -- **API Communication**: Consistent with Agent Zero's established API patterns -- **Error Handling**: Unified error formatting and toast notification system - -### **Implementation Quality Metrics:** - -**Code Quality:** ✅ -- Follows Agent Zero coding conventions -- Proper error handling and validation -- Clean separation of concerns -- Comprehensive documentation - -**User Experience:** ✅ -- Intuitive backup/restore workflow -- Real-time feedback and progress tracking -- Responsive design for all screen sizes -- Consistent with Agent Zero UI patterns - -**Performance:** ✅ -- Efficient file preview with grouping -- Debounced search and filtering -- Proper memory management and cleanup -- Optimized for large file sets - -**Reliability:** ✅ -- Comprehensive error handling -- Input validation and sanitization -- Proper file upload handling -- Graceful degradation for network issues - -### **Final Status: 🚀 PRODUCTION READY** - -The Agent Zero backup frontend is now: -- **Complete**: All planned features implemented and tested -- **Integrated**: Seamlessly integrated with existing Agent Zero infrastructure -- **Reliable**: Comprehensive error handling and edge case coverage -- **User-friendly**: Intuitive interface following Agent Zero design principles -- **Maintainable**: Clean code following established patterns and conventions - -**Ready for production use with full backup and restore capabilities!** - -The backup system provides users with a powerful, easy-to-use interface for backing up and restoring their Agent Zero configurations, data, and custom files using sophisticated pattern-based selection and real-time progress monitoring. diff --git a/docs/getting-started/mcp-setup.md b/docs/getting-started/mcp-setup.md deleted file mode 100644 index 1c456d58f..000000000 --- a/docs/getting-started/mcp-setup.md +++ /dev/null @@ -1,178 +0,0 @@ -# Agent Zero: MCP Client Integration Guide - -This guide explains how to configure and utilize external tool providers through the Model Context Protocol (MCP) with Agent Zero. This allows Agent Zero to leverage tools hosted by separate local or remote MCP-compliant servers. - -> [!NOTE] -> This guide covers Agent Zero as an MCP **client**. To expose Agent Zero as an MCP **server**, see [Connectivity → MCP Server](connectivity.md#mcp-server-connectivity). - -## What are MCP Servers? - -MCP servers are external processes or services that expose a set of tools that Agent Zero can use. Agent Zero acts as an MCP *client*, consuming tools made available by these servers. The integration supports three main types of MCP servers: - -1. **Local Stdio Servers**: These are typically local executables that Agent Zero communicates with via standard input/output (stdio). -2. **Remote SSE Servers**: These are servers, often accessible over a network, that Agent Zero communicates with using Server-Sent Events (SSE), usually over HTTP/S. -3. **Remote Streaming HTTP Servers**: These are servers that use the streamable HTTP transport protocol for MCP communication, providing an alternative to SSE for network-based MCP servers. - -## How Agent Zero Consumes MCP Tools - -Agent Zero discovers and integrates MCP tools dynamically: - -1. **Configuration**: You define the MCP servers Agent Zero should connect to in its configuration. The primary way to do this is through the Agent Zero settings UI. -2. **Saving Settings**: When you save your settings via the UI, Agent Zero updates the `usr/settings.json` file, specifically the `"mcp_servers"` key. -3. **Server Startup**: Agent Zero initializes configured MCP servers (stdio servers) or connects to them (remote servers). For `npx`/`uvx` based servers, the first run may download packages. -4. **Tool Discovery**: Upon initialization (or when settings are updated), Agent Zero connects to each configured and enabled MCP server and queries it for the list of available tools, their descriptions, and expected parameters. -5. **Dynamic Prompting**: The information about these discovered tools is then dynamically injected into the agent's system prompt. A placeholder like `{{tools}}` in a system prompt template (e.g., `prompts/agent.system.mcp_tools.md`) is replaced with a formatted list of all available MCP tools. This allows the agent's underlying Language Model (LLM) to know which external tools it can request. -6. **Tool Invocation**: When the LLM decides to use an MCP tool, Agent Zero's `process_tools` method (handled by `mcp_handler.py`) identifies it as an MCP tool and routes the request to the appropriate `MCPConfig` helper, which then communicates with the designated MCP server to execute the tool. - -## Recommended MCP Servers -Community-tested MCP servers include: - -- **Browser OS MCP** (browser automation) -- **Chrome DevTools MCP** (browser automation) -- **Playwright MCP** (browser automation) -- **n8n MCP** (workflow automation) -- **Gmail MCP** (email workflows) - -> [!TIP] -> The built-in browser agent can be unreliable; MCP-based browser tools are the recommended alternative. - -## Docker Networking Notes -If Agent Zero runs in Docker and your MCP server runs on the host: - -- Use `host.docker.internal` when available (macOS/Windows). -- On Linux, run the MCP server in the same Docker network and reference it by container name. - -If your MCP server is remote, use its HTTPS URL in the configuration. - -## Configuration - -### Configuration File & Method - -The primary method for configuring MCP servers is through **Agent Zero's settings UI**. - -When you input and save your MCP server details in the UI, these settings are written to: - -* `usr/settings.json` - -### The `mcp_servers` Setting in `usr/settings.json` - -Within `usr/settings.json`, the MCP servers are defined under the `"mcp_servers"` key. - -* **Value Type**: The value for `"mcp_servers"` must be a **JSON formatted string**. The string itself contains either: - * A JSON object containing `"mcpServers"` (recommended, matches the Settings UI) - * A JSON array of server configuration objects -* **Default Value**: An empty config (for example, `{"mcpServers": {}}`). -* **Manual Editing (Advanced)**: While UI configuration is recommended, you can also manually edit `usr/settings.json`. If you do, ensure the `"mcp_servers"` value is a valid JSON string, with internal quotes properly escaped. - -**Example `mcp_servers` configuration (recommended format):** - -```json -{ - "mcpServers": { - "sqlite": { - "command": "uvx", - "args": ["mcp-server-sqlite", "--db-path", "/root/db.sqlite"] - }, - "deep-wiki": { - "description": "Use this MCP to analyze GitHub repositories", - "url": "https://mcp.deepwiki.com/sse" - } - } -} -``` -*Note: In `usr/settings.json`, the entire value of `"mcp_servers"` is stored as a single string. The Settings UI handles escaping automatically.* - -* **Updating**: As mentioned, the recommended way to set or update this value is through Agent Zero's settings UI. -* **For Existing `settings.json` Files (After an Upgrade)**: If you have an existing `usr/settings.json` from a version of Agent Zero prior to MCP server support, the `"mcp_servers"` key will likely be missing. To add this key: - 1. Ensure you are running a version of Agent Zero that includes MCP server support. - 2. Run Agent Zero and open its settings UI. - 3. Save the settings (even without making changes). This action will write the complete current settings structure, including a default `"mcp_servers": ""` if not otherwise populated, to `usr/settings.json`. You can then configure your servers via the UI or by carefully editing this string. - -### MCP Server Configuration Structure - -Here are templates for configuring individual servers within the `mcp_servers` configuration: - -**1. Local Stdio Server** - -```json -{ - "name": "My Local Tool Server", - "description": "Optional: A brief description of this server.", - "type": "stdio", // Optional: Explicitly specify server type. Can be "stdio", "sse", or streaming HTTP variants ("http-stream", "streaming-http", "streamable-http", "http-streaming"). Auto-detected if omitted. - "command": "python", // The executable to run (e.g., python, /path/to/my_tool_server) - "args": ["path/to/your/mcp_stdio_script.py", "--some-arg"], // List of arguments for the command - "env": { // Optional: Environment variables for the command's process - "PYTHONPATH": "/path/to/custom/libs:.", - "ANOTHER_VAR": "value" - }, - "encoding": "utf-8", // Optional: Encoding for stdio communication (default: "utf-8") - "encoding_error_handler": "strict", // Optional: How to handle encoding errors. Can be "strict", "ignore", or "replace" (default: "strict"). - "disabled": false // Set to true to temporarily disable this server without removing its configuration. -} -``` - -**2. Remote SSE Server** - -```json -{ - "name": "My Remote API Tools", - "description": "Optional: Description of the remote SSE server.", - "type": "sse", // Optional: Explicitly specify server type. Can be "stdio", "sse", or streaming HTTP variants ("http-stream", "streaming-http", "streamable-http", "http-streaming"). Auto-detected if omitted. - "url": "https://api.example.com/mcp-sse-endpoint", // The full URL for the SSE endpoint of the MCP server. - "headers": { // Optional: Any HTTP headers required for the connection. - "Authorization": "Bearer YOUR_API_KEY_OR_TOKEN", - "X-Custom-Header": "some_value" - }, - "timeout": 5.0, // Optional: Connection timeout in seconds (default: 5.0). - "sse_read_timeout": 300.0, // Optional: Read timeout for the SSE stream in seconds (default: 300.0, i.e., 5 minutes). - "disabled": false -} -``` - -**3. Remote Streaming HTTP Server** - -```json -{ - "name": "My Streaming HTTP Tools", - "description": "Optional: Description of the remote streaming HTTP server.", - "type": "streaming-http", // Optional: Explicitly specify server type. Can be "stdio", "sse", or streaming HTTP variants ("http-stream", "streaming-http", "streamable-http", "http-streaming"). Auto-detected if omitted. - "url": "https://api.example.com/mcp-http-endpoint", // The full URL for the streaming HTTP endpoint of the MCP server. - "headers": { // Optional: Any HTTP headers required for the connection. - "Authorization": "Bearer YOUR_API_KEY_OR_TOKEN", - "X-Custom-Header": "some_value" - }, - "timeout": 5.0, // Optional: Connection timeout in seconds (default: 5.0). - "sse_read_timeout": 300.0, // Optional: Read timeout for the SSE and streaming HTTP streams in seconds (default: 300.0, i.e., 5 minutes). - "disabled": false -} -``` - -**Example `mcp_servers` value in `usr/settings.json`:** - -```json -{ - // ... other settings ... - "mcp_servers": "[{'name': 'MyPythonTools', 'command': 'python3', 'args': ['mcp_scripts/my_server.py'], 'disabled': false}, {'name': 'ExternalAPI', 'url': 'https://data.example.com/mcp', 'headers': {'X-Auth-Token': 'supersecret'}, 'disabled': false}]", - // ... other settings ... -} -``` - -**Key Configuration Fields:** - -* `"name"`: A unique name for the server. This name will be used to prefix the tools provided by this server (e.g., `my_server_name.tool_name`). The name is normalized internally (converted to lowercase, spaces and hyphens replaced with underscores). -* `"type"`: Optional explicit server type specification. Can be `"stdio"`, `"sse"`, or streaming HTTP variants (`"http-stream"`, `"streaming-http"`, `"streamable-http"`, `"http-streaming"`). If omitted, the type is auto-detected based on the presence of `"command"` (stdio) or `"url"` (defaults to sse for backward compatibility). -* `"disabled"`: A boolean (`true` or `false`). If `true`, Agent Zero will ignore this server configuration. -* `"url"`: **Required for Remote SSE and Streaming HTTP Servers.** The endpoint URL. -* `"command"`: **Required for Local Stdio Servers.** The executable command. -* `"args"`: Optional list of arguments for local Stdio servers. -* Other fields are specific to the server type and mostly optional with defaults. - -## Using MCP Tools - -Once configured, successfully installed (if applicable, e.g., for `npx` based servers), and discovered by Agent Zero: - -* **Tool Naming**: MCP tools will appear to the agent with a name prefixed by the server name you defined (and normalized, e.g., lowercase, underscores for spaces/hyphens). For instance, if your server is named `"sequential-thinking"` in the configuration and it offers a tool named `"run_chain"`, the agent will know it as `sequential_thinking.run_chain`. -* **Agent Interaction**: You can instruct the agent to use these tools. For example: "Agent, use the `sequential_thinking.run_chain` tool with the following input..." The agent's LLM will then formulate the appropriate JSON request. -* **Execution Flow**: Agent Zero's `process_tools` method (with logic in `python/helpers/mcp_handler.py`) prioritizes looking up the tool name in the `MCPConfig`. If found, the execution is delegated to the corresponding MCP server. If not found as an MCP tool, it then attempts to find a local/built-in tool with that name. - -This setup provides a flexible way to extend Agent Zero's capabilities by integrating with various external tool providers without modifying its core codebase. diff --git a/docs/guides/a2a-setup.md b/docs/guides/a2a-setup.md new file mode 100644 index 000000000..3212020fe --- /dev/null +++ b/docs/guides/a2a-setup.md @@ -0,0 +1,153 @@ +# A2A Server Setup + +Agent Zero can communicate with other Agent Zero instances using the A2A (Agent-to-Agent) protocol based on FastA2A. This guide shows you how to enable and configure A2A connectivity through the Settings UI. + +## What is A2A? + +A2A enables direct communication between multiple Agent Zero instances. This allows: + +- **Distributed workflows** - Delegate tasks to specialized agent instances +- **Context isolation** - Maintain separate workspaces for different agents +- **Long-running collaboration** - Persistent agent-to-agent conversations +- **Project-specific delegation** - Route work to agents with specific project contexts + +> [!NOTE] +> This guide covers enabling Agent Zero as an A2A server. For API-level integration details, see the [advanced connectivity documentation](../developer/connectivity.md). + +## Enabling the A2A Server + +### Step 1: Open A2A Configuration + +1. Click **Settings** in the sidebar +2. Navigate to the **MCP/A2A** tab +3. Scroll to the **A0 A2A Server** section +4. Toggle **Enable A2A server** to ON + +![A2A Server Settings](../res/setup/a2a/a2a-conn.png) + +### Step 2: Get Connection URL + +1. Click on **connection example** to view your A2A connection details +2. The dialog displays: + - **API Token** - Automatically generated from your username and password + - **A2A Connection URL** - The full URL other agents will use to connect + - Optional **Project selector** - To create project-specific connection URLs + +![A2A Connection Dialog](../res/setup/a2a/a2a2.png) + +### Step 3: Save Configuration + +1. Click **Save** to apply your settings +2. The A2A server is now active and ready to accept connections + +> [!IMPORTANT] +> The API token changes when you update your Agent Zero credentials. Existing connections will need to be reconfigured with the new token. + +## Connection URL Format + +The basic A2A connection URL follows this format: + +``` +http://YOUR_HOST:PORT/a2a/t-YOUR_API_TOKEN +``` + +### With Project Context + +To connect with a specific project active: + +``` +http://YOUR_HOST:PORT/a2a/t-YOUR_API_TOKEN/p-PROJECT_NAME +``` + +When a project is specified: +- All A2A conversations run in that project's context +- The agent has access to project-specific resources and knowledge +- Enables isolated, project-focused agent collaboration + +## Example Use Cases + +### 1. Local Development Setup + +Two Agent Zero instances on the same machine: + +``` +Instance 1: http://localhost:8080/a2a/t-abc123xyz +Instance 2: http://localhost:8081/a2a/t-def456uvw +``` + +### 2. Remote Agent Collaboration + +Connect to a remote Agent Zero instance: + +``` +http://agent.example.com:8080/a2a/t-remote-token +``` + +### 3. Project-Specific Delegation + +Main agent delegates frontend work to specialized agent: + +``` +http://localhost:8081/a2a/t-frontend-token/p-webapp-ui +``` + +## Docker Networking + +If running Agent Zero in Docker: + +- **Same Host:** Use `host.docker.internal:PORT` (macOS/Windows) or container networking (Linux) +- **Different Hosts:** Use the public IP or domain name of the target instance +- **Port Mapping:** Ensure the Agent Zero port is exposed in your Docker configuration + +## Security Considerations + +- **Token Protection:** Keep your API tokens secure - they provide full access to your Agent Zero instance +- **Network Access:** Consider using firewalls or reverse proxies to restrict A2A endpoint access +- **HTTPS:** For production deployments, use HTTPS to encrypt A2A communication +- **Credential Rotation:** Changing your password will invalidate all existing A2A connection URLs + +## Testing Your Connection + +You can test A2A connectivity using curl: + +```bash +curl -X POST http://localhost:8080/a2a/t-YOUR_TOKEN \ + -H "Content-Type: application/json" \ + -d '{"message": "Hello from another agent"}' +``` + +## A2A vs MCP + +| Feature | A2A | MCP | +|---------|-----|-----| +| **Purpose** | Agent-to-agent chat delegation | Tool/function access | +| **Use Case** | Long-running conversations | Specific tool calls | +| **Context** | Full chat context | Function parameters only | +| **Best For** | Workflow delegation | Tool integration | + +> [!TIP] +> Use A2A when you need another agent's reasoning and conversation capabilities. Use MCP when you just need access to specific tools or functions. + +## Troubleshooting + +### Connection Refused + +- Verify the A2A server is enabled in Settings +- Check that the Agent Zero instance is running +- Confirm the port is accessible (check firewall rules) + +### Invalid Token + +- Token may have changed due to credential updates +- Generate a new connection URL from Settings > MCP/A2A +- Update the connecting agent's configuration + +### Project Not Found + +- Verify the project name in the URL matches exactly +- Check that the project exists in the target instance +- Project names are case-sensitive + +## Advanced Configuration + +For detailed A2A protocol specifications, API examples, and integration patterns, see the [Advanced Connectivity Guide](../developer/connectivity.md). diff --git a/docs/guides/api-integration.md b/docs/guides/api-integration.md new file mode 100644 index 000000000..c0331212d --- /dev/null +++ b/docs/guides/api-integration.md @@ -0,0 +1,231 @@ +# Adding External APIs Without Code + +One of Agent Zero's most powerful capabilities is the ability to integrate external APIs on the fly without writing any code. By simply providing API documentation or code snippets, the agent can learn to use new services and remember how to use them in future conversations. + +This tutorial demonstrates how to integrate Google's image generation API from Google AI Studio - but the same process works for any public API. + +## How It Works + +Agent Zero can: + +1. **Analyze API code** - Understand how to use an API from provided snippets or documentation +2. **Execute the integration** - Run the code to accomplish your task +3. **Remember the solution** - Store the approach in its memory for future use +4. **Manage credentials** - Use secrets stored globally or per-project for authentication + +This means you can add capabilities like image generation, translation services, payment processing, or any other API-based feature simply by showing the agent how it works once. + +## Example: Image Generation with Google AI Studio + +Let's walk through adding image generation capabilities using Google's Gemini API. + +### Step 1: Get the API Code + +First, we need the code snippet that shows how to use the API. + +1. Go to [Google AI Studio](https://aistudio.google.com/) +2. Use the interface to create or test an image generation prompt +3. Click **"Get Code"** in the UI +4. Select **"Python"** as the language +5. Download the code file (or copy it to clipboard) + +![Getting code from Google AI Studio](../res/usage/api-int/api-int-1.png) + +> [!TIP] +> Most API platforms (OpenAI, Anthropic, Replicate, etc.) provide similar "Get Code" features or have documentation with ready-to-use snippets. + +### Step 2: Provide the Code to Agent Zero + +Now we'll tell Agent Zero to use this code: + +1. Open a chat with Agent Zero +2. Send a message like: **"Use this code to generate an image of the Agent Zero logo"** +3. Either: + - Attach the downloaded Python file, or + - Paste the code snippet into the chat + +Agent Zero will analyze the code and understand: +- What dependencies are needed (`google-genai` package) +- How to structure the API request +- What parameters are required +- How to handle the response + +![Agent Zero analyzing the API code](../res/usage/api-int/api-int-2image-gen-api2.png) + +### Step 3: Configure API Credentials + +On first run, Agent Zero will attempt to use the API but discover it needs an API key: + +![Missing API key error](../res/usage/api-int/api-int-3-api-key-missing-secrets.png) + +Agent Zero will tell you: +- What credential is missing (e.g., `GEMINI_API_KEY`) +- Where to configure it (Settings → External Services or Project settings) + +#### Adding the API Key + +You have two options for storing credentials: + +**Option 1: Global Secrets** (available to all chats and projects) +1. Click the **Settings** icon in the sidebar +2. Go to **External Services** +3. Add a new line: `GEMINI_API_KEY=your_actual_key_here` +4. Click **Save** + +**Option 2: Project Secrets** (available only within a specific project) +1. Open your project settings +2. Go to the **Secrets** tab +3. Add the key-value pair +4. Save the project + +![Configuring the API key in settings](../res/usage/api-int/api-int-4-secrets-setting.png) + +> [!NOTE] +> Global secrets are ideal for APIs you use frequently across different projects. Project secrets are better for client-specific or project-specific integrations. + +### Step 4: Generate the Image + +After configuring the API key, tell Agent Zero to proceed: + +**"I set the API key in secrets. Now you can use it."** + +Agent Zero will: +1. Retrieve the API key from secrets +2. Install required dependencies (`google-genai` package) +3. Execute the image generation code +4. Save the generated image to disk +5. Report the file location + +![Successful image generation](../res/usage/api-int/api-int-5-finish.png) + +The agent confirms: +- Mission complete +- File location: `/root/agent_zero_logo_0.jpg` +- File size: 378 KB + +## How Memory Works + +Here's where it gets interesting: **Agent Zero will remember this solution**. + +The next time you ask it to generate an image: +- It will automatically use the Gemini API approach it learned +- No need to provide the code snippet again +- The API key is already configured +- Dependencies are already installed + +The agent stores: +- **How to use the API** (code structure, parameters) +- **What the API does** (image generation) +- **What credentials are needed** (`GEMINI_API_KEY`) +- **Common patterns and best practices** from the interaction + +This memory persists across: +- Multiple conversations +- Agent restarts +- Different projects (for global memory and global secrets) + +## Use Cases + +This approach works for any external API. Common examples: + +### Communication & Notifications +- **SendGrid**: Email delivery +- **Twilio**: SMS and phone calls +- **Slack/Discord**: Message webhooks +- **Telegram**: Bot interactions + +### Data & Analytics +- **Google Sheets API**: Spreadsheet automation +- **Airtable**: Database operations +- **Stripe**: Payment processing +- **Plaid**: Banking data + +### Content & Media +- **Unsplash/Pexels**: Stock photos +- **ElevenLabs**: Text-to-speech +- **Whisper API**: Speech-to-text +- **Stable Diffusion**: Image generation +- **Replicate**: Various AI models + +### Development Tools +- **GitHub API**: Repository management +- **Jira/Linear**: Issue tracking +- **Vercel/Netlify**: Deployment +- **Docker Hub**: Container registry + +### Specialized Services +- **WeatherAPI**: Weather data +- **Google Maps**: Geocoding, directions +- **Currency exchange**: Forex rates +- **Translation APIs**: Multi-language support + +## Best Practices + +### 1. Start with Official Examples + +Always use code snippets from official documentation or API providers' "Get Code" features. These are: +- Tested and working +- Up-to-date with latest API versions +- Include proper error handling +- Show recommended practices + +### 2. Organize Credentials + +**For personal/global APIs:** +- Store in **Settings → External Services** +- Use clear naming: `SERVICE_API_KEY`, `SERVICE_SECRET` +- Add comments to document what each key is for + +**For project-specific APIs:** +- Store in **Project Settings → Secrets** +- Keeps client data isolated +- Prevents accidental cross-project usage + +### 3. Document in Project Instructions + +When integrating APIs for a specific project, add notes to the project instructions: + +```markdown +## Available APIs + +This project has access to: + +- **Gemini Image Generation**: Use for creating visuals and illustrations + - Credentials: GEMINI_API_KEY (configured in project secrets) + - Best for: Professional graphics, concept art, UI mockups + +- **SendGrid Email**: Use for sending automated emails + - Credentials: SENDGRID_API_KEY + - Best for: Notifications, reports, customer communications +``` + +This helps the agent understand what tools are available for the current project. + +## Advanced: Custom API Wrappers + +For APIs you use frequently, you can have Agent Zero create reusable wrapper functions: + +**"Create a Python module called `image_gen.py` with a function `generate_image(prompt, style='professional')` that uses the Gemini API. Include error handling and save the image to the current project folder."** + +Agent Zero will: +1. Create a clean, reusable module +2. Add proper documentation +3. Include error handling +4. Make it easy to call from future tasks + +Then in future chats: + +**"Use the image_gen module to create a logo"**, and it just works! + +## Conclusion + +By leveraging Agent Zero's ability to learn from API code snippets, you can: + +- **Add new capabilities instantly** without writing integration code +- **Keep solutions in memory** for reuse across conversations +- **Manage credentials securely** with global or project-scoped secrets +- **Scale across any public API** using the same simple workflow + +This makes Agent Zero incredibly versatile - it's not limited to its built-in features. Show it how to use an API once, and it becomes part of its permanent toolkit. + +Ready to try it yourself? Pick any API you want to integrate and follow the steps above! diff --git a/docs/development/contribution.md b/docs/guides/contribution.md similarity index 95% rename from docs/development/contribution.md rename to docs/guides/contribution.md index 3ee4d73bc..ed60e7501 100644 --- a/docs/development/contribution.md +++ b/docs/guides/contribution.md @@ -5,7 +5,7 @@ Contributions to improve Agent Zero are very welcome! This guide outlines how t ## Getting Started - 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 [extensions](../developer/extensions.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. diff --git a/docs/guides/mcp-setup.md b/docs/guides/mcp-setup.md new file mode 100644 index 000000000..09a259bbd --- /dev/null +++ b/docs/guides/mcp-setup.md @@ -0,0 +1,117 @@ +# MCP Server Setup + +Agent Zero can connect to external MCP (Model Context Protocol) servers to extend its capabilities with additional tools. This guide shows you how to add MCP servers through the Settings UI. + +## What are MCP Servers? + +MCP servers are external tools that Agent Zero can use to perform specialized tasks. Popular examples include: + +- **Browser automation** (Chrome DevTools, Playwright) +- **Workflow automation** (n8n) +- **Email operations** (Gmail) +- **Database access** (SQLite) + +> [!NOTE] +> This guide covers connecting to external MCP servers as a client. For exposing Agent Zero as an MCP server, see the [advanced documentation](../developer/mcp-configuration.md). + +## Adding an MCP Server + +### Step 1: Open MCP Configuration + +1. Click **Settings** in the sidebar +2. Navigate to the **MCP/A2A** tab +3. Click on **External MCP Servers** +4. Click the **Open** button to access the configuration editor + +![MCP Configuration Access](../res/setup/mcp/mcp-open-config.png) + +### Step 2: Add Your MCP Server + +In the JSON editor, add your MCP server configuration. Here's a simple example: + +```json +{ + "mcpServers": { + "chrome-devtools": { + "command": "npx", + "args": ["-y", "chrome-devtools-mcp@latest"] + } + } +} +``` + +![MCP Configuration Example](../res/setup/mcp/mcp-example-config.png) + +### Step 3: Apply and Verify + +1. Click **Apply now** to save your configuration +2. The server status will appear below, showing: + - Server name (e.g., `chrome_devtools`) + - Number of available tools + - Connection status (green indicator = connected) + +> [!TIP] +> The first time you run an `npx`-based MCP server, it may take a few moments to download and initialize. + +## Common MCP Server Examples + +### Local Command-Based Server + +```json +{ + "mcpServers": { + "sqlite": { + "command": "uvx", + "args": ["mcp-server-sqlite", "--db-path", "/root/db.sqlite"] + } + } +} +``` + +### Remote HTTP Server + +```json +{ + "mcpServers": { + "external-api": { + "url": "https://api.example.com/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } +} +``` + +## Docker Networking + +If Agent Zero runs in Docker and your MCP server runs on the host: + +- **macOS/Windows:** Use `host.docker.internal` in URLs +- **Linux:** Run the MCP server in the same Docker network and use the container name + +## Using MCP Tools + +Once connected, MCP tools become available to Agent Zero automatically. Tools are named with the server prefix, for example: + +- Server name: `chrome-devtools` +- Tool becomes: `chrome_devtools.navigate_to_url` + +Simply ask Agent Zero to perform tasks, and it will use the appropriate MCP tools when needed. + +## Advanced Configuration + +For detailed configuration options, server types, environment variables, and troubleshooting, see the [Advanced MCP Configuration Guide](../developer/mcp-configuration.md). + +## Recommended MCP Servers + +Community-tested and reliable MCP servers: + +- **Chrome DevTools MCP** - Direct Chrome control +- **Playwright MCP** - Cross-browser automation +- **n8n MCP** - Workflow automation +- **Gmail MCP** - Email management +- **VSCode MCP** - IDE workflows + +> [!TIP] +> For browser automation tasks, MCP-based browser tools are more reliable than the built-in browser agent. diff --git a/docs/guides/projects.md b/docs/guides/projects.md new file mode 100644 index 000000000..3a50782e0 --- /dev/null +++ b/docs/guides/projects.md @@ -0,0 +1,490 @@ +# Working with Projects + +Projects are one of Agent Zero's most powerful features for organizing your work. They create isolated workspaces with dedicated context, instructions, memory, and secrets - preventing context bleed between unrelated tasks or clients. + +This tutorial will guide you through creating, configuring, and using projects effectively. + +## What Are Projects? + +A project in Agent Zero is an isolated workspace that includes: + +- **Dedicated folder structure** under `/a0/usr/projects//` +- **Custom instructions** automatically injected into the agent's system prompt +- **Isolated or shared memory** to prevent context pollution +- **Project-specific secrets and variables** for secure credential management +- **Custom agent configurations** including subagent settings +- **Knowledge base integration** with project-scoped documents +- **Git repository integration** for version-controlled codebases +- **File structure injection** for automatic codebase awareness + +Think of projects as separate "personas" or "modes" for your agent - each with its own context, memory, and capabilities. + +## Creating Your First Project + +There are two ways to access the Projects interface: + +### Method 1: Dashboard Access +1. Open the **Dashboard** from the sidebar +2. Click the **Projects** button +3. The Projects modal will open + +### Method 2: Quick Access +1. Look at the top-right corner of the interface where it shows **"No project"** +2. Click on it to open the project dropdown +3. If you have no projects yet, click **"Projects"** to open the modal + +![Project Activation Dropdown](../res/usage/projects/projects-activate-project.png) + +### Creating an Empty Project + +Once in the Projects modal: + +1. Click **"Create project"** button +2. You'll see the project creation wizard + +![Project Creation Form](../res/usage/projects/projects-creation.png) + +The wizard includes: + +- **Title**: A human-readable name displayed in the UI +- **Color tag**: Visual identifier for quick recognition (choose from the color palette) +- **Git Repository** (optional): URL to clone a repository (see next section) + +> [!TIP] +> Choose meaningful titles and distinct colors, especially if you plan to work with multiple projects. This helps you quickly identify which project is active. + +### Creating a Git-Based Project + +Agent Zero's **Git Projects** feature allows you to clone repositories directly into your project workspace: + +1. In the creation form, enter a Git repository URL in the **Git Repository** field + - Supports both public and private repositories + - For private repositories, you can provide an authentication token +2. Click **"Create and continue"** +3. Agent Zero will clone the repository + +![Git Clone Progress](../res/usage/projects/projects-gitprojects-clone.png) + +The cloning process: +- Downloads the repository to `/a0/usr/projects//` +- By default, clones the `main` branch +- Supports authentication via token (stored securely, never in URLs) +- You can ask the agent to checkout different branches later + +![Git Project Status](../res/usage/projects/projects-git-projects-tree.png) + +After cloning completes, you'll see: +- Repository URL +- Current branch +- Clean/dirty status +- Last commit information + +> [!NOTE] +> If the cloned repository already contains a `.a0proj/` folder with `project.json`, Agent Zero will merge the existing configuration with your specified title and color preferences. + +## Project Configuration + +Once created, you can configure your project through the Edit Project interface: + +![Project Description and Instructions](../res/usage/projects/projects-desc-and-instructions.png) + +### Description and Instructions + +#### Description +The **Description** field helps both you and the agent understand the project's purpose. This is purely informational and helps provide context when switching between projects. + +**Example:** +``` +An intelligent Excel automation system that processes financial spreadsheets +from multiple sources, performs data validation and cleaning, consolidates +information, generates executive reports, and flags anomalies or compliance issues. +``` + +#### Instructions +The **Instructions** field is critical - these are automatically injected into the agent's system prompt when the project is active. Write clear, specific instructions that guide the agent's behavior for this project. + +**Example:** +```markdown +## Your Role +You are an expert Financial Data Analyst and Excel Automation Specialist. +Your job is to process, analyze, and report on financial spreadsheet data +with precision and business acumen. + +## Operational Context +- Work directory: `/usr/projects/excel-finance/` +- Input data location: `/usr/projects/excel-finance/data/incoming/` +- Processed files: `/usr/projects/excel-finance/data/processed/` +- Reports output: `/usr/projects/excel-finance/reports/` +- Templates: `/usr/projects/excel-finance/templates/` + +## Core Responsibilities + +### 1. Data Ingestion & Discovery +- Scan `/data/incoming/` for new Excel/CSV files +- Identify data types, sheets, and file structures +- Log source details and timestamps + +### 2. Data Validation & Cleaning +- Check for missing values, duplicates, and format inconsistencies +- Validate numerical ranges and date formats +- Flag suspicious patterns or outliers +- Document all cleaning operations + +### 3. Data Consolidation +- Merge data from multiple sources +- Normalize column names and formats +- Handle currency conversions and date standardization +- Create master datasets for reporting + +### 4. Executive Reporting +- Generate summary reports using templates in `/templates/` +- Include key metrics, trends, and visualizations +- Highlight anomalies and compliance issues +- Export as formatted Excel files with proper styling + +### 5. Compliance & Quality Checks +- Flag potential compliance issues +- Verify calculations and formulas +- Maintain audit trail of all operations +- Alert on critical errors or anomalies + +## Quality Standards +- Always validate input data before processing +- Use professional Excel formatting in outputs +- Include metadata (processing date, sources, versions) +- Document assumptions and limitations +- Provide clear error messages and suggestions +``` + +> [!IMPORTANT] +> Well-written instructions are the key to effective project-specific agent behavior. Be specific about: +> - The agent's role and expertise level +> - Directory paths and file locations +> - Expected workflows and procedures +> - Quality standards and validation rules +> - Output formats and requirements + +### Additional Instruction Files + +Besides the main instructions field, you can add multiple instruction files in the `.a0proj/instructions/` directory. These are automatically loaded and concatenated with the main instructions. + +This is useful for: +- Organizing complex instructions into logical sections +- Sharing common instructions across similar projects +- Version controlling instruction updates via Git + +### Memory Isolation + +Projects support two memory modes: + +- **Own memory** (default): The project has its own isolated memory directory + - Memories stored under `vector_db/projects//` + - Prevents context bleed between projects + - Ideal for client work, sensitive projects, or distinct domains + +- **Global memory**: The project shares the default memory pool + - Memories stored under `vector_db/default/` + - Useful when projects need shared knowledge + - Better for related projects in the same domain + +> [!TIP] +> Use **own memory** for: +> - Client projects with confidential information +> - Different programming languages/frameworks +> - Distinct domains (e.g., finance vs. marketing) +> +> Use **global memory** for: +> - Related sub-projects in the same domain +> - When you want the agent to remember across all work +> - Personal projects without sensitive data + +### Variables and Secrets + +Projects support scoped configuration values: + +#### Variables (Non-sensitive) +Stored in `.a0proj/variables.env`: +```bash +API_BASE_URL=https://api.example.com +DEFAULT_TIMEOUT=30 +OUTPUT_FORMAT=json +LOG_LEVEL=info +``` + +#### Secrets (Sensitive) +Stored in `.a0proj/secrets.env`: +```bash +API_KEY=sk-abc123xyz... +DATABASE_PASSWORD=super_secret_pwd +GITHUB_TOKEN=ghp_xyz789... +SMTP_PASSWORD=email_pwd_here +``` + +> [!IMPORTANT] +> - Secrets are stored locally in the container +> - They are masked in the UI when editing +> - Backups may not include secrets - keep a separate copy +> - Reference secrets in prompts by name: "Use my `API_KEY` to authenticate" + +### Subagent Configuration + +Projects can enable or disable specific subagents (like the Browser Agent). This is configured via the UI and stored in `.a0proj/agents.json`. + +### Knowledge Files + +Import project-specific knowledge documents: +1. Use the **Import Knowledge** button in the project interface +2. Files are stored in `.a0proj/knowledge/` organized by memory area +3. The agent can reference this knowledge when the project is active + +### File Structure Injection + +Projects can automatically inject their directory structure into the agent's context: + +**Settings (configurable per project):** +- **Enabled**: Toggle automatic file tree injection +- **Max depth**: How many directory levels to scan (default: 5) +- **Max files**: Maximum files to include (default: 20) +- **Max folders**: Maximum folders to include (default: 20) +- **Max lines**: Maximum lines in the output (default: 250) +- **Gitignore patterns**: Filter out unwanted files + +The default gitignore for projects excludes: +``` +.a0proj/ +venv/ +__pycache__/ +node_modules/ +.npm/ +.git/ +``` + +This feature is incredibly useful for code projects - the agent automatically "sees" your project structure and can navigate it intelligently. + +## Activating a Project + +To use a project, you need to activate it for your current chat: + +### In a New Chat +1. Create or select a project from the Projects modal +2. Start a new chat +3. The project is automatically active for that chat + +### In an Existing Chat +1. Click the project dropdown in the top-right corner (where it shows current project or "No project") +2. Select the desired project from the list +3. The project activates immediately for this chat + +![Project Activation](../res/usage/projects/projects-activate-project.png) + +> [!NOTE] +> Each chat can have its own active project. You can have multiple chats open with different projects active simultaneously. + +### First Interaction After Activation + +Once activated, the agent's behavior changes according to the project's configuration: + +![First Operations in Project](../res/usage/projects/projects-first-ops.png) + +The agent now: +- Has access to project-specific instructions +- Uses project-isolated memory (if configured) +- Can reference project secrets and variables +- Sees the project file structure (if enabled) +- Operates within the project's working directory + +**Example prompt after activation:** +``` +Hi A0. Start first development phase: +- recon +- scope definition +- AGENTS.md generation +``` + +The agent will understand the context based on the project's instructions and work accordingly. + +## Project Directory Structure + +Understanding the project directory structure helps you work effectively: + +``` +/a0/usr/projects// +├── .a0proj/ # Project metadata (hidden) +│ ├── project.json # Main configuration +│ ├── variables.env # Non-sensitive variables +│ ├── secrets.env # Sensitive credentials +│ ├── agents.json # Subagent settings +│ ├── instructions/ # Additional instruction files +│ │ ├── 01-setup.md +│ │ ├── 02-workflow.md +│ │ └── ... +│ └── knowledge/ # Project knowledge files +│ ├── main/ +│ ├── fragments/ +│ └── ... +├── src/ # Your actual project files +├── data/ # Data files +├── docs/ # Documentation +└── ... # Other project content +``` + +> [!TIP] +> The `.a0proj/` folder is automatically excluded from file structure injection (via gitignore patterns) to keep the agent's context clean. + +## Advanced Use Cases + +### Multi-Client Agency Work + +Use projects to isolate each client: + +``` +/usr/projects/client-acme/ +/usr/projects/client-globex/ +/usr/projects/client-initech/ +``` + +Each with: +- Client-specific instructions and context +- Isolated memory (no data leakage) +- Client API keys and credentials +- Project-specific knowledge bases + +### Multi-Language Development + +Create projects for different tech stacks: + +``` +/usr/projects/python-ml-research/ +/usr/projects/nodejs-webapp/ +/usr/projects/go-microservices/ +``` + +Each with language-specific: +- Code patterns and best practices +- Framework documentation +- Linting and formatting rules + +### Domain-Specific Work + +Organize by business domain: + +``` +/usr/projects/finance-automation/ +/usr/projects/marketing-analytics/ +/usr/projects/hr-automation/ +``` + +Each with domain-specific: +- Terminology and concepts +- Industry standards and regulations +- Specialized tools and APIs + +## Combining Projects with Tasks + +Projects work exceptionally well with Agent Zero's **Tasks & Scheduling** feature: + +1. Create a project for a specific domain (e.g., "Daily Email Reports") +2. Configure project instructions for the recurring task +3. Schedule a task that activates this project +4. The task runs in isolation with project-specific context + +**Example:** +- **Project**: "Daily Sales Summary" +- **Instructions**: "Fetch yesterday's sales data, generate summary report, email to team" +- **Task**: Scheduled daily at 8 AM +- **Result**: Consistent, context-aware automated reporting + +See [Tasks & Scheduling](usage.md#tasks--scheduling) for more details. + +## Best Practices + +### Instruction Writing +- **Be specific**: Don't say "analyze data" - specify format, methods, and output +- **Include paths**: Always mention where files should be read/written +- **Define quality standards**: What constitutes "good" output? +- **Specify error handling**: How should the agent respond to issues? +- **Use markdown formatting**: Clear sections and lists improve readability + +### Memory Management +- Use **own memory** by default for client work +- Use **global memory** only when projects truly need shared knowledge +- Regularly review and clean project memory via the Memory Dashboard +- Clear memory when archiving completed projects + +### Security +- Never commit `.a0proj/secrets.env` to version control +- Use project-scoped secrets instead of global secrets for sensitive work +- Consider separate projects for different security levels +- Backup secrets manually - they may not be included in automatic backups + +### Organization +- Use clear, descriptive project names +- Choose distinct colors for visual identification +- Keep instructions updated as project scope evolves +- Document any manual setup steps in project instructions + +### Performance +- Adjust file structure injection limits based on project size +- Use gitignore patterns to exclude large build artifacts +- Consider disabling file structure injection for very large codebases +- Monitor memory growth and clean periodically + +## Troubleshooting + +### Project Not Loading Instructions +**Problem**: Agent doesn't seem to follow project instructions + +**Solutions**: +- Verify project is actually activated (check top-right dropdown) +- Check instructions are saved (edit project and verify content) +- Look for syntax errors in instructions markdown +- Try deactivating and reactivating the project + +### Memory Not Isolated +**Problem**: Agent remembers things from other projects + +**Solutions**: +- Check project memory setting is "own" not "global" +- Deactivate and reactivate the project +- Clear the project's memory directory via Memory Dashboard +- Restart chat context if necessary + +### Git Clone Failures +**Problem**: Repository won't clone + +**Solutions**: +- Verify the Git URL is correct +- For private repos, ensure you provided a valid token +- Check network connectivity +- Try cloning manually via terminal to diagnose issue +- Look for error messages in console/logs + +### Secrets Not Available +**Problem**: Agent can't access project secrets + +**Solutions**: +- Verify secrets are saved in project settings +- Check secret variable names match what you're referencing +- Try referencing by exact name: "use my `API_KEY`" +- Ensure project is activated for current chat + +### File Structure Not Showing +**Problem**: Agent doesn't see project files + +**Solutions**: +- Enable file structure injection in project settings +- Increase max_files/max_folders limits +- Check gitignore patterns aren't too restrictive +- Verify files exist in project directory + +## Next Steps + +Now that you understand projects, explore: + +- [Tasks & Scheduling](usage.md#tasks--scheduling) - Automate project-based work +- [Memory Management](usage.md#memory-management) - Maintain project knowledge +- [Backup & Restore](usage.md#backup--restore) - Preserve project configurations +- [Extensions](../developer/extensions.md) - Extend project capabilities + +> [!TIP] +> Start with a simple project to learn the system, then gradually add complexity. Projects are most powerful when instructions are well-crafted and memory is properly managed. diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md index bde4009d1..ad75e1206 100644 --- a/docs/guides/troubleshooting.md +++ b/docs/guides/troubleshooting.md @@ -3,13 +3,13 @@ This page addresses frequently asked questions (FAQ) and provides troubleshootin ## Frequently Asked Questions **1. How do I ask Agent Zero to work directly on my files or dirs?** -- Place the files/dirs in `/a0/work_dir`. Agent Zero will be able to perform tasks on them. +- Place the files/dirs in `/a0/usr`. Agent Zero will be able to perform tasks on them. **2. When I input something in the chat, nothing happens. What's wrong?** - Check if you have set up API keys in the Settings page. If not, the application cannot call LLM providers. **3. I get “Invalid model ID.” What does that mean?** -- Verify the **provider** and **model naming**. For example, `openai/gpt-4.1` is correct for OpenRouter, but **incorrect** for the native OpenAI provider. +- Verify the **provider** and **model naming**. For example, `openai/gpt-5.3` is correct for OpenRouter, but **incorrect** for the native OpenAI provider, which goes without prefix. **4. Does ChatGPT Plus include API access?** - No. ChatGPT Plus does not include API credits. You must provide an OpenAI API key in Settings. @@ -27,7 +27,7 @@ Refer to the [Choosing your LLMs](installation.md#installing-and-using-ollama-lo Use **Settings → Backup & Restore** and avoid mapping the entire `/a0` directory. See [How to update Agent Zero](installation.md#how-to-update-agent-zero). **8. My browser agent fails or is unreliable. What now?** -The built-in browser agent is currently unstable on some systems. Use MCP alternatives such as Browser OS, Chrome DevTools, or Playwright. See [MCP Setup](mcp_setup.md). +The built-in browser agent is currently unstable on some systems. Use Skills or MCP alternatives such as Browser OS, Chrome DevTools, or Vercel's Agent Browser. See [MCP Setup](mcp-setup.md). **9. My secrets disappeared after a backup restore.** Secrets are stored in `/a0/usr/secrets.env` and are not always included in backup archives. Copy them manually. @@ -36,7 +36,7 @@ Secrets are stored in `/a0/usr/secrets.env` and are not always included in backu - Join the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/B8KZKNsPpj) community. **11. How do I adjust API rate limits?** -Use the model rate limit fields in Settings (Chat/Utility/Embedding model sections) to set request/input/output limits. These map to the model config limits (for example `limit_requests`, `limit_input`, `limit_output`). +Use the model rate limit fields in Settings (Chat/Utility/Browser model sections) to set request/input/output limits. These map to the model config limits (for example `limit_requests`, `limit_input`, `limit_output`). **12. My `code_execution_tool` doesn't work, what's wrong?** - Ensure Docker is installed and running. @@ -44,7 +44,7 @@ Use the model rate limit fields in Settings (Chat/Utility/Embedding model sectio - Verify that the Docker image is updated. **13. Can Agent Zero interact with external APIs or services (e.g., WhatsApp)?** -Yes, by creating custom tools or using MCP servers. See [Extensibility](extensibility.md) and [MCP Setup](mcp_setup.md). +Yes, by creating custom tools or using MCP servers. See [Extensions](../developer/extensions.md) and [MCP Setup](mcp-setup.md). ## Troubleshooting diff --git a/docs/guides/usage.md b/docs/guides/usage.md index 2a0b08591..eb570cc16 100644 --- a/docs/guides/usage.md +++ b/docs/guides/usage.md @@ -1,30 +1,29 @@ # Usage Guide This guide explores usage and configuration scenarios for Agent Zero. You can consider this as a reference post-installation guide. -![Utility Message with Solutions](../res/memory-man.png) +![Utility Message with Solutions](../res/usage/first-task.png) ## Basic Operations Agent Zero provides several basic operations through its interface: ### Restart Framework -The Restart button allows you to quickly restart the Agent Zero framework without using the terminal: +The Restart button allows you to quickly restart the Agent Zero container without using the terminal: -![Restart Framework](../res/ui-restarting.png) +![Restart Framework](../res/usage/restart.png) -* Click the "Restart" button in the sidebar -* A blue notification will appear indicating "Restarting..." -* Once complete, a green success message "Restarted" will be shown -* The framework will reinitialize while maintaining your current chat history and context +* Click the "Restart" button in the sidebar dropdown +* A blue inline confirmation will appear indicating "Confirm" +* Once confirmed, the framework will reinitialize and restart the container > [!TIP] > Use the Restart function when you want to: > - Reset the framework if you encounter unexpected behavior -> - Reinitialize the system when agents become unresponsive +> - See changes applied to the framework code ### Action Buttons Located beneath the chat input box, Agent Zero provides a set of action buttons for enhanced control and visibility: -![Action Buttons](../res/ui-actions.png) +![Action Buttons](../res/usage/action-btns.png) #### Chat Flow Control * **Pause/Resume Agent:** Toggle button to pause and resume chat flow - Click to pause ongoing agent operations @@ -36,14 +35,17 @@ Located beneath the chat input box, Agent Zero provides a set of action buttons - Supports `.txt`, `.pdf`, `.csv`, `.html`, `.json`, and `.md` formats - Files are stored in `/a0/knowledge/custom/main` - Success message confirms successful import - - See [knowledge](../advanced/architecture.md#knowledge) for more details + - See [knowledge](../developer/architecture.md#knowledge) for more details ### File Browser: Manage files in the Agent Zero environment + +![File Browser](../res/usage/file-browser.png) + - Upload new files and folders - Download files (click filename) or folders (as zip archives) - - Delete files and folders + - Rename and Delete files and folders - Navigate directories using the "Up" button - - Support for file renaming and search coming soon + - Edit files in the File Editor - See [File Browser](#file-browser) section for detailed features #### Debugging and Monitoring @@ -52,7 +54,7 @@ Located beneath the chat input box, Agent Zero provides a set of action buttons - Shows current conversation context - Displays active instructions and parameters -![Context](../res/ui-context.png) +![Context](../res/usage/ui-context1.png) ### History: Access the chat history in JSON format @@ -60,14 +62,14 @@ Access the chat history in JSON format - Useful for debugging and understanding agent behavior - Files are stored under `/a0/usr/chats/` inside the container -![History](../res/ui-history.png) +![History](../res/usage/ui-history1.png) * **Nudge:** Restart the agent's last process - Useful when agents become unresponsive - Retries the last operation - Helps recover from stuck states -![Nudge](../res/ui-nudge.png) +![Nudge](../res/usage/nudge.png) > [!TIP] > Use the Context and History buttons to understand how the agent interprets your instructions and debug any unexpected behavior. @@ -83,7 +85,7 @@ Agent Zero supports direct file attachments in the chat interface for seamless f - Images show thumbnails when available - Files are listed in the chat input area waiting to be sent -![File Attachments](../res/ui-attachments.png) +![File Attachments](../res/usage/attachments-1.png) #### Working with Attached Files * Files can be referenced directly in your messages @@ -93,13 +95,13 @@ Agent Zero supports direct file attachments in the chat interface for seamless f - Perform operations on multiple files simultaneously - Confirm successful file operations with detailed responses -![Working with Attachments](../res/ui-attachments-2.png) +![Working with Attachments](../res/usage/attachments-2.png) > [!TIP] > When working with multiple files, you can attach them all at once and then give instructions about what to do with them. The agent will handle them as a batch while keeping you informed of the progress. ## Tool Usage -Agent Zero's power comes from its ability to use [tools](../advanced/architecture.md#tools). Here's how to leverage them effectively: +Agent Zero's power comes from its ability to use [tools](../developer/architecture.md#tools). Here's how to leverage them effectively: - **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. @@ -110,7 +112,19 @@ The built-in browser agent currently has dependency issues on some systems. If w - **Chrome DevTools MCP** - **Playwright MCP** -See [MCP Setup](../getting-started/mcp-setup.md) for configuration guidance and recommended servers. +See [MCP Setup](mcp-setup.md) for configuration guidance and recommended servers. + +### Agent-to-Agent (A2A) Communication + +Agent Zero instances can communicate with each other using the A2A protocol. This enables: + +- **Task delegation** to specialized agent instances +- **Distributed workflows** across multiple agents +- **Project-specific collaboration** with isolated contexts + +To enable A2A connectivity, go to **Settings → MCP/A2A → A0 A2A Server** and toggle the server on. You'll receive a connection URL that other Agent Zero instances can use to communicate with your agent. + +See [A2A Setup](a2a-setup.md) for detailed configuration and use cases. ## 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: @@ -134,37 +148,502 @@ 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](../advanced/architecture.md#agent-hierarchy-and-communication), with superior agents delegating tasks to subordinates. This allows for structured problem-solving and efficient resource allocation. +* **Hierarchy:** Agent Zero uses a [hierarchical structure](../developer/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) +![](../res/usage/multi-agent.png) ## Projects -Projects create isolated workspaces with their own context, instructions, memory, and secrets. This prevents context bleed between unrelated tasks or clients. +Projects are isolated workspaces that provide dedicated context, instructions, memory, and secrets for specific tasks or clients. They are one of Agent Zero's most powerful organizational features, preventing context bleed and enabling focused, specialized agent behavior. -- Project files live under `/a0/usr/projects//` -- Project instructions are automatically injected from `.a0proj/instructions/` -- Project memory and knowledge are stored separately from global memory +### What Projects Provide -See [Projects in Extensibility](../development/extensibility.md#projects) for structure details and file locations. +Each project includes: -## Tasks & Scheduling -Tasks allow Agent Zero to spawn scheduled or on-demand work in separate contexts. +- **Isolated workspace** under `/a0/usr/projects//` +- **Custom instructions** automatically injected into system prompts +- **Dedicated or shared memory** to control context isolation +- **Project-scoped secrets and variables** for secure credential management +- **Git repository integration** for cloning and working with codebases +- **File structure injection** for automatic codebase awareness +- **Custom agent configurations** including subagent settings +- **Knowledge base integration** with project-specific documents -- **Schedule from UI:** Settings → Tasks Scheduler can run a task at a specified time. -- **Schedule from chat:** ask the agent to create a task for a future time. -- **Dedicated context:** each task runs in its own chat context, which pairs well with Projects. +### Creating Projects + +There are two ways to access project management: + +1. **Dashboard Access**: Click **Projects** in the sidebar to open the Projects modal +2. **Quick Access**: Click the project dropdown in the top-right corner (shows "No project" when none is active) + +![Project Creation](../res/usage/projects/projects-creation.png) + +#### Empty Projects + +Create a new empty project workspace: +1. Click **"Create project"** +2. Enter a **title** (human-readable name) +3. Choose a **color tag** for visual identification +4. Click **"Create and continue"** + +#### Git-Based Projects + +Clone a repository directly into your project workspace: +1. Enter a **Git repository URL** (public or private) +2. Optionally provide an authentication token for private repos +3. Agent Zero clones the repository and sets up the project structure + +![Git Clone Progress](../res/usage/projects/projects-gitprojects-clone.png) + +The system clones the `main` branch by default. You can ask the agent to checkout other branches later. After cloning, you'll see repository status including current branch, clean/dirty state, and last commit info. + +![Git Project Status](../res/usage/projects/projects-git-projects-tree.png) + +> [!NOTE] +> If the cloned repository already contains a `.a0proj/` configuration folder, Agent Zero merges the existing configuration with your specified preferences. + +### Project Configuration + +![Project Configuration](../res/usage/projects/projects-desc-and-instructions.png) + +#### Description and Instructions + +- **Description**: Helps you and the agent understand the project's purpose and context +- **Instructions**: Critical field that gets injected into the agent's system prompt when the project is active + +> [!IMPORTANT] +> Well-written instructions are key to effective project-specific behavior. Be specific about: +> - The agent's role and expertise for this project +> - Directory paths and file locations +> - Expected workflows and procedures +> - Quality standards and validation rules +> - Output formats and requirements + +**Example instructions:** +```markdown +## Your Role +You are an expert Financial Data Analyst working with Excel automation. + +## Operational Context +- Work directory: `/usr/projects/excel-finance/` +- Input data: `/usr/projects/excel-finance/data/incoming/` +- Reports output: `/usr/projects/excel-finance/reports/` + +## Core Responsibilities +1. Scan for new Excel/CSV files in incoming directory +2. Validate and clean data (check for missing values, duplicates) +3. Consolidate data from multiple sources +4. Generate executive reports with visualizations +5. Flag compliance issues and anomalies +``` + +#### Memory Isolation + +Choose how project memory is managed: + +- **Own memory** (recommended): Project has isolated memory under `vector_db/projects//` + - Prevents context bleed between projects + - Ideal for client work, sensitive projects, or distinct domains + +- **Global memory**: Project shares the default memory pool + - Useful when projects need shared knowledge + - Better for closely related projects + +#### Variables and Secrets + +Projects support scoped configuration: + +- **Variables** (non-sensitive): Stored in `.a0proj/variables.env` + ```bash + API_BASE_URL=https://api.example.com + OUTPUT_FORMAT=json + ``` + +- **Secrets** (sensitive): Stored in `.a0proj/secrets.env` + ```bash + API_KEY=sk-abc123xyz... + DATABASE_PASSWORD=super_secret_pwd + ``` + +Reference these in your prompts: "Use my `API_KEY` to authenticate with the service" + +> [!WARNING] +> Secrets may not be included in backup archives. Keep a separate manual copy of critical credentials. + +#### File Structure Injection + +Projects can automatically inject their directory structure into the agent's context. This is configurable per project: + +- **Max depth**: Directory levels to scan (default: 5) +- **Max files/folders**: Limits for context size +- **Gitignore patterns**: Filter out build artifacts, dependencies, etc. + +The default ignores: `.a0proj/`, `venv/`, `__pycache__/`, `node_modules/`, `.git/` + +This feature helps the agent understand your codebase structure without manual explanation. + +### Activating Projects + +To use a project, activate it for your current chat: + +1. Click the project dropdown in the top-right corner +2. Select the desired project from the list +3. The project activates immediately + +![Project Activation](../res/usage/projects/projects-activate-project.png) + +Each chat can have its own active project. Multiple chats can use different projects simultaneously. + +Once activated, the agent: +- Follows project-specific instructions +- Uses project memory (if isolated) +- Has access to project secrets and variables +- Sees the project file structure (if enabled) +- Works in the project directory by default + +![First Operations](../res/usage/projects/projects-first-ops.png) + +### Project Directory Structure + +``` +/a0/usr/projects// +├── .a0proj/ # Project metadata (managed by A0) +│ ├── project.json # Main configuration +│ ├── variables.env # Non-sensitive config +│ ├── secrets.env # Sensitive credentials +│ ├── agents.json # Subagent settings +│ ├── instructions/ # Additional instruction files +│ └── knowledge/ # Project knowledge base +├── src/ # Your actual project files +├── data/ # Data files +└── ... # Other project content +``` + +### Common Use Cases + +**Multi-Client Work**: Create separate projects for each client with isolated memory and credentials + +**Multi-Language Development**: Organize by tech stack (Python ML, Node.js webapp, Go microservices) + +**Domain-Specific Tasks**: Separate projects for finance, marketing, HR with domain-specific instructions + +**Automated Workflows**: Combine with [Tasks & Scheduling](#tasks--scheduling) for recurring project-based work + +### Best Practices + +- Use **own memory** by default for client work to prevent context bleed +- Write **specific instructions** - mention paths, formats, and quality standards +- Choose **distinct colors** for easy visual identification when switching +- Keep **secrets separate** from version control - backup manually +- **Adjust file structure limits** based on project size +- **Clean memory periodically** via Memory Dashboard for optimal performance > [!TIP] -> Combine **Projects + Tasks + Notifications** for recurring, scoped workflows (e.g., daily inbox summaries). See [Notifications](../advanced/notifications.md) for alerts. +> For a comprehensive guide to creating and managing projects, including detailed examples and troubleshooting, see the [Projects Tutorial](projects.md). -## Prompt Engineering -Effective prompt engineering is crucial for getting the most out of Agent Zero. Here are some tips and techniques: +See also: +- [Projects in Extensions](../developer/extensions.md#projects) - Technical structure details +- [Tasks & Scheduling](#tasks--scheduling) - Automate project-based work +- [Memory Management](#memory-management) - Maintain project knowledge -* **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. To achieve a full-stack, web-app development task, for example, you might need to iterate for a few hours for 100% success. +## Tasks & Scheduling +Tasks enable Agent Zero to run automated or scheduled work in isolated contexts. They're perfect for recurring workflows, batch processing, or time-delayed operations that don't require immediate attention. + +### What Are Tasks? + +Tasks are autonomous work units that Agent Zero executes in dedicated or shared chat contexts. Each task includes: + +- **Prompt and Instructions**: What the agent should do +- **Execution Schedule**: When to run (cron schedule, specific times, or manual) +- **Project Association**: Optional project context with its instructions and secrets +- **Dedicated Context**: Each task can maintain its own conversation history +- **State Management**: Tracks idle, running, disabled, or error states +- **Result Tracking**: Stores last run time and execution results + +### Task Types + +Agent Zero supports three types of tasks: + +#### Scheduled Tasks +Run on a recurring schedule using cron syntax: +- **Daily reports**: `0 9 * * *` (every day at 9 AM) +- **Hourly checks**: `0 * * * *` (every hour) +- **Weekly summaries**: `0 9 * * 1` (Mondays at 9 AM) +- **Custom intervals**: Full cron flexibility for complex schedules + +#### Planned Tasks +Execute at specific, predetermined times: +- **One-time future execution**: Single date/time +- **Multi-step campaigns**: List of specific execution times +- **Event-driven sequences**: Coordinate with external schedules + +#### Ad-hoc Tasks +Manual execution for on-demand work: +- **Quick batch jobs**: Run when needed +- **Testing workflows**: Verify task configuration +- **One-off operations**: Tasks that don't need scheduling + +### Creating Tasks + +#### From the UI + +Access the Task Scheduler from the sidebar: + +1. Click **Settings** → **Tasks Scheduler** +2. Click **"New Task"** to create a task + +![Task Scheduler](../res/usage/tasks/scheduler-1.png) + +The scheduler shows: +- **Task List**: All configured tasks with their state +- **Filter Controls**: By type (scheduled, planned, ad-hoc) and state +- **Quick Actions**: Run, pause, edit, or delete tasks +- **Task Details**: Name, project association, last run, next run time + +#### From Chat + +Ask the agent to create tasks programmatically: + +``` +Create a scheduled task that checks my email inbox every morning at 8 AM +and summarizes new messages from the last 24 hours. +``` + +The agent uses the `scheduler` tool to create tasks based on your natural language description. + +### Task Configuration + +![Edit Task](../res/usage/tasks/edit-task.png) + +When editing a task, you configure: + +#### Task Name +A unique identifier for the task: +- Use descriptive names: "Morning report for incoming Gmail" +- Keep it concise but clear +- Helps identify tasks in logs and notifications + +#### Task Type +Choose the execution model: +- **Scheduled**: Recurring cron-based execution +- **Planned**: Specific date/time list +- **Ad-hoc**: Manual execution only + +> [!NOTE] +> Task type cannot be changed after creation. To switch types, create a new task. + +#### Project Association +Optionally link the task to a project: + +**Benefits of project-scoped tasks:** +- Task inherits project instructions automatically +- Access to project-specific secrets and variables +- Uses project's isolated memory (if configured) +- Runs in project's working directory +- Perfect for client-specific or domain-specific automation + +**Example:** +- Project: "Financial Reports" +- Task: "Daily Portfolio Summary" +- Result: Task automatically uses financial analysis instructions, API keys, and memory from the project + +#### State Management +Control task execution: + +- **Idle**: Ready to run when scheduled (green indicator) +- **Running**: Currently executing (blue indicator) +- **Disabled**: Won't execute even if scheduled (gray indicator) +- **Error**: Last execution failed (red indicator) + +Toggle state to temporarily disable tasks without deleting them. + +#### Execution Plan +For **Scheduled Tasks**, configure the cron schedule: + +**Common patterns:** +``` +# Every day at 9 AM +0 9 * * * + +# Every hour +0 * * * * + +# Every Monday at 10 AM +0 10 * * 1 + +# Every 15 minutes +*/15 * * * * + +# First day of month at midnight +0 0 1 * * +``` + +**Timezone aware**: Tasks respect your configured timezone setting + +For **Planned Tasks**, add specific execution times: +- Click "Add Execution Time" +- Pick date and time +- Tasks execute in order +- Completed executions move to "Done" list + +### Task Execution + +#### Dedicated vs. Shared Context + +**Dedicated Context** (recommended): +- Each task has its own isolated chat history +- Prevents context pollution between tasks +- Better for independent, recurring workflows +- Default for UI-created tasks + +**Shared Context**: +- Task shares a chat context (useful for agent-created tasks) +- Can build on previous task executions +- Useful for sequential, related operations + +#### Execution Flow + +When a task runs: + +1. **Context Preparation** + - Creates or loads the task's chat context + - Activates associated project (if configured) + - Loads project instructions, secrets, and memory + +2. **Prompt Injection** + - Injects system prompt (if specified) + - Adds task-specific instructions + - Includes any file attachments + +3. **Agent Execution** + - Agent receives the prompt as a user message + - Executes using available tools + - Can use project-scoped resources + +4. **Result Handling** + - Stores execution result and timestamp + - Updates task state (idle or error) + - Sends notifications (if configured) + - For Planned Tasks: moves execution to "Done" list + +#### Monitoring Execution + +**Real-time monitoring:** +- Running tasks show "Running" state in scheduler +- View task's chat context to see agent progress +- Stop tasks mid-execution if needed + +**Execution history:** +- **Last Run**: Timestamp of most recent execution +- **Next Run**: Scheduled time for next execution +- **Last Result**: Output or error from last run + +### Common Use Cases + +#### Daily Reports +``` +Task: "Morning Inbox Summary" +Type: Scheduled (0 9 * * *) +Project: "Email Automation" +Prompt: "Check my Gmail inbox for new messages from the last 24 hours. +Summarize important emails by category and highlight any urgent items." +``` + +#### Recurring Monitoring +``` +Task: "Server Health Check" +Type: Scheduled (*/30 * * * *) +Project: "DevOps Monitoring" +Prompt: "Check server status, CPU usage, and disk space. +Alert me if any metric exceeds threshold." +``` + +#### Batch Processing +``` +Task: "Weekly Data Export" +Type: Scheduled (0 2 * * 0) +Project: "Analytics" +Prompt: "Export last week's analytics data to CSV. +Upload to cloud storage and send summary report." +``` + +#### Campaign Automation +``` +Task: "Product Launch Sequence" +Type: Planned +Executions: + - 2026-03-01 09:00 - Send launch announcement + - 2026-03-03 14:00 - Send feature highlights + - 2026-03-07 10:00 - Send customer testimonials +Project: "Marketing Campaigns" +``` + +### Integration with Projects + +Tasks and Projects are designed to work together: + +**Pattern: Project-Scoped Automation** + +1. Create a project with domain-specific instructions + ``` + Project: "Customer Support" + Instructions: "You are a customer support analyst. + Monitor ticket queue, categorize by urgency, draft responses." + ``` + +2. Create a recurring task for that project + ``` + Task: "Ticket Queue Monitor" + Schedule: Every 2 hours + Project: "Customer Support" + Prompt: "Check new tickets and categorize them." + ``` + +3. Task automatically uses: + - Project instructions (support analyst role) + - Project secrets (support system API keys) + - Project memory (previous ticket patterns) + - Project file structure (template responses) + +**Benefits:** +- Consistent behavior across task executions +- No need to repeat instructions in each task +- Easy to update behavior (edit project instructions once) +- Clean separation of concerns (project = context, task = action) + +### Notifications + +Tasks can trigger notifications on completion or failure: + +- Configure notification preferences in Settings +- Set up notification channels (email, Slack, webhook) +- Tasks automatically send status updates +- Critical for unattended automation + +See [Notifications](../developer/notifications.md) for configuration details. + + +### Multi-Source Aggregation +Tasks can pull from multiple sources: + +``` +"Aggregate data from: +1. Sales CRM API +2. Marketing analytics dashboard +3. Customer support tickets +Generate unified weekly report." +``` + +> [!TIP] +> Combine **Projects + Tasks + Notifications** for powerful automation workflows. Example: Create a "Client Reports" project with instructions, then add scheduled tasks for each client that inherit those instructions automatically. + +### Next Steps + +Explore related features: + +- [Projects](#projects) - Create isolated contexts for tasks +- [Notifications](../developer/notifications.md) - Understand A0's notification system +- [Memory Management](#memory-management) - Understand task memory isolation +- [Secrets & Variables](#secrets--variables) - Secure credentials for tasks ## Secrets & Variables Use the Settings → **Secrets** and **Variables** fields to store credentials and non-sensitive configuration values. @@ -180,6 +659,71 @@ You can reference these values in prompts by name. For example, store `MY_GMAIL` > [!NOTE] > Project-scoped secrets and variables (when using Projects) live under `/a0/usr/projects//.a0proj/` (`secrets.env`, `variables.env`). +## Remote Access via Tunneling + +Agent Zero includes a secure tunneling feature that allows you to expose your local instance to the internet. This makes it possible to access your Agent Zero instance from anywhere or share it with others without complex network configuration. + +### How Tunneling Works + +Agent Zero uses the [Flaredantic](https://pypi.org/project/flaredantic/) library to create secure tunnels. These tunnels: + +- Are secure (HTTPS) +- Don't require any configuration +- Generate unique URLs for each session +- Can be regenerated on demand + +### Creating a Tunnel + +1. Open **Settings** in the sidebar +2. Navigate to the **External Services** tab +3. Click on **Flare Tunnel** in the navigation menu +4. Click the **Create Tunnel** button to generate a new tunnel +5. Once created, the tunnel URL will be displayed and can be copied to share with others +6. The tunnel URL remains active until you stop the tunnel or close Agent Zero + +### Security Considerations + +When sharing your Agent Zero instance via a tunnel: + +- Anyone with the URL can access your Agent Zero instance +- No additional authentication is added beyond what your Agent Zero instance already has +- **Always set up authentication before creating a tunnel** (see below) +- The tunnel exposes only your Agent Zero instance, not your entire system + +> [!IMPORTANT] +> When attempting to create a tunnel without authentication configured, Agent Zero will display a security warning. + +### Adding Authentication for Tunnels + +To secure your tunneled Agent Zero instance, configure authentication in Settings: + +1. Open **Settings** in the Agent Zero UI +2. Navigate to the **Authentication** section +3. Enter your desired username in the **UI Login** field +4. Enter a strong password in the **UI Password** field +5. Click **Save** to apply the changes + +Alternatively, you can set environment variables: + +```bash +AUTH_LOGIN=your_username +AUTH_PASSWORD=your_password +``` + +This will require users to enter these credentials when accessing your tunneled Agent Zero instance. + +### Troubleshooting Tunnels + +If you encounter issues with the tunnel feature: + +1. Check your internet connection +2. Try regenerating the tunnel URL +3. Restart Agent Zero +4. Check the console logs for any error messages + +> [!TIP] +> Combine tunneling with authentication for secure remote access to your Agent Zero instance from any device, including mobile phones and tablets. + ## Voice Interface Agent Zero provides both Text-to-Speech (TTS) and Speech-to-Text (STT) capabilities for natural voice interaction: @@ -190,7 +734,7 @@ Enable voice responses from agents: * Click the "Stop Speech" button above the input area to immediately stop any ongoing speech * You can also click the speech button when hovering over messages to speak individual messages or their parts -![TTS Stop Speech](../res/ui-tts-stop-speech.png) +![TTS Stop Speech](../res/usage/ui-tts-stop-speech1.png) - The interface allows users to stop speech at any time if a response is too lengthy or if they wish to intervene during the conversation. @@ -225,7 +769,7 @@ Configure STT settings in the Settings page: - Duration: Set how long silence should last before ending recording - Timeout: Set maximum waiting time before closing the microphone -![Speech to Text Settings](../res/ui-settings-5-speech-to-text.png) +![Speech to Text Settings](../res/usage/ui-settings-5-speech-to-text.png) > [!IMPORTANT] > All STT and TTS functionalities operate locally within the Docker container, @@ -240,7 +784,7 @@ Configure STT settings in the Settings page: - Integrals, summations, and limits - Mathematical alignments and equations -![KaTeX display](../res/ui-katex-2.png) +![KaTeX display](../res/usage/ui-katex-2.png) > [!TIP] > When asking the agent to solve mathematical problems, it will automatically respond using KaTeX formatting for clear and professional-looking mathematical expressions. @@ -255,10 +799,11 @@ Agent Zero provides a powerful file browser interface for managing your workspac - Size in bytes - Last modified timestamp - **Action Icons**: Each file/directory has: + - menu for edit and rename actions - Download button - Delete button (with confirmation) -![File Browser](../res/ui-file-browser.png) +![File Browser](../res/usage/ui-file-browser.png) #### Features - **Directory Navigation**: @@ -267,7 +812,7 @@ Agent Zero provides a powerful file browser interface for managing your workspac - Current path always visible for context > [!NOTE] -> The file browser lets you navigate the Agent Zero filesystem. For file-based work, keep your working files in `/a0/work_dir` (or inside a Project workspace). +> The file browser lets you navigate the Agent Zero filesystem. For file-based work, keep your working files in `/a0/usr` (or inside a Project workspace). > - **File Operations**: - Create new files and directories @@ -280,11 +825,160 @@ Agent Zero provides a powerful file browser interface for managing your workspac - Last modification timestamps - **Bulk Operations**: - Upload multiple files simultaneously - - Select and manage multiple files at once +- **File and Directory Editing**: + - Limited to 100MB files + - Binary files cannot be edited > [!TIP] > The File Browser integrates seamlessly with Agent Zero's capabilities. You can reference files directly in your conversations, and the agent can help you manage, modify, and organize your files. +## Memory Management +Agent Zero includes a sophisticated memory management system that stores and retrieves information from conversations, knowledge sources, and learning experiences. The Memory Dashboard provides a powerful interface to view, search, filter, edit, and delete memory entries stored in the vector database. + +### Accessing the Memory Dashboard +Open the Memory Dashboard from the sidebar to manage your agent's memory: + +1. Click the **Memory** button in the sidebar +2. The dashboard displays all memory entries with their metadata and preview +3. Memory entries are organized by directory (e.g., "default") and area (e.g., "All Areas", "main") + +![Memory Dashboard](../res/usage/memory-dashboard.png) + +### Dashboard Features + +#### Filtering and Organization +The dashboard provides several ways to organize and filter memory entries: + +* **Memory Directory**: Select which memory directory to view (default or project-specific) +* **Area Filter**: Filter memories by area to focus on specific contexts +* **Limit Control**: Adjust the number of results displayed (default: 1000) +* **Statistics Bar**: View counts at a glance: + - Total: All memory entries in the directory + - Filtered: Entries matching current filters + - Knowledge: Entries from knowledge sources + - Conversation: Entries from chat interactions + +#### Search Functionality +Find specific memories using the powerful search feature: + +* **Search Bar**: Enter keywords to search memory content +* **Threshold Slider**: Adjust search sensitivity (0.00 - 1.00) + - Lower values return more results with looser matching + - Higher values return fewer, more precise matches + - Default threshold: 0.60 +* **Real-time Search**: Results update as you type + +> [!TIP] +> Use the threshold slider to balance between broad discovery (lower values) and precise matching (higher values). Start with 0.60 and adjust based on your results. + +#### Memory Entry Information +Each memory entry displays key information: + +* **Tags**: Visual indicators showing the memory type (MAIN, Knowledge, etc.) +* **Timestamp**: When the memory was created (format: MM/DD HH:MM) +* **Preview**: First few lines of the memory content +* **Action Icons**: Quick access to view details, edit, or delete + +### Viewing and Editing Memories +Click any memory entry to open the detailed view with full editing capabilities: + +![Memory Details](../res/usage/memory-editing.png) + +#### Memory Details View +The details panel provides comprehensive information about each memory: + +* **Memory Content**: Full text of the stored memory + - Syntax highlighting for structured content + - Editable text area for modifications +* **Metadata Panel**: Complete memory information + - Unique ID + - Area classification + - Source type (e.g., "Knowledge") + - Timestamp (creation date and time) + - Source file (if applicable) + +#### Editing Memories +Modify memory entries directly from the details view: + +1. Click on any memory entry to open the details panel +2. Edit the memory content in the text area +3. Click the **Save** button (checkmark icon) to apply changes +4. Click the **Cancel** button (X icon) to discard changes + +> [!NOTE] +> Edited memories are immediately updated in the vector database and will affect how the agent recalls and uses this information in future interactions. + +#### Deleting Memories +Remove unwanted or outdated memory entries: + +1. Open the memory details view +2. Click the **Delete** button (trash icon) in the action bar +3. Confirm the deletion when prompted +4. The memory is permanently removed from the vector database + +Alternatively, delete directly from the main dashboard: +* Click the delete icon on any memory entry in the list +* Confirm the deletion + +> [!WARNING] +> Deleted memories cannot be recovered. Use caution when removing entries, especially those from knowledge sources or important conversations. + +#### Clearing Memories +For bulk cleanup operations: + +* Click the **Clear** button in the dashboard header to remove all filtered memories +* This is useful when you need to reset a specific area or start fresh with a memory directory +* Always review your filters before clearing to avoid unintended deletions + +### Memory Types and Sources + +#### Knowledge Memories +Memories derived from uploaded knowledge files: +* Marked with "Knowledge" tag +* Include source file information +* Created when importing documents via Import Knowledge button +* Stored persistently unless manually deleted + +#### Conversation Memories +Memories from chat interactions: +* Marked with conversation indicators +* Created automatically as the agent learns from interactions +* Include contextual information about when and why they were created +* Help the agent maintain continuity across sessions + +### Best Practices with Memory + +#### Regular Maintenance +* **Review Periodically**: Check your memory entries monthly to remove outdated information +* **Organize by Area**: Use areas to categorize memories by project or topic +* **Clean Up Test Data**: Remove experimental or test memories that aren't needed +* **Monitor Growth**: Keep an eye on total memory count to maintain performance + +#### Search Optimization +* **Use Specific Keywords**: More specific terms yield better results +* **Adjust Threshold**: Fine-tune the threshold based on your needs +* **Filter First**: Use area and directory filters before searching for better results +* **Iterate Searches**: Try different search terms if initial results aren't helpful + +#### Content Quality +* **Keep Relevant**: Remove memories that are no longer useful or accurate +* **Update Information**: Edit memories when information becomes outdated +* **Add Context**: When editing, ensure memories remain clear and useful +* **Avoid Duplicates**: Remove redundant memories that store the same information + +#### Project Integration +When using Projects (see [Projects](#projects)): +* Each project maintains its own memory directory +* Memories are isolated between projects to prevent context bleed +* Use project-specific memory directories for focused work +* Clear project memories when archiving completed projects + +> [!TIP] +> Combine memory management with the backup system to preserve important memory states. Before clearing or making bulk changes, create a backup so you can restore if needed. + +> [!IMPORTANT] +> Memory management directly affects agent behavior and recall. Regularly maintaining your memory database ensures optimal agent performance and relevant context retention. + ## Backup & Restore Agent Zero provides a comprehensive backup and restore system to protect your data and configurations. This feature helps you safeguard your work and migrate Agent Zero setups between different systems. diff --git a/docs/quickstart.md b/docs/quickstart.md index dad044291..5d95f1340 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -12,7 +12,7 @@ Download and install Docker Desktop for your operating system: - **Linux:** Install Docker Desktop or docker-ce following the [official instructions](https://docs.docker.com/desktop/install/linux-install/) > [!TIP] -> For complete OS-specific installation instructions, see the [full Installation Guide](getting-started/installation.md#step-1-install-docker-desktop). +> For complete OS-specific installation instructions, see the [full Installation Guide](setup/installation.md#step-1-install-docker-desktop). ### Step 2: Pull the Agent Zero Image @@ -43,11 +43,11 @@ Open your browser and navigate to `http://localhost:`. The Web UI will sho Click **Add your API key** to open Settings and configure: - **Default Provider:** OpenRouter (supports most models with a single API key) -- **Alternative Providers:** Anthropic, OpenAI, Ollama (local models), and many others +- **Alternative Providers:** Anthropic, OpenAI, Ollama/LM Studio (local models), and many others - **Model Selection:** Choose your chat model (e.g., `anthropic/claude-sonnet-4-5` for OpenRouter) > [!NOTE] -> Agent Zero supports any LLM provider, including local models via Ollama. For detailed provider configuration and local model setup, see the [Installation Guide](getting-started/installation.md#choosing-your-llms). +> Agent Zero supports any LLM provider, including local models via Ollama. For detailed provider configuration and local model setup, see the [Installation Guide](setup/installation.md#choosing-your-llms). ### Step 5: Start Your First Chat @@ -95,3 +95,7 @@ Now that you've run a simple task, you can experiment with more complex requests Provides more in-depth information on tools, projects, tasks, and backup/restore. +## 🎓 Video Tutorials +- [MCP Server Setup](https://youtu.be/pM5f4Vz3_IQ) +- [Projects & Workspaces](https://youtu.be/RrTDp_v9V1c) +- [Memory Management](https://youtu.be/sizjAq2-d9s) diff --git a/docs/res/081_vid.png b/docs/res/081_vid.png deleted file mode 100644 index c4e7349af..000000000 Binary files a/docs/res/081_vid.png and /dev/null differ diff --git a/docs/res/arch-01.svg b/docs/res/arch-01.svg deleted file mode 100644 index 899e26ae8..000000000 --- a/docs/res/arch-01.svg +++ /dev/null @@ -1,1406 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - User - - - - - - - - - - - - - - - - - - - - - - - Agent 0 - - - - - - - - - - - - - - - - - - - - - - - Memory - , - K - nowledge, - Instruments, - P - rompts, - Extensions - - - - - - - - - - - - - - - - - - - - - - - Subordinate - Agent 1 - - - - - - - - - - - - - - - - - - - - - - - Subordinate - Agent 2 - - - - - - - - - - - - - - - - - - - - - - - - - T - ools - - - - - - - - - - - - - - - - - - - - - - - Code Execution - T - ool - - - - - - - - - - - - - - - - - - - - - - - W - ork Directory - work_dir - - - diff --git a/docs/res/banner.png b/docs/res/banner.png index a7a2ec1bf..03ea6eb40 100644 Binary files a/docs/res/banner.png and b/docs/res/banner.png differ diff --git a/docs/res/banner_high.png b/docs/res/banner_high.png index 69e415562..45ca87b70 100644 Binary files a/docs/res/banner_high.png and b/docs/res/banner_high.png differ diff --git a/docs/res/code_exec_jailbreak.png b/docs/res/code_exec_jailbreak.png deleted file mode 100644 index 3c09ca626..000000000 Binary files a/docs/res/code_exec_jailbreak.png and /dev/null differ diff --git a/docs/res/david_vid.jpg b/docs/res/david_vid.jpg deleted file mode 100644 index 70ba53cfa..000000000 Binary files a/docs/res/david_vid.jpg and /dev/null differ diff --git a/docs/res/dev/devinst-1.png b/docs/res/dev/devinst-1.png index d8993740a..09ed2cb6f 100644 Binary files a/docs/res/dev/devinst-1.png and b/docs/res/dev/devinst-1.png differ diff --git a/docs/res/dev/devinst-10.png b/docs/res/dev/devinst-10.png index 1744f2ccb..2fa3b3840 100644 Binary files a/docs/res/dev/devinst-10.png and b/docs/res/dev/devinst-10.png differ diff --git a/docs/res/dev/devinst-11.png b/docs/res/dev/devinst-11.png index 26a77ea1e..3f48e12c2 100644 Binary files a/docs/res/dev/devinst-11.png and b/docs/res/dev/devinst-11.png differ diff --git a/docs/res/dev/devinst-12.png b/docs/res/dev/devinst-12.png index 410afd10a..47b4a3652 100644 Binary files a/docs/res/dev/devinst-12.png and b/docs/res/dev/devinst-12.png differ diff --git a/docs/res/dev/devinst-13.png b/docs/res/dev/devinst-13.png index 61f2ab552..6eb8fffef 100644 Binary files a/docs/res/dev/devinst-13.png and b/docs/res/dev/devinst-13.png differ diff --git a/docs/res/dev/devinst-14.png b/docs/res/dev/devinst-14.png index 646531e34..c49c79dcc 100644 Binary files a/docs/res/dev/devinst-14.png and b/docs/res/dev/devinst-14.png differ diff --git a/docs/res/dev/devinst-2.png b/docs/res/dev/devinst-2.png index b2d692eb9..b533c8191 100644 Binary files a/docs/res/dev/devinst-2.png and b/docs/res/dev/devinst-2.png differ diff --git a/docs/res/dev/devinst-3.png b/docs/res/dev/devinst-3.png index aa3a8c3fa..71b8e3612 100644 Binary files a/docs/res/dev/devinst-3.png and b/docs/res/dev/devinst-3.png differ diff --git a/docs/res/dev/devinst-4.png b/docs/res/dev/devinst-4.png index 70b2adcf4..619b9e22c 100644 Binary files a/docs/res/dev/devinst-4.png and b/docs/res/dev/devinst-4.png differ diff --git a/docs/res/dev/devinst-5.png b/docs/res/dev/devinst-5.png index aae44f076..9c4e356b6 100644 Binary files a/docs/res/dev/devinst-5.png and b/docs/res/dev/devinst-5.png differ diff --git a/docs/res/dev/devinst-6.png b/docs/res/dev/devinst-6.png index 6a006c44b..f37d0eb9a 100644 Binary files a/docs/res/dev/devinst-6.png and b/docs/res/dev/devinst-6.png differ diff --git a/docs/res/dev/devinst-7.png b/docs/res/dev/devinst-7.png index 3869b0223..37f378256 100644 Binary files a/docs/res/dev/devinst-7.png and b/docs/res/dev/devinst-7.png differ diff --git a/docs/res/dev/devinst-8.png b/docs/res/dev/devinst-8.png index b125e6d96..a3b7f10c6 100644 Binary files a/docs/res/dev/devinst-8.png and b/docs/res/dev/devinst-8.png differ diff --git a/docs/res/dev/devinst-9.png b/docs/res/dev/devinst-9.png index 323c9a6d4..d1c6dad71 100644 Binary files a/docs/res/dev/devinst-9.png and b/docs/res/dev/devinst-9.png differ diff --git a/docs/res/devguide_vid.png b/docs/res/devguide_vid.png index eeb10cfb8..0b6f3288f 100644 Binary files a/docs/res/devguide_vid.png and b/docs/res/devguide_vid.png differ diff --git a/docs/res/easy_ins_vid.png b/docs/res/easy_ins_vid.png index 43fa0bac9..49e54b3cc 100644 Binary files a/docs/res/easy_ins_vid.png and b/docs/res/easy_ins_vid.png differ diff --git a/docs/res/favicon.png b/docs/res/favicon.png index f34f92463..32a1c127e 100644 Binary files a/docs/res/favicon.png and b/docs/res/favicon.png differ diff --git a/docs/res/favicon_round.png b/docs/res/favicon_round.png index 4fc7e8833..03d0be195 100644 Binary files a/docs/res/favicon_round.png and b/docs/res/favicon_round.png differ diff --git a/docs/res/flask_link.png b/docs/res/flask_link.png deleted file mode 100644 index 1db2c8552..000000000 Binary files a/docs/res/flask_link.png and /dev/null differ diff --git a/docs/res/flow-01.svg b/docs/res/flow-01.svg deleted file mode 100644 index f9398bb4b..000000000 --- a/docs/res/flow-01.svg +++ /dev/null @@ -1,144 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - User - input - - - - - V - ectorDB Initialize - - - - - Planning - - - - - T - ool Use - - - - - Sub-agent Creation - - - - - T - ool Use - - - - - Feedback - - - - - - - User - Response - - - - - - - Memory - Access - - \ No newline at end of file diff --git a/docs/res/header.png b/docs/res/header.png index c274e5056..a2acc5bef 100644 Binary files a/docs/res/header.png and b/docs/res/header.png differ diff --git a/docs/res/joke.png b/docs/res/joke.png deleted file mode 100644 index d25232b02..000000000 Binary files a/docs/res/joke.png and /dev/null differ diff --git a/docs/res/memory-man.png b/docs/res/memory-man.png deleted file mode 100644 index 374e3c9b5..000000000 Binary files a/docs/res/memory-man.png and /dev/null differ diff --git a/docs/res/new_vid.jpg b/docs/res/new_vid.jpg deleted file mode 100644 index 08ad2d291..000000000 Binary files a/docs/res/new_vid.jpg and /dev/null differ diff --git a/docs/res/physics-2.png b/docs/res/physics-2.png deleted file mode 100644 index df2c38887..000000000 Binary files a/docs/res/physics-2.png and /dev/null differ diff --git a/docs/res/physics.png b/docs/res/physics.png deleted file mode 100644 index 762451862..000000000 Binary files a/docs/res/physics.png and /dev/null differ diff --git a/docs/res/profiles.png b/docs/res/profiles.png new file mode 100644 index 000000000..55e2ef2f6 Binary files /dev/null and b/docs/res/profiles.png differ diff --git a/docs/res/prompts.png b/docs/res/prompts.png deleted file mode 100644 index 7c2764437..000000000 Binary files a/docs/res/prompts.png and /dev/null differ diff --git a/docs/res/quickstart/image-24.png b/docs/res/quickstart/image-24.png index d5c356751..b804d503a 100644 Binary files a/docs/res/quickstart/image-24.png and b/docs/res/quickstart/image-24.png differ diff --git a/docs/res/quickstart/ui_chat_management.png b/docs/res/quickstart/ui_chat_management.png index 39f353bf6..0190a7a6e 100644 Binary files a/docs/res/quickstart/ui_chat_management.png and b/docs/res/quickstart/ui_chat_management.png differ diff --git a/docs/res/quickstart/ui_newchat1.png b/docs/res/quickstart/ui_newchat1.png index b6e6122e8..34a6eb8d0 100644 Binary files a/docs/res/quickstart/ui_newchat1.png and b/docs/res/quickstart/ui_newchat1.png differ diff --git a/docs/res/settings-page-ui.png b/docs/res/settings-page-ui.png deleted file mode 100644 index 4c6d0010a..000000000 Binary files a/docs/res/settings-page-ui.png and /dev/null differ diff --git a/docs/res/settings-page-ui1.png b/docs/res/settings-page-ui1.png new file mode 100644 index 000000000..a8b4242f5 Binary files /dev/null and b/docs/res/settings-page-ui1.png differ diff --git a/docs/res/setup/1-docker-image-search.png b/docs/res/setup/1-docker-image-search.png index 09fc12bd4..78924a946 100644 Binary files a/docs/res/setup/1-docker-image-search.png and b/docs/res/setup/1-docker-image-search.png differ diff --git a/docs/res/setup/2-docker-image-run-3.png b/docs/res/setup/2-docker-image-run-3.png new file mode 100644 index 000000000..21323751f Binary files /dev/null and b/docs/res/setup/2-docker-image-run-3.png differ diff --git a/docs/res/setup/2-docker-image-run.png b/docs/res/setup/2-docker-image-run.png index 763d8ce23..7ff784458 100644 Binary files a/docs/res/setup/2-docker-image-run.png and b/docs/res/setup/2-docker-image-run.png differ diff --git a/docs/res/setup/2-docker-image-run2.png b/docs/res/setup/2-docker-image-run2.png deleted file mode 100644 index d4ae93f77..000000000 Binary files a/docs/res/setup/2-docker-image-run2.png and /dev/null differ diff --git a/docs/res/setup/3-docker-port-mapping.png b/docs/res/setup/3-docker-port-mapping.png index 3cf442f72..c67caab98 100644 Binary files a/docs/res/setup/3-docker-port-mapping.png and b/docs/res/setup/3-docker-port-mapping.png differ diff --git a/docs/res/setup/4-docker-container-started.png b/docs/res/setup/4-docker-container-started.png index 33a3bb783..0252e9dac 100644 Binary files a/docs/res/setup/4-docker-container-started.png and b/docs/res/setup/4-docker-container-started.png differ diff --git a/docs/res/setup/5-docker-click-to-open.png b/docs/res/setup/5-docker-click-to-open.png index 371d2c36f..3e0ca3700 100644 Binary files a/docs/res/setup/5-docker-click-to-open.png and b/docs/res/setup/5-docker-click-to-open.png differ diff --git a/docs/res/setup/6-docker-a0-running-new.png b/docs/res/setup/6-docker-a0-running-new.png index c68c0c499..03d78d07f 100644 Binary files a/docs/res/setup/6-docker-a0-running-new.png and b/docs/res/setup/6-docker-a0-running-new.png differ diff --git a/docs/res/setup/9-rfc-devpage-on-docker-instance-1.png b/docs/res/setup/9-rfc-devpage-on-docker-instance-1.png index 4c7a37966..7e14eb877 100644 Binary files a/docs/res/setup/9-rfc-devpage-on-docker-instance-1.png and b/docs/res/setup/9-rfc-devpage-on-docker-instance-1.png differ diff --git a/docs/res/setup/9-rfc-devpage-on-local-sbs-1.png b/docs/res/setup/9-rfc-devpage-on-local-sbs-1.png index 74c7623fe..dd2ee9ab4 100644 Binary files a/docs/res/setup/9-rfc-devpage-on-local-sbs-1.png and b/docs/res/setup/9-rfc-devpage-on-local-sbs-1.png differ diff --git a/docs/res/setup/a2a/a2a-conn.png b/docs/res/setup/a2a/a2a-conn.png new file mode 100644 index 000000000..d0ae234ae Binary files /dev/null and b/docs/res/setup/a2a/a2a-conn.png differ diff --git a/docs/res/setup/a2a/a2a2.png b/docs/res/setup/a2a/a2a2.png new file mode 100644 index 000000000..82856c38e Binary files /dev/null and b/docs/res/setup/a2a/a2a2.png differ diff --git a/docs/res/setup/docker-delete-image-1.png b/docs/res/setup/docker-delete-image-1.png index 042e57ea8..a8106c069 100644 Binary files a/docs/res/setup/docker-delete-image-1.png and b/docs/res/setup/docker-delete-image-1.png differ diff --git a/docs/res/setup/image-1.png b/docs/res/setup/image-1.png index 9ea2b068f..e6ef01cc1 100644 Binary files a/docs/res/setup/image-1.png and b/docs/res/setup/image-1.png differ diff --git a/docs/res/setup/image-10.png b/docs/res/setup/image-10.png index cdcb115e2..5ba5b0c39 100644 Binary files a/docs/res/setup/image-10.png and b/docs/res/setup/image-10.png differ diff --git a/docs/res/setup/image-11.png b/docs/res/setup/image-11.png index c08ba1b38..fb59dee9d 100644 Binary files a/docs/res/setup/image-11.png and b/docs/res/setup/image-11.png differ diff --git a/docs/res/setup/image-12.png b/docs/res/setup/image-12.png index 2e4a8b531..3d6d41441 100644 Binary files a/docs/res/setup/image-12.png and b/docs/res/setup/image-12.png differ diff --git a/docs/res/setup/image-13.png b/docs/res/setup/image-13.png index 2b2a91bf7..da111bf8a 100644 Binary files a/docs/res/setup/image-13.png and b/docs/res/setup/image-13.png differ diff --git a/docs/res/setup/image-14-u.png b/docs/res/setup/image-14-u.png index d20a84c2e..3c279a993 100644 Binary files a/docs/res/setup/image-14-u.png and b/docs/res/setup/image-14-u.png differ diff --git a/docs/res/setup/image-14.png b/docs/res/setup/image-14.png index f1823d6cc..ed7d9c503 100644 Binary files a/docs/res/setup/image-14.png and b/docs/res/setup/image-14.png differ diff --git a/docs/res/setup/image-15.png b/docs/res/setup/image-15.png index fe871994b..75fdbf7f5 100644 Binary files a/docs/res/setup/image-15.png and b/docs/res/setup/image-15.png differ diff --git a/docs/res/setup/image-16.png b/docs/res/setup/image-16.png index 72c8a2972..29ca4646a 100644 Binary files a/docs/res/setup/image-16.png and b/docs/res/setup/image-16.png differ diff --git a/docs/res/setup/image-17.png b/docs/res/setup/image-17.png index 222438acc..6a8379c20 100644 Binary files a/docs/res/setup/image-17.png and b/docs/res/setup/image-17.png differ diff --git a/docs/res/setup/image-18.png b/docs/res/setup/image-18.png index 62c52021c..460cb4838 100644 Binary files a/docs/res/setup/image-18.png and b/docs/res/setup/image-18.png differ diff --git a/docs/res/setup/image-19.png b/docs/res/setup/image-19.png index 54a1f745a..87c6f73ab 100644 Binary files a/docs/res/setup/image-19.png and b/docs/res/setup/image-19.png differ diff --git a/docs/res/setup/image-2.png b/docs/res/setup/image-2.png index 798f39105..5e2609f57 100644 Binary files a/docs/res/setup/image-2.png and b/docs/res/setup/image-2.png differ diff --git a/docs/res/setup/image-20.png b/docs/res/setup/image-20.png index dd9d80c57..405361805 100644 Binary files a/docs/res/setup/image-20.png and b/docs/res/setup/image-20.png differ diff --git a/docs/res/setup/image-21.png b/docs/res/setup/image-21.png index e3c93be94..bbb33b0a1 100644 Binary files a/docs/res/setup/image-21.png and b/docs/res/setup/image-21.png differ diff --git a/docs/res/setup/image-22-1.png b/docs/res/setup/image-22-1.png index 704f25921..a0b4e34a4 100644 Binary files a/docs/res/setup/image-22-1.png and b/docs/res/setup/image-22-1.png differ diff --git a/docs/res/setup/image-23-1.png b/docs/res/setup/image-23-1.png index 5d639fc81..aac45078b 100644 Binary files a/docs/res/setup/image-23-1.png and b/docs/res/setup/image-23-1.png differ diff --git a/docs/res/setup/image-3.png b/docs/res/setup/image-3.png index 3c1053170..dc0af02f5 100644 Binary files a/docs/res/setup/image-3.png and b/docs/res/setup/image-3.png differ diff --git a/docs/res/setup/image-4.png b/docs/res/setup/image-4.png index 04f936a39..b2b44e530 100644 Binary files a/docs/res/setup/image-4.png and b/docs/res/setup/image-4.png differ diff --git a/docs/res/setup/image-5.png b/docs/res/setup/image-5.png index 87437eecc..232a33bbb 100644 Binary files a/docs/res/setup/image-5.png and b/docs/res/setup/image-5.png differ diff --git a/docs/res/setup/image-6.png b/docs/res/setup/image-6.png index 4a9f59a71..7feda1384 100644 Binary files a/docs/res/setup/image-6.png and b/docs/res/setup/image-6.png differ diff --git a/docs/res/setup/image-7.png b/docs/res/setup/image-7.png index cb1c39dcf..5a915d278 100644 Binary files a/docs/res/setup/image-7.png and b/docs/res/setup/image-7.png differ diff --git a/docs/res/setup/image-8.png b/docs/res/setup/image-8.png index f148e8eb6..0296fc814 100644 Binary files a/docs/res/setup/image-8.png and b/docs/res/setup/image-8.png differ diff --git a/docs/res/setup/image-9.png b/docs/res/setup/image-9.png index 3d806d947..9d42f21c0 100644 Binary files a/docs/res/setup/image-9.png and b/docs/res/setup/image-9.png differ diff --git a/docs/res/setup/image.png b/docs/res/setup/image.png index 6f99debda..ee61eb897 100644 Binary files a/docs/res/setup/image.png and b/docs/res/setup/image.png differ diff --git a/docs/res/setup/macsocket.png b/docs/res/setup/macsocket.png index 531744eb2..2574848b4 100644 Binary files a/docs/res/setup/macsocket.png and b/docs/res/setup/macsocket.png differ diff --git a/docs/res/setup/mcp/mcp-example-config.png b/docs/res/setup/mcp/mcp-example-config.png new file mode 100644 index 000000000..5dbe327eb Binary files /dev/null and b/docs/res/setup/mcp/mcp-example-config.png differ diff --git a/docs/res/setup/mcp/mcp-open-config.png b/docs/res/setup/mcp/mcp-open-config.png new file mode 100644 index 000000000..dc63ce0da Binary files /dev/null and b/docs/res/setup/mcp/mcp-open-config.png differ diff --git a/docs/res/setup/oses/apple.png b/docs/res/setup/oses/apple.png index 2a64414dd..b11a74a82 100644 Binary files a/docs/res/setup/oses/apple.png and b/docs/res/setup/oses/apple.png differ diff --git a/docs/res/setup/oses/linux.png b/docs/res/setup/oses/linux.png index edd41ae30..cbeaf4547 100644 Binary files a/docs/res/setup/oses/linux.png and b/docs/res/setup/oses/linux.png differ diff --git a/docs/res/setup/oses/windows.png b/docs/res/setup/oses/windows.png index bad304fc7..130b33c8f 100644 Binary files a/docs/res/setup/oses/windows.png and b/docs/res/setup/oses/windows.png differ diff --git a/docs/res/setup/settings/1-agentConfig.png b/docs/res/setup/settings/1-agentConfig.png index 9d73abbf1..5082c40c3 100644 Binary files a/docs/res/setup/settings/1-agentConfig.png and b/docs/res/setup/settings/1-agentConfig.png differ diff --git a/docs/res/setup/settings/2-chat-model.png b/docs/res/setup/settings/2-chat-model.png index 497f3173d..52fa0fb10 100644 Binary files a/docs/res/setup/settings/2-chat-model.png and b/docs/res/setup/settings/2-chat-model.png differ diff --git a/docs/res/setup/settings/3-auth.png b/docs/res/setup/settings/3-auth.png index 59cebb9c5..15d294c15 100644 Binary files a/docs/res/setup/settings/3-auth.png and b/docs/res/setup/settings/3-auth.png differ diff --git a/docs/res/setup/settings/4-local-models.png b/docs/res/setup/settings/4-local-models.png index 78e17996c..216ada1d8 100644 Binary files a/docs/res/setup/settings/4-local-models.png and b/docs/res/setup/settings/4-local-models.png differ diff --git a/docs/res/setup/thumb_play.png b/docs/res/setup/thumb_play.png index 13646aa23..8e5f30965 100644 Binary files a/docs/res/setup/thumb_play.png and b/docs/res/setup/thumb_play.png differ diff --git a/docs/res/setup/thumb_setup.png b/docs/res/setup/thumb_setup.png index 27288fdbe..e56d5c99a 100644 Binary files a/docs/res/setup/thumb_setup.png and b/docs/res/setup/thumb_setup.png differ diff --git a/docs/res/setup/update-initialize.png b/docs/res/setup/update-initialize.png index 90759bd02..454753dc6 100644 Binary files a/docs/res/setup/update-initialize.png and b/docs/res/setup/update-initialize.png differ diff --git a/docs/res/showcase-thumb.png b/docs/res/showcase-thumb.png index c5e6d9d15..c2cb31020 100644 Binary files a/docs/res/showcase-thumb.png and b/docs/res/showcase-thumb.png differ diff --git a/docs/res/splash_wide.png b/docs/res/splash_wide.png index bfa2ab210..1f8654f98 100644 Binary files a/docs/res/splash_wide.png and b/docs/res/splash_wide.png differ diff --git a/docs/res/ui-actions.png b/docs/res/ui-actions.png deleted file mode 100644 index fe99b67ff..000000000 Binary files a/docs/res/ui-actions.png and /dev/null differ diff --git a/docs/res/ui-attachments-2.png b/docs/res/ui-attachments-2.png deleted file mode 100644 index 376e0bebd..000000000 Binary files a/docs/res/ui-attachments-2.png and /dev/null differ diff --git a/docs/res/ui-attachments.png b/docs/res/ui-attachments.png deleted file mode 100644 index 69f3360ae..000000000 Binary files a/docs/res/ui-attachments.png and /dev/null differ diff --git a/docs/res/ui-behavior-change-chat.png b/docs/res/ui-behavior-change-chat.png deleted file mode 100644 index 40ae9601a..000000000 Binary files a/docs/res/ui-behavior-change-chat.png and /dev/null differ diff --git a/docs/res/ui-context.png b/docs/res/ui-context.png deleted file mode 100644 index e3ca586a5..000000000 Binary files a/docs/res/ui-context.png and /dev/null differ diff --git a/docs/res/ui-file-browser.png b/docs/res/ui-file-browser.png deleted file mode 100644 index 03396fc11..000000000 Binary files a/docs/res/ui-file-browser.png and /dev/null differ diff --git a/docs/res/ui-history.png b/docs/res/ui-history.png deleted file mode 100644 index 209d905bf..000000000 Binary files a/docs/res/ui-history.png and /dev/null differ diff --git a/docs/res/ui-katex-1.png b/docs/res/ui-katex-1.png deleted file mode 100644 index 561e5143b..000000000 Binary files a/docs/res/ui-katex-1.png and /dev/null differ diff --git a/docs/res/ui-katex-2.png b/docs/res/ui-katex-2.png deleted file mode 100644 index 5bd52c915..000000000 Binary files a/docs/res/ui-katex-2.png and /dev/null differ diff --git a/docs/res/ui-nudge.png b/docs/res/ui-nudge.png deleted file mode 100644 index ea9b656db..000000000 Binary files a/docs/res/ui-nudge.png and /dev/null differ diff --git a/docs/res/ui-restarting.png b/docs/res/ui-restarting.png deleted file mode 100644 index 7ce626a03..000000000 Binary files a/docs/res/ui-restarting.png and /dev/null differ diff --git a/docs/res/ui-screen-2.png b/docs/res/ui-screen-2.png deleted file mode 100644 index b2215ffa4..000000000 Binary files a/docs/res/ui-screen-2.png and /dev/null differ diff --git a/docs/res/ui-screen.png b/docs/res/ui-screen.png deleted file mode 100644 index 977bdc170..000000000 Binary files a/docs/res/ui-screen.png and /dev/null differ diff --git a/docs/res/ui-settings-5-speech-to-text.png b/docs/res/ui-settings-5-speech-to-text.png deleted file mode 100644 index 7bc03a80a..000000000 Binary files a/docs/res/ui-settings-5-speech-to-text.png and /dev/null differ diff --git a/docs/res/ui-tts-stop-speech.png b/docs/res/ui-tts-stop-speech.png deleted file mode 100644 index bae9e222e..000000000 Binary files a/docs/res/ui-tts-stop-speech.png and /dev/null differ diff --git a/docs/res/ui_screen.png b/docs/res/ui_screen.png deleted file mode 100644 index 90bb5ab31..000000000 Binary files a/docs/res/ui_screen.png and /dev/null differ diff --git a/docs/res/ui_screen2.png b/docs/res/ui_screen2.png new file mode 100644 index 000000000..58c62582a Binary files /dev/null and b/docs/res/ui_screen2.png differ diff --git a/docs/res/usage/action-btns.png b/docs/res/usage/action-btns.png new file mode 100644 index 000000000..42679e02e Binary files /dev/null and b/docs/res/usage/action-btns.png differ diff --git a/docs/res/usage/api-int/api-int-1.png b/docs/res/usage/api-int/api-int-1.png new file mode 100644 index 000000000..35d868d25 Binary files /dev/null and b/docs/res/usage/api-int/api-int-1.png differ diff --git a/docs/res/usage/api-int/api-int-2image-gen-api2.png b/docs/res/usage/api-int/api-int-2image-gen-api2.png new file mode 100644 index 000000000..e80b8ddb8 Binary files /dev/null and b/docs/res/usage/api-int/api-int-2image-gen-api2.png differ diff --git a/docs/res/usage/api-int/api-int-3-api-key-missing-secrets.png b/docs/res/usage/api-int/api-int-3-api-key-missing-secrets.png new file mode 100644 index 000000000..e56e8cfb6 Binary files /dev/null and b/docs/res/usage/api-int/api-int-3-api-key-missing-secrets.png differ diff --git a/docs/res/usage/api-int/api-int-4-secrets-setting.png b/docs/res/usage/api-int/api-int-4-secrets-setting.png new file mode 100644 index 000000000..551576849 Binary files /dev/null and b/docs/res/usage/api-int/api-int-4-secrets-setting.png differ diff --git a/docs/res/usage/api-int/api-int-5-finish.png b/docs/res/usage/api-int/api-int-5-finish.png new file mode 100644 index 000000000..d673e7301 Binary files /dev/null and b/docs/res/usage/api-int/api-int-5-finish.png differ diff --git a/docs/res/usage/attachments-1.png b/docs/res/usage/attachments-1.png new file mode 100644 index 000000000..02c348dbe Binary files /dev/null and b/docs/res/usage/attachments-1.png differ diff --git a/docs/res/usage/attachments-2.png b/docs/res/usage/attachments-2.png new file mode 100644 index 000000000..744e3406c Binary files /dev/null and b/docs/res/usage/attachments-2.png differ diff --git a/docs/res/usage/file-browser.png b/docs/res/usage/file-browser.png new file mode 100644 index 000000000..82cc9cba6 Binary files /dev/null and b/docs/res/usage/file-browser.png differ diff --git a/docs/res/usage/file-edit.png b/docs/res/usage/file-edit.png new file mode 100644 index 000000000..f3706b4f4 Binary files /dev/null and b/docs/res/usage/file-edit.png differ diff --git a/docs/res/usage/first-task.png b/docs/res/usage/first-task.png new file mode 100644 index 000000000..5720acff7 Binary files /dev/null and b/docs/res/usage/first-task.png differ diff --git a/docs/res/usage/memory-dashboard.png b/docs/res/usage/memory-dashboard.png new file mode 100644 index 000000000..6c9506c35 Binary files /dev/null and b/docs/res/usage/memory-dashboard.png differ diff --git a/docs/res/usage/memory-editing.png b/docs/res/usage/memory-editing.png new file mode 100644 index 000000000..469fb7dc0 Binary files /dev/null and b/docs/res/usage/memory-editing.png differ diff --git a/docs/res/usage/multi-agent.png b/docs/res/usage/multi-agent.png new file mode 100644 index 000000000..9286f96f7 Binary files /dev/null and b/docs/res/usage/multi-agent.png differ diff --git a/docs/res/usage/nudge.png b/docs/res/usage/nudge.png new file mode 100644 index 000000000..8746667bd Binary files /dev/null and b/docs/res/usage/nudge.png differ diff --git a/docs/res/usage/projects/projects-activate-project.png b/docs/res/usage/projects/projects-activate-project.png new file mode 100644 index 000000000..722145a4b Binary files /dev/null and b/docs/res/usage/projects/projects-activate-project.png differ diff --git a/docs/res/usage/projects/projects-creation.png b/docs/res/usage/projects/projects-creation.png new file mode 100644 index 000000000..41630d87c Binary files /dev/null and b/docs/res/usage/projects/projects-creation.png differ diff --git a/docs/res/usage/projects/projects-desc-and-instructions.png b/docs/res/usage/projects/projects-desc-and-instructions.png new file mode 100644 index 000000000..c74cecbe7 Binary files /dev/null and b/docs/res/usage/projects/projects-desc-and-instructions.png differ diff --git a/docs/res/usage/projects/projects-first-ops.png b/docs/res/usage/projects/projects-first-ops.png new file mode 100644 index 000000000..228ec15dd Binary files /dev/null and b/docs/res/usage/projects/projects-first-ops.png differ diff --git a/docs/res/usage/projects/projects-git-projects-tree.png b/docs/res/usage/projects/projects-git-projects-tree.png new file mode 100644 index 000000000..55fd6391b Binary files /dev/null and b/docs/res/usage/projects/projects-git-projects-tree.png differ diff --git a/docs/res/usage/projects/projects-gitprojects-clone.png b/docs/res/usage/projects/projects-gitprojects-clone.png new file mode 100644 index 000000000..f0bad18fa Binary files /dev/null and b/docs/res/usage/projects/projects-gitprojects-clone.png differ diff --git a/docs/res/usage/restart.png b/docs/res/usage/restart.png new file mode 100644 index 000000000..383974d71 Binary files /dev/null and b/docs/res/usage/restart.png differ diff --git a/docs/res/usage/tasks/edit-task.png b/docs/res/usage/tasks/edit-task.png new file mode 100644 index 000000000..304393541 Binary files /dev/null and b/docs/res/usage/tasks/edit-task.png differ diff --git a/docs/res/usage/tasks/scheduler-1.png b/docs/res/usage/tasks/scheduler-1.png new file mode 100644 index 000000000..2ca582d56 Binary files /dev/null and b/docs/res/usage/tasks/scheduler-1.png differ diff --git a/docs/res/usage/ui-context1.png b/docs/res/usage/ui-context1.png new file mode 100644 index 000000000..3aa276f68 Binary files /dev/null and b/docs/res/usage/ui-context1.png differ diff --git a/docs/res/usage/ui-history1.png b/docs/res/usage/ui-history1.png new file mode 100644 index 000000000..62e42af62 Binary files /dev/null and b/docs/res/usage/ui-history1.png differ diff --git a/docs/res/usage/ui-katex-2.png b/docs/res/usage/ui-katex-2.png new file mode 100644 index 000000000..1adda894c Binary files /dev/null and b/docs/res/usage/ui-katex-2.png differ diff --git a/docs/res/usage/ui-settings-5-speech-to-text.png b/docs/res/usage/ui-settings-5-speech-to-text.png new file mode 100644 index 000000000..91c5c6faf Binary files /dev/null and b/docs/res/usage/ui-settings-5-speech-to-text.png differ diff --git a/docs/res/usage/ui-tts-stop-speech1.png b/docs/res/usage/ui-tts-stop-speech1.png new file mode 100644 index 000000000..1a8e97327 Binary files /dev/null and b/docs/res/usage/ui-tts-stop-speech1.png differ diff --git a/docs/res/web-ui.mp4 b/docs/res/web-ui.mp4 deleted file mode 100644 index 86fc850aa..000000000 Binary files a/docs/res/web-ui.mp4 and /dev/null differ diff --git a/docs/res/web_screenshot.jpg b/docs/res/web_screenshot.jpg deleted file mode 100644 index 19bb94286..000000000 Binary files a/docs/res/web_screenshot.jpg and /dev/null differ diff --git a/docs/res/win_webui2.gif b/docs/res/win_webui2.gif deleted file mode 100644 index e1f52aed6..000000000 Binary files a/docs/res/win_webui2.gif and /dev/null differ diff --git a/docs/development/setup.md b/docs/setup/dev-setup.md similarity index 95% rename from docs/development/setup.md rename to docs/setup/dev-setup.md index 07e5c8059..d9894bf6e 100644 --- a/docs/development/setup.md +++ b/docs/setup/dev-setup.md @@ -138,22 +138,22 @@ My VS Code instance: Agent Zero runs code inside the container by default. If you are running the framework locally in your IDE but want tools (like code execution) to run in Docker, configure RFC in **Settings -> Development** and point it to a running Agent Zero container. This routes execution through SSH/RFC to the container while keeping the UI and agent loop on your host. -# 🎉 Congratulations! 🚀 +# Congratulations! You have successfully set up a complete Agent Zero development environment! You now have: -- ✅ A local development instance running in your IDE with full debugging capabilities -- ✅ A dockerized instance for code execution and system operations -- ✅ RFC and SSH communication between both instances -- ✅ The ability to develop, debug, and test Agent Zero features seamlessly +- A local development instance running in your IDE with full debugging capabilities +- A dockerized instance for code execution and system operations +- RFC and SSH communication between both instances +- The ability to develop, debug, and test Agent Zero features seamlessly -You're now ready to contribute to Agent Zero, create custom extensions, or modify the framework to suit your needs. Happy coding! 💻✨ +You're now ready to contribute to Agent Zero, create custom extensions, or modify the framework to suit your needs. Happy coding! ## Next steps -- See [extensibility](extensibility.md) for instructions on how to create custom extensions. +- See [extensions](../developer/extensions.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. +- See [contribution](../guides/contribution.md) for instructions on how to contribute to the framework. ## Configuration via Environment Variables diff --git a/docs/getting-started/installation.md b/docs/setup/installation.md similarity index 95% rename from docs/getting-started/installation.md rename to docs/setup/installation.md index 11ffc442f..b61d1424f 100644 --- a/docs/getting-started/installation.md +++ b/docs/setup/installation.md @@ -38,6 +38,7 @@ Docker Desktop provides the runtime environment for Agent Zero, ensuring consist --- + ## Windows Windows Installation **1.1. Download Docker Desktop** @@ -67,6 +68,7 @@ Once installed, launch Docker Desktop from your Start menu or desktop shortcut. --- + ## macOS macOS Installation **1.1. Download Docker Desktop** @@ -103,6 +105,7 @@ Open Docker Desktop from your Applications folder. --- + ## Linux Linux Installation **1.1. Choose Installation Method** @@ -190,7 +193,7 @@ You can map just the `/a0/usr` directory (recommended) or individual subfolders - Click the `Run` button ![docker port mapping](../res/setup/2-docker-image-run.png) -![docker port mapping](../res/setup/2-docker-image-run2.png) +![docker volume mapping](../res/setup/2-docker-image-run-3.png) The container will start and show in the "Containers" tab: @@ -237,7 +240,7 @@ Agent Zero provides a comprehensive settings interface to customize various aspe - **Knowledge Subdirectory:** Specify the location of custom knowledge files to enhance the agent's understanding. > [!NOTE] -> Since v0.9.8, custom prompts belong in `/a0/usr/agents//prompts/` rather than a shared `/prompts` folder. See the [Extensibility guide](../development/extensibility.md#prompts) for details. +> Since v0.9.7, custom prompts belong in `/a0/agents//prompts/` rather than a shared `/prompts` folder. See the [Extensions guide](../developer/extensions.md#prompts) for details. > [!NOTE] > The Hacker profile is included in the main image. After launch, choose the **hacker** agent profile in Settings if you want the security-focused prompts and tooling. The "hacker" branch is deprecated. @@ -311,7 +314,7 @@ Configure API keys for various service providers directly within the Web UI. Cli - **RFC Parameters (local instances only):** Configure URLs and ports for remote function calls between instances - **RFC Password:** Configure password for remote function calls -Learn more about Remote Function Calls in the [Development guide](../development/setup.md#step-6-configure-ssh-and-rfc-connection). +Learn more about Remote Function Calls in the [Development Setup guide](dev-setup.md#step-6-configure-ssh-and-rfc-connection). > [!IMPORTANT] > Always keep your API keys and passwords secure. @@ -378,6 +381,7 @@ Ollama is a powerful tool that allows you to run various large language models l --- + ### Windows Windows Ollama Installation Download and install Ollama from the official website: @@ -388,6 +392,7 @@ Once installed, continue to [Pulling Models](#pulling-models). --- + ### macOS macOS Ollama Installation **Using Homebrew:** @@ -404,6 +409,7 @@ Once installed, continue to [Pulling Models](#pulling-models). --- + ### Linux Linux Ollama Installation Run the installation script: @@ -497,7 +503,7 @@ The Tunnel feature allows secure access to your Agent Zero instance from anywher > [!IMPORTANT] > **Security:** Always set a username and password in Settings → Authentication before creating a tunnel to secure your instance on the internet. -For complete details on tunnel configuration and security considerations, see the [Tunneling guide](../advanced/tunneling.md). +For complete details on tunnel configuration and security considerations, see the [Remote Access via Tunneling](../guides/usage.md#remote-access-via-tunneling) section in the Usage Guide. ### Alternative: Local Network Access @@ -510,7 +516,7 @@ If you prefer to keep access limited to your local network: > [!TIP] > Find your computer's IP address with `ipconfig` (Windows) or `ifconfig`/`ip addr` (macOS/Linux). It's usually in the format `192.168.x.x` or `10.0.x.x`. -For developers or users who need to run Agent Zero directly on their system, see the [In-Depth Guide for Full Binaries Installation](../development/setup.md). +For developers or users who need to run Agent Zero directly on their system, see the [In-Depth Guide for Full Binaries Installation](dev-setup.md). --- @@ -582,7 +588,7 @@ After following the instructions for your specific operating system, you should **Next Steps:** - For production server deployments, see the [VPS Deployment Guide](vps-deployment.md) -- For development setup and extensions, see the [Development Guide](../development/setup.md) -- For remote access via tunnel, see the [Tunneling Guide](../advanced/tunneling.md) +- For development setup and extensions, see the [Development Setup Guide](dev-setup.md) +- For remote access via tunnel, see [Remote Access via Tunneling](../guides/usage.md#remote-access-via-tunneling) If you encounter any issues during the installation process, please consult the [Troubleshooting section](../guides/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/getting-started/vps-deployment.md b/docs/setup/vps-deployment.md similarity index 98% rename from docs/getting-started/vps-deployment.md rename to docs/setup/vps-deployment.md index 4a1c7e516..24066f6c4 100644 --- a/docs/getting-started/vps-deployment.md +++ b/docs/setup/vps-deployment.md @@ -173,7 +173,7 @@ A0_PORT="50080" docker pull agent0ai/agent-zero:latest # Run container -docker run -d --name ${A0_NAME} --restart unless-stopped -p ${A0_PORT}:80 -v ${A0_PATH}/.env:/a0/.env -v ${A0_PATH}/work_dir:/a0/work_dir -v ${A0_PATH}/memory:/a0/memory -v ${A0_PATH}/logs:/a0/logs agent0ai/agent-zero:latest +docker run -d --name ${A0_NAME} --restart unless-stopped -p ${A0_PORT}:80 -v ${A0_PATH}/.env:/a0/.env -v ${A0_PATH}/usr:/a0/usr agent0ai/agent-zero:latest ``` ### Step 5: Verify Container @@ -638,7 +638,7 @@ docker stop a0-instance docker rm a0-instance # Recreate with same settings -docker run -d --name a0-instance --restart unless-stopped -p 50080:80 -v /opt/a0-instance/.env:/a0/.env -v /opt/a0-instance/work_dir:/a0/work_dir -v /opt/a0-instance/memory:/a0/memory -v /opt/a0-instance/logs:/a0/logs agent0ai/agent-zero:latest +docker run -d --name a0-instance --restart unless-stopped -p 50080:80 -v /opt/a0-instance/.env:/a0/.env -v /opt/a0-instance/usr:/a0/usr -v /opt/agent-zero:latest ``` ### Backup Strategy diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md deleted file mode 100644 index 152a93af2..000000000 --- a/docs/tutorials/README.md +++ /dev/null @@ -1,20 +0,0 @@ -# Agent Zero Video Library - -Welcome to the visual guide for Agent Zero. Here you'll find tutorials, walkthroughs, and real-world use cases. - -## 📺 Basics -- **[UI Walkthrough](basics.md)**: A tour of the interface, settings, and basic controls. -- **[Installation Guide](https://www.youtube.com/watch?v=w5v5Kjx51hs)**: Getting started on your machine. - -## 💡 Use Case Showcases - -| Use Case | Description | Link | -|----------|-------------|------| -| **Data Analysis** | Financial trending, charting, and report generation | [View Guide](data-analysis.md) | -| **Coding Assistant** | Building a full-stack web application from scratch | [View Guide](coding-assistant.md) | -| **Deep Research** | Gathering papers, summarizing, and synthesizing info | [View Guide](research.md) | - -## 🎓 Advanced Tutorials -- [MCP Server Setup](https://youtu.be/pM5f4Vz3_IQ) -- [Projects & Workspaces](https://youtu.be/RrTDp_v9V1c) -- [Memory Management](https://youtu.be/sizjAq2-d9s) diff --git a/docs/tutorials/basics.md b/docs/tutorials/basics.md deleted file mode 100644 index ac5e4b5d9..000000000 --- a/docs/tutorials/basics.md +++ /dev/null @@ -1,9 +0,0 @@ -# UI Walkthrough - -*(Placeholder for screenshots of the new Dashboard, Chat Interface, and Settings)* - -## The Dashboard -![Dashboard](/docs/res/splash_wide.png) - -## Chat Interface -![Chat](/docs/res/ui-screen-2.png) diff --git a/docs/tutorials/coding-assistant.md b/docs/tutorials/coding-assistant.md deleted file mode 100644 index 91e0bd4ba..000000000 --- a/docs/tutorials/coding-assistant.md +++ /dev/null @@ -1,5 +0,0 @@ -# Coding Assistant Use Case - -**Goal:** Build a React dashboard with real-time data visualization. - -*(Placeholder for step-by-step video/screenshots)* diff --git a/docs/tutorials/data-analysis.md b/docs/tutorials/data-analysis.md deleted file mode 100644 index 7389425fe..000000000 --- a/docs/tutorials/data-analysis.md +++ /dev/null @@ -1,5 +0,0 @@ -# Financial Analysis Use Case - -**Goal:** Analyze Bitcoin/USD price trends and generate a highlighted chart. - -*(Placeholder for step-by-step video/screenshots)* diff --git a/docs/tutorials/research.md b/docs/tutorials/research.md deleted file mode 100644 index f0c6aa420..000000000 --- a/docs/tutorials/research.md +++ /dev/null @@ -1,5 +0,0 @@ -# Deep Research Use Case - -**Goal:** Gather and summarize recent AI papers about CoT prompting. - -*(Placeholder for step-by-step video/screenshots)*