Article

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

Un agent peut écrire à partir d’une ancienne version. Une précondition vérifiée par le serveur permet de détecter le conflit et de reprendre sur un état relu.

Un agent lit la fiche d’un client à la révision 7 et prépare une modification. Pendant ce temps, une conseillère enregistre un changement sur la même fiche, qui passe à la révision 8. Si l’agent écrit sans condition, il peut effacer ce travail sans que personne le voie. Une écriture conditionnelle l’évite : la requête porte la version sur laquelle repose la modification, et le serveur refuse de l’appliquer si la fiche a changé depuis. L’agent relit alors la fiche et réexamine sa modification, au lieu de remplacer seulement le numéro de version.

Une fiche fictive, C42, illustre chaque étape : pourquoi une lecture, même récente, ne protège pas l’écriture ; la condition et ses deux formes en HTTP ; deux issues après un refus, l’une où l’agent peut fusionner les changements, l’autre où il doit faire arbitrer ; enfin ce que cette condition ne règle pas, une réponse perdue après une écriture réussie.

Entre la lecture et l’écriture, la fiche peut changer

La fiche C42 porte deux champs qui comptent ici : une note interne, « rappeler mardi », et la langue d’affichage, fr. L’agent la lit à la révision 7, un numéro que le serveur augmente à chaque modification. Sa mission est de reporter la relance : il prépare la note « rappeler jeudi ». Pendant qu’il la prépare, Inès, conseillère, remplace la note par « client déjà rappelé, ne plus relancer », et la fiche passe à la révision 8.

Si l’agent envoie sa note sans condition, le serveur remplace celle d’Inès et répond par un succès. Le titulaire de la fiche sera relancé contre la décision d’Inès, et personne ne s’en aperçoit. C’est la mise à jour perdue : une écriture fondée sur un état dépassé efface une modification faite entre-temps. La RFC 9110 la nomme ainsi, et une note du W3C de 1999 décrivait déjà ce problème pour l’édition de documents sur le Web, avec la parade que la suite de cet article présente.

Le problème concerne tous les clients, humains ou logiciels. Relire la fiche juste avant d’écrire réduit l’écart, mais ne le supprime pas : une modification peut toujours s’intercaler entre cette relecture et l’enregistrement. Une tâche longue d’un agent peut l’agrandir : l’agent y enchaîne une suite d’actions, comme le décrit Anthropic à propos du contexte des agents, et il peut garder la représentation lue dans son contexte pendant plusieurs étapes avant d’écrire. La représentation peut aussi venir d’un modèle de lecture, une copie des données organisée pour la lecture, que tient à jour un traitement appelé projection. Quand cette mise à jour est asynchrone, la copie peut prendre du retard, et la représentation être dépassée dès la lecture : c’est le cas d’une projection en retard.

Seul le serveur connaît l’état courant au moment d’écrire. C’est donc lui qui doit vérifier, au moment où il applique la modification, que l’hypothèse sur laquelle elle repose est encore vraie.

La requête porte la version lue, le serveur la compare

Le serveur envoie une version avec les données lues, et le client la renvoie avec sa demande de modification. Le serveur compare alors la version attendue à la version courante dans l’opération même qui réalise l’écriture : une vérification séparée, faite juste avant, laisserait une autre écriture s’intercaler entre les deux. Si les versions diffèrent, il refuse la modification au lieu de remplacer silencieusement les données. Laisser chacun préparer sa modification sans garder de verrou, puis vérifier au moment d’enregistrer, est une forme de contrôle de concurrence optimiste.

HTTP prévoit ce contrôle avec deux en-têtes. Le serveur accompagne la fiche d’un ETag, un identifiant de la version de la représentation envoyée. Un ETag fort, comme "revision-7", change dès que le contenu renvoyé par une lecture change (RFC 9110, §8.8.1). Le client le renvoie dans l’en-tête If-Match de sa modification, et le serveur doit comparer les deux valeurs de façon forte, c’est-à-dire exiger deux ETag forts, non marqués comme faibles, et identiques. Si l’ETag courant ne correspond plus, le serveur ne doit pas exécuter la requête (RFC 9110, §13.1.1) et répond normalement 412 Precondition Failed, le code d’une condition d’en-tête qui s’est révélée fausse.

