Les opérations bulk via une API doivent-elles d'abord afficher leurs cibles ?

Un agent IA ne doit jamais transformer une demande vague comme « archiver les comptes inactifs » en appel d'écriture sans limites. Avant de modifier de nombreux dossiers, il doit afficher l'ensemble exact des cibles, conserver la sélection présentée et demander une confirmation qui ne s'applique qu'à cette sélection.

Cela peut sembler tatillon jusqu'au jour où un mauvais filtre correspond à un client réel, à un environnement de test ou à un compte soumis à une exception absente du ticket. Un humain peut faire la même erreur, mais un agent peut envoyer la requête à la vitesse d'une machine et continuer après le premier mauvais résultat. Le contrôle important n'est pas un avertissement poli avant la requête. C'est une limite vérifiable entre le choix des personnes concernées et leur modification.

Un nombre ne décrit pas le périmètre d'impact

Un nombre indique combien de dossiers une opération va affecter. Il ne dit pas lesquels. « 482 abonnements » peut sembler plausible tout en incluant un environnement client d'entreprise, des comptes suspendus qui doivent être conservés pour des raisons légales ou des dossiers d'une région qui n'était pas mentionnée dans la demande.

Exigez un manifeste des cibles. Pour une petite opération, il peut énumérer chaque identifiant avec suffisamment de contexte pour qu'un examinateur repère les erreurs. Pour une opération plus importante, affichez la liste complète dans un espace de vérification exportable, avec des regroupements utiles comme le statut, l'environnement client, la région ou le responsable. Ne demandez pas à la personne de déduire l'appartenance à partir d'une simple chaîne de filtre.

Une bonne prévisualisation répond à cinq questions concrètes :

• Quelle ressource API et quel environnement recevront l'écriture ?
• Quel sélecteur a produit cet ensemble ?
• Quels dossiers en font partie, identifiés par des identifiants stables et des champs lisibles ?
• Quelle modification chaque dossier recevra-t-il ?
• Quels dossiers ont été exclus par une règle explicite ?

Le dernier point permet de détecter un échec gênant : une requête peut être techniquement correcte tout en contredisant l'intention, parce qu'une exception cachée n'a jamais été intégrée au sélecteur. Si l'opérateur demande « toutes les factures impayées sauf celles qui sont contestées », la prévisualisation doit signaler clairement l'exclusion des factures contestées. Le silence laisse l'examinateur deviner si l'agent a compris l'exception ou l'a oubliée.

Ne confondez pas un échantillon avec un manifeste. Afficher les 20 premiers dossiers d'une mise à jour qui en concerne 10 000 ne prouve pas grand-chose. Les échantillons aident à repérer les problèmes évidents, mais la sélection enregistrée doit couvrir chaque dossier susceptible d'être modifié.

La prévisualisation et le commit doivent utiliser la même sélection

Une prévisualisation n'a de sens que si le commit peut prouver qu'il agit sur l'ensemble examiné. Si un agent prévisualise une recherche à 14 h 00 puis relance cette même recherche à 14 h 05 avant l'écriture, il peut toucher une population différente. De nouveaux dossiers peuvent entrer dans le filtre, des dossiers existants peuvent changer d'état et la pagination peut réordonner les lignes.

La conception d'API la plus sûre crée un instantané de sélection côté serveur. L'endpoint de prévisualisation renvoie un identifiant de sélection, sa date d'expiration, le nombre de membres et une révision ou une empreinte. L'endpoint de commit accepte cet identifiant et le rejette lorsque l'instantané a expiré ou changé.

POST /v1/subscriptions/selections
Content-Type: application/json

{
  "filter": {
    "status": "past_due",
    "region": "eu",
    "exclude_tags": ["disputed", "legal_hold"]
  },
  "fields": ["id", "customer_name", "status", "amount_due", "tags"]
}

Une réponse solide peut avoir cette forme :

{
  "selection_id": "sel_7f2c",
  "expires_at": "2025-03-08T15:00:00Z",
  "count": 482,
  "digest": "sha256:4c76...",
  "records": [
    {"id":"sub_104","customer_name":"Northwind Parts","status":"past_due","amount_due":3100,"tags":[]},
    {"id":"sub_219","customer_name":"Orchard Studio","status":"past_due","amount_due":450,"tags":[]}
  ]
}

Le tableau records peut être livré au moyen d'un curseur, mais l'identifiant de sélection doit désigner l'ensemble complet et figé, pas seulement la page actuelle. L'interface de vérification peut parcourir les résultats sans modifier l'objet examiné.

