Timeout réseau sur un appel LLM. Tu retry. Mais le premier appel avait peut-être réussi côté serveur — tu viens de payer deux fois, et si le LLM déclenchait un tool send_email, le client a reçu deux mails. L'idempotence n'est pas un détail.
Où ça casse
La parade : clé d'idempotence
Le client génère une clé unique par intention (pas par tentative) et l'envoie à chaque essai. Le serveur — ou ta couche métier — déduplique sur cette clé : si la clé a déjà été traitée, renvoyer le résultat mémorisé sans ré-exécuter.
- Les APIs LLM sérieuses acceptent un header
Idempotency-Key: l'utiliser systématiquement. - Pour les tools à effet de bord, stocker
(idempotency_key → résultat)côté ta DB et vérifier avant d'agir. - La clé doit survivre au retry : la générer avant la boucle, pas dedans.
Règle simple : tout appel qui déclenche un paiement, un envoi, une écriture externe doit porter une clé d'idempotence. Le reste (lecture pure) s'en passe.
FAQ
Pourquoi un simple retry après timeout est-il dangereux ?
Le premier appel a pu réussir côté serveur (et déclencher un effet de bord comme un envoi d'email) ; retenter rejoue cet effet une seconde fois.
Comment garantir l'idempotence ?
Le client génère une clé unique par intention (pas par tentative) et l'envoie à chaque appel pour que le serveur déduplique.
Ce problème concerne-t-il uniquement les tools avec effets de bord ?
C'est là que le risque est le plus visible, mais la même clé protège aussi contre le double comptage de coûts.