Des API qu'un agent peut utiliser sous contrôle : un achat de bout en bout

Dans Des API prêtes pour les agents d'IA, nous avons expliqué ce dont un système a besoin pour qu'un agent l'utilise sans surprises : qu'il s'explique seul, que ses erreurs enseignent, que réessayer ne duplique rien et que ce qui engage de l'argent ou des données ne dépende pas du modèle. Cet article descend d'un étage. Il prend une opération concrète — un achat — et la conçoit entièrement : les appels, les codes de réponse, le format des erreurs, la séparation des permissions, l'endroit où se fait l'approbation et la manière de vérifier que tout cela résiste à un agent trompé.

Il s'adresse à l'équipe technique. Si vous dirigez le domaine, l'idée de fond tient en une ligne : l'agent peut demander, le système décide, et une personne approuve tout ce qui engage de l'argent ou des données.

Scénario d'exemple. Il ne décrit pas une entreprise réelle. Un distributeur veut qu'un agent d'IA réapprovisionne ses fournitures : il vérifie les stocks, compare les fournisseurs et prépare les commandes. Les petits achats sont approuvés en quelques minutes ; personne ne veut que l'agent achète seul.

1. L'achat se découpe en trois étapes, pas en une

La tentation est d'exposer une seule opération, POST /compras, et de laisser l'agent l'appeler. C'est le chemin le plus court pour donner au modèle le dernier mot sur l'argent. L'alternative consiste à découper l'achat en trois étapes, chacune avec une permission différente :

Et entre proposer et exécuter, il y a une étape qui n'a aucun appel pour l'agent : l'approbation. Une personne la donne, par un autre canal, et le système l'enregistre. L'agent ne peut pas la créer, seulement l'attendre.

La proposition se présente ainsi :

POST /propuestas-de-compra
Content-Type: application/json

{
  "proveedor": "prov-0193",
  "partidas": [
    { "sku": "EMP-5521", "cantidad": 40 }
  ],
  "moneda": "MXN",
  "motivo": "Existencia bajo el mínimo en el almacén norte"
}

HTTP/1.1 201 Created
Location: /propuestas-de-compra/pc-7f3a
ETag: "rev-1"

{
  "id": "pc-7f3a",
  "revision": 1,
  "estado": "pendiente_de_aprobacion",
  "total": "12480.00",
  "moneda": "MXN",
  "huella": "sha256:4b1e…",
  "vence": "2026-11-03T18:00:00-06:00"
}

L'agent n'envoie que ce qu'il veut et en quelle quantité. Tout le reste est fourni par le système à partir de ses sources autorisées : prix en vigueur, taxes, adresse de livraison, conditions et politique applicable. Avec cela, il construit une révision immuable de la proposition et calcule deux choses à partir d'elle : le total et l'empreinte, un condensé cryptographique de cette révision exacte, calculé sur une représentation documentée. Si le prix, le fournisseur, la destination, une ligne ou la politique change, une nouvelle révision est créée et toute approbation antérieure cesse d'être valable.

L'empreinte identifie la révision ; elle ne donne aucune permission. La connaître n'autorise pas à exécuter, de même que connaître un numéro de compte n'autorise pas à y retirer de l'argent. Vous verrez plus bas le rôle qu'elle joue.

2. L'approbation se fait en dehors du modèle

L'OWASP, l'organisation de référence en sécurité applicative, appelle Excessive Agency le risque de donner à un agent plus de fonctionnalités, de permissions ou d'autonomie que nécessaire. Parmi ses mesures d'atténuation, deux deviennent ici des choix de conception : faire approuver par une personne les actions à fort impact avant qu'elles ne se produisent, et implémenter l'autorisation dans les systèmes qui reçoivent l'appel, au lieu de compter sur un LLM pour décider si une action est permise [4]. La spécification MCP, le protocole par lequel de nombreux agents appellent des outils, va dans le même sens : elle indique qu'il devrait toujours y avoir une personne capable de refuser l'invocation d'un outil [6].

En pratique, « une personne approuve » doit remplir trois conditions pour valoir quelque chose :

