Skip to content

Agent Zero AI framework

add banners agentic docs

Alessandro5dd40db386ac
diff --git a/AGENTS.md b/AGENTS.md
index 71374fa46..63a3fe050 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](docs/agents/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) | [Banners & Discovery](docs/agents/AGENTS.banners.md)
---
diff --git a/docs/agents/AGENTS.banners.md b/docs/agents/AGENTS.banners.md
new file mode 100644
index 000000000..b5c65f115
--- /dev/null
+++ b/docs/agents/AGENTS.banners.md
@@ -0,0 +1,95 @@
+# Creating Discovery Cards and Banners
+
+Agent Zero allows plugin developers to surface UI elements using the `banners` extension point. This allows your plugin to present information, prompts, or actionable "discovery cards" directly on the Welcome Screen without needing to inject arbitrary HTML into the frontend.
+
+## The `banners` Extension Point
+
+Banners are collected on the backend and sent to the frontend UI as an array of dictionaries. By appending to the `banners` array inside a Python extension, you can easily surface your plugin to the user.
+
+To inject a banner, you create a Python extension script hooking into `banners`.
+
+### Where to put your extension script
+
+Create a python file in your plugin's extensions folder:
+`plugins/<your_plugin>/extensions/python/banners/10_my_plugin_banner.py`
+
+*(Note: the `10_` prefix is for ordering; extensions run in alphabetical order).*
+
+## Banner Types
+
+The UI distinguishes banners primarily by the `type` property.
+
+### 1. Alert Banners (`info`, `warning`, `error`)
+These are standard top-level alerts displayed on the welcome screen.
+
+```python
+banners.append({
+ "id": "my-plugin-warning",
+ "type": "warning",
+ "priority": 90,
+ "title": "My Plugin Issue",
+ "html": "<strong>Action required:</strong> Please configure your settings.",
+ "dismissible": True,
+})
+```
+
+### 2. Discovery Cards (`hero`, `feature`)
+These are rich, interactive cards displayed in the Discovery section. They are designed to prompt the user to try new plugins or features.
+
+* `hero`: A wide, prominent card. Usually reserved for core system features (e.g., the Plugin Hub).
+* `feature`: A smaller card in a grid layout. This is the **recommended type** for plugin contributors to showcase their plugin.
+
+### Anatomy of a Discovery Card
+
+Here is an example of injecting a `feature` card for a custom plugin:
+
+```python
+from helpers.extension import Extension
+from helpers import plugins
+
+class MyPluginDiscoveryCard(Extension):
+ """Injects a discovery card for My Custom Plugin."""
+
+ async def execute(self, banners: list = [], frontend_context: dict = {}, **kwargs):
+ # 1. Condition Check
+ # Only show the discovery card if the user hasn't configured the plugin yet.
+ config = plugins.get_plugin_config("my_custom_plugin") or {}
+
+ # If the API key is already set, we don't need to advertise the setup!
+ if config.get("api_key"):
+ return
+
+ # 2. Add the Card
+ banners.append({
+ "id": "discovery-my-custom-plugin",
+ "type": "feature", # 'feature' or 'hero'
+ "title": "Connect My Service", # Card title
+ "description": "Unlock amazing capabilities by linking your account.",
+
+ # Visuals (use either thumbnail OR icon)
+ "thumbnail": "/plugins/my_custom_plugin/assets/thumb.png", # Path to image
+ "icon": "bolt", # Or a Material Symbol icon name
+
+ # Call To Action (CTA)
+ "cta_text": "Setup Now",
+ "cta_action": "open-plugin-config:my_custom_plugin", # Opens your plugin's config modal
+
+ # Behavior
+ "dismissible": True, # Let the user hide it
+ "priority": 40, # Higher numbers appear first
+ })
+```
+
+## Call To Action (CTA) Actions
+
+When a user clicks the button on a discovery card, the `cta_action` string determines what happens. The frontend currently supports the following actions:
+
+* `open-plugin-config:<plugin_folder_name>`: Automatically opens the settings modal for the specified plugin. (e.g., `open-plugin-config:_telegram_integration`).
+* `open-plugin-hub`: Opens the main Plugin Hub UI.
+* `open-url:<url>`: Opens a web link in a new browser tab. (e.g., `open-url:https://example.com/docs`).
+
+## Best Practices
+
+1. **Check Configuration First**: Always check your plugin's configuration before injecting a card. If the user has already set up your plugin, they shouldn't keep seeing a discovery card asking them to set it up.
+2. **Unique IDs**: Ensure your banner `id` is highly unique (e.g., prefix it with your plugin name) to avoid collisions with other plugins.
+3. **Use `feature` type**: Community plugins should stick to the `feature` type rather than `hero` to ensure a clean grid layout for users.
\ No newline at end of file