Agent Zero AI framework
docs: update plugin docs and skill
Alessandroc51f313d94c8
diff --git a/AGENTS.md b/AGENTS.mdindex fc30c901c..a4ee3eb8d 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -7,7 +7,7 @@ Tech Stack: Python 3.12+ | Flask | Alpine.js | LiteLLM | WebSocket (Socket.io)Dev Server: python run_ui.py (runs on http://localhost:50001 by default)Run Tests: pytest (standard) or pytest tests/test_name.py (file-scoped)Documentation: README.md | docs/-Frontend Deep Dives: [Component System](docs/agents/AGENTS.components.md) | [Modal System](docs/agents/AGENTS.modals.md) | [Plugin Architecture](AGENTS.plugins.md)+Frontend Deep Dives: [Component System](docs/agents/AGENTS.components.md) | [Modal System](docs/agents/AGENTS.modals.md) | [Plugin Architecture](docs/agents/AGENTS.plugins.md)---@@ -98,7 +98,7 @@ Key Files:- python/helpers/api.py: Base class for all API endpoints.- docs/agents/AGENTS.components.md: Deep dive into the frontend component architecture.- docs/agents/AGENTS.modals.md: Guide to the stacked modal system.-- AGENTS.plugins.md: Comprehensive guide to the full-stack plugin system.+- docs/agents/AGENTS.plugins.md: Comprehensive guide to the full-stack plugin system.---diff --git a/AGENTS.plugins.md b/docs/agents/AGENTS.plugins.mdsimilarity index 98%rename from AGENTS.plugins.mdrename to docs/agents/AGENTS.plugins.mdindex 1aa637581..bfc9c26a7 100644--- a/AGENTS.plugins.md+++ b/docs/agents/AGENTS.plugins.md@@ -24,6 +24,7 @@ Each plugin lives in usr/plugins/<plugin_name>/.```textusr/plugins/<plugin_name>/├── plugin.yaml # Required: Title, version, settings + activation metadata+├── initialize.py # Optional: one-time setup script (dependencies, models, etc.)├── default_config.yaml # Optional: fallback settings defaults├── README.md # Optional: shown in Plugin List UI├── LICENSE # Optional: shown in Plugin List UIdiff --git a/docs/developer/plugins.md b/docs/developer/plugins.mdindex df4c8ce38..e3abad43e 100644--- a/docs/developer/plugins.md+++ b/docs/developer/plugins.md@@ -49,6 +49,7 @@ Field reference:```textusr/plugins/<plugin_name>/├── plugin.yaml+├── initialize.py # optional one-time setup script├── default_config.yaml # optional defaults├── README.md # optional, shown in Plugin List UI├── LICENSE # optional, shown in Plugin List UI@@ -66,6 +67,36 @@ usr/plugins/<plugin_name>/└── ...```+## Plugin Initialization (`initialize.py`)++Plugins can include an optional `initialize.py` at the plugin root for one-time setup such as installing dependencies, downloading models, or preparing databases.++- Triggered manually via the **Init** button in the Plugin List UI — never runs automatically+- Execution is tracked in `usr/plugins/<plugin_name>/init_exec.json` (timestamp + exit code)+- The modal streams output in real time and shows success/failure on completion++```python+import subprocess+import sys++def main():+ print("Installing dependencies...")+ result = subprocess.run(+ [sys.executable, "-m", "pip", "install", "requests==2.31.0"],+ text=True,+ )+ if result.returncode != 0:+ print("ERROR: Installation failed")+ return result.returncode+ print("Done.")+ return 0++if __name__ == "__main__":+ sys.exit(main())+```++Return `0` on success, non-zero on failure. Print progress for user feedback. Use `sys.executable` for pip commands.+## Settings ResolutionPlugin settings are resolved by scope. Higher priority overrides lower priority:@@ -191,6 +222,6 @@ A built-in **Plugin Marketplace** (always-active plugin) will allow users to bro## See Also-- `AGENTS.plugins.md` for full architecture details+- `docs/agents/AGENTS.plugins.md` for full architecture details- `skills/a0-create-plugin/SKILL.md` for plugin authoring workflow (agent-facing)- `plugins/README.md` for core plugin directory overviewdiff --git a/plugins/README.md b/plugins/README.mdindex f2f1c21be..50708bcea 100644--- a/plugins/README.md+++ b/plugins/README.md@@ -11,7 +11,7 @@ This directory contains the system-level plugins bundled with Agent Zero.For detailed guides on how to create, extend, or configure plugins, refer to:-- [`AGENTS.plugins.md`](../AGENTS.plugins.md): Full-stack plugin architecture, manifest format, extension points, and Plugin Index submission.+- [`docs/agents/AGENTS.plugins.md`](../AGENTS.plugins.md): Full-stack plugin architecture, manifest format, extension points, and Plugin Index submission.- [`docs/developer/plugins.md`](../docs/developer/plugins.md): Human-facing developer guide covering the full plugin lifecycle.- [`AGENTS.md`](../AGENTS.md): Main framework guide and backend context.- [`skills/a0-create-plugin/SKILL.md`](../skills/a0-create-plugin/SKILL.md): Agent-facing authoring workflow (local and community plugins).@@ -41,6 +41,10 @@ per_agent_config: falsealways_enabled: false```+## Plugin Initialization (`initialize.py`)++Plugins can include an optional `initialize.py` at the plugin root for one-time setup such as installing dependencies or downloading models. Users trigger it via the **Init** button in the Plugin List UI. The script should return `0` on success and print progress messages for user feedback.+## Plugin Index & Community SharingThe **Plugin Index** at https://github.com/agent0ai/a0-plugins is the community-maintained registry of plugins available to all Agent Zero users.diff --git a/skills/a0-create-plugin/SKILL.md b/skills/a0-create-plugin/SKILL.mdindex 6318755fe..eeb71aba1 100644--- a/skills/a0-create-plugin/SKILL.md+++ b/skills/a0-create-plugin/SKILL.md@@ -12,7 +12,7 @@ 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.yaml, settings system, Plugin Index)+- /a0/docs/agents/AGENTS.plugins.md (Extension points, plugin.yaml, settings system, Plugin Index)---@@ -168,6 +168,7 @@ save_plugin_config(```/a0/usr/plugins/<name>/plugin.yaml # Required manifest+ initialize.py # Optional one-time setup scriptdefault_config.yaml # Optional default settings fallbackREADME.md # Optional, shown in Plugin List UILICENSE # Optional, shown in Plugin List UI@@ -184,6 +185,32 @@ save_plugin_config(my-store.js # Alpine stores```+## Plugin Initialization Script (`initialize.py`)++If your plugin requires one-time setup (e.g., installing dependencies, downloading models), add an `initialize.py` at the plugin root:++```python+import subprocess+import sys++def main():+ print("Installing plugin dependencies...")+ result = subprocess.run(+ [sys.executable, "-m", "pip", "install", "requests==2.31.0"],+ text=True,+ )+ if result.returncode != 0:+ print("ERROR: Installation failed")+ return result.returncode+ print("Done.")+ return 0++if __name__ == "__main__":+ sys.exit(main())+```++Users trigger it via the **Init** button in the Plugin List UI. Return `0` on success, non-zero on failure.+---## Community Plugin: GitHub Repo + Plugin Index Submission