Après approbation, l'agent envoie la sélection enregistrée plutôt que le filtre initial :

POST /v1/subscriptions/bulk-actions
Content-Type: application/json
Idempotency-Key: 9b03c6f0-7dfa-4f22-b0e5-4b52ca4f1a51

{
  "selection_id": "sel_7f2c",
  "expected_digest": "sha256:4c76...",
  "action": {"type": "pause_collection", "reason": "approved credit hold review"}
}

Le serveur doit rejeter une empreinte qui ne correspond pas et renvoyer un conflit. Une requête réussie doit renvoyer un identifiant d'action et l'emplacement des résultats pour chaque dossier, pas seulement {"ok": true}. Un message de réussite global masque les traitements partiels, qui constituent le mode d'échec habituel des opérations bulk.

Si l'API du fournisseur ne peut pas créer d'instantanés, l'agent peut tout de même lier l'opération en enregistrant une liste ordonnée d'identifiants, en hachant une représentation canonique et en envoyant cette liste à l'endpoint d'écriture. Cette méthode a ses limites : taille maximale des URL et du corps, dossiers obsolètes et APIs qui n'acceptent qu'un filtre. Dans ces situations, ne prétendez pas que le contrôle est équivalent. Refaites immédiatement la prévisualisation avant chaque lot limité et arrêtez-vous dès que l'appartenance diffère.

La pagination stable détermine la valeur de la vérification

La pagination par offset est une mauvaise base pour une décision d'approbation portant sur des données qui changent. Imaginons que l'agent liste la première page, voie les dossiers 1 à 100, puis qu'un autre processus archive 20 dossiers proches du début. Lorsque l'agent demande l'offset 100, il peut ignorer les dossiers qui ont remonté. Des insertions peuvent aussi créer des doublons. Le nombre examiné peut rester assez proche de la normale pour sembler correct, alors que les dossiers eux-mêmes ont changé.

Utilisez un curseur émis par le service et demandez au fournisseur de l'API si ce curseur lit un instantané. Un curseur qui ne fait qu'encoder une position de tri peut encore dériver si le champ trié change. Trier par un champ modifiable comme updated_at est particulièrement risqué lorsque l'action proposée met elle-même à jour cet horodatage.

Lorsque vous contrôlez l'API, exposez clairement les propriétés suivantes :

• Un identifiant d'instantané ou une borne supérieure immuable.
• Un tri déterministe sur un identifiant immuable.
• Une expiration qui force une nouvelle prévisualisation au lieu de renvoyer silencieusement des données plus récentes.
• Un champ de réponse indiquant si l'appelant lit un instantané cohérent.

RFC 9110 classe des méthodes comme POST, PUT, PATCH et DELETE parmi les méthodes non sûres, car elles peuvent modifier l'état du serveur. Cette classification ne constitue pas une conception de workflow, mais elle appuie une règle pratique : ne considérez pas un endpoint de liste suivi d'une méthode non sûre comme une opération atomique simplement parce que les deux appels sont placés côte à côte dans le code.

Pour une API externe qui n'offre ni curseurs stables ni instantanés de sélection, réduisez la portée jusqu'à ce que quelqu'un puisse examiner chaque requête. Il est tentant de contourner la limite avec un cache côté agent et une longue boucle. Cette solution crée souvent une seconde base de données, sans limite transactionnelle ni réponse faisant autorité lorsqu'un dossier change en cours d'exécution.

L'approbation doit décrire la modification, pas seulement les dossiers

L'examinateur doit approuver à la fois l'appartenance et l'effet. « Appliquer des modifications à 482 dossiers » ne veut rien dire si l'interface ne précise pas s'il s'agit de supprimer, désactiver, réattribuer, facturer, publier ou modifier un champ. Incluez la valeur avant et la valeur proposée après pour chaque champ qui changera, avec un résumé concis lorsque tous les dossiers reçoivent la même mise à jour.

Distinguez les écritures absolues des écritures conditionnelles. Une écriture absolue dit status = archived, quel que soit ce qui s'est passé depuis la prévisualisation. Une écriture conditionnelle dit « archiver uniquement si le statut est toujours inactif et si la version est toujours 17 ». Les écritures conditionnelles sont généralement plus sûres, car elles échouent de manière fermée lorsqu'une autre personne a modifié le dossier.

