Skip to content

Agent Zero AI framework

update docs and add agents capability

3clyp50a3c06827e50a
diff --git a/PLUGIN_SYSTEM.md b/PLUGIN_SYSTEM.md
deleted file mode 100644
index 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.json
new file mode 100644
index 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.md
new file mode 100644
index 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.json
new file mode 100644
index 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.py
index 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 append
Returns:
@@ -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_data
diff --git a/python/helpers/settings.py b/python/helpers/settings.py
index ae78ec817..2d9099302 100644
--- a/python/helpers/settings.py
+++ b/python/helpers/settings.py
@@ -7,7 +7,7 @@ import subprocess
from typing import Any, Literal, TypedDict, cast, TypeVar
import models
-from python.helpers import runtime, whisper, defer, git
+from python.helpers import runtime, whisper, defer, git, subagents
from . import files, dotenv
from python.helpers.print_style import PrintStyle
from 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.py
index 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 merge
default_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 possible
if project_name:
@@ -102,12 +110,20 @@ def load_agent_data(name: str, project_name: str | None = None) -> SubAgent:
return original
return override
- # load default and user agents and merge
+ # load default, plugin, and user agents and merge
default_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 possible
if 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)):