Restauration automatisée des effets de bord d'agent

La restauration d'un agent peut rétablir du code, de la configuration ou certaines données applicatives. Elle ne peut pas faire oublier une requête à une autre organisation, retirer un e-mail distribué d'une boîte de réception ou prétendre qu'un prélèvement par carte n'a jamais atteint un processeur de paiement. Les équipes qui qualifient toutes ces opérations de « restauration » mettent en place un contrôle rassurant qui échoue justement lorsque les conséquences comptent.

Une conception sûre sépare quatre mécanismes : les instantanés applicatifs, les retours Git, la récupération de base de données et les actions compensatoires. Chacun a sa propre limite. Toute action qui franchit la limite de l'application a besoin de sa propre validation, de preuves, d'une règle de nouvelle tentative et d'un chemin de récupération avant que l'agent ne l'exécute. Si personne ne peut décrire ce chemin en une phrase, l'action n'est pas prête à être exécutée sans surveillance.

La restauration a quatre sens distincts

La restauration n'est utile que lorsque l'équipe nomme l'état qu'elle rétablira et celui qu'elle ne peut pas modifier. Ce terme masque souvent quatre mécanismes aux garanties très différentes.

Un instantané rétablit une version capturée d'une application ou d'un espace de travail. Selon le produit, cet instantané peut inclure du code généré, de la configuration et un état géré sélectionné. Il ne dit rien des services externes, sauf si le contrat de l'instantané les inclut explicitement.

Un retour Git enregistre un nouveau commit dont les modifications inversent un commit précédent. Il répare l'historique du code source sans le supprimer. Il ne contacte pas les services que l'ancien code a appelés pendant son exécution.

La récupération de base de données modifie les enregistrements détenus par la base. L'annulation d'une transaction écarte les écritures non validées d'une seule transaction. Restaurer une sauvegarde ou utiliser la récupération à un instant donné est une opération bien plus vaste qui ramène un cluster de bases de données vers un état antérieur. Aucune de ces opérations ne rapproche automatiquement les systèmes situés hors de cette base.

Une action compensatoire produit un nouvel effet destiné à compenser un ancien. Un remboursement compense un paiement capturé. Une demande d'annulation compense une commande. Un e-mail correctif peut atténuer l'effet d'un e-mail erroné, sans supprimer le premier message. La compensation préserve cette vérité inconfortable : l'action initiale a eu lieu.

J'utilise un tableau de responsabilité des effets lors des revues de conception, car il impose des réponses précises :

La dernière colonne compte le plus. Une opération inverse ne prouve pas que l'original a disparu. Les pistes d'audit, copies chez les destinataires, écritures de règlement, webhooks et travaux physiques peuvent persister.

Un retour de code modifie le programme, pas le passé

Un retour de code évite ou modifie un comportement futur. Il n'inverse pas le comportement que l'ancienne version a déjà produit. Cela reste vrai que l'équipe utilise Git, un instantané de plateforme ou un retour de déploiement.

La documentation Git décrit git revert comme l'enregistrement de commits qui inversent les modifications introduites par des commits antérieurs. La formulation est exacte : Git applique un correctif inverse au contenu du dépôt. Git ne connaît pas les e-mails, paiements, ressources cloud, tickets d'assistance ou API de partenaires créés lors de l'exécution du commit restauré.

Supposons qu'un agent modifie une fonction de facturation, la déploie et l'appelle deux fois avant que la surveillance ne détecte le défaut. Restaurer le commit peut empêcher la mauvaise fonction de s'exécuter à nouveau. Cela laisse deux tentatives de paiement chez le processeur. Si la base locale n'a enregistré qu'une tentative, le retour peut même compliquer l'enquête en supprimant le chemin de code qui interprétait la seconde réponse.

