La journalisation des nouvelles tentatives d'un agent IA révèle les effets en double

Une nouvelle tentative d'un agent n'est pas une seconde copie d'une action. C'est une deuxième tentative pour mener à bien une action déclarée, et la piste d'audit doit conserver cette distinction. Si vos enregistrements montrent seulement une série d'appels HTTP similaires, vous avez rendu la récupération et la répétition indissociables.

Cette lacune compte surtout lorsque l'action modifie le monde : créer un ticket, révoquer un accès, enregistrer un paiement, pousser un déploiement ou exécuter une commande via SSH. L'agent peut recevoir un délai d'attente alors que la destination a déjà agi. Il peut aussi recommencer après une défaillance locale, avant même qu'un octet ait quitté la machine. Ces situations exigent des réponses différentes, pourtant trop de systèmes les enregistrent toutes deux comme request failed, retrying.

J'ai vu des équipes enquêter manuellement sur de prétendues actions en double en comparant les horodatages et les charges utiles. C'est un mauvais substitut à un modèle d'événements. Intégrez la relation dans chaque enregistrement au moment où l'action se produit. L'enquêteur doit pouvoir sélectionner une opération et voir son intention, chaque tentative, la raison de chaque tentative ultérieure et le résultat qui a finalement tranché la question.

Une nouvelle tentative appartient à une opération, pas à une ligne de journal

Chaque action d'agent produisant un effet de bord a besoin de deux identités : un identifiant d'opération pour le résultat visé et un identifiant de tentative pour une exécution donnée. L'identifiant d'opération persiste dès que l'agent décide ce qu'il veut faire, jusqu'à la clôture ou au rapprochement de cette intention. Chaque appel réseau ou exécution SSH reçoit un nouvel identifiant de tentative.

Supposons qu'un agent veuille désactiver un compte. Il crée l'opération op_7f2c. La première requête, att_01, atteint l'API d'identité, mais la connexion se ferme avant l'arrivée de la réponse. Une deuxième requête, att_02, peut être une tentative de récupération justifiée. Les deux enregistrements doivent pointer vers op_7f2c, et att_02 doit pointer directement vers att_01, la tentative qui l'a déclenchée.

N'utilisez pas l'identifiant de conversation comme identifiant d'opération. Une conversation d'agent peut contenir de nombreuses actions, et une action peut survivre à une conversation lorsqu'un superviseur reprend le travail. N'utilisez pas non plus un simple hachage de requête. Un hachage décrit des octets, tandis qu'une opération décrit l'effet visé. Deux requêtes peuvent différer par des détails de transport sans importance tout en appartenant à une seule opération. À l'inverse, des octets identiques peuvent créer deux actions distinctes lorsque l'agent les envoie délibérément deux fois.

Utilisez une identité d'opération lorsque l'agent prend un engagement tel que « désactiver le compte A », « créer un incident pour l'alerte B » ou « exécuter cette migration une fois sur l'hôte C ». Capturez cette intention dans des champs structurés. Un résumé en langage naturel est utile aux personnes, mais ne peut pas être la seule identité, car la formulation change d'une exécution d'agent à l'autre.

Une hiérarchie claire ressemble à ceci :

• Une session identifie une exécution d'un processus d'agent.
• Une opération identifie un effet externe visé.
• Une tentative identifie une exécution réelle.
• Une observation identifie une preuve reçue plus tard, comme un rappel, une vérification après écriture ou une décision d'opérateur.

Cette hiérarchie résout un cas délicat qui se présente souvent : un agent envoie une requête, dépasse le délai d'attente, puis demande à un autre point d'accès si l'action a eu lieu. La recherche n'est pas une nouvelle tentative. C'est une observation attachée à l'opération d'origine. La traiter comme une autre tentative enfouit la preuve la plus utile dans la mauvaise catégorie.

Inconnu est un résultat, pas un message d'erreur

Un délai d'attente produit de l'incertitude, pas la preuve d'un échec. Votre journal doit posséder un état pour cette incertitude et le conserver jusqu'à ce que des éléments ultérieurs la résolvent.

De nombreuses bibliothèques clientes regroupent plusieurs événements dans une seule exception : connexion refusée, échec DNS, corps de réponse arrivé trop tard et connexion réinitialisée après que le serveur a validé une écriture. Cette commodité peut convenir au flux de contrôle de l'application. Elle est inacceptable comme enregistrement d'audit final. Les enregistrements doivent indiquer ce que l'appelant a observé et éviter les affirmations sur la destination que l'appelant ne peut pas justifier.

