Docs contents
Alerts
Alerts notify you when something goes wrong, or goes quiet, with your agents. AgentOS checks your rules regularly against recent run data. Intelligence-finding alerts are the exception: they fire as soon as the finding is written.
Creating an alert rule
On the Alerts page, click New to open the New alert rule drawer. Every rule has:
- Name: a label for the rule, shown in notifications (up to 80 characters)
- Agent: optional. Leave it blank to apply the rule to every agent in the workspace
- Condition: what triggers the alert
- Channels: where to send the notification
Only owners and admins can create rules. The Alerts list shows when each rule last fired, and you can pause or resume a rule from the list.
To manage rules from code, use the control plane (alerts.list, alerts.create, alerts.update, alerts.delete) or the matching MCP tools (alerts_list, alerts_create, alerts_update, alerts_delete).
How often a rule fires
After a rule fires, it stays quiet for 30 minutes. If several matching runs happen in that time, or between two checks, you get one alert for the most recent one.
The Monthly budget exceeded condition fires at most once per calendar month.
Test runs are ignored by every run- and event-based condition.
Conditions
Any run fails
Fires when a run ends with status failed. There is no threshold.
Run duration exceeds threshold
Fires when a run takes longer than the threshold.
| Field | Description |
|---|---|
duration_ms | Threshold in milliseconds (e.g. 60000 = 1 minute) |
Error rate exceeds threshold
Fires when the share of failed runs among the most recent runs reaches the threshold.
| Field | Description |
|---|---|
threshold_pct | Failure percentage that triggers the alert. Default 10 |
window_runs | How many of the most recent runs to include. Default 20 |
Example: with threshold 10 and window 20, the rule fires when 2 or more of the last 20 runs failed. The rule does nothing until there are at least as many runs as the window.
Agent has no activity
Fires when no run has started within the time window. An agent that has never run also triggers it.
| Field | Description |
|---|---|
hours_since_last_run | Window in hours. Default 24 |
Use it to catch agents that have gone silent, such as a scheduled agent that stopped running.
Custom event type observed
Fires when a run emits an event of a specific type.
| Field | Description |
|---|---|
event_type | The exact event type (e.g. order.failed) |
Emit the event from your code with run.emit("order.failed", { orderId }), then set the rule's event type to order.failed. The first check looks back one hour; after that, each check looks for events since the rule last fired.
Intelligence finding escalates
Fires when an intelligence agent's finding about an agent rises in severity, for example from healthy to warn, or from warn to critical. A finding reported again at the same or a lower severity does not alert.
| Field | Description |
|---|---|
| Minimum severity | Warn or higher or Critical only |
For this condition, the rule's Agent is the agent the finding is about.
Monthly budget exceeded
Fires when estimated month-to-date spend crosses the monthly budget set in Backoffice → Usage, for the selected agent or for the whole workspace. Without a budget, the rule never fires.
Every workspace comes with a built-in Monthly budget exceeded rule that notifies in-app, so setting a workspace budget is enough to be alerted when you cross it. For a per-agent budget, create a rule with that agent selected.
Channels
In-app
Always on. Alerts appear on the Notifications page, which you open from the user menu. The menu shows a badge with the number of unread notifications.
Available on every paid plan. Enter up to 10 recipient addresses, separated by commas.
Webhook
Enter a URL (use HTTPS). AgentOS sends a POST request each time the rule fires. See Alert webhooks for the payload and retries.