Utilisez une version, un ETag ou la dernière révision connue dans chaque modification lorsque l'API le permet. Cela ne remplace pas le manifeste des cibles. Il s'agit d'un autre problème : un dossier examiné peut ne plus être éligible au moment de l'exécution.

Un enregistrement d'approbation compact peut être représenté ainsi :

{
  "request_id": "req_91a8",
  "selection_id": "sel_7f2c",
  "selection_digest": "sha256:4c76...",
  "target_count": 482,
  "action": {
    "type": "pause_collection",
    "precondition": {"status": "past_due"}
  },
  "approved_by": "operator account identifier",
  "approved_at": "2025-03-08T14:16:02Z"
}

Ne laissez pas un agent réutiliser cette approbation pour une autre action sur le même ensemble. Suspendre la collecte, émettre des crédits et supprimer des dossiers ont des conséquences différentes, même lorsque la liste des cibles est identique. Liez l'approbation à une charge utile d'action canonique ainsi qu'à l'empreinte de sélection.

Les limites de temps comptent. Une approbation qui reste valable jusqu'au moment choisi par l'agent transforme un instant de vérification humaine en permission permanente. Donnez aux approbations une courte durée de validité adaptée à l'opération, invalidez-les lorsque la sélection change et demandez une nouvelle décision si l'agent modifie substantiellement l'action.

Les traitements partiels nécessitent un journal et une règle d'arrêt

Toute opération bulk finit par rencontrer une limite de débit, un délai d'attente, un échec de validation ou une rupture réseau. La réponse dangereuse consiste à relancer tout le travail sans savoir quels dossiers ont déjà changé. Cela crée des facturations en double, des notifications répétées ou une piste d'audit trompeuse.

Attribuez un identifiant d'opération et une clé d'idempotence à l'action demandée. Enregistrez le résultat pour chaque cible : réussie, échouée, ignorée parce qu'une précondition a changé ou inconnue parce que le service n'a pas renvoyé de résultat durable. « Inconnue » ne signifie pas « échouée ». Traitez ce cas comme un état à examiner avant toute nouvelle tentative.

Définissez une règle d'arrêt avant l'exécution. Une règle raisonnable peut interrompre le traitement après une erreur structurelle, comme un échec d'autorisation ou une réponse de schéma inattendue, tout en permettant de regrouper les échecs de validation isolés pour examen. Évitez un réglage générique « continuer en cas d'erreur ». Il transforme une modification imprévue du contrat API en une longue liste de dossiers endommagés.

Prenons un échec courant. Un agent prévisualise 800 comptes utilisateurs pour modifier un rôle, puis commence une boucle côté client. Les 300 premières requêtes réussissent. Un déploiement modifie l'endpoint, de sorte qu'un champ manquant attribue par défaut le rôle administrateur au lieu du rôle lecteur prévu. La réponse suivante semble réussie. Si la boucle continue, l'erreur se propage. Si l'agent enregistre la forme de chaque réponse et s'arrête lorsque le contrat diffère de l'action approuvée, le périmètre d'impact s'arrête à la première réponse anormale.

Pour les opérations destructives, concevez la compensation avant l'exécution. Une requête de compensation doit capturer la valeur précédente pour chaque dossier, et non s'appuyer sur la vague promesse que quelqu'un pourra annuler l'action. Même dans ce cas, ne considérez pas un retour arrière comme inoffensif. Une modification légitime ultérieure peut rendre l'annulation aveugle incorrecte, et certains effets externes comme les e-mails ou les exports peuvent ne pas être réversibles.

L'accès en lecture peut être aussi exposé qu'une mauvaise écriture

Les équipes appliquent souvent une confirmation rigoureuse à la suppression et aucune à la sélection. Elles oublient qu'un agent peut récupérer une liste complète de clients, des adresses personnelles, des états de paiement ou des notes internes pour préparer sa prévisualisation. Celle-ci doit exposer suffisamment de données pour permettre à une personne de reconnaître les dossiers, pas tous les champs proposés par l'API sous-jacente.

Demandez un ensemble de champs volontairement limité. Un identifiant stable, un nom d'affichage, le statut, le responsable et les valeurs liées à la modification proposée suffisent généralement. Écartez de la réponse de sélection les secrets, les jetons, les notes en texte libre et les données personnelles sans rapport. La vérification sera moins bruyante et l'agent aura moins de données à répéter dans ses messages ultérieurs.

Le même principe s'applique aux filtres. Un agent ne doit pas élargir une requête parce qu'il n'a pas le droit d'inspecter un champ. S'il ne peut pas prouver qu'un dossier appartient à la sélection, il doit signaler l'ambiguïté et attendre qu'une personne la résolve. Deviner n'est pas faire preuve de jugement opérationnel.