Une API peut aussi porter sa propre révision dans le corps de la requête, et signaler l’écart par 409 Conflict, le code d’un conflit avec l’état courant de la ressource (RFC 9110, §15.5.10). C’est la convention du schéma ci-dessous. Les deux conventions doivent être documentées sans confondre leur rôle : 412 pour une précondition d’en-tête, 409 pour un conflit que l’application décrit.

L’agent lit C42 en révision 7. Inès crée la révision 8 ; l’écriture fondée sur 7 est refusée par un conflit applicatif 409. L’agent relit la révision 8 et réexamine sa modification. If-Match relèverait de 412.
Après un conflit applicatif 409, l’agent relit et réexamine sa modification. Une précondition HTTP If-Match non satisfaite relève de 412. Le parcours s’arrête ici avant l’arbitrage ou une éventuelle nouvelle tentative.

Dans l’API fictive de l’exemple, la fiche porte un ETag, et c’est celui de la fiche C42 que vise la modification : la condition porte sur la ressource cible de la requête (§13.1.1). Si l’agent avait lu une autre ressource, par exemple une liste ou un modèle de lecture exposé à une autre adresse, son ETag ne vaudrait pas pour la fiche. Le contrat de cette lecture doit alors fournir la révision utile à l’écriture, ou l’agent relit la fiche cible avant d’écrire. Ici, l’agent envoie sa note avec la condition :

PATCH /fiches/C42 HTTP/1.1
Content-Type: application/merge-patch+json
If-Match: "revision-7"

{"note":"rappeler jeudi"}

HTTP/1.1 412 Precondition Failed
Content-Type: application/problem+json

{"type":"https://api.example/problemes/version-depassee",
 "title":"La fiche a changé","status":412}

Le corps de la requête suit le format JSON Merge Patch : il ne contient que les champs à modifier, ici la note. Le serveur refuse avant d’écrire, et la note d’Inès reste intacte.

Après le refus, l’agent relit et réexamine sa modification

L’agent relit la fiche, désormais en révision 8, et y trouve la note d’Inès. Sa proposition, « rappeler jeudi », la contredit. Il présente donc les deux intentions à la personne pour qui il travaille et demande un arbitrage, ou applique une règle explicitement prévue pour ce cas. Renvoyer la même note avec If-Match: "revision-8" ferait passer la condition et effacerait l’information même qui a motivé le refus.

Changeons une seule chose au scénario. Inès n’a pas touché à la note : elle a seulement changé la langue en en. La fiche est passée à la révision 8 de la même façon, et le même PATCH reçoit le même 412, car la condition porte sur toute la fiche. Le refus est correct, mais il coûte une relecture. L’agent relit la fiche et constate que seule la langue a changé depuis sa lecture. Dans ce métier, la note et la langue sont indépendantes, et la règle du produit autorise à modifier l’une sans tenir compte de l’autre. L’agent renvoie donc son patch avec If-Match: "revision-8" ; le serveur enregistre la note et garde la langue anglaise. Ce nouvel envoi peut encore échouer si une autre écriture intervient entre-temps, et il faut alors reprendre l’examen.

Cette fusion est légitime parce que le contrat métier déclare les deux champs indépendants, pas parce que leurs noms diffèrent. Si le changement de langue obligeait à traduire la note, il faudrait une autre décision. Les requêtes de l’exemple sont illustratives : la comparaison forte de If-Match et la vérification liée à l’écriture protègent la version, le format Merge Patch décrit la modification partielle, et aucun de ces mécanismes ne décide du sens de la relance. Cette décision revient à l’agent, selon les règles qu’il a reçues, ou à la personne qu’il sert.

Une erreur qui permet de reprendre

