Idempotence d’un workflow IA : éviter les doubles actions

Un workflow IA devient dangereux lorsqu’il sait écrire, envoyer, réserver, facturer ou modifier un système et qu’une relance peut répéter cet effet. Le problème apparaît souvent après un simple délai réseau : le service cible a peut-être exécuté l’action, mais le workflow n’a pas reçu la réponse. Relancer à l’aveugle peut créer un doublon ; abandonner peut laisser l’opération incomplète.

L’idempotence consiste à rendre la répétition d’une même opération logique sans effet supplémentaire. Elle ne se résume ni à désactiver les retries, ni à dédupliquer deux lignes identiques, ni à ajouter un identifiant aléatoire à chaque tentative. Il faut reconnaître la même intention métier, enregistrer son état avant l’effet et savoir réconcilier un résultat inconnu.

Le protocole présenté ici convient à une automatisation Python, un outil no-code, une file de messages ou un agent qui appelle une API. Il s’applique d’abord à un effet borné. Il ne promet pas une garantie universelle « exactement une fois » dans tous les systèmes distribués.

Réponse en bref

Pour rendre un workflow IA idempotent :

1. nommez l’effet métier à protéger ;
2. définissez ce qui constitue la même opération logique ;
3. construisez une clé stable à partir d’identifiants non sensibles ;
4. enregistrez cette clé avant l’effet externe ;
5. bloquez les exécutions concurrentes portant la même clé ;
6. distinguez prepared, executing, succeeded, failed et unknown ;
7. propagez la clé au service cible lorsqu’il l’accepte ;
8. renvoyez le résultat déjà obtenu pour une opération réussie ;
9. réconciliez un résultat inconnu avant toute nouvelle tentative ;
10. testez les délais, doubles clics, reprises et courses concurrentes.

La clé identifie l’opération, pas la tentative. Deux retries gardent la même clé. Une demande réellement modifiée reçoit une nouvelle version et donc une nouvelle clé.

Le scénario qui révèle le problème

Imaginez un workflow qui prépare un email, attend une validation puis appelle un service d’envoi.

09:00:00  envoi demandé
09:00:02  le service accepte le message
09:00:03  la réponse réseau est perdue
09:00:10  le workflow conclut à un timeout
09:01:00  une reprise automatique recommence l’appel

Le timeout ne dit pas que l’envoi a échoué. Il dit seulement que le client ne connaît pas le résultat. Le système se trouve dans un état ambigu.

Cette ambiguïté existe aussi pour :

• une réservation dont la confirmation n’est jamais revenue ;
• une écriture CRM suivie d’un crash ;
• un paiement reçu avant la perte de la connexion ;
• un fichier créé, mais non enregistré dans le journal local ;
• un message retiré d’une file puis redistribué après la perte d’un verrou ;
• une publication déclenchée par un double clic.

Microsoft documente ce cas dans Azure Service Bus : une opération peut être rejouée après une exécution réussie mais non acquittée. La détection de doublons côté envoi ne remplace pas un traitement idempotent côté réception.

Définir l’effet avant la clé

La question n’est pas « ce JSON est-il identique ? ». Elle est « quelle action le métier considère-t-il comme unique ? ».

Workflow	Effet logique à protéger	Mauvaise unité
invitation	envoyer une invitation pour une campagne et un destinataire	chaque clic sur le bouton
réservation	attribuer un créneau à une demande	chaque appel HTTP
CRM	créer une fiche pour une demande reçue	chaque passage du scénario
export	produire la version d’un rapport	chaque processus Python
publication	publier une version d’un contenu	chaque tentative de déploiement

Une clé trop large bloque des opérations légitimes. Par exemple, client-42 empêcherait toute nouvelle action pour ce client. Une clé trop étroite, comme l’identifiant aléatoire de la tentative, ne reconnaît jamais un doublon.

Écrivez une phrase testable :

Pour une demande, une version approuvée et une action données, le workflow ne produit qu’un seul effet final.

Cette phrase détermine les composants de la clé et les tests.

