Agent Zero AI framework
update docs and add agents capability
3clyp50a3c06827e50a
diff --git a/PLUGIN_SYSTEM.md b/PLUGIN_SYSTEM.mddeleted file mode 100644index 0ba822b31..000000000--- a/PLUGIN_SYSTEM.md+++ /dev/null@@ -1,116 +0,0 @@-# Unified Plugin System - Implementation Summary--This document provides a technical overview of the Plugin System implementation in Agent Zero.--## Overview--The Plugin System allows users and the community to create full-stack plugins that integrate seamlessly with Agent Zero. It supports backend capabilities (API endpoints, tools, helpers) and frontend UI extensions. It uses a manifest-driven approach (`plugin.json`) to declare capabilities.--## Architecture--### Components--1. Backend Plugin Discovery (`python/helpers/plugins.py`)- - Resolves plugin directories across repo (`plugins/`) and user (`usr/plugins/`) locations.- - Loads and validates `plugin.json` manifests.- - Provides `import_plugin_module()` for dynamic dependency injection, replacing static imports.- - Implements override logic (user plugins override repo plugins).--2. API Endpoints- - `POST /plugins_resolve` - Resolves a plugin manifest by ID (for frontend).- - `GET/POST /plugins_list` - Lists all available plugins.- - `GET /plugins/<id>/<path>` - Serves plugin static assets (UI, scripts).--3. Frontend Plugin Loader (`webui/js/plugins.js`)- - Discovers and loads `<x-extension>` tags.- - Fetches plugin manifests via `/plugins_resolve`.- - Path Traversal Strategy: Integrates with the standard component loader by adjusting paths (e.g., prepending `components/../` to plugin URLs) to bypass default path restrictions without modifying the core loader.- - Handles module imports and props merging.--4. Standard Component Loader (`webui/js/components.js`)- - Vanilla Implementation: Remains unmodified to ensure stability and compatibility.- - Enforces `components/` prefix for all loaded resources.- - Used by `plugins.js` via relative path traversal to load plugin UI components.--5. DOM Integration- - Automatic loading on DOM ready.- - MutationObserver for dynamic plugin injection.- - Alpine.js integration via `globalThis.xAttrs()`.--## File Structure--```-/plugins/ # Repo plugins (default)- ├── memory/- │ ├── plugin.json # Manifest- │ ├── api/ # Backend endpoints- │ ├── tools/ # Agent tools- │ ├── helpers/ # Python helpers- │ ├── ui/ # Frontend components- │ │ ├── memory-dashboard.html- │ │ └── memory-dashboard-store.js- │ └── prompts/ # System prompts- └── README.md--/usr/plugins/ # User plugins (override)- ├── my-plugin/- │ ├── plugin.json- │ └── ...- └── README.md-```--## Plugin Manifest Schema--```json-{- "id": "plugin-id", // Required: Must match directory name- "name": "Display Name", // Optional: Human-readable name- "provides": {- "api": [- { "module": "api/my_endpoint.py", "description": "..." }- ],- "tool": [- { "module": "tools/my_tool.py", "description": "..." }- ],- "ui": {- "component": "ui/index.html",- "module": "ui/main.js"- },- "prompt": [- { "module": "prompts/system.md", "description": "..." }- ]- },- "props": { // Optional: Default UI properties- "key": "value"- }-}-```--## Usage--### Creating a Plugin--1. Create plugin directory: `plugins/my-plugin`-2. Create `plugin.json` declaring provided capabilities.-3. Implement backend modules in `api/`, `tools/`, etc.-4. Implement frontend components in `ui/`.--### Using Plugin Capabilities--Backend (Python):-Instead of static imports, use the dynamic loader:-```python-from python.helpers.plugins import import_plugin_module--# Dynamically load a helper from the 'memory' plugin-memory = import_plugin_module("memory", "helpers/memory.py")-memory.some_function()-```--Frontend (HTML/JS):-Plugins can be embedded via `<x-extension>` or loaded dynamically via `openModal`.-```javascript-// Open a plugin component in a modal-// Uses relative path to traverse out of 'components/' and into 'plugins/'-openModal("../plugins/my-plugin/ui/dashboard.html");-```diff --git a/plugins/example_agent/agents/plugin_example/agent.json b/plugins/example_agent/agents/plugin_example/agent.jsonnew file mode 100644index 000000000..4e299f268--- /dev/null+++ b/plugins/example_agent/agents/plugin_example/agent.json@@ -0,0 +1,5 @@+{+ "title": "Plugin Example Agent",+ "description": "This is an example agent profile loaded from the 'example_agent' plugin.",+ "context": "You are an example agent provided by the 'example_agent' plugin. Your purpose is to demonstrate how plugins can distribute agent profiles."+}diff --git a/plugins/example_agent/agents/plugin_example/prompts/agent.system.plugin_example.md b/plugins/example_agent/agents/plugin_example/prompts/agent.system.plugin_example.mdnew file mode 100644index 000000000..97fefe1a6--- /dev/null+++ b/plugins/example_agent/agents/plugin_example/prompts/agent.system.plugin_example.md@@ -0,0 +1,3 @@+You are the Example Plugin Agent.+You were loaded from the `plugins/example_agent` directory.+Your main goal is to demonstrate that agent profiles can be distributed via plugins.diff --git a/plugins/example_agent/plugin.json b/plugins/example_agent/plugin.jsonnew file mode 100644index 000000000..c024a77bc--- /dev/null+++ b/plugins/example_agent/plugin.json@@ -0,0 +1,15 @@+{+ "id": "example_agent",+ "name": "Example Agent Plugin",+ "version": "0.1.0",+ "description": "An example plugin demonstrating the agent profile capability.",+ "author": "Agent Zero",+ "provides": {+ "agent": [+ {+ "dir": "agents",+ "description": "Example agent profile"+ }+ ]+ }+}diff --git a/python/helpers/plugins.py b/python/helpers/plugins.pyindex 6ea165149..75aacd132 100644--- a/python/helpers/plugins.py+++ b/python/helpers/plugins.py@@ -144,9 +144,10 @@ def _extract_module_dir(module_path: str) -> str:def get_plugin_paths(cap_type: str, *subpaths: str) -> List[str]:"""Get all paths from loaded plugins for a given capability type.+ Supports both 'module' (parent dir used) and 'dir' (direct path used) in config.Args:- cap_type: Capability type (e.g., "tool", "extension", "api")+ cap_type: Capability type (e.g., "tool", "extension", "api", "agent")subpaths: Additional path components to appendReturns:@@ -160,18 +161,27 @@ def get_plugin_paths(cap_type: str, *subpaths: str) -> List[str]:continue# Normalize to list for uniform processing- modules = []+ items = []if isinstance(cap_config, list):- modules = [cap.get("module") for cap in cap_config if isinstance(cap, dict) and cap.get("module")]- elif isinstance(cap_config, dict) and cap_config.get("module"):- modules = [cap_config["module"]]+ items = [c for c in cap_config if isinstance(c, dict)]+ elif isinstance(cap_config, dict):+ items = [cap_config]- # Build paths from modules- for module_path in modules:- module_dir = _extract_module_dir(module_path)- full_path = files.get_abs_path(str(plugin.path), module_dir, *subpaths)- if files.exists(full_path) and full_path not in paths:- paths.append(full_path)+ # Build paths from items+ for item in items:+ path_to_add = ""++ # Priority 1: Explicit directory+ if item.get("dir"):+ path_to_add = item["dir"]+ # Priority 2: Module parent directory+ elif item.get("module"):+ path_to_add = _extract_module_dir(item["module"])++ if path_to_add:+ full_path = files.get_abs_path(str(plugin.path), path_to_add, *subpaths)+ if files.exists(full_path) and full_path not in paths:+ paths.append(full_path)return paths@@ -259,4 +269,4 @@ def build_plugin_response_data(plugin: Plugin) -> dict:if ui_config.get("props"):response_data["props"] = ui_config["props"]- return response_data\ No newline at end of file+ return response_datadiff --git a/python/helpers/settings.py b/python/helpers/settings.pyindex ae78ec817..2d9099302 100644--- a/python/helpers/settings.py+++ b/python/helpers/settings.py@@ -7,7 +7,7 @@ import subprocessfrom typing import Any, Literal, TypedDict, cast, TypeVarimport models-from python.helpers import runtime, whisper, defer, git+from python.helpers import runtime, whisper, defer, git, subagentsfrom . import files, dotenvfrom python.helpers.print_style import PrintStylefrom python.helpers.providers import get_providers, FieldOption as ProvidersFO@@ -248,9 +248,9 @@ def convert_out(settings: Settings) -> SettingsOutput:embedding_providers=get_providers("embedding"),shell_interfaces=[{"value": "local", "label": "Local Python TTY"}, {"value": "ssh", "label": "SSH"}],is_dockerized=runtime.is_dockerized(),- agent_subdirs=[{"value": subdir, "label": subdir}- for subdir in files.get_subdirectories("agents")- if subdir != "_example"],+ agent_subdirs=[{"value": item["key"], "label": item["label"]}+ for item in subagents.get_all_agents_list()+ if item["key"] != "_example"],knowledge_subdirs=[{"value": subdir, "label": subdir}for subdir in files.get_subdirectories("knowledge", exclude="default")],stt_models=[@@ -815,4 +815,3 @@ def create_auth_token() -> str:def _get_version():return git.get_version()-diff --git a/python/helpers/subagents.py b/python/helpers/subagents.pyindex e7dbdbf12..a851fdb23 100644--- a/python/helpers/subagents.py+++ b/python/helpers/subagents.py@@ -10,7 +10,7 @@ USER_DIR = "usr"DEFAULT_AGENTS_DIR = "agents"USER_AGENTS_DIR = "usr/agents"-type Origin = Literal["default", "user", "project"]+type Origin = Literal["default", "user", "project", "plugin"]if TYPE_CHECKING:from agent import Agent@@ -57,10 +57,18 @@ def get_agents_dict()return merged- # load default and custom agents and merge+ # load default, plugin, and custom agents and mergedefault_agents = _get_agents_list_from_dir(DEFAULT_AGENTS_DIR, origin="default")+ merged: dict[str, SubAgentListItem] = dict(default_agents)++ # merge with plugin agents+ from python.helpers import plugins+ for plugin_dir in reversed(plugins.get_plugin_paths("agent")):+ plugin_agents = _get_agents_list_from_dir(plugin_dir, origin="plugin")+ merged = _merge_agent_dicts(merged, plugin_agents)+custom_agents = _get_agents_list_from_dir(USER_AGENTS_DIR, origin="user")- merged = _merge_agent_dicts(default_agents, custom_agents)+ merged = _merge_agent_dicts(merged, custom_agents)# merge with project agents if possibleif project_name:@@ -102,12 +110,20 @@ def load_agent_data(name: str, project_name: str | None = None) -> SubAgent:return originalreturn override- # load default and user agents and merge+ # load default, plugin, and user agents and mergedefault_agent = _load_agent_data_from_dir(DEFAULT_AGENTS_DIR, name, origin="default")+ merged = default_agent++ # merge with plugin agents+ from python.helpers import plugins+ for plugin_dir in reversed(plugins.get_plugin_paths("agent")):+ plugin_agent = _load_agent_data_from_dir(plugin_dir, name, origin="plugin")+ merged = _merge_agent(merged, plugin_agent)+user_agent = _load_agent_data_from_dir(USER_AGENTS_DIR, name, origin="user")- merged = _merge_agent(default_agent, user_agent)+ merged = _merge_agent(merged, user_agent)# merge with project agent if possibleif project_name:@@ -121,7 +137,7 @@ def load_agent_data(name: str, project_name: str | None = None) -> SubAgent:if merged is None:raise FileNotFoundError(- f"Agent '{name}' not found in default or custom directories"+ f"Agent '{name}' not found in default, plugin, or custom directories")return merged@@ -222,9 +238,13 @@ def _merge_agent_list_items(def get_agents_roots() -> list[str]:+ from python.helpers import plugins++ plugin_agents = list(reversed(plugins.get_plugin_paths("agent")))project_agents = files.find_existing_paths_by_pattern("usr/projects/*/.a0proj/agents")paths = [files.get_abs_path(DEFAULT_AGENTS_DIR),+ *plugin_agents,files.get_abs_path(USER_AGENTS_DIR),*project_agents,]@@ -249,6 +269,8 @@ def get_all_agents_list() -> list[dict[str, str]]:return "project"if rel.startswith("usr/agents"):return "user"+ if "/plugins/" in rel or rel.startswith("plugins/"):+ return "plugin"return "default"merged: dict[str, SubAgentListItem] = {}@@ -339,6 +361,13 @@ def get_paths(if (not must_exist_completely) or files.exists(files.get_abs_path(USER_AGENTS_DIR, profile_name, *check_subpaths)):paths.append(path)+ # plugin agents/<profile>/...+ from python.helpers import plugins+ for plugin_dir in plugins.get_plugin_paths("agent"):+ path = files.get_abs_path(plugin_dir, profile_name, *subpaths)+ if (not must_exist_completely) or files.exists(files.get_abs_path(plugin_dir, profile_name, *check_subpaths)):+ paths.append(path)+# agents/<profile>/...path = files.get_abs_path(DEFAULT_AGENTS_DIR, profile_name, *subpaths)if (not must_exist_completely) or files.exists(files.get_abs_path(DEFAULT_AGENTS_DIR, profile_name, *check_subpaths)):