Des endpoints de simulation qui responsabilisent les agents de programmation IA

Les agents de programmation IA ne devraient pas découvrir qu'une modification est valide en l'appliquant. C'est une conception d'API paresseuse, et l'autonomie en révèle rapidement le coût. Un agent peut réessayer, créer une branche et passer à la tâche suivante plus vite qu'un opérateur ne peut reconstituer une modification accidentelle de permission, une migration partielle ou une suppression mal ciblée.

Une action d'aperçu ne mérite sa place que si elle prédit une exécution précise, avec une fidélité suffisante pour qu'une personne ou un agent décide de poursuivre. Une réponse qui dit «valide» n'est pas un plan. Un diff qui omet une mise à jour en cascade est pire que l'absence de diff, car il fabrique une confiance injustifiée.

La cible de conception est simple : soumettre l'écriture proposée, l'évaluer par rapport à l'état actuel et aux règles métier habituelles, renvoyer les effets prévus et les échecs, puis faire refuser par l'exécution les plans obsolètes ou modifiés. Cela demande plus de soin que d'ajouter dryRun=true. Cela donne aussi à l'agent un moyen de corriger une requête invalide avant de demander l'approbation d'une personne.

Un aperçu doit décrire l'écriture exacte

Les endpoints de simulation doivent accepter la même intention significative que l'exécution et calculer les effets de cette intention exacte. Si POST /memberships peut attribuer un rôle, envoyer une invitation, ajouter le membre à un groupe de facturation et écrire une entrée d'audit, l'aperçu doit signaler chacun des effets que l'exécution créerait.

Les équipes livrent souvent un endpoint de «validation» qui vérifie la structure JSON et les champs obligatoires. Cet endpoint a son utilité, mais il ne prévisualise pas une écriture. Il ne peut pas indiquer à l'appelant que le rôle demandé entre en conflit avec un rôle existant, que le compte cible est suspendu ou que l'invitation consommera une place limitée. Appelez-le validation si c'est tout ce qu'il fait.

La distinction compte, car les agents considèrent les appels réussis comme des preuves. Une réponse limitée à la validation, suivie de l'exécution, laisse l'agent aveugle aux aspects de la décision qui dépendent de l'état. Un aperçu complet évalue à la fois la requête et la situation actuelle.

Pour chaque opération d'écriture, décrivez d'abord le contrat d'exécution en une phrase, avant de concevoir l'aperçu :

Pour cette entrée et cette révision observée de la cible, l'exécution créera, modifiera, supprimera ou déclenchera les effets nommés suivants.

Cette phrase met en évidence les comportements vagues. «Modifier les paramètres du projet» est trop large. «Faire passer retention_days de 30 à 14, recalculer l'expiration de 18 éléments actifs et refuser ceux qui font l'objet d'une obligation légale de conservation» donne à l'aperçu quelque chose de précis à renvoyer.

Un bon aperçu préserve la sémantique de l'opération. Ne transformez pas une suppression groupée en simple compteur parce que la liste réelle est moins pratique. N'employez pas «peut affecter» lorsque votre service peut déterminer les ressources exactes. Si l'ensemble est trop volumineux pour être renvoyé en ligne, renvoyez un total, un échantillon limité et un curseur ou une référence de rapport permettant à l'appelant d'examiner l'ensemble avant l'exécution.

Le plan doit préciser l'identité, le périmètre et les conséquences

Personne ne peut juger «12 enregistrements vont changer» sans savoir lesquels et de quelle manière. L'action prévue doit identifier ses entrées, son périmètre cible et ses conséquences sous une forme lisible par un programme comme par une personne.

Pour la modification d'une ressource unique, un diff au niveau des champs fonctionne souvent bien. Pour un déploiement, le plan peut devoir préciser les images, les environnements, les révisions de configuration, le comportement des redémarrages et les contrôles de santé. Pour un changement de facturation, il peut devoir indiquer l'ancien montant, le nouveau, la date d'effet et la réception éventuelle d'une notification par le client. Adaptez la sortie au domaine au lieu de faire entrer chaque opération dans un tableau JSON Patch.