Le 412 de l’exemple porte un corps au format Problem Details, défini par la RFC 9457 : un objet JSON dont le champ type désigne la catégorie de problème, ici une version dépassée, et dont le champ title la résume. Une erreur utile identifie la ressource, le type de conflit et la manière de relire son état ; ce format peut fournir une structure commune aux erreurs de toute l’API.

La réponse ne doit pas exposer pour autant des données auxquelles le client n’a pas droit. La RFC 9457 demande d’examiner le contenu de chaque problème, qui peut laisser fuir des informations sur le système ou sur ses utilisateurs. Un lien vers une lecture autorisée de la fiche peut être préférable à l’inclusion de toute la ressource.

Après une réussite, renvoyer l’état actualisé et son nouvel ETag simplifie la suite : l’agent dispose de la version utile à sa prochaine modification sans relire. Une API peut aussi choisir un simple accusé de réception et un lien de lecture. Le contrat doit seulement permettre au client d’obtenir cette version. Des actions hypermédia, c’est-à-dire des liens et des formulaires de la réponse qui annoncent ce que le client peut faire ensuite, peuvent préciser les possibilités actuelles : modifier, annuler ou consulter un résultat. Elles facilitent le parcours d’un agent client de l’API, sans remplacer les contrôles du serveur.

Une réponse perdue relève d’un autre mécanisme

La condition empêche une écriture fondée sur un état dépassé. Elle ne règle pas une autre incertitude : une écriture qui a réussi, mais dont la réponse s’est perdue. Supposons que le second envoi de l’agent, avec If-Match: "revision-8", réussisse et fasse passer la fiche à la révision 9, mais que la connexion coupe avant la réponse. L’agent ignore si la note est enregistrée. S’il renvoie la même requête, la condition est fausse, puisque la fiche est en révision 9 à cause de son propre envoi, et le serveur peut répondre 412. Ce refus ne prouve donc pas l’échec du premier envoi. La RFC 9110 permet d’ailleurs au serveur de répondre par un succès quand la modification demandée semble déjà appliquée, par exemple parce qu’une réponse précédente s’est perdue, sans l’y obliger (§13.1.1).

L’agent relit donc la fiche avant de conclure, à sa source plutôt que dans une copie dont la fraîcheur est inconnue. S’il trouve la note « rappeler jeudi », le résultat voulu est atteint. Sinon, il réexamine sa modification sur l’état relu, comme après le premier refus. Pour une opération qui crée quelque chose, comme un paiement, relire ne suffit pas toujours, car l’agent ne sait pas quoi chercher. L’idempotence traite ce cas, avec un identifiant d’opération que le client choisit avant l’envoi et garde d’une tentative à l’autre : une reprise avec la même référence peut être sûre, selon le contrat de l’API, alors qu’une nouvelle référence crée une nouvelle demande. Le contrôle de version et l’idempotence peuvent intervenir dans le même parcours ; le premier protège contre un état dépassé, la seconde contre un effet répété.

Vérifier le parcours avec deux clients

Ces comportements se vérifient avant de confier l’API à un agent. 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 après relecture. Testez aussi une réponse perdue après réussite, et une lecture issue d’une projection en retard.

Dans le cas de C42, la note d’Inès a survécu : le serveur a refusé une écriture fondée sur la révision 7, et l’agent a fait arbitrer la relance au lieu de la forcer. Quand seule la langue avait changé, la relance a été enregistrée, et la langue anglaise est restée. Toute écriture qu’un agent calcule à partir d’une lecture doit donc porter cette condition : l’agent propose une modification, le serveur la juge sur l’état courant, et le client distingue ce qui a réussi, ce qui a été refusé et ce qui doit être réexaminé.

Sources

Explorer

Sur le même sujet

Choisis dans l’index d’après les étiquettes de cet article — les plus proches d’abord, hors de sa série. Rien n’est écrit à la main : un article publié demain avec les mêmes étiquettes y prendra place.

Laisser un commentaire

Elle n'est jamais affichée ni publiée. Elle sert à regrouper vos commentaires et, si vous vous inscrivez un jour avec elle, à vous les rendre.

Votre commentaire sera relu avant d'être publié.