Operations March 4, 2026 · 5 min read

How to Build a Real-Time Alert System for Your AI Agent

AI trading agents are autonomous by design — they execute strategies, manage positions, and respond to market events without human intervention. But autonomous doesn't mean unmonitored. The most robust agent deployments combine autonomous execution with external monitoring systems that notify humans or trigger secondary agents when something requires attention.

This tutorial walks through building a complete alert system: configuring alerts via Purple Flea, building a Flask webhook handler to receive them, routing alerts to Discord or email, and designing cascading alert logic that escalates appropriately based on severity.

Why Agents Need External Monitoring

A common mistake is assuming that an agent's own internal logic handles all failure cases. In practice, agents can fail in ways that their internal state doesn't detect: a process crash, a network timeout during a critical order, a position that silently accumulates losses due to an edge case in the strategy logic.

External monitoring solves this because it operates independently of the agent's own process. Purple Flea's alert system runs on separate infrastructure — it monitors the agent's positions, balances, and performance from the outside. Even if the agent's process crashes, the alert system continues monitoring and will alert on the resulting abnormal state (e.g., positions not being updated, balances changing unexpectedly).

There's also the human judgment problem. Many trading scenarios benefit from a human check before taking action. A 12% drawdown might warrant a phone call rather than an automated position close. The alert system is the bridge between the agent's automated world and human decision-making.

Step 1: Configure Alerts via Purple Flea

Register your alerts using the AlertClient. Each alert is persistent — it lives on Purple Flea's servers and survives agent restarts. You can register all your alert rules at startup and they'll stay active indefinitely.

import purpleflea

alerts = purpleflea.AlertClient(api_key="YOUR_KEY")
WEBHOOK_BASE = "https://mybot.io"

# 1. Price alert — BTC crosses $90k downward
alerts.create(
    type="price",
    asset="BTC",
    condition="below",
    value=90000,
    channels=["webhook"],
    webhook_url=f"{WEBHOOK_BASE}/alert/price",
    cooldown_minutes=60   # Don't fire more than once per hour
)

# 2. Drawdown alert — 5% loss in 24h (warning level)
alerts.create(
    type="drawdown",
    agent_id="my_trading_agent",
    condition="exceeds",
    value=5,
    period_hours=24,
    channels=["webhook"],
    webhook_url=f"{WEBHOOK_BASE}/alert/drawdown-warning",
    severity="warning"
)

# 3. Drawdown alert — 12% loss in 24h (critical level)
alerts.create(
    type="drawdown",
    agent_id="my_trading_agent",
    condition="exceeds",
    value=12,
    period_hours=24,
    channels=["webhook", "email"],
    webhook_url=f"{WEBHOOK_BASE}/alert/drawdown-critical",
    email="operator@mybot.io",
    severity="critical"
)

# 4. Balance alert — wallet drops below $50
alerts.create(
    type="balance",
    agent_id="my_trading_agent",
    condition="below",
    value=50,
    channels=["webhook"],
    webhook_url=f"{WEBHOOK_BASE}/alert/low-balance"
)
  

Step 2: Build a Flask Webhook Handler

Each alert fires a POST request to your specified webhook URL with a signed JSON payload. Your handler verifies the signature, then routes the alert to the appropriate response function. Here's a production-ready Flask handler covering all four alert types.

from flask import Flask, request, jsonify
import hmac, hashlib, json
import purpleflea
import requests  # for Discord webhook

app = Flask(__name__)
WEBHOOK_SECRET = "your_webhook_secret_from_dashboard"
DISCORD_WEBHOOK_URL = "https://discord.com/api/webhooks/YOUR_WEBHOOK"
trader = purpleflea.TradingClient(api_key="YOUR_KEY")

def verify_signature(payload: bytes, sig_header: str) -> bool:
    expected = hmac.new(
        WEBHOOK_SECRET.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, sig_header)

def notify_discord(message: str, color: int = 0x9333EA):
    requests.post(DISCORD_WEBHOOK_URL, json={
        "embeds": [{"description": message, "color": color}]
    })

# --- Warning drawdown: notify Discord, continue ---
@app.route("/alert/drawdown-warning", methods=["POST"])
def drawdown_warning():
    data = request.get_json()
    notify_discord(
        f"⚠️ Agent drawdown {data['value']:.1f}% in 24h — monitoring",
        color=0xEAB308  # yellow
    )
    return jsonify({"status": "received"})

# --- Critical drawdown: halt trading + email human ---
@app.route("/alert/drawdown-critical", methods=["POST"])
def drawdown_critical():
    data = request.get_json()
    # Halt all open orders
    trader.cancel_all_orders(agent_id="my_trading_agent")
    notify_discord(
        f"🚨 CRITICAL: Agent drawdown {data['value']:.1f}% — trading halted",
        color=0xEF4444  # red
    )
    return jsonify({"status": "halted"})

# --- Low balance: notify + top up from treasury ---
@app.route("/alert/low-balance", methods=["POST"])
def low_balance():
    notify_discord("💰 Low balance alert — agent needs refill")
    return jsonify({"status": "notified"})

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8080)
  

Step 3: Routing Alerts to Discord, Slack, or Email

The webhook handler above routes alerts to Discord. For Slack, replace the notify_discord function with a Slack Incoming Webhook POST. For email, use Python's smtplib or a service like SendGrid.

A useful pattern is severity-based routing: info-level alerts (price milestone, position opened) go to a low-priority Discord channel; warning-level alerts (5% drawdown, approaching balance threshold) go to a high-priority channel; critical alerts (12%+ drawdown, liquidation risk) send an email and trigger a phone notification via a service like PagerDuty.

Step 4: Cascading Alert Trees

The most powerful use of the alert system is cascading: one alert triggers a condition that creates or modifies another alert. This creates graduated response behavior without requiring a human to manage each escalation level.

5% Drawdown — Warning Level

Fire Discord notification. No trading action. Create a new temporary 8% alert with a 4-hour window if not already active.

8% Drawdown — Elevated Level

Reduce all position sizes by 50%. Fire Discord (high-priority channel) and send email. Monitor every 30 minutes.

12% Drawdown — Critical Level

Cancel all open orders. Close all positions. Email + phone call via PagerDuty. Agent halted pending human review.

Design principle: Each escalation level should take an increasingly forceful response, but the thresholds should be wide enough that normal volatility doesn't trigger cascades. A 5% intraday drawdown on a volatile asset is normal — only escalate if it continues deteriorating, not just because it occurred.

Connecting Agents to Each Other via Alerts

One of the most powerful features of the Purple Flea alert system is the agent-to-agent channel. Instead of (or in addition to) notifying a human, you can fire an alert directly to another agent ID. That agent receives the alert in its inbox and can take programmatic action.

Example: a monitoring agent receives a drawdown alert about agent_001, then queries agent_001's positions, calculates optimal risk reduction, and sends trade commands directly. This full agent-to-agent coordination happens without any human involvement — the monitoring agent is the automation layer that activates when the primary agent hits trouble.

Conclusion

A robust alert system is the difference between a production-grade autonomous agent and a prototype that works until it doesn't. The cost of setting it up is 30 minutes. The cost of not having it is discovering a blown position hours after the fact.

Start with the four fundamental alerts: price, drawdown, position size, and balance. Add the Flask webhook handler, connect it to Discord. Then iterate — add cascading logic, agent-to-agent routing, and severity-based escalation. Your agent will be genuinely resilient to the real-world surprises that come with operating in live markets.