Au minimum, exposez les éléments suivants :

• Le nom de l'opération et un statut d'aperçu explicite.
• Un identifiant stable pour chaque ressource concernée, ainsi que sa révision lorsque le service en gère.
• Les anciennes et nouvelles valeurs de chaque changement important.
• Les effets secondaires, comme les tâches, les notifications, les changements d'accès ou les montants calculés.
• Les avertissements, les blocages d'exécution et les hypothèses susceptibles de modifier le résultat.

La notion d'«important» demande du discernement. Un horodatage brut de base de données aide rarement une personne qui approuve. Un nouveau propriétaire, l'élargissement d'une appartenance à un groupe ou une suppression prévue sont en revanche essentiels. Montrez d'abord le résultat métier et proposez les détails de bas niveau lorsqu'un appelant en a besoin.

L'aperçu doit aussi distinguer les effets directs des effets dérivés. Supposons qu'un agent réduise le quota de stockage d'une équipe. Le changement direct porte sur un seul champ de quota. Le résultat dérivé pourrait bloquer les téléversements de trois projets existants. Le cacher dans un avertissement générique rend l'opération moins inquiétante qu'elle ne l'est. Placez-le dans un tableau effects distinct et indiquez-en la cause.

Soyez tout aussi précis sur l'incertitude. Un aperçu peut indiquer que l'exécution interrogera un service externe de calcul des taxes ou programmera une tâche ultérieure. Il ne doit pas annoncer un montant final si le service ne l'a pas encore déterminé. Utilisez un enregistrement d'hypothèse qui nomme la dépendance et précise si l'exécution peut continuer sans elle.

La validation doit séparer les blocages des avertissements

Un aperçu doit dire exactement ce qui empêche l'exécution, ce qui mérite un examen et ce qui ne fournit qu'un contexte. Mélanger ces catégories garantit de mauvaises tentatives répétées et une lassitude face aux approbations.

Un blocage signifie que le service refusera l'exécution dans les conditions évaluées. L'agent doit corriger l'entrée, obtenir l'autorité manquante ou s'arrêter. Un avertissement signifie que l'exécution peut continuer, mais qu'un opérateur raisonnable voudra peut-être examiner la conséquence. Le contexte apporte une information sans signaler un danger.

Renvoyez des erreurs structurées, pas un texte qu'un agent devrait devoir analyser. Cette forme reste volontairement ordinaire :

{
  "mode": "preview",
  "executable": false,
  "validation": [
    {
      "severity": "error",
      "code": "version_conflict",
      "path": "/if_match",
      "message": "Project prj_184 is at revision 73, not revision 71.",
      "blocks_execution": true,
      "repair": "Fetch the current project and create a new preview."
    },
    {
      "severity": "warning",
      "code": "member_count_change",
      "message": "The group will gain 42 members through nested groups.",
      "blocks_execution": false
    }
  ]
}

Les codes stables permettent à un agent de choisir sa réaction. Il peut récupérer une révision actuelle après version_conflict; il ne peut pas inventer une correction de manière responsable après legal_hold_active. Le champ message s'adresse à la personne qui examine l'action. Gardez les deux.

Ne qualifiez pas de manière systématique toute condition surprenante d'avertissement. Un avertissement qui exige toujours une modification de la requête doit être une erreur. À l'inverse, ne bloquez pas l'exécution parce que l'API rencontre une situation inhabituelle mais autorisée. Les équipes transforment chaque avertissement en blocage par peur de manquer quelque chose, puis les agents soumettent des aperçus qui ne peuvent jamais aboutir sans nettoyage manuel. L'interface devient théâtrale.

