Agent IA planifié ne s'exécute pas ? Diagnostic rapide

Un agent planifié peut s’arrêter à deux endroits : le scheduler qui le déclenche, ou l’agent lui-même. Parcourez ces points dans l’ordre.

1. Le déclencheur a-t-il seulement tiré ?

Avant de déboguer l’agent, confirmez que quelque chose l’a réellement lancé. Regardez d’abord le journal de la couche scheduler :

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

Chaque déclencheur a ses propres modes de panne — voir cron Docker ne s’exécute pas, CronJob Kubernetes ne s’exécute pas ou schedule GitHub Actions ne s’exécute pas. Si rien n’a lancé le processus, arrêtez-vous ici : le problème est le déclencheur, pas l’agent.

2. Rate limits, plafonds de dépense et clés API mortes

La cause spécifique aux agents la plus fréquente. Une rafale de 429, un budget mensuel épuisé ou une clé API que quelqu’un a fait tourner interrompent le run avant qu’il ne produise quoi que ce soit :

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

Consultez le tableau de bord de consommation du fournisseur, et journalisez l’erreur API brute — une boucle d’agent qui attrape l’exception et la paraphrase (« Je n’ai pas pu terminer la tâche ») détruit exactement l’information dont vous avez besoin maintenant.

3. Le run se bloque sur un appel API figé

Beaucoup de SDK sont livrés sans timeout de requête. Une seule connexion figée et le run ne se termine jamais — et selon votre configuration cron, les runs suivants s’empilent derrière. Bornez à la fois l’appel et le run entier :

# crontab : échéance dure pour tout le run, pas d'instances qui se chevauchent
0 2 * * * flock -n /tmp/agent.lock timeout 30m python run_agent.py

Et fixez explicitement le timeout côté SDK (timeout=60 ou équivalent) pour qu’une seule génération lente ne consomme pas toute l’échéance.

4. Le modèle ou l’API a changé sous vos pieds

Les fournisseurs déprécient des ID de modèles et remodèlent leurs réponses à leur propre rythme. Votre job casse sans le moindre déploiement de votre côté. Symptômes : des 400/404 soudains sur le nom du modèle, ou des erreurs de parsing sur une réponse qui fonctionnait avant.

Épinglez ce que vous pouvez — une version de modèle explicite et datée, une version de SDK verrouillée — pour que les montées de version arrivent quand vous le décidez, pas quand le fournisseur le décide :

# requirements.txt — épingler le SDK, ne pas flotter sur « latest »
openai==1.54.3

5. L’agent a « réussi » mais n’a rien produit

Un code de sortie 0 signifie que le processus s’est terminé, pas que du travail a eu lieu. Les boucles d’agents avalent les erreurs d’outils par conception : l’outil de recherche a échoué, le modèle s’est excusé, la boucle s’est conclue « avec succès » sans rien écrire. Validez l’artefact, pas le code de sortie :

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

Le problème de fond : pour un agent sans surveillance, le silence ressemble au succès

Chaque cause ci-dessus se termine de la même façon — aucune sortie, et rien pour vous le dire. Le déclencheur ne signalera pas un planning mort, le fournisseur ne signalera pas votre plafond de dépense, et l’agent ne signalera pas son propre run vide.

Faites pinger un heartbeat par le run seulement une fois sa sortie validée. Si un résultat valide cesse d’arriver — pour n’importe laquelle des raisons ci-dessus — le ping est manqué et vous êtes alerté, quelle que soit la couche qui a cassé :

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

Voir Des cron jobs pour agents IA pour le patron complet — y compris déplacer le déclencheur lui-même vers un job HTTP, afin que planning, relances et alertes vivent en dehors de la machine qui exécute l’agent.