Un client dit au téléphone : « Oui, mardi à 14 h me convient. » L’agent envoie la réservation. L’API du calendrier ne répond pas avant le timeout.
La réservation existe-t-elle ?
L’agent ne le sait pas. Il recommence. Cette fois, l’API confirme le succès. Plus tard, deux rendez-vous apparaissent : la première requête avait également été exécutée, seule sa réponse s’était perdue.
Le modèle avait compris. Le créneau était bon. Le retry était logique. Pourtant le résultat métier est faux.
L’idempotence permet de redemander la même opération sans créer un deuxième effet réel.
L’idempotence des agents IA commence au niveau métier
Une API voit des requêtes. L’entreprise voit des opérations.
« Réserver le client 4711 le 17 août à 14 h pour les pneus » représente une seule intention. Trois transmissions réseau ne devraient pas devenir trois rendez-vous.
Stripe documente les clés d’idempotence pour ce type de comportement : le client associe une clé stable à une opération, afin qu’une répétition ne recrée pas l’effet. AWS souligne également l’intérêt de participants idempotents dans les workflows Saga, où une étape peut être rejouée après une panne.
Fait confirmé : les opérations idempotentes sont un pattern établi pour gérer des retries sans dupliquer l’effet.
Recommandation : identifiez l’opération métier, pas seulement le paquet réseau.
Les doublons ne viennent pas uniquement des timeouts
Un utilisateur clique deux fois. Un webhook est livré à nouveau. Un worker exécute le write mais plante avant de marquer la tâche comme terminée. Un salarié traite manuellement un dossier pendant une panne et l’ancienne queue le rejoue plus tard.
Avec un agent, deux phrases différentes peuvent également exprimer la même action. « Prenez mardi à deux heures » et « Oui, le créneau de mardi me va » ne sont pas deux réservations.
Créer une nouvelle UUID à chaque tentative ne protège donc pas. Si chaque retry possède une nouvelle clé, le système cible le considère comme une nouvelle opération.
La clé doit être rattachée à un contexte stable : ID du dossier + action, client + demande de réservation + créneau, facture + étape de paiement, ticket + changement de statut.
Un flow d’idempotence simple
La mise en œuvre peut rester lisible.
- Définissez l’opération unique. Qu’est-ce qui ne doit arriver qu’une fois ?
- Créez une clé stable. Elle survit aux retries du modèle, du réseau et de la queue.
- Vérifiez avant d’exécuter. Cette clé est-elle déjà en traitement ou terminée ? L’objet cible existe-t-il ?
- Enregistrez le résultat. ID de réservation, paiement ou objet créé restent liés à l’opération.
- Traitez le timeout comme un état inconnu. Vérifiez avant de recommencer.
- Envoyez l’ambiguïté dans une file d’exception. Si le commit reste incertain, on contrôle au lieu de dupliquer.
Lorsque l’API cible supporte nativement les clés d’idempotence, profitez-en. Sinon, l’orchestrateur peut conserver l’état, à condition de gérer correctement concurrence et crash.
Le vrai casse-tête : téléphone plus WhatsApp
Le client appelle, ne reçoit pas encore de confirmation et écrit sur WhatsApp deux minutes après. Deux agents, deux sessions, même besoin possible.
Ici, une clé d’API ne suffit plus. Il faut une déduplication métier basée sur des signaux : client authentifié, prestation, lieu, créneau et proximité temporelle.
Mais la prudence reste importante. Un client peut avoir deux véhicules. Un hôtel peut recevoir une demande pour deux chambres.
Exemple, pas règle universelle : deux demandes identiques du même client à trois minutes d’intervalle peuvent être signalées comme doublon possible et reliées au même dossier, sans supprimer automatiquement la seconde.
En cas de doute, un humain tranche mieux qu’un algorithme trop agressif.
Le pilote minimum doit provoquer les répétitions
Faites en sorte que le premier write réussisse mais que la réponse soit perdue. Livrez deux fois le même webhook. Lancez deux workers en parallèle. Traitez un job manuellement avant le replay.
Mesurez les doublons par 1 000 opérations, les retries qui conservent la même clé, les opérations au statut de commit inconnu, le temps de résolution des exceptions, les faux doublons et les actions externes dont l’ID résultat reste lié au dossier initial.
Viser zéro doublon réel est un bon objectif d’exploitation, pas une promesse que toute race condition est impossible.
Conclusion : l’idempotence ne corrige pas l’intelligence du modèle. Elle corrige la réalité des systèmes : messages répétés, réseaux imparfaits, utilisateurs pressés et canaux qui se chevauchent. Une intention qui ne doit produire qu’un effet a besoin d’une identité stable jusqu’au bout.
Ajoutez un journal d’intention séparé du simple log technique. Il relie la demande métier d’origine à la clé d’idempotence, au résultat du système cible et aux éventuelles tentatives. Ainsi, après un timeout, l’agent ne demande pas seulement « l’appel API a-t-il répondu ? », mais « cette intention a-t-elle déjà produit l’effet attendu ? ».
Pour une réservation, le résultat utile est par exemple l’ID de rendez-vous. Pour un e-mail, c’est l’ID du message envoyé. Pour une écriture CRM, c’est l’identifiant de l’objet et sa version. Conserver ce lien permet aussi à un humain de reprendre un cas sans lancer involontairement une deuxième action.
La durée de conservation de la clé doit correspondre au processus. Une fenêtre de cinq minutes peut être suffisante pour un webhook très local, mais trop courte pour une file qui peut être rejouée le lendemain. La règle doit venir du cycle de vie métier, pas d’une valeur copiée d’un exemple technique.
Le mode dégradé a besoin de cette protection. Le rapprochement vérifie ensuite les deux systèmes.
Sources
FAQ
L’idempotence concerne-t-elle uniquement les paiements ?
Non. Réservations, commandes, messages, CRM et tickets peuvent tous être dupliqués.
Une UUID aléatoire par requête suffit-elle ?
Non si le retry en crée une nouvelle. La même opération métier doit conserver la même clé.
Si l’API n’a pas d’idempotency key ?
L’orchestrateur ou une base de données peut gérer l’état et empêcher une deuxième exécution.
Peut-on détecter automatiquement les doublons entre canaux ?
Partiellement. Des demandes proches peuvent aussi être deux vrais besoins ; les cas ambigus doivent être revus.
Un timeout signifie-t-il que l’action a échoué ?
Non. Il signifie souvent que le résultat est inconnu. Vérifiez l’état avant de répéter.