Alerts

Alerts notify you when something goes wrong — or goes quiet — with your agents. Rules are evaluated continuously against incoming run data.

---

Creating an alert rule

Go to Alerts → New rule. Every rule has:

• Name — a label for the rule (shown in notifications)
• Agent — optional. Leave blank to apply the rule to all agents in the workspace
• Condition — what triggers the alert
• Channels — where to send the notification

---

Conditions

Run failed

Fires every time a run ends with status: failed. No threshold — fires on every failure.

Error rate

Fires when the failure rate across recent runs exceeds a threshold.

Field	Description
threshold_pct	Percentage of runs that must fail to trigger (e.g. 10 = 10%)
window_runs	How many recent runs to include in the calculation (e.g. 20)

Example: threshold 10, window 20 → alert if more than 2 of the last 20 runs failed.

Run duration exceeded

Fires when a single run takes longer than the specified duration.

Field	Description
duration_ms	Threshold in milliseconds (e.g. 60000 = 1 minute)

No activity

Fires if no run completes within a given time window.

Field	Description
hours_since_last_run	Alert if no run completes within this many hours

Use this to catch agents that have gone silent — e.g. a cron-triggered agent that stopped firing.

Custom event

Fires when a run emits a specific event type.

Field	Description
event_type	The exact event type string (e.g. order.failed)

Use run.emit("order.failed", { orderId }) in your agent code, then set event_type: order.failed in the rule.

---

Channels

In-app

Always enabled. Alerts appear in the notification bell in the sidebar.

Email (Pro+)

Enter one or more recipient addresses (comma-separated). AgentOS sends an email when the rule fires.

Webhook

Enter an HTTPS URL. AgentOS sends a POST request when the rule fires.

Request body:

{
  "rule_id": "uuid",
  "rule_name": "Invoice agent failure",
  "agent_id": "uuid",
  "condition": "run_failed",
  "triggered_at": "2026-05-17T09:00:00.000Z",
  "run_id": "uuid"
}

Signature verification:

Every webhook request includes an X-AgentOS-Signature header. The value is sha256=<hmac> where <hmac> is the HMAC-SHA256 of the raw request body, signed with the secret shown when the rule was saved.

import { createHmac } from "crypto";

function verifySignature(body: string, secret: string, header: string): boolean {
  const expected = "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
  return expected === header;
}

Validate the signature before trusting the payload. Your endpoint must return a 2xx response — non-2xx responses are treated as delivery failures.

---

Alert history

Open any alert rule from the Alerts list to see its full firing history — timestamp, triggering run, and which channel was notified.