Skip to main content
The Notifications system proactively monitors every agent execution and delivers alerts to the portal in real time — the bell in the top bar updates over WebSocket, no refresh needed. Failures are detected automatically, and your agent code can emit custom alerts with a single SDK call.

​
Automatic alerts

The platform watches every execution and raises an alert without any instrumentation on your side:
Alert typeTriggered whenSeverityTypical latency
Execution failureAn execution ends with an uncaught error (a throw that escapes your handler)warningseconds
Execution timeoutAn execution exceeds the runtime cap, or gets stuck in RUNNING beyond the limit — including when the runtime itself crashed mid-flightcriticalunder a minute
Connector failureA connector call fails, even if your code catches the error and the execution succeedswarningseconds
Detection is two-layered: most alerts fire from the trace pipeline within seconds, and an independent watchdog reads the execution store directly — so a worker that dies without reporting anything still produces an alert. Both staging and production are monitored; every notification carries an environment badge.

​
Grouping and deduplication

Alerts are designed to inform, not to flood:
  • The first failure of an agent notifies immediately.
  • Subsequent failures of the same agent and type within a 15-minute window increment the same notification (“12 failures in the last 15 min”) instead of creating new ones.
  • Each execution is counted once, even when detected by more than one path.
  • Within a group, severity only escalates (a critical event upgrades a warning group, never the opposite).

​
Custom alerts from the SDK

Available from @runflow-ai/sdk v1.4.1. Call sendNotification() anywhere inside an execution — no IDs required, everything is resolved from the execution context: 
import { sendNotification } from '@runflow-ai/sdk';

// Simple warning (default severity)
sendNotification('Customer record missing in CRM');

// Critical alert with details
sendNotification('Stock depleted in ERP', {
  severity: 'critical',
  body: `SKU ${sku} returned zero availability during order flow`,
});

// Deduplicate by your own key: the same document only alerts once per execution
sendNotification('Invoice validation failed', {
  severity: 'warning',
  dedupeKey: invoiceId,
});

​
Options

OptionTypeDefaultDescription
severity'warning' | 'critical''warning'Controls the notification severity; critical escalates an open alert group
bodystring—Extra detail shown in the notification body
dedupeKeystring—Distinct alerts within one execution deduplicate by this key (defaults to the title)

​
Behavior

  • Fire-and-forget — sendNotification() never throws and never blocks your agent’s execution.
  • The alert title you pass becomes the notification title in the portal, grouped per agent like automatic alerts.
  • Custom alerts appear with the type Alert in the bell and history filters.
sendNotification() is designed to run inside the Runflow runtime. Outside of it (a plain local script with no execution context), the alert is discarded server-side since there is no execution to attach it to.

​
Where notifications surface

Notification bell

Real-time badge in the top bar. Click an alert to jump straight to the affected agent.

History

Full paginated history with filters: environment, type, severity and unread-only.

Agent health

The dashboard ranks all agents by health (error rate, timeouts, connector failures), and each agent’s overview shows its health badge plus the most common errors, grouped and normalized.

Multi-tenant watchlist

Users with access to multiple tenants can pick which ones to watch — the bell aggregates alerts across all of them, tagged per tenant.

​
Health metrics

The health views are computed from real execution data over a 24h/7d window:
  • Executions and failures per agent (combining the trace layer with the execution store of record)
  • Error rate with health classification: healthy (<5%), degraded (5–20%), critical (≥20%)
  • Timeouts and stuck executions
  • Connector failures per agent
  • Most common errors, grouped by normalized message (IDs and numbers collapsed so identical failures group together)