Agent Alerts Setup

Einrichtung von Agent Alerts

Entwerfe die Automatisierung, konfiguriere den gehosteten Webhook und übergebe die Laufzeitausführung an $agent-alerts-execution. Sende während der Einrichtung keine Nachrichten, es sei denn, der Benutzer wünscht einen Rauchtest.

Starte hier

Öffne oder leite den Benutzer zu:

https://www.andreas.ink/agent

Folge dem aktuellen Verbindungsablauf der Seite mit Agent Alerts auf dem iPhone. Es wird ein Nur-Veröffentlichungs-Token für die Laufzeit erstellt. Bitte den Benutzer nicht, diesen Token in den Chat einzufügen.

Konfiguriere den Webhook

1. Benenne die Laufzeit und schließe den Verbindungsablauf auf der öffentlichen Einrichtungsseite ab.
2. Wähle den Speicherort des Tokens für die Laufzeit:
   • Gehostete Laufzeit: Speichere den Einmal-Token im Secret Manager dieser Laufzeit als AGENTALERTS_AGENT_TOKEN.
   • Lokaler Mac: Speichere genau eine Zeile, AGENTALERTS_AGENT_TOKEN=<token>, in der vom Benutzer genehmigten Datei ~/.config/agent-alerts/token.env und setze ihre Berechtigung auf 0600.
3. Lasse den Benutzer den Token direkt in den ausgewählten Secret Store eingeben, außerhalb der KI-Konversation. Bitte ihn niemals, den Token in den Agent-Chat einzufügen.
4. Verwende den im Skript ../agent-alerts-execution/scripts/send_webhook.sh integrierten Endpunkt. Setze AGENTALERTS_WEBHOOK_URL nur, wenn die Einrichtungsseite einen anderen HTTPS-Endpunkt bereitstellt.
5. Erlaube ausgehende HTTPS-Verbindungen nur zu diesem Endpunkt.
6. Autorisiere den exakten absoluten Pfad zu send_webhook.sh für unbeaufsichtigte Ausführungen. Gewähre keinen breiten Shell-Zugriff.

Setze den Token niemals in eine Eingabeaufforderung, URL, Abfragezeichenfolge, ein Log, eine Quelldatei, eine getrackte Einstellungsdatei, den Shell-Verlauf oder ein Kommandoargument.

Erstelle und validiere einen Test

Kopiere ../agent-alerts-execution/assets/compact-webhook-payload.json in eine beschreibbare Payload-Datei und ersetze die Beispielwerte. Verwende einen stabilen, eindeutigen Idempotenz-Schlüssel für das Ereignis.

Validiere das Payload:

../agent-alerts-execution/scripts/send_webhook.sh --check payload.json

Validiere das Payload, die Token-Quelle, die Berechtigungen und den Endpunkt ohne Senden:

../agent-alerts-execution/scripts/send_webhook.sh --check-config payload.json

Sende dann einen nicht sensiblen Rauchtest:

../agent-alerts-execution/scripts/send_webhook.sh payload.json

Für eine unbeaufsichtigte Automatisierung wiederhole --check-config und den Rauchtest vom echten gespeicherten Runner. Beide müssen ohne Genehmigungsaufforderung abgeschlossen werden. Wenn der Runner das exakte Hilfsskript nicht ausführen oder den Endpunkt nicht erreichen kann, stoppe mit AGENTALERTS_SCRIPT_NOT_AUTHORIZED.

Gestalte die Benachrichtigung

Definiere:

1. Signal, Datenquelle und Auslöser.
2. Zuordnungen für good, warning und critical.
3. Überspringbedingungen, Ruhezeiten und Ausnahmen.
4. Eine stabile activity_id oder Benachrichtigungskennung.
5. Oberflächen: live_activity, widget und/oder notification.
6. Aktionstext und eine sichere Ziel-URL oder App-Deep-Link.
7. Einen dauerhaften Scheduler, wenn die Benachrichtigung später oder wiederholt ausgeführt wird.

Agent Alerts liefert Updates; es hält keine Agent-Sitzung aufrecht. Eine zukünftige oder wiederholte Ausführung ist erst vollständig, wenn der Scheduler nach dem Schließen der aktuellen Sitzung registriert bleibt. Andernfalls gib AGENTALERTS_SCHEDULER_NOT_DURABLE zurück.

Payload-Vertrag

Verwende den kompakten Webhook-Body für normale Benachrichtigungen:

{
  "title": "Build finished",
  "summary": "All tests passed.",
  "status": "good",
  "activity_id": "build-monitor",
  "source_name": "Codex",
  "surfaces": ["live_activity", "notification"],
  "idempotency_key": "build-monitor-2026-07-29T18-30-00Z"
}

Der Webhook erfordert:

Authorization: Bearer <AGENTALERTS_AGENT_TOKEN>
Content-Type: application/json
Idempotency-Key: <same value as idempotency_key>

Das Hilfsskript stellt diese Header bereit, ohne den Token in den Prozessargumenten offenzulegen. Verwende immer das Hilfsskript; erstelle die Anfrage nicht manuell neu.

Kompakte Sendungen standardmäßig auf eine upsertierte Aktivität namens webhook, Produktionsauslieferung und live_activity plus notification, wenn diese Felder weggelassen werden. Setze sie explizit, wenn die Automatisierung ein anderes Ergebnis benötigt.

Für Widgets, Control Widget-Zustand, Builder-Layouts oder andere erweiterte Felder verwende den vollständigen snake_case-Vertrag des Webhooks mit einem verschachtelten payload-Objekt. Mische kein vollständiges payload-Objekt mit kompakten title, summary, status, source_name- oder deep_link-Feldern.

Kopier- und Auslieferungsregeln

Halte den sichtbaren Text vollständig und innerhalb dieser Grenzen:

Feld	Maximale Zeichen
source_name	14
title	32
summary	96

Verlasse dich nicht auf Abschneiden oder füge Auslassungspunkte hinzu.

• live_activity aktualisiert die Dynamic Island oder den Sperrbildschirm.
• widget benötigt seine Widget-Kennung, eine kleine nicht geheime Momentaufnahme und aktiviertes Neuladen.
• notification benötigt eine stabile Thread-Kennung zur Gruppierung.
• Control Widget-Zustand sollte für aktive Warn- oder Kritisch-Zustände true sein und für geklärte oder aufgelöste Zustände false.

Laufzeitübergabe

Schreibe eine genaue Laufzeitanweisung:

Verwende $agent-alerts-execution. Werte zuerst die konfigurierte Überspringbedingung aus.
Wenn ein Senden erforderlich ist, schreibe das vorbereitete Agent Alerts JSON in den genehmigten Payload-Pfad und rufe dann den autorisierten absoluten send_webhook.sh-Pfad mit dieser Datei auf. Lese den Token nur aus AGENTALERTS_AGENT_TOKEN oder der genehmigten token.env-Datei. Melde den zurückgegebenen Status sowie Ziel-, Erfolgs- und Fehleranzahlen, ohne Geheimnisse preiszugeben.

Die Einrichtung ist erst vollständig, wenn der echte Runner die Konfiguration validiert und ohne Interaktion sendet, der Zeitplan bei Bedarf dauerhaft ist und das Ergebnis gemeldet wird, ohne die gerätesichtbare Zustellung zu übertreiben.