Pour une tentative, séparez l'observation locale de l'état résolu de l'opération. Une tentative peut être not_sent, sent_no_response, response_received ou execution_error. L'opération peut être open, succeeded, failed, unknown ou cancelled. Les noms peuvent varier, pas la séparation.

not_sent signifie que le client s'est arrêté avant l'envoi. Un échec local de recherche d'identifiants peut entrer dans cette catégorie. Le recommencer ne peut pas dupliquer un effet distant, car aucune requête distante n'est partie.

sent_no_response signifie que l'appelant a envoyé l'action, mais ne dispose pas d'une réponse exploitable. C'est l'état dangereux. Une nouvelle tentative automatique peut être sûre uniquement si la destination dispose d'un mécanisme fiable de déduplication ou si l'action elle-même ne peut pas créer d'effet en double.

response_received ne signifie pas automatiquement réussite. Un serveur peut renvoyer une erreur de validation, un conflit ou une réponse positive décrivant un travail asynchrone. Stockez le statut, l'empreinte de réponse pertinente et toute référence d'opération fournie par la destination. Définissez ensuite l'état de l'opération selon le contrat de cette API particulière.

Évitez d'écrire failed lorsque vous voulez dire unknown. Le mot rend les tableaux de bord plus nets, mais il indique au prochain agent ou opérateur de répéter une action qui a peut-être déjà eu lieu. Pendant un incident, ce champ malhonnête peut transformer une seule action erronée en une série d'actions.

La sémantique HTTP ne rend pas une action métier sûre à répéter

Les méthodes HTTP décrivent la sémantique du protocole, pas vos garanties métier. RFC 9110 indique qu'une méthode est idempotente lorsque l'effet visé par plusieurs requêtes identiques est le même que celui d'une seule requête. La norme cite PUT, DELETE et les méthodes sûres comme idempotentes, tandis que POST ne l'est pas par défaut.

Cette indication est utile, mais les ingénieurs lui font dire trop de choses. Une requête DELETE peut être idempotente au niveau du protocole, car supprimer une ressource absente la laisse absente. Votre question d'audit peut toutefois être différente : l'agent a-t-il supprimé le bon compte, a-t-il déclenché deux fois un nettoyage en aval et le second appel utilisait-il une autorité différente ? L'étiquette du protocole ne répond pas à ces questions.

PUT pose aussi problème. Un PUT qui définit une ressource sur une représentation fixe tolère souvent les nouvelles tentatives. Un point d'accès PUT qui déclenche une notification, alloue un enregistrement ou lance une intégration à chaque réception n'offre pas la sécurité que l'on suppose. Lisez le contrat documenté de la destination et testez le comportement en provoquant une perte de réponse. Les noms des méthodes ne sont pas des preuves.

Les points d'accès POST prennent souvent en charge un jeton d'idempotence. Envoyez un jeton stable dérivé de l'identifiant d'opération, pas de l'identifiant de tentative. Si att_01 et att_02 ont des jetons différents, vous avez neutralisé la fonction qui vous protège de la nouvelle tentative.

Une enveloppe de requête peut ressembler à ceci :

{
  "operation_id": "op_7f2c9c",
  "attempt_id": "att_01",
  "idempotency_key": "op_7f2c9c",
  "intent": {
    "kind": "disable_account",
    "subject_ref": "user:1842"
  },
  "destination": {
    "method": "POST",
    "route_template": "/v1/accounts/{id}/disable",
    "authority_ref": "vault:identity-prod"
  },
  "request_fingerprint": "sha256:...",
  "dispatch_state": "sent_no_response"
}

Ne journalisez pas l'en-tête d'autorisation, le cookie de session, le matériel SSH privé ou un corps contenant des secrets. Enregistrez une référence d'identifiant et l'empreinte de la représentation canonique de la requête. Une empreinte aide les enquêteurs à comparer les tentatives sans transformer la piste d'audit en un autre coffre à secrets.

La destination doit respecter le jeton d'idempotence pour empêcher les effets répétés. Si elle le fait, enregistrez la référence renvoyée par la destination et indiquez si la réponse provenait d'un résultat antérieur conservé. Si elle ne le fait pas, le jeton n'est qu'un en-tête inerte et votre politique de nouvelle tentative doit en tenir compte.

Une nouvelle tentative SSH peut répéter plusieurs commandes

SSH rend le suivi des tentatives plus difficile, car une connexion peut transporter une syntaxe shell, des pipelines, des redirections et des commandes qui s'exécutent partiellement. Une session SSH interrompue ne permet pas de savoir quelles parties de la commande distante ont été exécutées.

