Agent IA et API : éviter d’écraser une modification concurrente

Un agent lit une fiche à la révision 7. Pendant qu'il prépare sa modification, une personne l'enregistre à la révision 8. Si l'agent remplace la fiche sans condition, il peut effacer ce travail. Une écriture conditionnelle permet au serveur de détecter que la décision repose sur une version dépassée.

Une lecture reste une observation à un instant donné

Le problème concerne tous les clients, humains ou logiciels. Rafraîchir juste avant d'écrire réduit parfois l'écart, mais ne supprime pas la possibilité d'un changement entre la lecture et l'enregistrement.

Un agent peut conserver une représentation dans son contexte pendant plusieurs étapes. Si cette représentation vient déjà d'une projection en retard, l'écart avec l'état de référence peut être plus grand.

Le serveur doit donc vérifier l'hypothèse sur laquelle repose la modification au moment où il l'applique.

Faire voyager la version avec la demande

Le client reçoit une révision avec les données. Il renvoie cette révision lorsqu'il demande une modification. Le serveur compare la valeur attendue à la version courante dans l'opération qui réalise l'écriture.

Si les versions diffèrent, il refuse la modification au lieu de remplacer silencieusement les données. C'est une forme de contrôle de concurrence optimiste.

Le contrat peut employer un champ applicatif ou les mécanismes HTTP. Avec un validateur fort ETag: "revision-7", le client peut envoyer If-Match: "revision-7". Si cette précondition n'est plus satisfaite, la réponse HTTP prévue est 412 Precondition Failed.

Une API utilisant sa propre révision dans le corps peut représenter un conflit applicatif par 409 Conflict, comme dans le schéma. Les deux conventions doivent être documentées sans confondre leur rôle.

Après un conflit, réexaminer la modification

1. Relire la ressource et sa nouvelle révision.
2. Comparer son état avec celui qui a servi à préparer la modification.
3. Vérifier que la demande reste pertinente et autorisée.
4. Préparer une nouvelle modification, ou demander un arbitrage si les changements se contredisent.
5. Envoyer cette nouvelle demande avec la révision relue.

Il ne suffit pas de remplacer « 7 » par « 8 » dans l'ancienne requête. Cela présenterait une décision préparée sur l'ancien état comme si elle avait été prise sur le nouveau.

Une fusion automatique peut convenir pour des changements indépendants. Elle doit être définie et vérifiable. Dans les autres cas, le conflit doit rester visible.

Donner au client les informations pour poursuivre

Une erreur utile identifie la ressource, le type de conflit et la manière de relire son état. Le format Problem Details de la RFC 9457 peut fournir une structure commune aux erreurs d'API.

La réponse ne doit pas exposer des données auxquelles le client n'a pas droit. Un lien vers une lecture autorisée peut être préférable à l'inclusion de toute la ressource.

Après une réussite, renvoyer l'état actualisé et son validateur simplifie la suite. Une API peut aussi choisir un accusé et un lien de lecture. Le contrat doit permettre au client d'obtenir la version utile à sa prochaine opération.

Des actions hypermédia peuvent préciser les possibilités actuelles : modifier, annuler ou consulter un résultat. Elles facilitent le parcours, sans remplacer les contrôles serveur.

Traiter séparément les répétitions et la concurrence

Le contrôle de version empêche une écriture fondée sur un état dépassé. L'idempotence évite qu'une même opération répétée produise un effet supplémentaire. Les deux problèmes peuvent apparaître dans le même parcours.

Si la réponse à une écriture réussie se perd, le client ne sait pas encore si elle a été appliquée. Un identifiant d'opération ou un moyen de consulter son résultat peut alors éviter une reprise ambiguë.

Vérifier le parcours avec deux clients

Faites lire la même version par deux clients. Enregistrez avec le premier, puis tentez l'ancienne modification avec le second. Vérifiez le refus, le contenu de l'erreur et la possibilité de préparer une nouvelle demande.

Testez aussi une réponse perdue après réussite et une lecture issue d'une projection en retard. L'objectif est que le client distingue ce qui a réussi, ce qui a été refusé et ce qui doit être réexaminé.

Sources

• H. T. Kung et J. T. Robinson, On Optimistic Methods for Concurrency Control, ACM TODS 6(2), 1981.
• W3C, Editing the Web: Detecting the Lost Update Problem Using Unreserved Checkout, 1999.
• RFC 9110, HTTP Semantics, §13 Conditional Requests.
• RFC 9457, Problem Details for HTTP APIs, 2023.
• Anthropic, Effective context engineering for AI agents, 2025.