Skip to content

Agent Zero AI framework

update docs

Alessandro618179fa5bb2
diff --git a/plugins/README.md b/plugins/README.md
index a664f6b40..4bac307e3 100644
--- a/plugins/README.md
+++ b/plugins/README.md
@@ -6,9 +6,9 @@ This directory contains default plugins shipped with Agent Zero.
Agent Zero uses a convention-over-configuration plugin model:
-- `plugin.json` is not used by runtime discovery.
- Runtime capabilities are discovered from directory structure.
-- Backend owns discovery and routing; frontend consumes resolved URLs.
+- Backend owns discovery, routing, and static asset serving.
+- Frontend uses explicit `x-extension` breakpoints plus the standard `x-component` loader.
## Directory Conventions
@@ -16,39 +16,88 @@ Each plugin lives in `plugins/<plugin_id>/` (or `usr/plugins/<plugin_id>/` for o
Capability discovery is based on these paths:
-- `api/*.py` - API handlers (`ApiHandler` subclasses), exposed as `/plugins/{plugin_id}/{handler_name}`
-- `tools/*.py` - Agent tools (`Tool` subclasses)
-- `helpers/*.py` - Shared Python helpers
-- `extensions/backend/{extension_point}/*.py` - Backend lifecycle extensions
-- `extensions/frontend/**/*.html` - Frontend UI components (auto-injected via `<meta name="plugin-target">`)
-- `prompts/**/*.md` - Prompt templates
-- `agents/` - Agent profiles
-- `extensions/frontend/` - Frontend UI assets and auto-injected components
+- `api/*.py` - API handlers (`ApiHandler` subclasses), exposed under `/api/plugins/<plugin_id>/<handler>`
+- `tools/*.py` - agent tools (`Tool` subclasses)
+- `helpers/*.py` - shared Python helpers
+- `extensions/python/<extension_point>/*.py` - backend lifecycle extensions
+- `extensions/webui/<extension_point>/*` - WebUI extension assets (HTML/JS)
+- `webui/**` - full plugin-owned UI pages/components (loaded directly by path)
+- `prompts/**/*.md` - prompt templates
+- `agents/` - agent profiles
-## Frontend Auto-Injection (PoC)
+## Frontend Extensions
-Plugins can inject HTML components into the core UI. Place components under `extensions/frontend/` and declare the injection target with a `<meta>` tag:
+### HTML insertion via breakpoints
+
+Core UI defines insertion points like:
```html
-<meta name="plugin-target" content=".quick-actions-dropdown">
+<x-extension id="sidebar-quick-actions-main-start"></x-extension>
```
-Components without the meta tag (e.g. modals, dashboards) are standalone and not auto-injected.
-
Resolution flow:
-TODO update:ú
+1. `webui/js/extensions.js` finds `x-extension` nodes.
+2. It calls `/api/load_webui_extensions` with the extension point and HTML filters.
+3. Backend returns matching files from `plugins/*/extensions/webui/<extension_point>/`.
+4. `extensions.js` injects returned entries as `<x-component path="...">`.
+5. `components.js` loads each component using the standard component pipeline.
+
+Baseline extension template (project convention):
+
+```html
+<div x-data>
+ <button
+ x-move-after=".config-button#dashboard"
+ class="config-button"
+ id="my-plugin-button"
+ @click="openModal('../plugins/my-plugin/webui/my-modal.html')"
+ title="My Plugin">
+ <span class="material-symbols-outlined">extension</span>
+ </button>
+</div>
+```
+
+Required baseline for HTML UI extensions in this repository:
+- include a root `x-data` scope
+- include one explicit `x-move-*` placement directive
+
+### JS hook extensions
+
+JS hooks are loaded from the same extension point structure:
+
+`plugins/<plugin_id>/extensions/webui/<extension_point>/*.js`
+
+Runtime code calls:
+
+`callJsExtensions("<extension_point>", ...args)`
+
+Example:
+
+`set_messages_before_loop` and `set_messages_after_loop` in `webui/js/messages.js`.
+
+### Fine placement helpers
+
+`initFw.js` provides Alpine move directives for plugin markup:
+
+- `x-move-to-start`
+- `x-move-to-end`
+- `x-move-to`
+- `x-move-before`
+- `x-move-after`
+
+## Plugin Author Flow
-1. The backend parses `<meta name="plugin-target">` from each component HTML at scan time.
-2. `/plugins_resolve` returns component URLs with their target selectors.
-3. TODO REM: `plugins.js` (loaded globally) creates `<x-component>` elements at the declared target selectors.
-4. The standard `components.js` MutationObserver handles loading automatically.
-5. A MutationObserver in `plugins.js` retries for targets that appear after initial page render.
+1. Pick an existing core breakpoint ID (`<x-extension id="...">`).
+2. Add an HTML/JS extension under `extensions/webui/<extension_point>/`.
+3. For HTML UI entries, use the baseline pattern: root `x-data` plus one explicit `x-move-*` directive.
+4. Put complete plugin pages/components in `webui/` and open them directly by path.
## Routes
- Plugin static assets: `GET /plugins/<plugin_id>/<path>`
-- Plugin APIs: `/plugins/<plugin_id>/<handler>`
+- Plugin APIs: `POST /api/plugins/<plugin_id>/<handler>`
+- WebUI extension discovery: `POST /api/load_webui_extensions`
## Notes