Un agent IA qui travaille pendant des heures devrait-il journaliser sa progression ? Des Heartbeats pour éviter « il s’est arrêté ? »

Dans une longue tâche d’IA, le plus inquiétant n’est pas toujours l’échec. C’est le silence.

Une personne peut finir ses tâches, faire des courses, manger puis revenir : l’IA affiche toujours « en cours ». Deux explications très différentes sont possibles :

1. elle exécute sérieusement une énorme suite de tests ;
2. elle s’est bloquée quelque part il y a plusieurs heures.

Un indicateur de chargement ne permet pas de trancher. L’absence de commit non plus : tests, enquête, comparaison, génération ou attente d’un service externe peuvent rester longtemps sans produire d’artefact visible.

Une IA de longue durée a donc besoin d’autre chose que de l’intelligence : de l’observabilité.

1. Conclusion――si une tâche peut durer longtemps, il faut exposer son état actuel

Un agent de longue durée ne devrait pas seulement rendre compte à la fin. Son état intermédiaire doit aussi être lisible.

Il n’est pas nécessaire qu’il dise « je suis vivant » chaque minute. Il faut surtout pouvoir savoir :

• ce qu’il fait maintenant ;
• ce qui est terminé ;
• ce qui reste ;
• s’il teste ;
• s’il est bloqué ;
• quand son activité a été confirmée pour la dernière fois ;
• quand le dernier changement matériel a eu lieu.

Un exemple de réglage pratique consiste à rafraîchir un Heartbeat après environ 10 minutes sans artefact visible, puis à classer un Heartbeat vieux de plus de 20 minutes comme STALE_UNKNOWN, et non comme « arrêté ».

Le silence signifie d’abord « nous ne savons pas », pas « il a échoué ».

2. Pourquoi l’historique des commits ne suffit pas

Les commits Git sont excellents comme preuve de changement matériel, mais faibles comme unique preuve d’activité actuelle.

Une suite de régression d’une heure peut fonctionner parfaitement sans produire un seul commit. À l’inverse, committer un fichier Heartbeat inutile toutes les dix minutes ne fait qu’encombrer l’historique.

Il vaut mieux séparer :

Heartbeat = état actuel
Material change = preuve qu’un code, contrat, artefact ou résultat de vérification a réellement changé

En séparant lastHeartbeatAt et lastMaterialChangeAt, on comprend facilement « aucun commit depuis 30 minutes, mais TESTING confirmé il y a 5 minutes ».

Le but n’est pas d’avoir plus de commits, mais de rendre le silence interprétable.

3. Que faut-il enregistrer au minimum ?

Pour un run long, ces champs sont utiles :

• runId
• state : RUNNING / BLOCKED / COMPLETED / STALE_UNKNOWN, etc.
• phase : READING / IMPLEMENTING / TESTING / VERIFYING, etc.
• workingOn
• startedAt
• lastHeartbeatAt
• lastMaterialChangeAt
• branch / baseSha / headSha / PR
• completedMilestones / remainingMilestones
• blockers
• tests
• nextCheckpoint

Ainsi, une tâche de six heures cesse d’être « une boîte noire de six heures » et devient lisible comme :

IMPLEMENTING → TESTING → INTEGRATING → VERIFYING

Une boîte noire très intelligente reste une boîte noire. Au bout de quelques heures, cela devient stressant.

4. Pendant les tests, les Heartbeats sont particulièrement importants

Un test long ressemble énormément à un agent figé.

Avant un test long, on peut enregistrer :

• phase = TESTING
• nom de la suite
• périmètre
• un compte objectif tel que 84 / 127 si le total est fixe
• présence ou non d’un échec

Évitez les pourcentages inventés comme « 82 % terminé » pour la conception ou le débogage. Personne ne sait réellement ce que représentent les 18 % restants.

Un pourcentage n’a de sens que si le dénominateur est fixe :

• 84 / 127 tests
• 3 / 5 acceptance gates

« Implémentation terminée à 82 % » est l’équivalent IA de « j’arrive » dit par quelqu’un qui est peut-être encore chez lui.

5. Lire « s’est-il arrêté ? » par étapes

Une politique pratique peut classer l’ancienneté du Heartbeat ainsi :

Ancienneté	Interprétation
0–10 minutes	CURRENT
10–20 minutes	HEARTBEAT_OVERDUE
Plus de 20 minutes	STALE_UNKNOWN

STALE_UNKNOWN n’est pas FAILED.

Puis vérifier dans cet ordre :

1. l’enregistrement de progression courant ;
2. Check / Status ;
3. branch / PR ;
4. dernier commit ;
5. l’inférence seulement en dernier.

Si le Heartbeat est ancien mais qu’un nouveau PR ou commit apparaît ensuite, l’agent a probablement continué à travailler et a simplement oublié de mettre à jour son état.

L’IA peut elle aussi faire : travail fait, feuille de temps oubliée.

6. Erreurs de gestion à éviter

Ne pas empiler des commits de Heartbeat sur main

Cela pollue l’historique, crée des conflits et peut déclencher du CI ou du déploiement inutile. Préférer une surface légère et mutable : commentaire d’Issue, Check, Status ou espace ops non production.

Ne pas créer un nouveau commentaire à chaque Heartbeat

Un enregistrement mutable par run est bien plus lisible. Un commentaire toutes les dix minutes finit en fouille archéologique.

Ne pas confondre silence et échec

Si le Heartbeat est simplement ancien, utiliser STALE_UNKNOWN. L’échec demande une preuve affirmative.

Ne pas écrire de secrets dans les logs

Pas de clés API, tokens, mots de passe, URL privées, conversations privées brutes, données personnelles ou fichiers confidentiels.

Ne pas arrêter un travail sûr parce que le canal d’observabilité est cassé

Si l’API de progression échoue, passer à un autre sink et continuer ce qui peut l’être en sécurité.

7. Modèle pratique

State: RUNNING
Phase: TESTING

Run ID: agent-20260916-long-task
Started: 10:00
Last heartbeat: 14:05
Last material change: 13:42

Branch: feat/long-task
Head SHA: abc1234
PR: #123

Working on:
- regression tests

Completed:
- runtime implementation
- contract update

Remaining:
- regression completion
- merge verification
- production readback

Blockers:
- none

Tests:
- 84 / 127 passed so far
- no failure observed

Next checkpoint:
- finish regression, then integration

Avec cela, « il s’est arrêté ? » devient « d’accord, il est en test ».

La visibilité n’a pas pour objectif principal de mettre la pression sur l’IA. Elle évite que les humains redémarrent, interrompent ou répètent des instructions uniquement par manque d’information.

8. Résumé――concevoir séparément intelligence et visibilité

Dans les tâches longues, il faut distinguer :

• pas de commit ≠ arrêté
• Heartbeat ≠ progression matérielle
• Heartbeat ancien ≠ échec
• un blocker ≠ arrêt global
• silence pendant les tests ≠ endormi

Si une IA peut travailler six heures, un humain ne devrait pas avoir à la regarder six heures.

Le meilleur design permet de revenir à n’importe quel moment et de voir immédiatement où elle en est.

L’agent de longue durée idéal n’est pas celui qui parle sans arrêt.

Il travaille silencieusement, mais sa position est évidente dès qu’on regarde.

---