Considérez cette commande :

create-user deployer \u0026\u0026 install-key deployer /tmp/new.pub \u0026\u0026 restart-service api

Si le client perd la connexion après l'envoi, une nouvelle tentative peut échouer parce que l'utilisateur existe déjà, installer deux fois une clé si l'assistant l'ajoute, ou redémarrer le service une seconde fois. Le \u0026\u0026 du shell ne contrôle le comportement que pendant une exécution. Il ne protège pas une nouvelle connexion qui relance toute la chaîne.

Ne journalisez la commande exacte que si elle ne contient aucun secret. Sinon, stockez une forme d'affichage masquée et une empreinte canonique. Enregistrez l'alias de l'hôte ou la référence de sa clé, la référence du compte distant, le répertoire de travail s'il est pertinent, le code de sortie s'il a été reçu et la limite d'exécution. Cette limite doit indiquer si l'assistant a démarré la commande et s'il a reçu un code de sortie, pas seulement si l'appelant local a signalé une erreur.

Le modèle le plus sûr consiste à utiliser un script distant avec un marqueur d'opération que le script vérifie avant d'agir. Le marqueur doit se trouver à un endroit que le système cible peut lire de manière atomique. Une transaction de base de données, un enregistrement de déploiement ou un fichier créé exclusivement peuvent convenir, selon l'environnement. Un cache local de l'agent ne peut rien prouver après un crash ou une seconde exécution de l'agent.

Par exemple, un script de déploiement peut accepter OPERATION_ID, l'écrire dans un enregistrement de version avant l'activation et renvoyer le résultat existant si cet enregistrement existe déjà. L'événement d'audit capture alors à la fois l'identifiant d'opération local et l'identifiant de l'enregistrement distant. L'enquêteur dispose ainsi d'un lien entre l'enregistrement de l'agent et les preuves présentes sur l'hôte.

Ne considérez pas des commandes shell arbitraires comme relançables parce qu'elles sont « généralement sûres ». Classez les familles de commandes. La collecte en lecture seule peut être relancée librement. Les commandes qui définissent un état ont besoin d'une condition explicite de convergence. Les commandes d'ajout, financières, destructrices ou de notification exigent un enregistrement distant de déduplication ou une décision humaine après un résultat inconnu.

Chaque tentative ultérieure a besoin d'une raison et d'un parent

Un événement de nouvelle tentative doit nommer la tentative qui l'a déclenché et la condition qui justifiait un nouvel essai. retry_count: 2 est trop faible. Il indique qu'il y a eu des appels précédents, mais ne précise pas lequel a échoué, si l'agent a modifié quoi que ce soit ni si un humain a approuvé la poursuite.

Utilisez un ensemble contrôlé de raisons, puis joignez les détails justificatifs séparément. Parmi les raisons utiles figurent connection_not_established, rate_limited, destination_5xx, response_lost_after_dispatch, credential_refreshed et operator_requested. Ne laissez pas un agent inventer une explication en prose rassurante mais impossible à regrouper ou à examiner.

Pour chaque nouvelle tentative, conservez ces liens :

{
  "operation_id": "op_7f2c9c",
  "attempt_id": "att_02",
  "retry_of_attempt_id": "att_01",
  "retry_reason": "response_lost_after_dispatch",
  "retry_decision": "destination_idempotency_confirmed",
  "attempt_budget_remaining": 1,
  "request_fingerprint": "sha256:...",
  "prior_request_fingerprint": "sha256:..."
}

Les deux empreintes devraient normalement correspondre. Si elles diffèrent, consignez la raison. Une modification de l'en-tête d'horodatage peut être attendue. Une modification de l'identifiant de compte, du montant, du nom d'hôte, du chemin ou de l'autorité n'est pas une nouvelle tentative au sens ordinaire. Il s'agit d'une nouvelle opération ou d'une intention modifiée manuellement, et la piste d'audit doit le dire.

C'est ici que les systèmes d'agents se trompent souvent eux-mêmes. Le modèle lit une erreur, modifie un paramètre pour la « corriger » et appelle la requête suivante une nouvelle tentative. Il s'agit d'une nouvelle décision, avec un nouvel effet possible. La relier comme une nouvelle tentative masque le changement de plan et rend l'examen presque impossible.

Limitez le nombre de tentatives par opération et enregistrez la décision relative à cette limite. Recommencer après une réponse de limitation de débit, une fois le délai indiqué par la destination écoulé, est différent de recommencer une écriture inconnue après un délai d'attente. Dans le premier cas, la réponse distante est souvent sans ambiguïté. Dans le second, il faut une preuve d'idempotence ou un rapprochement avant de recommencer.