L'environnement fait partie du manifeste. Production, staging et sandbox peuvent exposer des noms de ressources identiques. Placez l'hôte de destination ou l'identifiant du compte à côté du nombre de cibles et du résumé de l'action. Des ingénieurs ont approuvé une liste de dossiers parfaitement raisonnable dans le mauvais environnement parce que la prévisualisation présentait l'environnement comme un détail secondaire.

Les agents doivent contrôler l'appel, pas détenir les identifiants

Un agent qui détient un jeton API étendu peut effectuer l'appel bulk avant que quiconque voie l'ensemble des cibles. Vous pouvez ajouter des invites et des journaux autour de cette conception, mais l'identifiant donne toujours au processus une échappatoire. Conservez-le auprès d'un exécuteur d'actions capable de refuser ou d'approuver la requête avant qu'elle n'atteigne l'API externe.

Sallyport adopte cette approche pour les actions HTTP et SSH prises en charge : l'agent effectue la demande via sa connexion MCP, tandis que l'application conserve l'identifiant et exécute l'action. Son autorisation par session et l'approbation facultative de la clé à chaque appel conviennent à un workflow où un agent peut préparer une requête bulk sans recevoir de secret réutilisable.

Cette approbation ne constitue pas toute la conception de sécurité bulk. Une carte d'approbation pour un appel HTTP ne peut pas dire à l'examinateur si un filtre renverra 10 dossiers ou 10 000, sauf si l'agent a d'abord produit et conservé le manifeste des cibles. Utilisez la passerelle pour contrôler l'autorité, puis faites en sorte que le workflow de l'application lie prévisualisation, sélection, approbation et commit.

Le journal d'audit doit également comporter deux niveaux de détail. Un journal doit montrer l'exécution de l'agent qui a demandé le travail et la personne qui l'a approuvé. Un autre doit afficher chaque appel externe, avec l'empreinte de sélection, l'identifiant d'opération, l'endpoint et l'état du résultat. En cas d'incident, les enquêteurs doivent pouvoir répondre à « quel processus a fait la demande ? » et à « quels dossiers ont changé ? »

Un workflow bulk doit échouer de manière fermée lorsque l'intention devient ambiguë

Concevez le workflow de l'agent de façon à empêcher le passage direct d'une demande en langage naturel à une modification. La séquence suivante est volontairement monotone, car ce qui est monotone est plus facile à examiner.

1. L'agent transforme la demande en sélecteur, modification proposée, environnement et exclusions. Il demande une précision si l'un de ces éléments reste ambigu.
2. Il crée une sélection stable et récupère les champs de vérification pour tous ses membres. Il enregistre l'identifiant de sélection, l'empreinte, la requête, l'horodatage et l'état complet de la pagination.
3. Il présente le manifeste et l'effet proposé. Une personne approuve cette paire exacte ou la rejette.
4. Il envoie une requête de commit contenant la référence de sélection, l'empreinte attendue, la charge utile d'action, la clé d'idempotence et, lorsque c'est possible, les versions des dossiers.
5. Il présente séparément les résultats terminés, échoués, ignorés et inconnus. Il ne transforme jamais un résultat partiel en message enthousiaste annonçant que le travail est terminé.

N'approuvez pas une commande brute comme « exécuter le script de nettoyage » lorsque la commande peut calculer ses cibles plus tard. Cette pratique est populaire parce qu'elle est rapide et familière, notamment dans les équipes qui font déjà confiance à leurs scripts. Elle échoue parce que l'approbation porte sur le texte du code, pas sur le jeu de données réel. Une petite modification des données entre la confirmation et l'exécution peut faire réaliser à la commande un travail non approuvé.

Pour les tâches récurrentes, prédéfinissez des sélecteurs étroits et un nombre maximal, puis demandez une vérification chaque fois que la sélection dépasse cette limite ou contient une catégorie inhabituelle. Un nombre maximal est une barrière de sécurité, pas une autorisation. Le manifeste reste la preuve des dossiers réellement touchés par la tâche.

La première tâche d'implémentation est simple : faites renvoyer à votre endpoint bulk un identifiant et une empreinte de sélection, puis rejetez les requêtes de commit qui ne répètent pas ces deux valeurs. Une fois ce contrat établi, les agents, les tableaux de bord et les scripts disposent tous d'une limite stricte qu'ils peuvent respecter.