Construire une clé d’idempotence stable

Une clé applicative peut réunir :

workflow + action + objet_metier + version_autorisee + destination_logique

Exemple synthétique :

support.reply.send:ticket_584:v3:channel_email

La version est importante. Si la personne corrige le destinataire ou le contenu après approbation, l’opération n’est plus identique. Le système doit exiger une nouvelle validation et produire une nouvelle clé.

Respectez cinq propriétés :

• stable : un retry reconstruit exactement la même valeur ;
• déterministe : les mêmes composants donnent la même clé ;
• bornée : elle identifie une seule action métier ;
• non sensible : aucun email, nom, secret ou contenu brut ;
• versionnée : une modification significative ne réutilise pas l’ancienne autorisation.

Un UUID peut convenir si le premier composant du système le crée une fois et le transmet à toutes les tentatives. Générer un nouvel UUID dans chaque worker détruit la déduplication.

Stripe illustre une autre règle importante : le service compare les paramètres d’une requête avec ceux de la première utilisation de la clé et refuse une réutilisation incohérente. La clé ne doit jamais servir à faire passer silencieusement une autre opération.

Le registre d’opérations à cinq états

La mémoire doit être persistante. Une variable dans le processus ou le cache d’une seule instance disparaît au redémarrage et ne protège pas deux workers.

État	Sens	Nouvelle tentative
prepared	opération enregistrée, effet non commencé	peut être exécutée selon les contrôles
executing	un worker possède temporairement l’opération	attendre ou examiner l’expiration
succeeded	effet confirmé et résultat enregistré	retourner le résultat existant
failed	échec explicite avant effet ou échec final connu	corriger ou créer une nouvelle tentative selon la règle
unknown	l’effet a peut-être eu lieu	réconcilier avant de recommencer

Le registre minimal contient :

operation_key
workflow_version
payload_fingerprint
state
attempt_count
lease_until
target_reference
result_reference
last_error_code
created_at
updated_at

L’empreinte sert à détecter une modification inattendue. Elle ne remplace pas l’objet métier et ne doit pas être calculée sur un contenu contenant des secrets si sa conservation crée un risque inutile.

AWS Powertools utilise le même type d’idée avec une couche persistante, une clé, un état en cours, un état terminé et des expirations. Sa documentation montre aussi qu’un enregistrement INPROGRESS empêche deux invocations portant la même charge d’exécuter simultanément la fonction.

L’algorithme de réservation d’une opération

Le cœur doit être atomique : lire puis écrire en deux commandes indépendantes laisse deux workers passer ensemble.

1. calculer operation_key et payload_fingerprint
2. tenter de créer l’enregistrement prepared avec une contrainte UNIQUE
3. si succeeded, retourner result_reference
4. si executing et lease valide, répondre « déjà en cours »
5. si la clé existe avec une autre empreinte, refuser
6. acquérir atomiquement un lease et passer à executing
7. effectuer ou reprendre les contrôles
8. appeler le service cible avec la même clé si possible
9. enregistrer succeeded avec la référence du résultat
10. si le résultat est ambigu, enregistrer unknown

Une contrainte unique en base, une écriture conditionnelle ou une transaction adaptée vaut mieux qu’une comparaison effectuée seulement dans le code applicatif.

Le lease doit expirer, sinon un crash laisse l’opération bloquée pour toujours. Son expiration n’autorise toutefois pas automatiquement à répéter l’effet : après un timeout externe, l’état reste unknown jusqu’à réconciliation.

Propager la protection jusqu’au service cible

Une déduplication locale empêche deux workers coopératifs de lancer la même action. Elle ne protège pas contre un autre client, une reprise manuelle hors workflow ou un crash entre l’effet distant et la mise à jour locale.

Lorsque l’API cible accepte une clé d’idempotence :

• transmettez la même clé à chaque retry ;
• conservez la référence de requête retournée ;
• respectez la durée de validité documentée ;
• ne modifiez pas les paramètres sous la même clé ;
• vérifiez la sémantique précise des erreurs.