Le test utile est simple : si l'exécution recevait la même entrée dans le même état, s'exécuterait-elle ? Si oui, renvoyez un avertissement ou un contexte. Si non, renvoyez une erreur. Séparez les échecs d'autorisation de la validation métier. Ils décrivent des problèmes différents et demandent des corrections différentes.

Une simulation ne doit pas écrire à l'insu de l'appelant

Un aperçu doit éviter les effets externes durables, y compris ceux que les développeurs minimisent en les considérant comme de simples tâches d'entretien. Créer une ligne «temporaire», réserver un stock, incrémenter une séquence visible par les utilisateurs, mettre un webhook en file, envoyer un e-mail ou mettre à jour un horodatage de dernier accès contredit l'attente selon laquelle la requête pouvait être examinée sans danger.

Ce bug apparaît dans les services matures parce que le code d'exécution s'est construit autour de la facilité. Un gestionnaire de création peut allouer un identifiant au début, écrire un enregistrement en attente avant la validation et appeler un diffuseur d'événements avant la validation de la transaction. Quelqu'un l'entoure ensuite d'un if preview avant l'insertion finale. L'aperçu semble inoffensif dans un test local, mais consomme toujours des identifiants, produit du trafic d'événements ou laisse des déchets en production.

Traitez l'exécution d'un aperçu comme un mode distinct du service applicatif, et non comme une condition placée uniquement dans le contrôleur. Ce mode peut réutiliser les fonctions d'analyse, d'autorisation, de politique et de planification. Il doit faire passer les écritures et les envois externes par des interfaces qui produisent soit un effet proposé, soit un échec de la requête.

Une limite d'implémentation utile ressemble à ceci :

parse request
  -> authorize caller
  -> load consistent current state
  -> validate business rules
  -> build plan
  -> preview: return plan
  -> execute: apply plan in a transaction, then publish committed effects

L'ordre compte. Si votre base de données prend en charge les transactions, construisez le plan à partir des mêmes lectures que celles qui guideront l'exécution. Si une dépendance ne peut pas participer à la transaction, signalez son interaction en attente comme un effet explicite et concevez une action compensatoire en cas d'échec. Faire comme si un appel externe était transactionnel ne le rend pas transactionnel.

Les enregistrements d'audit méritent eux aussi une décision. Vous pouvez vouloir noter qu'un appelant a demandé un aperçu. C'est raisonnable, mais écrivez cet événement dans une voie d'audit clairement distincte et assurez-vous qu'il ne déclenche pas les workflows conçus pour les modifications terminées. Ne placez pas «aperçu» à côté de «permission accordée» en espérant que les consommateurs en aval comprennent la différence.

Testez l'absence d'effets, pas seulement la sortie. Avant et après une requête d'aperçu, vérifiez que les tables concernées, les files sortantes, le stockage d'objets, les récepteurs de test d'e-mails et les récepteurs de webhooks en aval n'ont pas changé. Les tests unitaires détectent rarement ce problème. Un test d'intégration dans un environnement jetable le fera.

La sémantique HTTP a besoin d'un contrat explicite

HTTP ne définit aucune méthode universelle de simulation, et faire comme si c'était le cas crée des problèmes d'interopérabilité. RFC 9110 définit GET, HEAD, OPTIONS et TRACE comme des méthodes sûres, au sens où un client ne demande pas de changement d'état. Elle ne dit pas qu'un POST accompagné d'un paramètre de requête est sûr et ne définit pas dryRun comme un contrôle standard.

Le concepteur d'un endpoint doit donc rendre le mode visible dans la requête comme dans la réponse. Un POST reste souvent approprié, car la planification d'écritures complexes nécessite un corps de requête et peut demander une évaluation coûteuse. L'essentiel est que les clients, les journaux et les personnes puissent distinguer un aperçu d'une exécution sans deviner.

Pour une opération simple, un champ explicite dans le corps est facile à lire et difficile à perdre :

POST /v1/projects/prj_184/memberships/plan
Content-Type: application/json