Un retour de déploiement a la même limite. Renvoyer le trafic vers une version antérieure rétablit le comportement exécutable. Les requêtes déjà acceptées par la version remplacée conservent leurs conséquences. Des tâches en file d'attente peuvent aussi survivre au déploiement et appliquer d'anciennes hypothèses à la version restaurée.

Avant de revenir en arrière, préservez les preuves opérationnelles produites par l'ancienne version :

• Identifiant de déploiement et commit source
• Identifiants d'exécution et d'intention de l'agent
• Identifiants des messages de file et état du bail
• Identifiants de requêtes externes
• Réponses et horodatages du fournisseur

Arrêtez ensuite les nouvelles exécutions, rapprochez les opérations incomplètes et restaurez le code. Revenir en arrière avant de poser les questions détruit souvent le moyen le plus simple de comprendre quels effets se sont échappés.

Un instantané peut couvrir davantage qu'un commit Git, mais la même règle s'applique. Son contrat doit indiquer exactement quelles ressources il contient. S'il contient du code et de la configuration, appelez-le mécanisme de récupération du code et de la configuration. Ne le présentez pas comme une annulation universelle par une formulation optimiste dans l'interface.

La récupération de base de données a un rôle plus restreint qu'on ne le pense

La récupération de base de données rétablit l'état de la base, pas la réalité métier chez tous les participants à une transaction. Une transaction peut être atomique dans une base de données alors que l'opération globale reste répartie entre plusieurs systèmes.

Prenons cette séquence :

1. L'agent insère une ligne de facture.
2. Il appelle une API de paiement.
3. Le processeur accepte le prélèvement.
4. La validation de la base échoue.

L'annulation locale supprime la ligne de facture. Le prélèvement existe toujours. Relancer toute l'opération sans rapprochement peut débiter à nouveau le client. C'est l'échec classique de double écriture : l'application a tenté de rendre atomique une action métier entre des systèmes qui ne partagent pas de coordinateur de transaction.

Inverser l'ordre ne résout rien. Si l'application valide d'abord la facture et que l'appel de paiement échoue ensuite, la base contient une facture impayée. Cet état est plus facile à examiner, mais l'application a toujours besoin d'une machine à états qui distingue payment_pending, payment_confirmed, payment_failed et payment_unknown.

La documentation PostgreSQL explique que la récupération à un instant donné consiste à restaurer une sauvegarde de base puis à rejouer les journaux d'écriture anticipée jusqu'à une cible de récupération choisie. C'est une procédure d'opérateur pour récupérer un cluster de bases de données. Ce n'est pas une annulation sélective d'une exécution d'agent, et elle ne peut pas demander à un processeur de paiement ou à un service de messagerie de revenir au même horodatage.

Ramener la base en arrière peut créer un second décalage. Imaginez une restauration à 10:00 après une panne. Un fournisseur a accepté des requêtes jusqu'à 10:07, mais la base restaurée ne contient plus leurs enregistrements. Des agents qui voient des lignes « manquantes » risquent de recréer les sept minutes de travail. La récupération a donc besoin d'une phase de rapprochement externe avant la reprise des workers.

Un modèle d'outbox réduit un écart dangereux. L'application valide son changement métier et une intention d'effet dans la même transaction locale :

BEGIN;

INSERT INTO invoices (invoice_id, customer_id, status)
VALUES ('inv_2048', 'cust_91', 'payment_pending');

INSERT INTO effect_intents
  (intent_id, operation, subject_id, status)
VALUES
  ('eff_7f31', 'capture_payment', 'inv_2048', 'pending');

COMMIT;

Un worker réclame ensuite eff_7f31, appelle le fournisseur avec une valeur d'idempotence stable et enregistre le résultat. L'outbox ne rend pas l'appel externe atomique. Elle fournit une preuve durable que le travail était prévu, ce qui rend les nouvelles tentatives et le rapprochement possibles.

Les actions externes ont besoin de compensations, et certaines n'en ont pas

