| 1 | # Agent Zero Notifications |
| 2 | |
| 3 | Quick guide for using the notification system in Agent Zero. |
| 4 | |
| 5 | > [!TIP] |
| 6 | > Notifications pair well with scheduled tasks. See [Tasks & Scheduling](../guides/usage.md#tasks-and-scheduling) for automation patterns. |
| 7 | |
| 8 | ## Backend Usage |
| 9 | |
| 10 | Use `AgentNotification` helper methods anywhere in your Python code: |
| 11 | |
| 12 | ```python |
| 13 | from helpers.notification import AgentNotification |
| 14 | |
| 15 | # Basic notifications |
| 16 | AgentNotification.info("Operation completed") |
| 17 | AgentNotification.success("File saved successfully", "File Manager") |
| 18 | AgentNotification.warning("High CPU usage detected", "System Monitor") |
| 19 | AgentNotification.error("Connection failed", "Network Error") |
| 20 | AgentNotification.progress("Processing files...", "Task Progress") |
| 21 | |
| 22 | # With details and custom display time |
| 23 | AgentNotification.info( |
| 24 | message="System backup completed", |
| 25 | title="Backup Manager", |
| 26 | detail="<p>Backup size: <strong>2.4 GB</strong></p>", |
| 27 | display_time=8 # seconds |
| 28 | ) |
| 29 | |
| 30 | # Grouped notifications (replaces previous in same group) |
| 31 | AgentNotification.progress("Download: 25%", "File Download", group="download-status") |
| 32 | AgentNotification.progress("Download: 75%", "File Download", group="download-status") # Replaces previous |
| 33 | AgentNotification.progress("Download: Complete!", "File Download", group="download-status") # Replaces previous |
| 34 | ``` |
| 35 | |
| 36 | ## Frontend Usage |
| 37 | |
| 38 | Use the notification store in Alpine.js components: |
| 39 | |
| 40 | ```javascript |
| 41 | // Basic notifications |
| 42 | $store.notificationStore.info("User logged in") |
| 43 | $store.notificationStore.success("Settings saved", "Configuration") |
| 44 | $store.notificationStore.warning("Session expiring soon") |
| 45 | $store.notificationStore.error("Failed to load data") |
| 46 | |
| 47 | // With grouping |
| 48 | $store.notificationStore.info("Connecting...", "Status", "", 3, "connection") |
| 49 | $store.notificationStore.success("Connected!", "Status", "", 3, "connection") // Replaces previous |
| 50 | |
| 51 | // Frontend notifications with backend persistence (new feature!) |
| 52 | $store.notificationStore.frontendError("Database timeout", "Connection Error") |
| 53 | $store.notificationStore.frontendWarning("High memory usage", "Performance") |
| 54 | $store.notificationStore.frontendInfo("Cache cleared", "System") |
| 55 | ``` |
| 56 | |
| 57 | ## Frontend Notifications with Backend Sync |
| 58 | |
| 59 | **New Feature**: Frontend notifications now automatically sync to the backend when connected, providing persistent history and cross-session availability. |
| 60 | |
| 61 | ### How it Works: |
| 62 | - **Backend Connected**: Notifications are sent to backend and appear via polling (persistent) |
| 63 | - **Backend Disconnected**: Notifications show as frontend-only toasts (temporary) |
| 64 | - **Automatic Fallback**: Seamless degradation when backend is unavailable |
| 65 | |
| 66 | ### Global Functions: |
| 67 | ```javascript |
| 68 | // These functions automatically try backend first, then fallback to frontend-only |
| 69 | toastFrontendError("Server unreachable", "Connection Error") |
| 70 | toastFrontendWarning("Slow connection detected") |
| 71 | toastFrontendInfo("Reconnected successfully") |
| 72 | ``` |
| 73 | |
| 74 | ## HTML Usage |
| 75 | |
| 76 | ```html |
| 77 | <button @click="$store.notificationStore.success('Task completed!')"> |
| 78 | Complete Task |
| 79 | </button> |
| 80 | |
| 81 | <button @click="$store.notificationStore.warning('Progress: 50%', 'Upload', '', 5, 'upload-progress')"> |
| 82 | Update Progress |
| 83 | </button> |
| 84 | |
| 85 | <!-- Frontend notifications with backend sync --> |
| 86 | <button @click="$store.notificationStore.frontendError('Connection failed', 'Network')"> |
| 87 | Report Connection Error |
| 88 | </button> |
| 89 | ``` |
| 90 | |
| 91 | ## Notification Groups |
| 92 | |
| 93 | Groups ensure only the latest notification from each group is shown in the toast stack: |
| 94 | |
| 95 | ```python |
| 96 | # Progress updates - each new notification replaces the previous one |
| 97 | AgentNotification.info("Starting backup...", group="backup-status") |
| 98 | AgentNotification.progress("Backup: 30%", group="backup-status") # Replaces previous |
| 99 | AgentNotification.progress("Backup: 80%", group="backup-status") # Replaces previous |
| 100 | AgentNotification.success("Backup complete!", group="backup-status") # Replaces previous |
| 101 | |
| 102 | # Connection status - only show current state |
| 103 | AgentNotification.warning("Disconnected", group="network") |
| 104 | AgentNotification.info("Reconnecting...", group="network") # Replaces previous |
| 105 | AgentNotification.success("Connected", group="network") # Replaces previous |
| 106 | ``` |
| 107 | |
| 108 | ## Parameters |
| 109 | |
| 110 | All notification methods support these parameters: |
| 111 | |
| 112 | - `message` (required): Main notification text |
| 113 | - `title` (optional): Notification title |
| 114 | - `detail` (optional): HTML content for expandable details |
| 115 | - `display_time` (optional): Toast display duration in seconds (default: 3) |
| 116 | - `group` (optional): Group identifier for replacement behavior |
| 117 | |
| 118 | ## Types |
| 119 | |
| 120 | - **info** (ℹ️): General information |
| 121 | - **success** (✅): Successful operations |
| 122 | - **warning** (⚠️): Important alerts |
| 123 | - **error** (❌): Error conditions |
| 124 | - **progress** (⏳): Ongoing operations |
| 125 | |
| 126 | ## Behavior |
| 127 | |
| 128 | - **Toast Display**: Notifications appear as toasts in the bottom-right corner |
| 129 | - **Persistent History**: All notifications (including synced frontend ones) are stored in notification history |
| 130 | - **Modal Access**: Full history accessible via the bell icon |
| 131 | - **Auto-dismiss**: Toasts automatically disappear after `display_time` |
| 132 | - **Group Replacement**: Notifications with the same group replace previous ones immediately |
| 133 | - **Backend Sync**: Frontend notifications automatically sync to backend when connected |