{
  "subject_id": "usr_92",
  "role": "admin",
  "if_match": "73"
}

Un endpoint /plan dédié convient lorsque la planification possède sa propre sortie, son propre cycle de vie ou ses propres permissions. Il évite aussi un problème récurrent des indicateurs de requête : un client généré omet l'indicateur, un proxy l'ignore dans sa configuration de cache ou un appelant copie mal l'URL et déclenche l'écriture. Si vous choisissez un endpoint unique avec un champ mode, refusez les valeurs absentes ou inconnues lorsque l'exécution accidentelle serait grave.

Renvoyez un type de réponse impossible à confondre avec la ressource exécutée. 201 Created accompagné d'un corps ayant la forme d'une ressource est une mauvaise réponse d'aperçu, même avec un champ preview: true. Utilisez 200 OK pour un plan immédiat, ou 202 Accepted uniquement lorsque la planification elle-même s'exécute de manière asynchrone. Incluez mode: "preview" dans le corps de la réponse et définissez un type de contenu explicite si votre API utilise des types de médias spécialisés.

Évitez de mettre les aperçus en cache à moins de comprendre chaque entrée qui les influence, y compris l'identité et les autorisations de l'appelant. La valeur par défaut la plus sûre est Cache-Control: no-store. Un plan obsolète n'est pas seulement une ancienne page. Il peut guider un agent vers une écriture qui concerne désormais un autre ensemble de ressources.

N'utilisez pas OPTIONS à cette fin. RFC 9110 l'emploie pour décrire les possibilités de communication, pas pour simuler une écriture avec un corps arbitraire. Un service qui le détourne embrouillera les bibliothèques, les contrôles de sécurité et toute personne qui s'attend au comportement HTTP habituel.

L'exécution doit prouver que le plan est toujours actuel

Un aperçu peut devenir faux entre le moment où il est produit et celui où l'exécution commence. Un autre utilisateur peut modifier l'enregistrement, une tâche planifiée peut s'exécuter, une autorisation peut expirer ou l'agent peut changer la requête après avoir lu la réponse. C'est un problème de temps de vérification et de temps d'utilisation, et un aperçu rassurant ne le supprime pas.

Liez un plan à la requête évaluée, aux révisions des ressources lues, à l'identité de l'appelant et à une courte durée de validité. Le serveur peut renvoyer un plan_token opaque signé ou conserver le plan et renvoyer un identifiant. Les jetons opaques empêchent un client de traiter le plan comme une autorité modifiable. Les plans conservés facilitent l'examen des effets volumineux et la révocation d'une approbation. Les deux approches fonctionnent si l'exécution revérifie les bonnes conditions.

Une réponse peut contenir :

{
  "mode": "preview",
  "plan_id": "plan_7f4c",
  "expires_at": "2025-06-18T14:05:00Z",
  "request_digest": "sha256:...",
  "read_revisions": [
    {"resource": "projects/prj_184", "revision": "73"}
  ],
  "executable": true
}

Lors de l'exécution, le service doit vérifier l'appelant, l'empreinte, l'expiration et les révisions. Il doit ensuite appliquer atomiquement le plan déjà approuvé ou le régénérer dans la transaction d'écriture et le comparer au plan approuvé. S'il ne peut pas garantir l'équivalence, il doit refuser la requête avec plan_stale et demander un nouvel aperçu.

Ne permettez pas à un agent de prévisualiser une requête pour un sujet, puis d'exécuter l'identifiant du plan avec un autre sujet dans le corps. Mieux encore, faites en sorte que l'exécution n'accepte que l'identifiant du plan et une révision attendue, afin d'éviter une seconde copie modifiable de la requête que le serveur devrait réconcilier.

