Alerting

What is Alerting?

Alerting lets you set up automatic notifications when something important happens with your voice AI agents. Instead of manually checking dashboards, you define rules — and EfficientAI will notify you via Slack, email, or both when those rules are triggered.

Think of it as a smoke detector for your voice AI operations. You tell it what to watch (e.g., "error rate is above 10%"), and it will ring the alarm when something goes wrong.

Quick Example

"If the average latency of my Customer Support Agent exceeds 3 seconds over the last 30 minutes, send a Slack notification to #ops-alerts."

That's it — one alert rule, and you'll never miss a latency spike again.

Key Concepts

Alert

An Alert is a monitoring rule. It defines:

• What to measure (metric + aggregation)
• When to fire (threshold + operator)
• How far back to look (time window)
• Who to notify (emails + webhooks)
• How often to notify (frequency / cooldown)

Alert History

Every time an alert's condition is met and fires, an Alert History record is created. This gives you a full audit trail of when alerts were triggered, what the value was, and whether notifications were sent.

Setting Up an Alert

Step 1: Navigate to Alerts

From the sidebar, go to Alerting > Alerts. You'll see a list of all configured alerts.

Step 2: Create a New Alert

Click Create Alert and fill in the following:

Basic Information

Metric Condition

This is the core of your alert — the rule that determines when it fires.

Example: Average of Latency > 3 over a 30 minute window means: "If the average latency across all calls in the last 30 minutes exceeds 3 seconds, fire the alert."

Agent Selection

Choose which agents this alert applies to:

• All Agents — monitors every agent in your organization (default)
• Specific Agents — select one or more agents to scope the alert

Notification Settings

You must configure at least one email or webhook for notifications to work.

Step 3: Save

Click Create Alert. Your alert is now Active and will be evaluated automatically.

Available Metrics

Aggregations

Aggregations determine how metric values are combined over the time window:

Operators

Notification Channels

Slack Webhooks

EfficientAI sends rich Slack messages using Block Kit formatting. Each notification includes:

• Alert name and severity
• The triggered metric value vs. the threshold
• Timestamp and agent scope

To set up a Slack webhook:

1. Go to your Slack workspace's Apps settings
2. Create or select an Incoming Webhook app
3. Choose the channel to post to
4. Copy the webhook URL (it looks like https://hooks.slack.com/services/T.../B.../xxx)
5. Paste it in the alert's Webhook field

Email Notifications

Email alerts are sent as rich HTML emails containing:

• Alert name and description
• Triggered value, threshold, and operator
• Metric type, aggregation, and time window
• Agent scope information
• Timestamp

Requirements: Email notifications require SMTP to be configured in your EfficientAI deployment. See the Configuration Reference for SMTP settings.

Notification Frequency

The notification frequency controls how often you are re-notified when an alert condition remains true. This prevents notification fatigue.

If an alert fires and you were already notified within the cooldown period, the alert will still be evaluated (and recorded in history) but no new notification will be sent.

Alert Lifecycle

Statuses

You can Pause and Resume alerts at any time from the alert detail page.

Alert History Statuses

Each alert history entry progresses through:

Managing Alerts

Viewing Alert Details

Click on any alert in the list to open its Detail Page. Here you'll see:

• Metric Condition — the full rule (aggregation, metric, operator, threshold, time window)
• Agent Scope — which agents are monitored
• Notification Config — email recipients and webhooks
• Recent Alert History — the last 10 triggered events
• Metadata — created/updated timestamps and total trigger count

Editing an Alert

From the alert detail page, click the Edit button. This switches to an inline edit form where you can modify any field:

• Basic information (name, description)
• Metric condition (metric, aggregation, operator, threshold, time window)
• Agent selection
• Notification settings (frequency, emails, webhooks)

Click Save Changes to apply, or Cancel to discard.

Pausing / Resuming

Click the Pause button on the detail page to temporarily stop an alert from being evaluated. Click Resume to reactivate it. Pausing does not delete any history.

Deleting an Alert

Click Delete on the detail page. This permanently removes the alert and all its history. This action cannot be undone.

Testing & Debugging

Trigger (Manual Evaluation)

The Trigger button on the alert detail page manually evaluates the alert right now, regardless of the automatic schedule. This is useful to:

• Verify your alert condition is configured correctly
• Check if a threshold is currently being breached
• Debug why an alert isn't firing

If the condition is met, a real notification is sent and an alert history record is created (just like an automatic evaluation). Cooldown rules still apply.

Test Notification

The Test Notification button sends a sample notification to all configured channels (emails and webhooks) without evaluating the alert condition. This is useful to:

• Verify that your Slack webhook URL is correct
• Verify that email delivery is working
• Preview what the notification looks like

Test notifications are clearly labeled with a [TEST] prefix and use placeholder values. They do not create alert history records and ignore cooldown rules.

Evaluate All

From the alerts list page, the Evaluate All button triggers evaluation of every active alert in your organization at once. The results banner shows:

• How many alerts were evaluated
• How many triggered
• How many were within cooldown
• How many had errors

Automatic Evaluation

Alerts are automatically evaluated every 5 minutes by a Celery Beat schedule (evaluate_alerts, routed to the platform queue). You do not need to manually trigger evaluations — they run continuously as long as Beat and a platform queue worker are running.

The evaluation cycle:

1. Fetches all active alerts for the organization
2. For each alert, computes the metric over the configured time window
3. Compares the computed value against the threshold
4. If the condition is met and the cooldown has elapsed, sends notifications
5. Records the result in alert history

API Reference

All alert endpoints are under /api/v1/alerts and require authentication via API key.

Alerts

Alert History

Create Alert — Request Body

{
  "name": "High Error Rate",
  "description": "Fires when error rate exceeds 10%",
  "metric_type": "error_rate",
  "aggregation": "avg",
  "operator": ">",
  "threshold_value": 10,
  "time_window_minutes": 60,
  "agent_ids": ["uuid-1", "uuid-2"],
  "notify_frequency": "hourly",
  "notify_emails": ["ops@company.com"],
  "notify_webhooks": ["https://hooks.slack.com/services/..."]
}

Alert Response

{
  "id": "uuid",
  "organization_id": "uuid",
  "name": "High Error Rate",
  "description": "Fires when error rate exceeds 10%",
  "metric_type": "error_rate",
  "aggregation": "avg",
  "operator": ">",
  "threshold_value": 10.0,
  "time_window_minutes": 60,
  "agent_ids": ["uuid-1", "uuid-2"],
  "notify_frequency": "hourly",
  "notify_emails": ["ops@company.com"],
  "notify_webhooks": ["https://hooks.slack.com/services/..."],
  "status": "active",
  "created_at": "2026-02-15T10:00:00Z",
  "updated_at": "2026-02-15T10:00:00Z"
}

Configuration

SMTP Settings (for Email Notifications)

To enable email notifications, configure the following in your config.yml or environment variables:

smtp:
  host: "smtp.gmail.com"
  port: 587
  username: "your-email@gmail.com"
  password: "your-app-password"
  from_email: "alerts@yourcompany.com"
  from_name: "EfficientAI Alerts"
  use_tls: true

Or via environment variables:

Celery Workers

Alert evaluation runs as a Celery Beat periodic task on the platform queue. Beat only enqueues tasks — you must also run a worker that consumes platform.

Recommended:

eai beat --config config.yml

Or run Beat and the platform worker separately:

# Worker for alert evaluation (and other platform tasks)
celery -A app.workers.celery_app worker --queues=platform --pool=threads --loglevel=info

# Scheduler (single replica)
celery -A app.workers.celery_app beat --loglevel=info

A default-queue worker does not process evaluate_alerts.

Common Patterns

Monitor Error Rate Spikes

Metric: Error Rate | Aggregation: Average | Operator: > | Threshold: 5 | Window: 30 min

Alert when the average error rate exceeds 5% in the last 30 minutes.

Detect Call Volume Drops

Metric: Number of Calls | Aggregation: Count | Operator: < | Threshold: 10 | Window: 60 min

Alert when fewer than 10 calls are received in the last hour (possible outage).

Track High Latency

Metric: Latency | Aggregation: Max | Operator: > | Threshold: 5 | Window: 15 min

Alert when any single call has latency above 5 seconds in the last 15 minutes.

Monitor Success Rate

Metric: Success Rate | Aggregation: Average | Operator: < | Threshold: 90 | Window: 60 min

Alert when the average success rate drops below 90% in the last hour.