Le RFC 9110 définit une méthode HTTP comme idempotente lorsque plusieurs requêtes identiques ont le même effet voulu qu’une seule. Il précise que PUT, DELETE et les méthodes sûres le sont par définition, mais que POST ne doit pas être répété automatiquement sans mécanisme supplémentaire ou preuve que la première opération n’a pas été appliquée.

Le verbe HTTP ne suffit pas à protéger un workflow métier. Un endpoint PUT mal conçu peut déclencher deux emails ; un POST muni d’une clé stable peut être rendu répétable selon le contrat du fournisseur.

Distinguer reprise, répétition et nouvelle demande

Ces trois actions ne partagent pas la même clé.

• reprise : poursuivre une opération interrompue, avec la même clé et la même version ;
• répétition : rejouer volontairement le même contenu comme un nouvel effet, avec une nouvelle opération ;
• nouvelle demande : paramètres ou autorisation modifiés, donc nouvelle version.

Une interface doit les nommer. Un bouton « Relancer » est ambigu : relancer le calcul, renvoyer l’email ou créer une nouvelle campagne ?

Affichez plutôt :

• reprendre la vérification ;
• vérifier le statut chez le fournisseur ;
• créer un nouvel envoi ;
• dupliquer comme nouveau brouillon.

Choisir une stratégie selon l’erreur

Toutes les erreurs ne méritent pas un retry.

Famille	Exemple	Décision proposée
validation	champ obligatoire absent	corriger, aucune répétition automatique
authentification	accès expiré	arrêter et rétablir l’accès selon la procédure
autorisation	droit insuffisant	arrêter, ne pas contourner
limite de débit	HTTP 429	attendre selon le fournisseur, même clé si le contrat le prévoit
indisponibilité	HTTP 502 ou 503	répétition bornée si l’opération est idempotente
réseau	timeout sans réponse	état unknown, réconciliation prioritaire
refus métier	destinataire invalide	échec final connu, correction nécessaire
conflit de clé	paramètres différents	refuser et créer une nouvelle version si légitime

Le délai exponentiel avec une part aléatoire réduit les rafales, mais il ne rend pas l’action idempotente. Il espace seulement les tentatives.

Fixez un budget : nombre maximal de retries, durée totale, erreurs admises et point de passage au traitement manuel. Une boucle infinie peut amplifier une panne, saturer une API et produire des effets difficiles à compter.

Réconcilier l’état inconnu

La réconciliation cherche une preuve de l’effet sans le répéter.

Selon le service, elle peut :

• interroger le statut par identifiant d’opération ;
• rechercher la référence métier unique ;
• lire un webhook signé déjà reçu ;
• vérifier une ressource créée ;
• comparer l’état attendu dans le système cible ;
• demander une décision manuelle si aucune lecture fiable n’existe.

Le modèle de requête asynchrone de Microsoft propose de répondre rapidement avec une ressource de statut. Si le client soumet une clé déjà connue, le serveur peut retourner cette ressource au lieu d’ajouter un second travail à la file.

Une absence dans une liste partielle n’est pas toujours une preuve d’échec. La requête de réconciliation doit utiliser une clé ou une référence conçue pour cela.

Concurrence, files et effets multiples

Deux exécutions peuvent démarrer à quelques millisecondes d’écart. Testez le cas avec une vraie écriture conditionnelle, pas seulement avec deux appels séquentiels.

Lorsque le workflow produit plusieurs effets, ne les cachez pas sous un seul statut global. Par exemple :

operation: dossier_42:v5
  effect 1: créer le PDF       succeeded
  effect 2: enregistrer le PDF succeeded
  effect 3: envoyer le lien    unknown
  effect 4: écrire dans le CRM prepared

Chaque effet possède sa clé dérivée et son état. Le workflow peut ainsi reprendre à l’étape correcte sans recréer le fichier.