Certains changements ne peuvent pas recevoir de garantie significative. Un plan d'envoi de message peut devenir inadapté parce que l'adresse du destinataire change un instant plus tard. Un plan d'appel à un service tiers peut dépendre d'un prix qui évolue avant l'appel. Indiquez-le dans la sortie, revalidez juste avant l'action irréversible et exigez une nouvelle décision lorsque la différence compte.

Les workflows d'agent ont besoin d'un arrêt volontaire avant l'exécution

Un agent doit traiter un aperçu comme un élément à examiner pour prendre une décision, et non comme une permission d'exécuter automatiquement l'écriture. Il lui faut des règles pour savoir quand exécuter, quand corriger la requête et quand présenter le plan à une personne.

Le workflow le plus fiable comporte quatre actions :

1. Soumettre l'écriture prévue en mode aperçu, avec une référence d'idempotence et les révisions attendues des ressources.
2. S'arrêter si la réponse contient des blocages, puis corriger uniquement les champs signalés par la réponse ou demander à une personne de préciser l'intention manquante.
3. Présenter les effets prévus et les avertissements lorsque l'opération franchit la limite d'approbation de l'équipe.
4. Exécuter uniquement le plan renvoyé tant qu'il reste actuel, puis enregistrer séparément le résultat de l'exécution et celui de l'aperçu.

L'approbation doit porter sur les conséquences, pas sur un dump JSON brut. Une personne qui décide d'accorder un accès veut voir le principal, le rôle, les ressources atteintes par l'expansion des groupes et la durée. Elle ne devrait pas avoir à déduire cet impact d'un corps de requête rempli d'identifiants.

Ne demandez pas à l'agent de prévisualiser chaque action inoffensive et de solliciter une approbation pour chaque avertissement. Vous obtiendriez une file de cartes que personne ne lit. Définissez des limites significatives dans l'application : opérations irréversibles, changements d'accès, argent, communications externes, ensembles de ressources étendus et actions dont le service marque les effets comme incertains. L'agent peut exécuter les changements petits et bien compris dans le cadre de l'autorité que vous lui accordez.

Sallyport peut exiger une décision humaine pour l'appel HTTP ou SSH réel d'un agent, tandis que l'aperçu de l'API donne un contenu concret à cette décision. Ces deux contrôles répondent à des problèmes différents : l'un détermine si un processus peut agir, l'autre explique ce que fera le service cible.

Un changement groupé échoué montre pourquoi les résumés ne suffisent pas

Imaginez qu'un agent soit chargé de retirer des prestataires d'un groupe de support en production. Il trouve un filtre correspondant à 37 comptes et soumet un aperçu. Le service renvoie count: 37, valid: true et une note générique indiquant que les appartenances héritées peuvent changer. Un opérateur approuve, car le résultat demandé semble courant.

L'exécution retire l'appartenance directe de ces 37 comptes. Quatre conservent un accès par l'intermédiaire de groupes imbriqués. Six autres perdent une permission d'astreinte distincte, car le service supprime aussi un droit associé. Une tâche de notification informe les 37 personnes que leur accès a changé. L'opérateur doit alors déterminer quels effets étaient voulus, lesquels étaient cachés et si la notification décrivait l'état réel des accès.

L'aperçu était techniquement vrai au sens le plus strict. Il ne promettait pas que le filtre identifiait uniquement des prestataires. Il restait une interface médiocre, car il renvoyait un compteur alors que l'utilisateur avait besoin d'un graphe d'appartenances et d'une liste d'effets.

Une meilleure réponse regroupe le résultat par conséquence :

{
  "mode": "preview",
  "operation": "remove_group_members",
  "selected": 37,
  "effects": [
    {"type": "direct_membership_removed", "count": 37},
    {"type": "access_retained_via_nested_group", "subjects": ["usr_8", "usr_19", "usr_31", "usr_44"]},
    {"type": "on_call_entitlement_removed", "subjects": ["usr_2", "usr_7", "usr_11", "usr_24", "usr_29", "usr_35"]},
    {"type": "notification_queued", "count": 37}
  ],
  "validation": [
    {
      "severity": "warning",
      "code": "access_outcome_varies",
      "message": "Four selected subjects retain group-derived access."
    }
  ]
}