Les jetons d'idempotence et les identités d'audit remplissent des fonctions différentes

Un jeton d'idempotence indique à une destination de traiter des soumissions répétées comme une seule opération. Un identifiant d'opération d'audit indique à vos enquêteurs quelles tentatives appartiennent à une même intention. Utilisez les deux lorsque c'est possible, mais ne prétendez jamais que l'un remplace l'autre.

Le jeton peut être limité à un chemin, un commerçant, une période ou un compte précis. Certaines API ne conservent les jetons que pendant une durée limitée. Certaines renvoient la réponse d'origine pour un doublon, d'autres renvoient un conflit. Certaines refusent la réutilisation d'un jeton lorsque le corps de la requête change. Ces détails doivent figurer dans le contrat du connecteur et dans votre suite de tests.

Votre identifiant d'opération a un rôle plus large. Il relie la session de l'agent, les preuves d'approbation, la construction de la requête, les tentatives de transport, la réponse distante et le rapprochement ultérieur. Il doit rester valide même lorsqu'une API fournisseur n'offre pas d'idempotence, lorsque l'action utilise SSH ou lorsqu'un opérateur effectue manuellement la récupération finale.

Ne créez pas un nouvel identifiant d'opération après un redémarrage simplement parce que la mémoire du processus a disparu. Faites persister les opérations en attente avant l'envoi. Lors de la reprise, examinez chaque opération non résolue et choisissez l'une de ces trois voies : la rapprocher à l'aide de preuves distantes, la relancer selon une garantie d'idempotence documentée ou la transmettre à une personne. Un redémarrage est un événement technique, pas une permission d'oublier l'incertitude.

Une recommandation fréquente mais erronée consiste à relancer chaque écriture échouée avec un délai exponentiel. Le délai réduit la pression sur un service en difficulté. Il ne transforme pas une écriture inconnue en écriture sûre. C'est la répétabilité de l'action et le comportement de déduplication de la destination qui déterminent si une autre tentative est acceptable.

Le rapprochement clôt l'incertitude sans réécrire l'historique

Le rapprochement consiste à recueillir ultérieurement des preuves sur une opération non résolue. Il ne consiste pas à modifier la première tentative jusqu'à ce qu'elle ait l'air réussie.

Supposons qu'un agent crée un incident avec une référence fournie par le client dans le corps de la requête. Le POST initial se termine par sent_no_response. Avant de recommencer, l'agent recherche les incidents avec cette référence. S'il trouve un enregistrement correspondant, ajoutez un événement d'observation qui cite l'identifiant d'opération d'origine, l'empreinte de la recherche, l'identifiant distant renvoyé et les critères de correspondance. Clôturez ensuite l'opération comme réussie par rapprochement.

Si la recherche ne renvoie rien, soyez prudent. Une absence prouve peu de choses lorsque l'API présente un délai de réplication, un retard d'indexation ou un filtrage peu précis. Enregistrez l'observation négative avec l'heure et le point d'accès utilisés. Ne recommencez que si le contrat de la destination indique que le jeton d'idempotence reste efficace, ou attendez et demandez une décision.

Si la recherche trouve deux enregistrements correspondants, ne déclarez pas l'opération réussie pour passer à autre chose. Clôturez-la comme duplicate_effect_confirmed, conservez les deux identifiants distants et créez une opération de correction distincte. Cette correction ne doit pas partager l'identifiant d'opération d'origine, car son effet visé est différent.

Conservez des événements en ajout seulement, plutôt que des lignes d'état modifiables comme source de vérité. Vous pouvez projeter un état actuel pratique pour une interface, mais les preuves doivent conserver les transitions : intention créée, tentative envoyée, réponse perdue, recherche effectuée, enregistrement distant trouvé, opération résolue. L'enquêteur a besoin de la séquence, y compris de la tentative erronée si elle a eu lieu.

Un journal permettant de détecter les altérations ajoute une propriété importante : il permet de vérifier qu'un processus ultérieur n'a pas discrètement supprimé la première tentative inconnue. Sallyport enregistre les sessions des agents et les actions individuelles dans un journal d'audit chiffré, chaîné par hachage et insensible aux écritures, tandis que sp audit verify vérifie la chaîne hors ligne sur le texte chiffré. Cela aide à préserver la chronologie, mais le schéma d'événements doit toujours contenir les liens entre opérations et tentatives décrits ici.

