add banners agentic docs
Alessandro committed
Mar 31, 2026 at 21:23 UTC
5dd40db386ac3e1c047be86a900a13963b2a6ebc
2 files changed
+96
-1
AGENTS.md
+1
-1
@@ -7,7 +7,7 @@ Tech Stack: Python 3.12+ | Flask | Alpine.js | LiteLLM | WebSocket (Socket.io)
7
Dev Server: python run_ui.py (runs on http://localhost:50001 by default)
8
Run Tests: pytest (standard) or pytest tests/test_name.py (file-scoped)
9
Documentation: README.md | docs/
10
-Frontend Deep Dives: [Component System](docs/agents/AGENTS.components.md) | [Modal System](docs/agents/AGENTS.modals.md) | [Plugin Architecture](docs/agents/AGENTS.plugins.md)
10
+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)
11
12
---
13
docs/agents/AGENTS.banners.md
new
+95
@@ -0,0 +1,95 @@
1
+# Creating Discovery Cards and Banners
2
+
3
+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.
4
+
5
+## The `banners` Extension Point
6
+
7
+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.
8
+
9
+To inject a banner, you create a Python extension script hooking into `banners`.
10
+
11
+### Where to put your extension script
12
+
13
+Create a python file in your plugin's extensions folder:
14
+`plugins/<your_plugin>/extensions/python/banners/10_my_plugin_banner.py`
15
+
16
+*(Note: the `10_` prefix is for ordering; extensions run in alphabetical order).*
17
+
18
+## Banner Types
19
+
20
+The UI distinguishes banners primarily by the `type` property.
21
+
22
+### 1. Alert Banners (`info`, `warning`, `error`)
23
+These are standard top-level alerts displayed on the welcome screen.
24
+
25
+```python
26
+banners.append({
27
+ "id": "my-plugin-warning",
28
+ "type": "warning",
29
+ "priority": 90,
30
+ "title": "My Plugin Issue",
31
+ "html": "<strong>Action required:</strong> Please configure your settings.",
32
+ "dismissible": True,
33
+})
34
+```
35
+
36
+### 2. Discovery Cards (`hero`, `feature`)
37
+These are rich, interactive cards displayed in the Discovery section. They are designed to prompt the user to try new plugins or features.
38
+
39
+* `hero`: A wide, prominent card. Usually reserved for core system features (e.g., the Plugin Hub).
40
+* `feature`: A smaller card in a grid layout. This is the **recommended type** for plugin contributors to showcase their plugin.
41
+
42
+### Anatomy of a Discovery Card
43
+
44
+Here is an example of injecting a `feature` card for a custom plugin:
45
+
46
+```python
47
+from helpers.extension import Extension
48
+from helpers import plugins
49
+
50
+class MyPluginDiscoveryCard(Extension):
51
+ """Injects a discovery card for My Custom Plugin."""
52
+
53
+ async def execute(self, banners: list = [], frontend_context: dict = {}, **kwargs):
54
+ # 1. Condition Check
55
+ # Only show the discovery card if the user hasn't configured the plugin yet.
56
+ config = plugins.get_plugin_config("my_custom_plugin") or {}
57
+
58
+ # If the API key is already set, we don't need to advertise the setup!
59
+ if config.get("api_key"):
60
+ return
61
+
62
+ # 2. Add the Card
63
+ banners.append({
64
+ "id": "discovery-my-custom-plugin",
65
+ "type": "feature", # 'feature' or 'hero'
66
+ "title": "Connect My Service", # Card title
67
+ "description": "Unlock amazing capabilities by linking your account.",
68
+
69
+ # Visuals (use either thumbnail OR icon)
70
+ "thumbnail": "/plugins/my_custom_plugin/assets/thumb.png", # Path to image
71
+ "icon": "bolt", # Or a Material Symbol icon name
72
+
73
+ # Call To Action (CTA)
74
+ "cta_text": "Setup Now",
75
+ "cta_action": "open-plugin-config:my_custom_plugin", # Opens your plugin's config modal
76
+
77
+ # Behavior
78
+ "dismissible": True, # Let the user hide it
79
+ "priority": 40, # Higher numbers appear first
80
+ })
81
+```
82
+
83
+## Call To Action (CTA) Actions
84
+
85
+When a user clicks the button on a discovery card, the `cta_action` string determines what happens. The frontend currently supports the following actions:
86
+
87
+* `open-plugin-config:<plugin_folder_name>`: Automatically opens the settings modal for the specified plugin. (e.g., `open-plugin-config:_telegram_integration`).
88
+* `open-plugin-hub`: Opens the main Plugin Hub UI.
89
+* `open-url:<url>`: Opens a web link in a new browser tab. (e.g., `open-url:https://example.com/docs`).
90
+
91
+## Best Practices
92
+
93
+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.
94
+2. **Unique IDs**: Ensure your banner `id` is highly unique (e.g., prefix it with your plugin name) to avoid collisions with other plugins.
95
+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