Pour une base et une file qui ne partagent pas la même transaction, le modèle d’outbox consiste à enregistrer la modification métier et le message à publier dans la même transaction locale. Un relais publie ensuite l’outbox. Le consommateur reste idempotent, car une livraison répétée reste possible.

Implémenter dans un outil no-code

Un scénario visuel a besoin du même contrat :

1. normaliser l’entrée ;
2. calculer ou recevoir la clé ;
3. réserver atomiquement l’opération dans un stockage persistant ;
4. brancher selon l’état existant ;
5. exécuter l’effet ;
6. enregistrer la référence distante ;
7. traiter séparément le timeout ;
8. alerter après épuisement du budget.

Un tableur partagé peut servir à un prototype séquentiel, mais il protège mal contre les écritures concurrentes et les délais. Pour un effet important, utilisez un stockage avec contrainte unique ou écriture conditionnelle.

La validation humaine dans un workflow IA explique où placer l’approbation. L’idempotence répond à une autre question : que se passe-t-il lorsque l’action approuvée revient deux fois ?

Les 12 tests avant production

1. la même demande séquentielle revient deux fois ;
2. deux workers reçoivent la même clé simultanément ;
3. le processus s’arrête avant l’appel externe ;
4. le processus s’arrête après l’effet mais avant l’enregistrement local ;
5. la réponse du service cible se perd ;
6. la charge change sous la même clé ;
7. l’approbation expire avant l’exécution ;
8. un retry arrive après l’expiration du lease ;
9. la limite de débit renvoie un délai ;
10. un webhook identique arrive plusieurs fois ;
11. un effet réussit et le suivant échoue ;
12. un opérateur demande volontairement une nouvelle action identique.

Pour chaque test, observez le nombre d’effets métier, pas seulement le nombre de réponses HTTP. Le critère principal est : un seul effet pour une opération logique, ou un état explicite qui bloque la répétition lorsque le résultat est inconnu.

Mesurer le fonctionnement

Suivez au minimum :

• opérations créées ;
• doublons reconnus ;
• appels évités ;
• conflits d’empreinte ;
• opérations bloquées en cours ;
• états inconnus ;
• temps de réconciliation ;
• retries par famille d’erreur ;
• passages manuels ;
• doublons métier constatés malgré le contrôle.

Le dernier indicateur compte le plus. Un taux élevé de déduplication peut simplement révéler une interface qui soumet trop souvent la même demande.

Reliez ces métriques à une journalisation d’agent IA centrée sur les événements sans enregistrer de secret ni de contenu brut par défaut.

Limites

L’idempotence est définie dans un périmètre. Elle n’annule pas un effet déjà produit, ne garantit pas l’ordre global des événements et ne remplace pas une transaction lorsque plusieurs écritures doivent réussir ensemble.

Un registre local ne peut pas toujours déterminer si un service externe a exécuté une action. Si le fournisseur ne propose ni clé d’idempotence, ni identifiant de requête, ni lecture de statut fiable, certaines pannes exigent un traitement manuel.

Les durées de conservation, expirations, verrous et stratégies de retry dépendent du processus. Une clé expirée trop tôt laisse repasser un doublon tardif ; une clé conservée trop longtemps peut bloquer une opération légitime et accumuler des données inutiles.

Les exemples de Stripe, AWS et Azure illustrent des contrats propres à leurs services. Vérifiez toujours la documentation du connecteur réellement utilisé et testez le système complet dans sa configuration de production.

À propos de l’auteur

Je suis Ayoub Kahouadji, développeur Python, formateur et consultant IA. Je conçois des workflows où une reprise doit pouvoir être expliquée, testée et arrêtée avant de produire un double effet.

Prochaine étape

Choisissez une seule action externe de votre workflow. Écrivez sa phrase d’unicité, construisez la clé, créez le registre à cinq états puis exécutez les tests 2, 4 et 5. Le protocole de file d’erreurs et de reprise d’un workflow IA complète cette protection lorsque plusieurs échecs doivent être triés et rejoués. La page automatisation IA et Python présente l’accompagnement pour intégrer ces contrôles à un système réel.