La délégation d'un agent a besoin d'un propriétaire de l'opération

Les sous-agents facilitent les effets en double, car chaque processus peut croire qu'il possède la tâche. Désignez un seul processus comme propriétaire de l'identifiant d'opération et exigez que chaque travailleur délégué transporte cet identifiant dans son contexte d'action.

Un planificateur peut demander à un travailleur de recueillir des informations et à un autre d'exécuter une action. Les appels de collecte d'informations doivent recevoir leurs propres opérations, car ils correspondent à des intentions distinctes. Le travailleur d'exécution ne doit recevoir l'identifiant d'opération d'origine que lorsqu'il agit sur le même effet déclaré. Ses appels individuels utilisent de nouveaux identifiants de tentative et indiquent le processus du travailleur qui les a effectués.

Ne laissez pas les travailleurs relancer indépendamment une écriture inconnue pendant que le parent la relance aussi. Le parent doit recevoir l'état d'envoi du travailleur avant de décider quoi faire. Si le travailleur se termine de façon inattendue, marquez l'opération comme non résolue et rapprochez-la. L'absence du résultat d'un enfant n'est pas une invitation pour un superviseur à rejouer la commande.

Les approbations par session appartiennent également à la chaîne de preuves. Lorsqu'un processus d'agent obtient l'autorité d'effectuer un groupe d'appels, enregistrez séparément l'identité du processus, l'heure d'approbation et l'heure de révocation, indépendamment du résultat de l'action. L'approbation explique qui avait le droit d'essayer. Elle n'établit pas que la destination a exécuté l'action.

Pour les opérations sensibles, exigez une approbation par appel pour la nouvelle tentative elle-même lorsque la première tentative a produit un résultat inconnu. Les personnes prennent une meilleure décision lorsque la fiche d'approbation indique l'intention d'origine, l'état d'envoi précédent et la méthode de récupération prévue. Une invite générique disant « autoriser l'appel API » masque précisément le fait qui devrait les inciter à ralentir.

La vue d'enquête doit montrer une chronologie, pas un tas de requêtes

L'enquêteur a besoin d'une page ou d'un résultat de requête consacré à une seule opération, qui commence par l'intention et se termine par le résultat le mieux étayé. Les journaux de requêtes triés par heure obligent l'examinateur à reconstituer les relations sous pression, souvent à travers plusieurs systèmes dont les horloges diffèrent légèrement.

Affichez l'état de l'opération en haut, mais rendez les preuves disponibles en dessous. Chaque tentative doit afficher son numéro, son état d'envoi, son parent de nouvelle tentative, sa raison, la référence d'autorité, la destination, l'empreinte de la requête, le résumé de la réponse et sa durée. Chaque observation doit indiquer ce qu'elle a vérifié et pourquoi cette preuve a modifié ou n'a pas modifié l'état.

Ne dissimulez pas les requêtes en double parce que l'effet final était sans conséquence. Une duplication inoffensive aujourd'hui peut devenir un effet coûteux après une modification de l'API ou l'ajout d'un webhook à une intégration. L'enregistrement doit permettre de distinguer « l'agent a correctement recommencé et la destination a dédupliqué » de « l'agent a envoyé deux fois la requête et a eu de la chance ».

Traitez toute modification du corps de la requête pendant la récupération comme une bifurcation explicite. L'opération d'origine reste ouverte ou reçoit son résultat résolu. L'action modifiée reçoit un nouvel identifiant d'opération et un lien tel que supersedes_operation_id. L'enregistrement dit la vérité : l'agent n'a pas simplement recommencé, il a changé ce qu'il voulait faire.

Mettez en place un test d'échec forcé avant de faire confiance à la conception. Demandez à la destination de valider une action de test connue comme idempotente, puis supprimez la réponse envoyée à l'appelant. Vérifiez que l'exécution suivante de l'agent conserve l'identifiant d'opération d'origine, utilise le même jeton de destination, journalise la première tentative inconnue, effectue le rapprochement ou la nouvelle tentative documentée et clôture l'opération avec des preuves. Si votre test ne peut pas répondre à ces questions, un incident ne le pourra pas non plus.

Le premier champ que je cherche dans le journal d'action d'un agent n'est pas un statut HTTP. C'est l'identifiant d'opération stable. Sans lui, toute enquête sur une nouvelle tentative commence par des suppositions. Avec lui, vous pouvez poser les questions importantes : que voulait faire l'agent, qu'est-ce qui a quitté la machine, qu'est-ce qui a changé entre les tentatives et quelles preuves étayent le résultat final.