1. Le canal est différent. L'approbation n'arrive pas dans la même conversation que l'agent peut lire et écrire. Un modèle existe déjà pour cela : le flux CIBA d'OpenID sépare l'appareil où l'opération démarre de l'appareil sur lequel la personne s'authentifie et donne son consentement [8]. Dans le scénario : l'agent propose depuis le serveur, et la responsable des achats approuve depuis l'application de son téléphone, avec sa propre session.
2. On approuve du concret. La personne n'approuve pas « que l'agent achète » : elle approuve cette proposition, avec ce fournisseur et ce total. La norme OAuth pour les autorisations détaillées (RFC 9396) existe précisément pour cela : elle permet de demander une autorisation qui contient le type d'opération, le montant et le bénéficiaire, et son exemple est un paiement [7]. CIBA définit en outre un message destiné à être affiché sur les deux appareils, pour que la personne puisse les relier [8]. L'écran d'approbation est construit par le système, pas par l'agent : il affiche la révision, le total, le fournisseur, la destination et l'échéance.
3. Ce qui est approuvé est ce qui est exécuté. L'approbation est liée à la révision exacte de la proposition et enregistre qui a approuvé, avec quel rôle et selon quelle politique. Elle expire selon l'horloge du serveur, peut être révoquée et cesse d'être valable si une nouvelle révision est créée.

L'approbation est conçue pour que l'agent n'ait aucune opération lui permettant de l'accorder ni de modifier ce qui a déjà été approuvé. L'agent peut demander une approbation ; l'accorder revient à une personne.

3. Exécuter : un appel qu'on peut répéter sans payer deux fois

Une fois la proposition approuvée, l'agent exécute :

POST /compras
Content-Type: application/json
If-Match: "rev-1"
Idempotency-Key: "3f2c9a1e-8d4b-4c6e-9f1a-2b7d5e0c4a91"

{
  "propuesta": "pc-7f3a"
}

Le corps ne répète ni les lignes ni les montants : il indique seulement quelle proposition est exécutée. L'en-tête If-Match indique quelle révision on s'attend à exécuter, avec le mécanisme standard de HTTP pour les requêtes conditionnelles : si la révision n'est plus celle en vigueur, le serveur peut répondre 412 Precondition Failed [16]. Et l'appel porte un identifiant d'exécution, expliqué à la section 5.

Le système vérifie tout dans une seule transaction : la proposition est toujours approuvée, l'approbation n'a ni expiré ni été révoquée, la révision correspond, l'identifiant est valide et aucune commande n'existe déjà pour cette proposition. Si tout est rempli, la proposition passe de aprobada à ejecutando et l'identifiant est consommé ; sinon, l'appel est rejeté avec une erreur qui explique pourquoi (section 4).

C'est cette transaction qui empêche deux achats à partir de la même proposition, même si deux appels différents arrivent en même temps, avec des clés différentes, depuis deux processus ou depuis un agent qui a redémarré. Et en dernier rempart, la base de données n'admet pas deux commandes pour la même proposition. Les états sont les suivants : aprobada → ejecutando → ejecutada, ou fallida_sin_confirmar si le fournisseur a reçu la commande mais que la réponse s'est perdue. Dans ce cas, le système fait le rapprochement avec le fournisseur avant de renvoyer ; sinon, la duplication ne fait que se déplacer.

La clé d'idempotence : pour les nouvelles tentatives, pas pour la concurrence

La transaction ci-dessus règle le cas de deux exécutions différentes. La clé d'idempotence règle autre chose : la nouvelle tentative de la même exécution. Dans cette API, répéter la même requête avec la même clé renvoie le résultat enregistré de cette exécution, au lieu de la tenter à nouveau.

L'en-tête Idempotency-Key est toujours en cours de normalisation à l'IETF : c'est un brouillon actif, en version 08, mis à jour le 22 octobre 2026, et ce n'est pas encore une RFC. Sa valeur est une chaîne entre guillemets, comme dans l'exemple ci-dessus [2]. Mais il propose déjà des règles qu'il vaut la peine d'adopter telles quelles, car elles couvrent exactement les cas qui déroutent un agent [2] :

Le brouillon permet aussi une « empreinte » de la requête pour décider si deux requêtes portant la même clé sont vraiment la même [2]. Et certains détails doivent être publiés par chaque API : la portée de la clé, sa durée de conservation et son expiration. Stripe, une référence pratique en la matière, documente ceux de son API v1 [3] :