Un effet de bord externe a besoin d'une compensation propre au fournisseur ou d'une déclaration explicite indiquant qu'aucune compensation pertinente n'existe. Traiter toutes les actions comme réversibles est plus dangereux que reconnaître que certaines nécessitent une validation.

L'e-mail est l'exemple le plus simple. Avant que le fournisseur n'accepte le message, l'application peut annuler une tâche en file d'attente. Après acceptation, le fournisseur peut permettre une annulation pendant une courte étape interne, mais il n'existe aucune garantie générale de rappel auprès des destinataires et des systèmes de messagerie. Après distribution, un second message peut corriger l'information, sans effacer le premier. Les données sensibles, notifications légales et atteintes à la réputation restent exposées.

Les paiements ont plusieurs états que les équipes regroupent souvent sous le terme « débité ». Une autorisation réserve une capacité de dépense. Une capture demande le mouvement des fonds au titre de cette autorisation. Une annulation peut libérer une autorisation qui n'est pas encore réglée. Un remboursement crée une écriture financière ultérieure qui rend l'argent après la capture. Ces opérations ont des délais, frais, autorisations et impacts client distincts. Un outil générique undo_payment masque les informations dont l'agent a besoin pour agir en sécurité.

D'autres API coopèrent encore moins. Une requête peut commander du stock, provisionner une infrastructure, publier du contenu, accorder un accès, expédier un colis ou amener une personne à commencer un travail. Un endpoint DELETE ne prouve pas la réversibilité. Supprimer une ressource peut laisser des journaux d'audit, des données copiées, des notifications, des ressources dépendantes ou des conséquences physiques.

Classez les compensations selon ce qu'elles peuvent réellement accomplir :

• Un inverse local exact ramène un état contrôlé à sa valeur antérieure.
• Une annulation par le fournisseur arrête un travail non terminé.
• Une compensation financière crée un remboursement ou un avoir.
• Une communication corrective reconnaît que le premier message reste visible.
• Une correction manuelle traite les effets dont le contexte ne peut pas tenir dans une règle automatisée sûre.

Une compensation peut aussi échouer. L'endpoint de remboursement peut expirer. La fenêtre d'annulation peut se fermer. L'adresse du destinataire peut rejeter la correction. Le compte utilisé par l'agent peut manquer d'autorisation. Le système doit donc suivre la compensation comme une autre opération, avec son propre identifiant d'intention, état, tentatives, preuves et politique de validation.

Ne créez pas une fonctionnalité récursive « restaurer la restauration ». Modélisez l'historique comme un registre d'actions. Si une compensation provoque une nouvelle erreur, effectuez une autre action explicite après examen de l'état actuel. L'historique est plus long, mais reste compréhensible pendant un incident.

L'idempotence évite les répétitions, mais n'inverse pas une réussite

L'idempotence protège les nouvelles tentatives contre la production d'effets prévus en double. Elle n'annule pas le premier effet réussi. Les équipes confondent régulièrement ces idées et découvrent la différence après un délai d'attente.

La RFC 9110 définit une méthode de requête idempotente par le fait que l'effet prévu de plusieurs requêtes identiques est le même que celui d'une seule requête. Elle identifie PUT, DELETE et les méthodes sûres comme idempotentes au niveau de la sémantique du protocole. POST n'est généralement pas idempotente, même si une API peut ajouter un comportement idempotent dans son propre contrat.

La nuance compte. Un DELETE idempotent peut tout de même produire une nouvelle entrée de journal, une métrique ou une réponse à chaque appel. L'implémentation de l'idempotence par un fournisseur peut aussi expirer les enregistrements, limiter les identifiants à un compte, refuser des paramètres modifiés ou ne mettre en cache que certains résultats. Lisez le contrat du fournisseur au lieu de déduire des garanties à partir d'un verbe HTTP.

