Agent Zero AI framework
update docs, skill and enhance activation model
Alessandro8639069104a4
diff --git a/AGENTS.md b/AGENTS.mdindex f81ad76a6..fc30c901c 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -126,9 +126,10 @@ Key Files:### Plugin Architecture- Location: Always develop new plugins in usr/plugins/.-- Manifest: Every plugin requires a plugin.json with name, description, version, and optionally settings_sections.+- Manifest: Every plugin requires a plugin.yaml with name, description, version, and optionally settings_sections, per_project_config, per_agent_config, and always_enabled.- Discovery: Conventions based on folder names (api/, tools/, webui/, extensions/).- Settings: Use get_plugin_config(plugin_name, agent=agent) to retrieve settings. Plugins can expose a UI for settings via webui/config.html. For plugins wrapping core settings, set $store.pluginSettings.saveMode = 'core' in x-init.+- Activation: Global and scoped activation rules are stored as .toggle-1 (ON) and .toggle-0 (OFF). Scoped rules are handled via the plugin "Switch" modal.### Lifecycle Synchronization| Action | Backend Extension | Frontend Lifecycle |diff --git a/AGENTS.plugins.md b/AGENTS.plugins.mdindex cf3b9fd24..76aac112a 100644--- a/AGENTS.plugins.md+++ b/AGENTS.plugins.md@@ -23,12 +23,12 @@ Each plugin lives in usr/plugins/<plugin_name>/.```textusr/plugins/<plugin_name>/-├── plugin.json # Required: Name, version, settings config+├── plugin.yaml # Required: Name, version, settings + activation metadata├── api/ # API handlers (ApiHandler subclasses)├── tools/ # Agent tools (Tool subclasses)├── helpers/ # Shared Python logic├── prompts/ # Prompt templates-├── agents/ # Agent profiles+├── agents/ # Agent profiles (agents/<profile>/agent.yaml)├── extensions/│ ├── python/<point>/ # Backend lifecycle hooks│ └── webui/<point>/ # UI HTML/JS contributions@@ -37,14 +37,17 @@ usr/plugins/<plugin_name>/└── ... # Full plugin pages/components```-### plugin.json format-```json-{- "name": "My Plugin",- "description": "What this plugin does.",- "version": "1.0.0",- "settings_sections": ["agent"]-}+### plugin.yaml format+```yaml+name: My Plugin+description: What this plugin does.+version: 1.0.0+settings_sections:+ - agent+per_project_config: false+per_agent_config: false+# Optional: lock plugin permanently ON in UI/back-end+always_enabled: false```settings_sections values: agent, external, mcp, developer, backup.@@ -75,16 +78,25 @@ Place *.js files in extensions/webui/<extension_point>/ and export a default asy2. project/.a0proj/plugins/<name>/config.json3. usr/agents/<profile>/plugins/<name>/config.json4. usr/plugins/<name>/config.json+5. plugins/<name>/default_config.yaml (fallback defaults)++## 5. Plugin Activation Model++- Global and scoped activation are independent, with no inheritance between scopes.+- Activation flags are files: `.toggle-1` (ON) and `.toggle-0` (OFF).+- UI states are `ON`, `OFF`, and `Advanced` (shown when any project/profile-specific override exists).+- `always_enabled: true` in `plugin.yaml` forces ON and disables toggle controls in the UI.+- The "Switch" modal is the canonical per-scope activation surface, and "Configure Plugin" keeps scope synchronized with the settings modal.----## 5. Routes+## 6. Routes| Route | Purpose ||---|---|| GET /plugins/<name>/<path> | Serve static assets || POST /api/plugins/<name>/<handler> | Call plugin API |-| POST /api/plugins | Management (action: get_config, save_config) |+| POST /api/plugins | Management (actions: get_config, save_config, list_configs, delete_config, toggle_plugin) |---diff --git a/docs/README.md b/docs/README.mdindex 55dcaf965..38d476c9f 100644--- a/docs/README.md+++ b/docs/README.md@@ -22,6 +22,7 @@ Welcome to the Agent Zero documentation hub. Whether you're getting started or d## Developer Documentation- **[Architecture Overview](developer/architecture.md):** Understand Agent Zero's internal structure and components.+- **[Plugins](developer/plugins.md):** Build plugins with `plugin.yaml`, scoped settings, and activation toggles.- **[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.@@ -105,6 +106,7 @@ Welcome to the Agent Zero documentation hub. Whether you're getting started or d- [Knowledge](developer/architecture.md#5-knowledge)- [Skills](developer/architecture.md#6-skills)- [Extensions](developer/architecture.md#7-extensions)+ - [Plugins](developer/plugins.md)- [Extensions](developer/extensions.md)- [Connectivity](developer/connectivity.md)- [WebSockets](developer/websockets.md)diff --git a/docs/developer/plugins.md b/docs/developer/plugins.mdnew file mode 100644index 000000000..03348b3b6--- /dev/null+++ b/docs/developer/plugins.md@@ -0,0 +1,129 @@+# Plugins++This page documents the current Agent Zero plugin system, including manifest format, discovery rules, scoped configuration, and activation behavior.++## Overview++Plugins extend Agent Zero through convention-based folders. A plugin can provide:++- Backend: API handlers, tools, helpers, Python lifecycle extensions+- Frontend: WebUI components and extension-point injections+- Agent profiles: plugin-scoped subagent definitions+- Settings: scoped plugin configuration loaded through the plugin settings store+- Activation control: global and per-scope ON/OFF rules++Primary roots (priority order):++1. `usr/plugins/` (user/custom plugins)+2. `plugins/` (core/built-in plugins)++On name collisions, user plugins take precedence.++## Manifest (`plugin.yaml`)++Every plugin must contain `plugin.yaml`:++```yaml+name: My Plugin+description: What this plugin does.+version: 1.0.0+settings_sections:+ - agent+per_project_config: false+per_agent_config: false+always_enabled: false+```++Field reference:++- `name`: UI display name+- `description`: short plugin summary+- `version`: plugin version string+- `settings_sections`: where plugin settings appear (`agent`, `external`, `mcp`, `developer`, `backup`)+- `per_project_config`: enables project-scoped settings/toggles+- `per_agent_config`: enables agent-profile-scoped settings/toggles+- `always_enabled`: forces ON state and disables toggle controls++## Recommended Structure++```text+usr/plugins/<plugin_name>/+├── plugin.yaml+├── default_config.yaml # optional defaults+├── api/ # ApiHandler implementations+├── tools/ # Tool implementations+├── helpers/ # shared Python logic+├── prompts/+├── agents/+│ └── <profile>/agent.yaml # optional plugin-distributed agent profile+├── extensions/+│ ├── python/<extension_point>/+│ └── webui/<extension_point>/+└── webui/+ ├── config.html # optional settings UI+ └── ...+```++## Settings Resolution++Plugin settings are resolved by scope. Higher priority overrides lower priority:++1. `project/.a0proj/agents/<profile>/plugins/<name>/config.json`+2. `project/.a0proj/plugins/<name>/config.json`+3. `usr/agents/<profile>/plugins/<name>/config.json`+4. `usr/plugins/<name>/config.json`+5. `plugins/<name>/default_config.yaml` (fallback defaults)++Notes:++- Runtime reads support JSON and YAML fallback files.+- Save path is scope-specific and persisted through plugin settings APIs.++## Activation Model++Activation is independent per scope and file-based:++- `.toggle-1` means ON+- `.toggle-0` means OFF+- no explicit rule means ON by default++WebUI activation states:++- `ON`: explicit ON or implicit default+- `OFF`: explicit OFF rule at selected scope+- `Advanced`: at least one project/agent-profile override exists++`always_enabled: true` bypasses OFF state and keeps the plugin ON in both backend and UI.++## UI Flow++Current plugin UX surfaces activation in two places:++- Plugin list: simple ON/OFF selector, with `Advanced` option when scoped overrides are enabled+- Plugin switch modal: scope-aware ON/OFF controls per project/profile, with direct handoff to settings++Scope synchronization behavior:++- Opening "Configure Plugin" from the switch modal propagates current scope into settings store+- Switching scope in settings also mirrors into toggle store so activation status stays aligned++## API Surface++Core plugin management endpoint: `POST /api/plugins`++Supported actions:++- `get_config`+- `save_config`+- `list_configs`+- `delete_config`+- `toggle_plugin`++## Migration Notes++Current plugin format is YAML-based (`plugin.yaml`, `default_config.yaml`, `agent.yaml` for agent profiles). Legacy JSON manifests should be migrated.++## See Also++- `AGENTS.plugins.md` for full architecture details+- `skills/a0-create-plugin/SKILL.md` for plugin authoring workflowdiff --git a/plugins/README.md b/plugins/README.mdindex b793a763d..a6bca7ff8 100644--- a/plugins/README.md+++ b/plugins/README.md@@ -16,7 +16,8 @@ For detailed guides on how to create, extend, or configure plugins, please refer## Usage-Plugins are automatically discovered based on the presence of a plugin.json file. Each plugin can contribute:+Plugins are automatically discovered based on the presence of a plugin.yaml file. Each plugin can contribute:- Backend: APIs, Tools, Helpers, and Lifecycle Extensions.- Frontend: HTML/JS UI contributions via core breakpoints.- Config: Isolated settings scoped per-project and per-agent profile.+- Activation: Global/scoped ON-OFF rules via `.toggle-1` and `.toggle-0` files, including advanced per-scope switching in WebUI.diff --git a/plugins/memory/plugin.yaml b/plugins/memory/plugin.yamlindex 3c43c4a29..38a20286e 100644--- a/plugins/memory/plugin.yaml+++ b/plugins/memory/plugin.yaml@@ -4,4 +4,4 @@ version: 1.0.0settings_sections:- agentper_project_config: true-per_agent_config: false\ No newline at end of file+per_agent_config: true\ No newline at end of filediff --git a/python/api/plugins.py b/python/api/plugins.pyindex 54c7bdf90..0ed8b280d 100644--- a/python/api/plugins.py+++ b/python/api/plugins.py@@ -120,6 +120,7 @@ class Plugins(ApiHandler):enabled = input.get("enabled")project_name = input.get("project_name", "")agent_profile = input.get("agent_profile", "")+ clear_overrides = bool(input.get("clear_overrides", False))if not plugin_name:return Response(status=400, response="Missing plugin_name")@@ -127,7 +128,7 @@ class Plugins(ApiHandler):return Response(status=400, response="Missing enabled state")plugins.toggle_plugin(- plugin_name, bool(enabled), project_name, agent_profile+ plugin_name, bool(enabled), project_name, agent_profile, clear_overrides)return {"ok": True}diff --git a/skills/a0-create-plugin/SKILL.md b/skills/a0-create-plugin/SKILL.mdindex 2d7e0df01..e87325788 100644--- a/skills/a0-create-plugin/SKILL.md+++ b/skills/a0-create-plugin/SKILL.md@@ -1,6 +1,6 @@---name: a0-create-plugin-description: Create, extend, or modify Agent Zero plugins. Follows strict full-stack conventions (usr/plugins, plugin.json, Store Gating, AgentContext, plugin settings). Use for UI hooks, API handlers, lifecycle extensions, or plugin settings UI.+description: Create, extend, or modify Agent Zero plugins. Follows strict full-stack conventions (usr/plugins, plugin.yaml, Store Gating, AgentContext, plugin settings). Use for UI hooks, API handlers, lifecycle extensions, or plugin settings UI.---# Agent Zero Plugin Development@@ -12,22 +12,24 @@ Primary references:- /a0/AGENTS.md (Full-stack architecture & AgentContext)- /a0/docs/agents/AGENTS.components.md (Component system deep dive)- /a0/docs/agents/AGENTS.modals.md (Modal system & CSS conventions)-- /a0/AGENTS.plugins.md (Extension points, plugin.json, settings system)+- /a0/AGENTS.plugins.md (Extension points, plugin.yaml, settings system)-## Plugin Manifest (plugin.json)+## Plugin Manifest (plugin.yaml)-Every plugin must have a plugin.json or it will not be discovered:+Every plugin must have a plugin.yaml or it will not be discovered:-```json-{- "name": "My Plugin",- "description": "What this plugin does.",- "version": "1.0.0",- "settings_sections": ["agent"]-}+```yaml+name: My Plugin+description: What this plugin does.+version: 1.0.0+settings_sections:+ - agent+per_project_config: false+per_agent_config: false```settings_sections controls which Settings tabs show a subsection for this plugin. Valid values: agent, external, mcp, developer, backup. Use [] for no subsection.+Activation defaults to ON when no toggle rule exists. Set `per_project_config` and/or `per_agent_config` to enable advanced per-scope switching. Core system plugins may also use `always_enabled: true` to lock the plugin permanently ON (reserved for framework use).## Mandatory Frontend Patterns@@ -64,7 +66,7 @@ Import it in the HTML <head>:## Plugin Settings-If your plugin needs user-configurable settings, add webui/config.html. The system detects it automatically and shows a Settings button in the relevant tabs (per settings_sections in plugin.json).+If your plugin needs user-configurable settings, add webui/config.html. The system detects it automatically and shows a Settings button in the relevant tabs (per settings_sections in plugin.yaml).### Settings modal contract@@ -143,7 +145,10 @@ save_plugin_config(## Directory Layout```usr/plugins/<name>/- plugin.json # Required manifest+ plugin.yaml # Required manifest+ default_config.yaml # Optional default settings fallback+ agents/+ <profile>/agent.yaml # Optional plugin-distributed agent profileapi/ # API Handlers (ApiHandler base class)tools/ # Tool subclassesextensions/diff --git a/webui/components/plugins/list/pluginListStore.js b/webui/components/plugins/list/pluginListStore.jsindex c2d244211..b1f3790a0 100644--- a/webui/components/plugins/list/pluginListStore.js+++ b/webui/components/plugins/list/pluginListStore.js@@ -65,11 +65,14 @@ const model = {if (!pluginSettingsStore?.open) {throw new Error("Plugin settings store is unavailable.");}- // Set saveMode before open() so loadSettings picks up the right mode+ await pluginSettingsStore.open(plugin.name, {+ perProjectConfig: !!plugin.per_project_config,+ perAgentConfig: !!plugin.per_agent_config,+ });+ // Set saveMode after open() (open resets it to 'plugin')if (plugin.settings_sections?.includes('core')) {pluginSettingsStore.saveMode = 'core';}- await pluginSettingsStore.open(plugin.name);window.openModal?.("components/plugins/plugin-settings.html");} catch (e) {showErrorNotification(e, "Failed to open plugin config");@@ -100,14 +103,20 @@ const model = {}const enabled = value === 'enabled';- this.loading = true; // Show loading state+ const clearOverrides = plugin.toggle_state === 'advanced';+ if (clearOverrides && !window.confirm(+ `"${plugin.display_name || plugin.name}" has per-scope activation rules that will be removed. Set globally to ${enabled ? 'ON' : 'OFF'}?`+ )) return;++ this.loading = true;try {const response = await api.callJsonApi("plugins", {action: "toggle_plugin",plugin_name: plugin.name,enabled: enabled,- project_name: "", // Global- agent_profile: "" // Global+ project_name: "",+ agent_profile: "",+ clear_overrides: clearOverrides,});if (response?.error) throw new Error(response.error);await this.refresh();diff --git a/webui/components/plugins/plugin-settings-store.js b/webui/components/plugins/plugin-settings-store.jsindex 2ded1396c..f6918d780 100644--- a/webui/components/plugins/plugin-settings-store.js+++ b/webui/components/plugins/plugin-settings-store.js@@ -169,6 +169,9 @@ const model = {// 'core' = save via $store.settings.saveSettings() (for plugins that surface core settings)saveMode: 'plugin',+ perProjectConfig: true,+ perAgentConfig: true,+isLoading: false,isSaving: false,error: null,@@ -176,13 +179,15 @@ const model = {// Called by the subsection button before openModal()// Optional scope: { projectName, agentProfileKey } — skips redundant global loadSettings()// when the caller already knows which scope to open at.- async open(pluginName, { projectName = "", agentProfileKey = "" } = {}) {+ async open(pluginName, { projectName = "", agentProfileKey = "", perProjectConfig = true, perAgentConfig = true } = {}) {this.pluginName = pluginName;this.pluginMeta = null;this.settings = {};this.settingsSnapshotJson = "";this.error = null;this.saveMode = 'plugin';+ this.perProjectConfig = perProjectConfig;+ this.perAgentConfig = perAgentConfig;this.projectName = projectName;this.agentProfileKey = agentProfileKey;this.previousProjectName = projectName;@@ -316,6 +321,8 @@ const model = {this.isListingConfigs = false;this.configsError = null;this.configs = [];+ this.perProjectConfig = true;+ this.perAgentConfig = true;},// Reactive URL for the plugin's settings component (used with x-html injection)diff --git a/webui/components/plugins/plugin-settings.html b/webui/components/plugins/plugin-settings.htmlindex a6af8e7f9..49d2e846d 100644--- a/webui/components/plugins/plugin-settings.html+++ b/webui/components/plugins/plugin-settings.html@@ -11,8 +11,9 @@<div x-create="$store.pluginSettings.onModalOpen()"x-destroy="$store.pluginSettings.cleanup()">- <!-- Context toolbar: Project + Agent profile (mirrors skills list) -->- <div class="plugin-settings-scope-section">+ <!-- Context toolbar: Project + Agent profile (only when at least one scope is configurable) -->+ <div class="plugin-settings-scope-section"+ x-show="$store.pluginSettings.perProjectConfig || $store.pluginSettings.perAgentConfig"><div class="plugin-settings-scope-header"><div class="plugin-settings-scope-title">Settings scope</div><div class="plugin-settings-scope-desc">This plugin supports settings per project or agent profile.</div>@@ -24,7 +25,8 @@<span class="plugin-settings-toolbar-label">Project</span><select x-model="$store.pluginSettings.projectName"x-init="$nextTick(() => $el.value = $store.pluginSettings.projectName)"- @change="$store.pluginSettings.onScopeChanged()">+ @change="$store.pluginSettings.onScopeChanged()"+ :disabled="!$store.pluginSettings.perProjectConfig"><option value="">Global</option><template x-for="project in $store.pluginSettings.projects" :key="project.key"><option :value="project.key" x-text="project.label"></option>@@ -36,7 +38,8 @@<span class="plugin-settings-toolbar-label">Agent profile</span><select x-model="$store.pluginSettings.agentProfileKey"x-init="$nextTick(() => $el.value = $store.pluginSettings.agentProfileKey)"- @change="$store.pluginSettings.onScopeChanged()">+ @change="$store.pluginSettings.onScopeChanged()"+ :disabled="!$store.pluginSettings.perAgentConfig"><option value="">All profiles</option><template x-for="profile in $store.pluginSettings.agentProfiles" :key="profile.key"><option :value="profile.key" x-text="profile.label"></option>@@ -50,7 +53,7 @@</div>- <!-- Activation row: ON/OFF toggle + link to Advanced per-scope modal -->+ <!-- Activation row: ON/OFF toggle --><div class="plugin-settings-toolbar plugin-activation-toolbar" x-show="$store.pluginToggle"><div class="plugin-settings-toolbar-row"><div class="plugin-activation-toggle-group">@@ -63,11 +66,6 @@</label><span class="plugin-toggle-status-text" x-text="$store.pluginToggle?.statusLabel"></span></div>- <button type="button" class="button plugin-settings-toolbar-button"- @click="window.openModal?.('components/plugins/toggle/plugin-toggle-advanced.html')">- <span class="icon material-symbols-outlined">toggle_on</span>- Switch- </button></div></div></div>diff --git a/webui/components/plugins/toggle/plugin-toggle-advanced.html b/webui/components/plugins/toggle/plugin-toggle-advanced.htmlindex 6a7b839b8..209fd9ebc 100644--- a/webui/components/plugins/toggle/plugin-toggle-advanced.html+++ b/webui/components/plugins/toggle/plugin-toggle-advanced.html@@ -38,7 +38,8 @@<label class="plugin-settings-toolbar-item"><span class="plugin-settings-toolbar-label">Project</span><select x-model="$store.pluginToggle.projectName"- @change="$store.pluginToggle.onScopeChanged()">+ @change="$store.pluginToggle.onScopeChanged()"+ :disabled="!$store.pluginToggle.perProjectConfig"><option value="">Global</option><template x-for="p in $store.pluginToggle.projects" :key="p.key"><option :value="p.key" x-text="p.label"></option>@@ -49,7 +50,8 @@<label class="plugin-settings-toolbar-item"><span class="plugin-settings-toolbar-label">Agent profile</span><select x-model="$store.pluginToggle.agentProfileKey"- @change="$store.pluginToggle.onScopeChanged()">+ @change="$store.pluginToggle.onScopeChanged()"+ :disabled="!$store.pluginToggle.perAgentConfig"><option value="">All profiles</option><template x-for="a in $store.pluginToggle.agentProfiles" :key="a.key"><option :value="a.key" x-text="a.label"></option>diff --git a/webui/components/plugins/toggle/plugin-toggle-store.js b/webui/components/plugins/toggle/plugin-toggle-store.jsindex a656bf262..9f797e9d1 100644--- a/webui/components/plugins/toggle/plugin-toggle-store.js+++ b/webui/components/plugins/toggle/plugin-toggle-store.js@@ -20,6 +20,8 @@ const model = {// Status: 'enabled' | 'disabled'status: 'enabled',alwaysEnabled: false,+ perProjectConfig: true,+ perAgentConfig: true,explicitPath: null,configs: [],@@ -35,10 +37,16 @@ const model = {const pluginName = typeof plugin === 'string' ? plugin : plugin?.name;this.pluginName = pluginName;this.alwaysEnabled = typeof plugin === 'object' ? !!plugin.always_enabled : false;+ this.perProjectConfig = typeof plugin === 'object' ? !!plugin.per_project_config : true;+ this.perAgentConfig = typeof plugin === 'object' ? !!plugin.per_agent_config : true;try {await Promise.all([this.loadProjects(), this.loadAgentProfiles()]);await this.loadConfigs();+ // Auto-save ON for the default scope (Global + All profiles)+ if (!this.explicitPath && !this.alwaysEnabled && this.pluginName) {+ await this.setEnabled(true);+ }} finally {this.isLoading = false;}@@ -50,6 +58,9 @@ const model = {this.agentProfileKey = "";this.error = null;this.configs = [];+ this.perProjectConfig = true;+ this.perAgentConfig = true;+ this.alwaysEnabled = false;},async loadProjects() {@@ -212,6 +223,11 @@ const model = {async onScopeChanged() {this.calculateStatus();+ // Auto-save immediately so the displayed default state is persisted+ if (!this.explicitPath && !this.alwaysEnabled && this.pluginName) {+ await this.setEnabled(true);+ }+// Sync scope with settings store so its loadSettings picks up the right contextsettingsStore.projectName = this.projectName || "";settingsStore.agentProfileKey = this.agentProfileKey || "";