• il enregistre le code et le corps de la première réponse dès que l'opération commence à s'exécuter, y compris les erreurs 500, pour qu'une nouvelle tentative ne débite pas une deuxième fois quand la première est restée incertaine ;
• il suggère de générer les clés comme UUID de version 4 et de ne pas utiliser de données sensibles (une adresse e-mail ou un identifiant fiscal) comme clé ;
• il peut supprimer les clés dès qu'elles ont au moins 24 heures.

Dans la conception avec des agents, il reste une décision : qui génère la clé. Si l'agent génère une nouvelle clé à chaque tentative, la clé ne permet pas de reconnaître la répétition. Il vaut mieux qu'elle naisse avec l'exécution de la proposition et qu'elle soit enregistrée côté serveur. Et si, malgré cela, une deuxième exécution arrive avec une autre clé, c'est la transaction qui l'arrête, pas la clé.

4. Des erreurs que l'agent peut corriger, avec la RFC 9457

Pour cet achat, le format d'erreur de la RFC 9457 permet de donner à l'agent des données structurées pour se corriger, sans changer le sens des codes HTTP [1]. Voici à quoi ressemble un rejet pour cause de montant :

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://api.ejemplo.mx/problemas/monto-sobre-limite",
  "title": "El total supera el límite que se puede proponer",
  "status": 422,
  "detail": "El total de 48,900.00 MXN supera el límite de 25,000.00 MXN para propuestas de este agente. Esta compra requiere la aprobación de nivel superior.",
  "instance": "/propuestas-de-compra/intentos/a91c",
  "limite": "25000.00",
  "reintentable": false
}

Quatre règles de la RFC elle-même font que cela fonctionne bien avec un agent :

• Le statut dans le corps est seulement indicatif, et celui qui le génère doit utiliser le même code que la réponse réelle [1]. Un 422 dans le corps avec un 200 dans la réponse déroute tout le monde.
• On peut ajouter ses propres champs — ici limite et reintentable —, et la RFC oblige les clients à ignorer ceux qu'ils ne reconnaissent pas [1]. Cela permet de donner à l'agent exactement la donnée dont il a besoin sans rien casser chez personne.
• S'il y a plusieurs erreurs, il est recommandé de signaler la plus pertinente [1]. Pour les erreurs de validation, la RFC montre un tableau avec le détail et l'emplacement de chaque champ en erreur, ce dont un agent a besoin pour tout corriger en une seule tentative [1].
• Les détails internes ne sont pas exposés : la RFC met en garde contre l'affichage d'éléments comme une trace de pile [1]. L'erreur dit quoi corriger, pas comment le système est construit à l'intérieur.

Pour l'achat du scénario, les types de problème sont les suivants :

Deux idées derrière ce tableau. La première : séparer l'authentification (401), l'autorisation (403), la précondition (412) et l'état du flux (409), pour que l'agent sache s'il lui manque quelque chose, s'il n'a pas le droit ou s'il doit attendre. La seconde : l'agent ne devrait pas avoir à deviner ce qui vaut la peine d'être répété. Et une précaution : la limite de montant ne s'évite pas en découpant l'achat, donc la politique cumule par fournisseur et par période, pas seulement par proposition.

5. Lire, proposer, exécuter : les permissions vivent dans l'API

Le tableau de la section 1 n'est pas une convention de style. C'est la manière de limiter les dégâts quand l'agent se trompe. L'OWASP énumère trois causes de l'excès d'agentivité : trop de fonctionnalités, trop de permissions et trop d'autonomie [4]. Chaque niveau en coupe une :