Chaque intention d'effet doit recevoir une valeur d'idempotence stable avant sa première tentative. Les nouvelles tentatives pour cette même intention la réutilisent. Une nouvelle intention métier reçoit une nouvelle valeur. Ne la dérivez jamais uniquement de paramètres modifiables comme le client, le montant et la date, car deux achats légitimes peuvent partager ces valeurs.

Un délai d'attente crée un résultat inconnu, pas un échec. Suivez cette séquence :

1. Marquez la tentative outcome_unknown, sans créer d'intention de remplacement.
2. Interrogez le fournisseur à l'aide de la valeur d'idempotence ou de la référence de l'opération.
3. S'il confirme la réussite, enregistrez-la localement.
4. S'il confirme l'absence d'opération, réessayez avec la même valeur.
5. S'il ne peut pas répondre, bloquez l'opération pour rapprochement ou revue humaine.

Cette forme de réponse donne à l'agent assez d'informations pour distinguer l'acceptation de l'incertitude de transport :

{
  "intent_id": "eff_7f31",
  "attempt": 2,
  "idempotency_key": "eff_7f31",
  "transport_status": "timeout",
  "provider_status": "unknown",
  "provider_reference": null,
  "next_action": "reconcile"
}

Une valeur d'idempotence doit circuler dans les journaux, messages de file, en-têtes d'API et métadonnées du fournisseur lorsque c'est pris en charge. Si les opérateurs ne peuvent pas la rechercher des deux côtés de la limite, ils devront deviner pendant la récupération.

La validation doit intervenir à la limite de l'effet

La validation doit intervenir après que l'agent a défini l'action externe exacte et avant que la première requête irréversible ne quitte le système. Une validation au début d'une tâche générale laisse trop de latitude à l'agent pour modifier ensuite les destinataires, montants, périmètres ou outils.

« Traite le compte de ce client » n'est pas une validation suffisante pour débiter une carte ou envoyer un e-mail à tous les utilisateurs. Une validation valide décrit l'opération concrète : destinataire, montant et devise, condensat du message ou de la charge utile, compte cible, outil, expiration et nombre de tentatives autorisées. Si l'un des champs validés change, la validation ne correspond plus.

Une politique utile classe les effets selon leurs conséquences plutôt que selon l'agent ou le modèle qui les a demandés. L'accès en lecture peut tout de même exposer des données privées, mais il ne pose pas le même problème de récupération qu'une action sortante. Rédiger un e-mail est local et réversible. L'envoyer franchit la limite. Créer une proposition de paiement est local. Capturer des fonds franchit la limite.

Exigez une validation explicite pour les actions qui :

• Déplacent de l'argent ou créent une obligation financière
• Envoient des informations à une personne ou à une organisation externe
• Publient, suppriment ou divulguent des données hors d'un stockage contrôlé
• Modifient l'identité, l'accès, la propriété ou les paramètres de sécurité
• Démarrent un travail physique ou un autre processus qui ne peut pas être rappelé de façon fiable

Les actions répétitives aux conséquences limitées peuvent utiliser une validation permanente encadrée. La limite doit indiquer un montant maximal, l'ensemble des destinataires, l'outil autorisé, l'heure d'expiration, le débit et le nombre total d'opérations. « Approuvé pour la facturation » n'a aucune limite applicable.

La validation doit aussi être protégée contre la réutilisation. Liez-la à un condensat immuable de l'opération et marquez-la comme consommée lorsque la politique n'autorise qu'une exécution. Si l'exécution produit un résultat inconnu, ne demandez pas une nouvelle validation pour créer une seconde intention. Rapprochez d'abord l'intention validée.

L'écran de validation doit expliquer la réalité de la récupération en langage courant. « Ce message ne peut pas être rappelé après sa distribution » est utile. « Cette opération est réversible » est trompeur quand la récupération réelle consiste en un remboursement qui peut prendre du temps et rester inscrit sur les relevés financiers.

Les contrats d'outils doivent exposer tout le cycle de vie de l'effet