La bonne réponse peut inclure un rapport téléchargeable ou des détails paginés pour les lots importants. Le but n'est pas de forcer une personne à lire des milliers de lignes. Il faut rendre visibles les résultats inhabituels et irréversibles avant l'écriture.

Cet exemple révèle aussi une mauvaise recommandation fréquente : «utilisez les simulations uniquement pour les actions destructives». Les équipes la répètent parce que les suppressions semblent dangereuses et que les aperçus demandent du temps d'ingénierie. Pourtant, une attribution de permission, une modification de configuration ou une notification peut avoir un rayon d'impact supérieur à celui d'une suppression. Choisissez la prise en charge des aperçus selon les conséquences et la réversibilité, pas selon le verbe HTTP ou l'opération de base de données.

Les tests doivent comparer les effets prévus aux effets exécutés

Un endpoint d'aperçu se dégrade lorsque les tests prouvent seulement qu'il renvoie une réponse 200. Sa promesse centrale est l'équivalence : lorsque l'état et la requête correspondent, les effets signalés doivent correspondre à ceux de l'exécution.

Construisez des tests par paires. Préparez un scénario, envoyez l'aperçu, capturez le plan normalisé, réinitialisez le scénario, exécutez la même intention et comparez le journal d'exécution à l'ensemble des effets prédits. Ignorez les champs qui ne peuvent raisonnablement pas correspondre, comme les horodatages du serveur ou les identifiants de corrélation générés. N'ignorez pas les ressources créées, les valeurs modifiées, les événements publiés, les notifications ou les appels sortants.

Les tests de propriétés aident pour les filtres et les opérations groupées. Générez une collection de ressources dans des états variés, demandez un aperçu sur un prédicat, exécutez-le dans une copie vierge et vérifiez que l'ensemble sélectionné et l'état final correspondent. Ces tests trouvent les cas difficiles où la requête de planification joint une table, mais la requête d'écriture en joint une autre.

Conservez un test consacré aux effets secondaires des aperçus. Utilisez de faux adaptateurs pour les e-mails, les webhooks, les files et les fournisseurs de paiement, qui font échouer le test si le mode aperçu les appelle. Exécutez ensuite au moins un test d'intégration sur la véritable couche de persistance, car un flush d'ORM ou un déclencheur peut écrire même lorsque le code applicatif semble propre.

Enfin, testez volontairement l'obsolescence. Prévisualisez une modification, modifiez une ressource avec une autre requête, puis exécutez l'ancien plan. Le service doit le refuser. Un système qui applique l'ancien plan parce que le diff «semble encore assez proche» finira par écraser le travail de quelqu'un d'autre.

L'aperçu est une capacité d'API, pas une raison de supprimer les contrôles

Les endpoints d'aperçu réduisent les surprises. Ils ne remplacent ni l'autorisation, ni les contrôles de concurrence, ni la conception transactionnelle, ni l'idempotence, ni les pistes d'audit, ni l'examen des opérations qui le méritent. Un appelant sans autorité ne devrait pas obtenir une carte détaillée des ressources protégées en sondant les aperçus. Un appelant qui répète une requête d'exécution ne devrait pas créer deux fois le même effet secondaire parce qu'un jeton de plan était valide.

Commencez par l'écriture qui a le plus nui à votre équipe lors d'une répétition ou en production. Dressez la liste de chaque effet direct et indirect, implémentez un plan qui les signale et faites refuser les plans obsolètes par l'exécution. Écrivez ensuite le test par paire qui prouve l'accord entre l'aperçu et l'exécution. Si vous ne pouvez pas dire ce qu'une écriture fera avant qu'elle ne s'exécute, l'agent n'est pas la partie la plus risquée du système. C'est l'API.