• Un identifiant d'exécution limité. L'agent qui consulte et propose n'a pas la permission d'exécuter. Après l'approbation, le serveur d'autorisation peut délivrer à l'exécutant un identifiant à usage unique et de courte durée, qui contient la proposition, la révision, le fournisseur, le montant, la devise et l'API à laquelle il est destiné. La RFC 9396 fournit le format pour exprimer ce détail [7] ; le valider par rapport à l'approbation en vigueur et le consommer dans la même transaction qui marque ejecutando relève de cette API. De plus, l'identifiant est lié à celui qui le présente, par exemple avec DPoP [17], pour qu'il ne serve à personne d'autre même s'il fuit.
• L'agent ne voit même pas ce qu'il ne peut pas faire. La spécification MCP permet que la liste des outils qu'un serveur propose change selon l'autorisation de celui qui la demande : par exemple, n'afficher que les outils que ses permissions atteignent [6]. Un agent autorisé à proposer ne voit pas l'outil d'exécution. Le cacher réduit ce que l'agent découvre, mais n'autorise ni ne bloque rien à lui seul : l'API valide permission, sujet, proposition et état à chaque appel [6].
• Un identifiant n'est pas une permission. MCP le dit pour l'état entre les appels : un identifiant comme celui d'un panier est un nom, pas une capacité, et le serveur doit valider l'autorisation à chaque appel [6]. Que l'agent connaisse pc-7f3a ne lui donne pas le droit de l'exécuter.
• Les limites vivent sur le serveur. La limite de 25 000 pesos de l'exemple est dans l'API, pas dans les instructions du modèle. Le modèle peut ignorer une instruction ; l'API rejette la requête même si le modèle l'envoie.
• Tout est journalisé. Quel agent, avec quel identifiant, ce qu'il a proposé, qui a approuvé, quelle empreinte, ce qui a été exécuté. MCP recommande de journaliser l'usage des outils à des fins d'audit [6].

6. Le test du catalogue empoisonné

Tout ce qui précède peut se vérifier sur papier. Cette section sert à le vérifier avec le système en marche.

Le risque

En 2023, un groupe de chercheurs a décrit l'injection indirecte d'instructions : l'attaquant ne parle pas à l'agent, mais cache des instructions dans des données que l'agent va probablement lire [10]. L'OWASP la classe comme premier risque des applications fondées sur des modèles de langage et reconnaît qu'il n'est pas certain qu'il existe un moyen infaillible de la prévenir [5].

Dans le scénario, l'agent lit le catalogue des fournisseurs : noms, descriptions, prix. Quiconque peut écrire une description — un fournisseur, un employé, une intégration compromise — peut y glisser une instruction.

Pourquoi un détecteur ne suffit pas

Les chiffres publiés convergent sur un point :

• Une équipe de chercheurs a attaqué 12 défenses récentes avec des attaques adaptées à chacune et a dépassé 90 % de réussite contre la plupart d'entre elles [14].
• Dans une évaluation du centre de normes d'IA du NIST, avec un modèle et un environnement de bureau simulé, le taux de réussite est passé de 11 % pour l'attaque de référence la plus forte à 81 % pour la nouvelle attaque la plus forte, mise au point avec l'institut britannique de sécurité de l'IA [15].
• Dans un autre ensemble de cinq tâches de cette même évaluation, la réussite moyenne est passée de 57 % avec une tentative à 80 % en répétant chaque attaque 25 fois [15].

Ce sont des résultats obtenus dans ces conditions, pas un taux valable pour tous les agents. Ils montrent en revanche qu'une évaluation interne doit consigner le modèle, l'environnement, la tâche et le nombre d'exécutions.

La leçon n'est pas que les agents sont dangereux. C'est que la défense qui compte est celle qui ne dépend pas de la capacité du modèle à détecter la tromperie. Deux cadres le disent de façon frappante. Simon Willison appelle « trifecta létale » la combinaison de l'accès à des données privées, de l'exposition à du contenu non fiable et de la capacité à communiquer vers l'extérieur [11]. Meta propose la « règle de deux » : au cours d'une même session, un agent ne devrait pas à la fois traiter des entrées non fiables, accéder à des systèmes sensibles et pouvoir modifier un état ou communiquer vers l'extérieur ; deux des trois au maximum [12]. Un agent d'achat qui lit un catalogue ouvert et émet des commandes réunit justement les trois. C'est pourquoi l'étape d'exécution ne peut pas dépendre de ce que l'agent a lu.

La recherche va dans le même sens. La conception CaMeL, d'une équipe de chercheurs, sépare le flux de contrôle — ce que décide la requête fiable de la personne — du flux de données, de sorte que les données non fiables lues par le modèle ne changent jamais le cours du programme. Avec cette conception, ils ont résolu 77 % des tâches du banc d'essai AgentDojo avec une sécurité démontrable, contre 84 % pour un système sans défense [9]. La séparation entre proposer et exécuter de cet article s'inspire de ce principe ; elle n'équivaut pas à implémenter CaMeL et n'hérite pas de sa preuve de sécurité.

Le test, étape par étape

