Skip to content

Agent Zero AI framework

update docs, skill and enhance activation model

Alessandro8639069104a4
diff --git a/AGENTS.md b/AGENTS.md
index 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.md
index cf3b9fd24..76aac112a 100644
--- a/AGENTS.plugins.md
+++ b/AGENTS.plugins.md
@@ -23,12 +23,12 @@ Each plugin lives in usr/plugins/<plugin_name>/.
```text
usr/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 asy
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)
+
+## 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.md
index 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.md
new file mode 100644
index 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 workflow
diff --git a/plugins/README.md b/plugins/README.md
index 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.yaml
index 3c43c4a29..38a20286e 100644
--- a/plugins/memory/plugin.yaml
+++ b/plugins/memory/plugin.yaml
@@ -4,4 +4,4 @@ version: 1.0.0
settings_sections:
- agent
per_project_config: true
-per_agent_config: false
\ No newline at end of file
+per_agent_config: true
\ No newline at end of file
diff --git a/python/api/plugins.py b/python/api/plugins.py
index 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.md
index 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 profile
api/ # API Handlers (ApiHandler base class)
tools/ # Tool subclasses
extensions/
diff --git a/webui/components/plugins/list/pluginListStore.js b/webui/components/plugins/list/pluginListStore.js
index 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.js
index 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.html
index 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.html
index 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.js
index 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 context
settingsStore.projectName = this.projectName || "";
settingsStore.agentProfileKey = this.agentProfileKey || "";