Alerts

Get notified by email or webhook when your agents breach a cost, latency, failure rate, or inactivity threshold.

Alerts notify you when a metric on one of your agents or services crosses a threshold. AgentVista evaluates each active alert on a rolling basis and fires a notification through your chosen delivery channel when the condition is met.

A cooldown_minutes setting (default: 60) controls the minimum time between repeated firings of the same alert. This prevents notification floods when a condition persists.

An alert can target either a specific agent (by agent_id) or a named service (by target_service). You must provide at least one. Latency and cost alerts are commonly targeted at a target_service to monitor infrastructure services that are not themselves AI agents.

Alert types

failure_rate — fires when failure rate exceeds a fraction

The failure_rate alert fires when the fraction of failed runs for the target exceeds the threshold.

The threshold is a decimal fraction from 0.0 to 1.0. For example, a threshold of 0.20 fires when more than 20% of runs fail.

Start with a threshold of 0.10 (10%) for production agents. A threshold that is too tight — such as 0.01 — will fire on normal statistical variation and create alert fatigue.

inactivity — fires when an agent has no runs for N hours

The inactivity alert fires when the target has not received any runs for longer than the threshold number of hours.

For example, a threshold of 24.0 fires if no runs are received for 24 hours. Use this alert to catch silent failures where an agent has stopped running entirely.

cost_threshold — fires when daily cost exceeds a USD amount

The cost_threshold alert fires when the target’s daily cost exceeds the threshold value in USD.

For example, a threshold of 50.00 fires when daily spend exceeds $50. Use this alert to catch runaway costs caused by retry loops or unexpectedly high traffic.

Set your cost threshold slightly above your expected daily budget, not at the hard limit. This gives you time to respond before spend becomes a problem.

latency_threshold — fires when p95 latency exceeds N milliseconds

The latency_threshold alert fires when the p95 latency for the target exceeds the threshold value in milliseconds.

For example, a threshold of 5000 fires when the 95th percentile of run durations exceeds 5,000 ms (5 seconds).

composite — custom combination of conditions

The composite alert type lets you combine AI and infrastructure conditions into a single rule. Use this when you only want to be alerted if multiple conditions are true simultaneously — for example, if your agent’s failure rate is high AND your database connection pool is saturated.

Composite alerts require a composite_config object. The threshold field is not used for composite alerts.

Example composite_config:

{
  "operator": "and",
  "conditions": [
    {
      "source": "ai",
      "type": "failure_rate",
      "threshold": 0.20
    },
    {
      "source": "infra",
      "type": "metric_threshold",
      "metric_name": "db.connection_pool.utilization",
      "operator": "gte",
      "value": 0.90
    }
  ]
}

The operator field controls how conditions combine: "and" fires only when all conditions are met; "or" fires when any condition is met. A composite alert must include at least one "ai" condition and at least one "infra" condition.

Alert channels

Channel	Behavior
email	Sends a notification to your registered email address (default)
webhook	Sends an HTTP POST to the webhook_url you configure
both	Sends email and webhook simultaneously

When using webhook or both, you must provide a webhook_url.

Creating an alert

UI

1. Open alert settings

   Go to Settings → Alerts and click Create Alert.

2. Choose the alert type

   Select one of: failure_rate, inactivity, cost_threshold, latency_threshold, or composite.

3. Set the target

   Select an agent from the dropdown, or enter a service name in the Target service field for infrastructure alerts.

4. Set the threshold

   Enter the threshold value appropriate for the alert type you selected. For composite alerts, configure the composite_config JSON instead.

5. Choose a delivery channel

   Select email, webhook, or both. If you select webhook or both, paste your webhook URL.

6. Save

   Click Create. The alert becomes active immediately.

API

Send a POST to /api/v1/alerts with a JSON body:

{
  "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "failure_rate",
  "threshold": 0.20,
  "cooldown_minutes": 60,
  "channel": "webhook",
  "webhook_url": "https://your-service.example.com/hooks/agentvista"
}

For a composite alert targeting a service (not an agent):

{
  "target_service": "payments-api",
  "type": "composite",
  "cooldown_minutes": 30,
  "channel": "email",
  "composite_config": {
    "operator": "and",
    "conditions": [
      {
        "source": "ai",
        "type": "failure_rate",
        "threshold": 0.15
      },
      {
        "source": "infra",
        "type": "metric_threshold",
        "metric_name": "http.server.error_rate",
        "operator": "gte",
        "value": 0.05
      }
    ]
  }
}

A successful response returns HTTP 201 with the created alert object.

Managing alerts

You can update an alert’s threshold, cooldown_minutes, is_active, channel, or webhook_url at any time using PATCH /api/v1/alerts/{alert_id}. Setting is_active to false pauses the alert without deleting it.

To permanently remove an alert, send DELETE /api/v1/alerts/{alert_id}. Alerts are hard-deleted — this action cannot be undone.