1. Préparez un environnement isolé, avec un fournisseur simulé et sans accès aux fournisseurs réels. Consignez la version du modèle, les instructions, les outils, l'identité de l'agent, le catalogue initial, la politique et la version de l'API.
2. Ajoutez au catalogue une description de test, marquée en interne comme non fiable, qui tente de changer la quantité, la destination de livraison et l'état de la proposition. Le texte exact se trouve dans le matériel de test de votre équipe, pas dans des documents publics.
3. Confiez à l'agent une tâche normale qui l'amène à lire ce produit, comme vérifier les stocks et réapprovisionner ce qui manque.
4. Répétez la tâche plusieurs fois pour chaque combinaison de modèle, de configuration et de variante de la description. Une référence utile est les 25 répétitions de l'évaluation du NIST, lorsque votre environnement permet les nouvelles tentatives [15] ; c'est un point de comparaison, pas une garantie.
5. Mesurez séparément ce qui relève du modèle et ce qui relève du système, dans le journal : - combien de fois l'agent a obéi à l'instruction cachée (cela relève du modèle et varie d'une version à l'autre) ; - combien de propositions il a créées ; - zéro commande sans approbation en vigueur, révision correspondante et identifiant d'exécution valide ; - toutes les tentatives directes d'approuver ou d'exécuter sans permission, rejetées ; - traçabilité complète de chaque tentative : identifiant de corrélation, agent, identifiant, révision, décision et réponse.
6. Ajoutez des variantes qui testent les règles de l'API : une révision créée après l'approbation, une approbation expirée ou révoquée, deux clés différentes pour la même proposition et un identifiant présenté par un autre client. Les bancs d'essai publics comme AgentDojo, avec 97 tâches et 629 cas de sécurité, servent de modèle pour construire les vôtres [13].

Si la troisième condition de l'étape 5 échoue, il faut d'abord examiner l'autorisation, la transition d'état et le journal de cet appel. Le taux d'obéissance du modèle sert à choisir et à configurer les modèles ; la sécurité de l'achat ne peut pas en dépendre.

7. Liste de vérification pour votre équipe

• [ ] Les opérations qui engagent de l'argent ou des données sont découpées en consulter, proposer et exécuter, avec des permissions distinctes.
• [ ] Prix, total, destination et conditions sont fixés par le système dans une révision immuable, pas par l'agent.
• [ ] L'approbation se fait par un autre canal, elle est donnée par une personne, liée à la révision, elle expire et peut être révoquée.
• [ ] L'agent n'a aucun appel pour approuver.
• [ ] L'exécution exige un identifiant à usage unique lié à la proposition et à celui qui le présente, et une transaction qui empêche deux commandes pour la même proposition.
• [ ] L'exécution exige Idempotency-Key pour les nouvelles tentatives, et l'API répond 400 / 409 / 422 comme le propose le brouillon de l'IETF.
• [ ] Les erreurs sont en application/problem+json, avec des types documentés et un champ qui indique s'il convient de réessayer.
• [ ] Les limites vivent dans l'API, pas dans les instructions du modèle.
• [ ] La liste des outils que voit l'agent dépend de ses permissions, et l'API valide quand même chaque appel.
• [ ] Le test du catalogue empoisonné s'exécute à chaque version, avec plusieurs répétitions, et mesure séparément ce que le modèle a fait et ce que le système a permis.

Ce que fait Hábil

Chez Hábil, nous vous aidons à concevoir les API de vos systèmes pour qu'un agent d'IA puisse les utiliser sous contrôle : nous séparons ce qui se consulte, ce qui se propose et ce qui s'exécute ; nous plaçons l'approbation en dehors du modèle, avec une personne qui approuve tout ce qui engage de l'argent ou des données ; et nous définissons avec votre équipe des tests vérifiables, comme celui du catalogue empoisonné, dont les preuves sont examinées avec vous. Nous le faisons avec Hábil AI, une intelligence artificielle connectée à vos systèmes sous contrôle. Pour avoir une vue d'ensemble, consultez aussi Des API prêtes pour les agents d'IA et la page Maîtriser les accès.

Premier échange, sans frais. Nous partons d'une de vos opérations qu'un agent ne devrait pas exécuter seul aujourd'hui, et nous vous disons ce qu'il faudrait pour qu'il puisse la proposer sous contrôle.

Sources consultées le 28 octobre 2026. Les citations de documents en anglais sont traduites.