Geplanter KI-Agent läuft nicht? Schnell diagnostizieren

Ein geplanter Agent kann an zwei Stellen stehen bleiben: beim Scheduler, der ihn startet, oder im Agenten selbst. Gehen Sie diese Punkte der Reihe nach durch.

1. Hat der Trigger überhaupt gefeuert?

Bevor Sie den Agenten debuggen, prüfen Sie, ob ihn überhaupt etwas gestartet hat. Schauen Sie zuerst in das Log der Scheduler-Ebene:

grep run_agent /var/log/syslog          # klassisches Cron
kubectl get jobs --sort-by=.metadata.creationTimestamp   # Kubernetes CronJob

Jeder Trigger hat seine eigenen Fehlerarten — siehe Docker-Cron läuft nicht, Kubernetes CronJob läuft nicht oder GitHub-Actions-Schedule läuft nicht. Wenn nichts den Prozess gestartet hat, hören Sie hier auf: Das Problem ist der Trigger, nicht der Agent.

2. Rate-Limits, Ausgabenlimits und tote API-Schlüssel

Die häufigste agentenspezifische Ursache. Ein 429-Sturm, ein erschöpftes Monatsbudget oder ein API-Schlüssel, den jemand rotiert hat, beenden den Lauf, bevor er etwas produziert:

python run_agent.py 2>&1 | grep -iE "429|rate.?limit|quota|401|invalid.*key"

Prüfen Sie das Nutzungs-Dashboard des Providers und protokollieren Sie den rohen API-Fehler — eine Agenten-Schleife, die die Exception fängt und paraphrasiert („Ich konnte die Aufgabe nicht abschließen”), zerstört genau die Information, die Sie jetzt brauchen.

3. Der Lauf hängt an einem festgefahrenen API-Aufruf

Viele SDKs kommen ohne Request-Timeout. Eine einzige eingefrorene Verbindung, und der Lauf endet nie — und je nach Cron-Setup stauen sich die nächsten Läufe dahinter. Begrenzen Sie sowohl den Aufruf als auch den gesamten Lauf:

# crontab: harte Frist für den gesamten Lauf, keine überlappenden Instanzen
0 2 * * * flock -n /tmp/agent.lock timeout 30m python run_agent.py

Und setzen Sie das SDK-Timeout explizit (timeout=60 oder Entsprechendes), damit eine einzelne langsame Generierung nicht die ganze Frist aufbraucht.

4. Das Modell oder die API hat sich unter Ihnen geändert

Provider künden Modell-IDs ab und ändern Antwortformate nach ihrem eigenen Zeitplan. Ihr Job bricht, ohne dass Sie irgendetwas deployt haben. Symptome: plötzliche 400/404 auf den Modellnamen oder Parsing-Fehler bei einer Antwort, die vorher funktionierte.

Pinnen Sie fest, was Sie können — eine explizite, datierte Modellversion und eine fixierte SDK-Version — damit Upgrades passieren, wenn Sie es entscheiden, nicht wenn der Provider es tut:

# requirements.txt — SDK pinnen, nicht auf „latest" treiben lassen
openai==1.54.3

5. Der Agent war „erfolgreich” — und hat nichts produziert

Exit-Code 0 bedeutet, dass der Prozess geendet hat, nicht dass Arbeit passiert ist. Agenten-Schleifen verschlucken Tool-Fehler konstruktionsbedingt: Das Suchwerkzeug scheiterte, das Modell entschuldigte sich, die Schleife wurde „erfolgreich” abgeschlossen, ohne etwas zu schreiben. Validieren Sie das Artefakt, nicht den Exit-Code:

python run_agent.py --task nightly-digest
test -s out/digest.md || { echo "leerer Digest" >&2; exit 1; }

Das tiefere Problem: Bei einem unbeaufsichtigten Agenten sieht Stille aus wie Erfolg

Jede Ursache oben endet gleich — keine Ausgabe, und nichts, das es Ihnen sagt. Der Trigger meldet keinen toten Zeitplan, der Provider meldet nicht Ihr Ausgabenlimit, und der Agent meldet nicht seinen eigenen leeren Lauf.

Lassen Sie den Lauf erst dann einen Heartbeat pingen, wenn seine Ausgabe validiert ist. Bleibt ein gültiges Ergebnis aus — aus welchem der obigen Gründe auch immer — wird der Ping verpasst und Sie werden alarmiert, unabhängig davon, welche Ebene kaputt ist:

curl -fsS https://ping.steadycron.com/<ihr-ping-token>/start
python run_agent.py --task nightly-digest && test -s out/digest.md \
  && curl -fsS https://ping.steadycron.com/<ihr-ping-token> \
  || curl -fsS https://ping.steadycron.com/<ihr-ping-token>/fail

Siehe Cron-Jobs für KI-Agenten für das vollständige Muster — einschließlich der Option, den Trigger selbst zu einem HTTP-Job zu machen, damit Zeitplan, Wiederholungen und Alarmierung außerhalb der Maschine leben, auf der der Agent läuft. Warum das für Agenten dringender gilt als für reines Cron, steht in Totmannschalter für KI-Agenten.