Un contrat d'outil d'agent doit décrire séparément l'intention, l'exécution, l'observation et la compensation. Une seule fonction qui produit un effet et renvoie success: true laisse trop peu de preuves pour les nouvelles tentatives, validations ou réponses aux incidents.

Le fragment de politique suivant est assez court pour être appliqué et assez précis pour être revu :

tools:
  send_email:
    effect: irreversible
    approval: required
    idempotency_field: intent_id
    evidence_field: provider_message_id
    compensation: null

  capture_payment:
    effect: compensatable
    approval: required
    idempotency_field: intent_id
    evidence_field: provider_payment_id
    compensation: refund_payment

  update_draft:
    effect: local_reversible
    approval: none
    compensation: restore_version

effect indique au planificateur quelle catégorie de récupération s'applique. approval bloque l'exécution jusqu'à l'autorisation des arguments exacts. Le champ d'idempotence permet aux nouvelles tentatives de réutiliser une même identité. Le champ de preuve indique aux opérateurs ce qui doit survivre. Le champ de compensation désigne un outil distinct au lieu de prétendre que l'appel initial peut s'exécuter à l'envers.

L'exécution doit accepter une enveloppe immuable :

{
  "intent_id": "eff_7f31",
  "operation": "capture_payment",
  "arguments": {
    "invoice_id": "inv_2048",
    "amount_minor": 12900,
    "currency": "USD"
  },
  "approval": {
    "approval_id": "apr_662",
    "scope_hash": "sha256:8b4f...",
    "expires_at": "2026-07-27T18:00:00Z"
  }
}

L'exécuteur calcule le condensat de l'opération, le compare à scope_hash, vérifie l'expiration, réserve l'intention et contacte seulement alors le fournisseur. Il stocke les métadonnées de la requête avant l'appel et la réponse après. S'il tombe en panne entre ces écritures, l'intention durable reste disponible pour le rapprochement.

L'exécuteur doit rejeter quatre situations sans improviser : des arguments modifiés, une validation expirée, la réutilisation d'une intention pour une autre opération et une tentative de compenser un effet dont la réussite n'a pas été confirmée. Les agents savent trouver des suites plausibles. Les contrôles financiers et de communication doivent préférer un arrêt visible à une supposition plausible.

Donnez à l'observation son propre outil, tel que get_payment_status(intent_id). L'observation ne doit produire aucun effet. En la séparant, l'agent peut résoudre des résultats ambigus sans recevoir l'autorisation de réessayer l'action initiale.

Une seule exécution en échec peut franchir toutes les limites de récupération

Une seule exécution d'agent peut laisser le code, les enregistrements de base et les systèmes externes à des moments différents. Examiner cet échec avant le lancement révèle les lacunes qu'un contrôle générique de restauration masque.

Supposez qu'un agent crée une application d'adhésion, déploie une modification, importe une liste de clients, prélève des cotisations annuelles et envoie des e-mails de bienvenue. La tâche paraît unifiée, mais elle franchit au moins quatre limites de récupération.

À 14:00, l'agent déploie du code qui calcule la cotisation annuelle à partir de la mauvaise colonne. À 14:02, il écrit 40 intentions de paiement et brouillons d'e-mail dans la base. À 14:03, un worker capture plusieurs paiements. À 14:04, le fournisseur de messagerie accepte des messages de bienvenue indiquant une cotisation erronée. À 14:05, la surveillance arrête le worker. Certains appels de paiement ont expiré après avoir atteint le processeur, donc l'état local ne révèle pas s'ils ont réussi.

Restaurer l'instantané de code de 13:59 arrête le calcul erroné lors des exécutions futures. Cela ne modifie pas la cotisation copiée dans les intentions existantes. Restaurer le commit Git documente la correction du code source, avec la même limite.

Restaurer la base à 13:59 supprimerait les enregistrements locaux d'intentions qui contiennent les références du fournisseur et les valeurs d'idempotence. Cela aggraverait le décalage externe. La meilleure action sur la base est une correction logique : préserver les intentions, marquer les opérations incertaines pour rapprochement et ne corriger les lignes qu'après comparaison avec l'état du fournisseur.

L'équipe de réponse doit ensuite agir selon la catégorie d'effet. Elle interroge chaque paiement incertain avec son identité d'opération stable. Les captures confirmées passent en revue de remboursement, les tentatives échouées sont clôturées sans nouvelle tentative et les tentatives non résolues restent bloquées. Les e-mails distribués reçoivent une correction soigneusement validée. Les messages en file qui n'ont pas atteint le fournisseur sont annulés. Chaque compensation reçoit une nouvelle intention liée à l'originale.

Cet exemple montre aussi pourquoi la compensation automatique peut être dangereuse. Si le système rembourse immédiatement chaque enregistrement local payment_unknown, il peut effectuer des remboursements pour des paiements inexistants ou appeler un endpoint de remboursement avec une mauvaise référence. S'il renvoie chaque e-mail manquant après une récupération de base, les destinataires peuvent recevoir des doublons. Le rapprochement doit précéder la compensation dès que l'état local et celui du fournisseur divergent.

L'exécution est terminée seulement lorsque chaque intention atteint un état terminal tel que succeeded, confirmed_failed, compensated ou manual_exception. « L'application a été restaurée » ne décrit que la première partie de l'incident.

La récupération ne fonctionne que si les preuves survivent

Les contrôles de récupération échouent lorsqu'une restauration supprime les enregistrements nécessaires pour déterminer ce qui s'est passé. Conservez un registre d'effets en ajout seul, hors de l'état applicatif que les instantanés ou restaurations de routine peuvent remplacer, et gardez suffisamment de preuves du fournisseur pour rapprocher chaque opération.

Le registre doit consigner la création de l'intention, le condensat des arguments, la validation, le bail d'exécution, la tentative, le résultat de transport, la référence du fournisseur, l'état observé chez le fournisseur et les liens de compensation. Limitez les modifications aux transitions d'état au lieu de laisser les agents écraser les anciennes entrées. Les corrections doivent ajouter des événements plutôt que modifier l'historique.

Surveillez les états non résolus, pas uniquement les erreurs explicites. Un outcome_unknown qui reste dix minutes peut être plus dangereux qu'un refus clair, car un opérateur risque de le relancer manuellement. Alertez aussi lorsqu'une validation expire pendant l'exécution, qu'une valeur d'idempotence apparaît avec un condensat d'arguments différent ou qu'une compensation échoue.

Organisez des exercices de récupération avec des points de défaillance volontairement difficiles. Arrêtez un worker après que le fournisseur a accepté une requête mais avant l'écriture locale de la réussite. Restaurez les données applicatives depuis un instantané antérieur en préservant le registre d'effets. Faites expirer une validation entre la planification et l'exécution. Rendez l'API d'observation indisponible. L'exercice réussit lorsque le système s'arrête, rapproche les états et expose la décision non résolue sans dupliquer l'effet.

Avec Koder.ai, considérez ses instantanés et sa restauration comme la couche de récupération applicative, puis concevez des contrôles distincts pour l'historique de la base de données et chaque action externe que l'application peut déclencher. L'export du code source, les contrôles de déploiement et la restauration aident à rétablir le logiciel, tandis que les contrats d'outils de l'application restent responsables des validations et des compensations.

Un bouton de restauration doit indiquer sa limite à côté du bouton : code, configuration, données gérées ou effets externes. Si l'interface ne peut pas formuler cette phrase avec précision, elle ne doit pas promettre de restauration. Le contrôle honnête paraît peut-être moins magique, mais il donne à l'équipe d'incident ce dont elle a besoin à 2 heures du matin : un compte rendu fiable de ce qui a changé, de ce qui s'est échappé et de l'action qu'il est sûr d'entreprendre ensuite.