# Concevoir des actions d'agent OpenAPI que les agents peuvent utiliser en toute sécurité

Un document OpenAPI peut indiquer à un agent comment appeler un endpoint. À lui seul, il ne peut pas lui dire ce que cet appel est autorisé à signifier, quand une intervention humaine est nécessaire ni comment se comporter après un échec ambigu. Traiter chaque opération documentée comme une action d'agent produit des outils qui semblent complets dans une démonstration, puis deviennent dangereux en situation réelle.

Une action utile est plus petite qu'un endpoint. Elle a un objectif limité, des entrées que l'agent peut justifier, un résultat sur lequel il peut agir, une décision d'approbation liée aux conséquences et un plan explicite en cas d'échec. Faites ce travail de conception avant de relier une opération à un agent. Le faire après un double débit, une modification accidentelle en production ou une fuite de jeton est une façon pénible d'apprendre la leçon.

## Une opération n'est pas encore une action d'agent

Un endpoint HTTP, une opération OpenAPI et une action d'agent répondent à des questions différentes. On les confond parce qu'une opération OpenAPI constitue un point de départ pratique, mais ces distinctions déterminent si l'automatisation reste compréhensible.

Un endpoint est une adresse comme `/v1/deployments`. Une opération ajoute une méthode HTTP : `POST /v1/deployments` diffère donc de `GET /v1/deployments`. Une action d'agent ajoute le contrat humain et opérationnel : quel objectif elle poursuit, quels arguments elle accepte, quels effets elle peut produire, quelles preuves attestent sa réussite et qui doit donner son consentement.

La spécification OpenAPI définit un objet Operation avec des champs comme `operationId`, `parameters`, `requestBody`, `responses` et `security`. Utilisez ces champs comme des éléments d'information, pas comme une liste de contrôle automatique pour la publication. Une opération dont le schéma est entièrement défini peut tout de même être une très mauvaise action d'agent si sa description dissimule un effet en production derrière un nom anodin.

Prenons ces deux opérations :

```text
GET  /v1/projects/{project_id}/builds/{build_id}
POST /v1/projects/{project_id}/builds/{build_id}/promote
```

La première récupère un enregistrement. La seconde peut modifier le trafic, publier des artefacts ou changer un canal de mise en production. La route ne fait qu'esquisser cette différence. La conception de l'action doit l'énoncer clairement.

J'ai vu des équipes exposer un outil générique `request` parce que leur API possédait déjà un fichier OpenAPI propre. L'agent pouvait alors composer des chemins, des chaînes de requête et des corps arbitraires. Ce n'est pas un catalogue d'actions. C'est une exécution de code à distance contre une API métier, avec une ponctuation plus soignée.

N'exposez une opération qu'après avoir pu écrire une phrase de cette forme : « Cette action [fait quelque chose de précis] sur [un objet limité] et renvoie [la preuve de l'état obtenu]. » Si vous ne pouvez pas l'écrire sans verbes vagues comme « gérer », « traiter » ou « prendre en charge », l'action reste trop large.

## Commencez par la conséquence, pas par le schéma de requête

L'approbation doit dépendre des conséquences d'un appel, pas de sa méthode HTTP ni de la simplicité apparente de son corps JSON. Un petit `POST` peut créer une obligation irréversible. Un `GET` détaillé peut exposer des données privées. Un `DELETE` peut se contenter de supprimer un brouillon jetable, tandis qu'un `PATCH` peut révoquer l'accès de tous les autres utilisateurs.

Avant d'examiner les champs, décrivez l'effet avec des termes qu'une personne responsable du système reconnaîtrait. Demandez-vous ce qui change si le serveur exécute l'appel deux fois, s'il l'exécute sur le mauvais objet ou s'il l'exécute cinq minutes plus tard que prévu par l'agent. Ces questions séparent une récupération courante d'une action qui mérite un examen.

J'utilise quatre classes de conséquences pour examiner une opération candidate :

- Observation : récupère des informations limitées et ne modifie rien côté serveur.
- Changement réversible : crée, met à jour ou supprime quelque chose avec une procédure d'annulation documentée et réellement praticable.
- Engagement externe : envoie un message, lance une tâche payante, publie du contenu ou modifie un état visible par un client.
- Changement irréversible ou étendu : supprime définitivement des enregistrements, renouvelle des accès, modifie des permissions ou affecte de nombreux objets.

Ces classes ne constituent pas un modèle d'autorisations. Elles imposent des descriptions honnêtes. Une opération « créer une facture » relève d'un engagement externe même si la requête ne comporte que deux champs. Une opération « redémarrer l'environnement » peut devenir un changement étendu lorsqu'un environnement contient de nombreux services.

N'inférez pas la sécurité à partir du nom d'une méthode. HTTP définit `GET` comme sûr au sens du protocole : le client ne doit pas demander de modification d'état au moyen de cette méthode. C'est une convention, pas la preuve qu'un serveur donné la respecte. J'ai rencontré des endpoints de diagnostic qui actualisaient des caches, déclenchaient la génération de rapports et consommaient une capacité limitée lorsqu'ils étaient appelés à répétition. Testez le comportement réel, pas celui que le verbe semble suggérer.

Séparez aussi l'effet d'une action de la sensibilité de son résultat. Récupérer un jeton d'accès est peut-être une opération en lecture seule, mais renvoyer cette valeur à un agent annule l'intérêt de contrôler l'appel. La récupération d'une fiche client privée peut nécessiter une approbation même si l'API ne modifie pas un seul octet.

Une bonne fiche d'action consigne ces deux dimensions en langage clair :

```text
Action: promote_preview_build
Effect: Changes one named preview build into the staging release channel.
Scope: One project and one build ID.
Result: Release ID, resulting channel, and server timestamp.
Human consent: Required for every call.
Retry: Never retry automatically unless the server accepts the same idempotency token.
```

Cette fiche révèle souvent des sémantiques manquantes de l'API avant même qu'un agent écrive une ligne de code. Si personne ne peut dire si une nouvelle tentative est sûre, l'action n'est pas prête.

## Les entrées doivent avoir des limites qu'un agent ne peut pas contourner en discutant

Une action d'agent a besoin d'un contrat d'entrée plus restreint que celui qu'accepte souvent l'endpoint. Les schémas OpenAPI définissent les types et la structure, mais un agent a aussi besoin de contraintes qui l'empêchent d'élargir une tâche avec des arguments inventifs.

Prenons une opération de création de déploiement. L'API brute peut proposer de nombreuses options pour les clients internes : environnement, référence d'artefact, région, nombre de réplicas, variables d'environnement, fonctionnalités expérimentales, étiquettes et objet de configuration libre. Donner tous ces champs à un agent transforme une demande simple en surface d'administration non examinée.

Créez une action dont les entrées correspondent à la tâche. Si la tâche est « déployer le build qui a passé les tests dans un environnement de prévisualisation », l'agent peut n'avoir besoin que de `project_id`, `build_id` et d'une courte `reason`. L'exécuteur peut sélectionner l'environnement autorisé et rejeter tout ce qui sort du périmètre de l'action.

Cette forme de requête rend la limite concrète :

```json
{
  "project_id": "proj_4821",
  "build_id": "build_9017",
  "reason": "Preview requested after integration tests passed"
}
```

N'ajoutez pas de `target_url`, d'`headers` arbitraires, de corps de requête brut ou d'objet général `options` simplement parce que l'endpoint sous-jacent les accepte. Chaque échappatoire transforme votre action soigneusement nommée en client générique.

Utilisez les champs OpenAPI qui portent déjà des limites utiles. Définissez `additionalProperties: false` lorsqu'un objet ne doit accepter que des champs nommés. Utilisez `enum` pour un ensemble réellement restreint de valeurs autorisées. Ajoutez des restrictions de longueur et de format lorsque les identifiants suivent une convention établie. Marquez les champs comme obligatoires lorsque l'exécuteur ne peut pas les déduire sans risque.

Par exemple, ce fragment rejette les champs de configuration non examinés et rend la portée prévue visible dans le schéma :

```yaml
DeployPreviewRequest:
  type: object
  additionalProperties: false
  required:
    - project_id
    - build_id
    - reason
  properties:
    project_id:
      type: string
      pattern: '^proj_[A-Za-z0-9]+$'
    build_id:
      type: string
      pattern: '^build_[A-Za-z0-9]+$'
    reason:
      type: string
      minLength: 8
      maxLength: 240
```

`additionalProperties: false` évite un échec courant : l'agent apprend d'un autre exemple d'API qu'il peut envoyer `environment_variables`, y place des secrets ou des remplacements dangereux, et le serveur les accepte discrètement. Le rejet du champ fournit à l'agent une erreur utile plutôt qu'un déploiement inattendu.

Les schémas ne remplacent pas l'autorisation au niveau de l'objet. Un `project_id` valide peut tout de même désigner un projet situé hors de la tâche. L'exécuteur doit vérifier que l'objet demandé appartient au compte, à l'espace de travail, au dépôt ou à l'environnement autorisé. Effectuez cette vérification près de l'exécuteur de l'action, sans dépendre de l'explication de l'agent.

Le texte libre mérite une attention particulière. Un champ `reason` peut aider un réviseur, mais il ne doit jamais devenir un canal d'instructions pour l'exécuteur. Stockez-le comme annotation d'audit. Ne l'analysez pas pour y chercher des commandes, des sélecteurs de ressources ou des exceptions de permission.

## Les résultats attendus doivent aider à prendre la décision suivante

Un agent a besoin d'un résultat qu'il peut interpréter, pas d'une réponse HTTP brute déversée dans son contexte. Renvoyer chaque en-tête, champ de débogage et objet imbriqué augmente la confusion et peut divulguer des données inutiles à la tâche.

Définissez la réussite en termes métier avant de choisir les codes de réponse. Pour une action de déploiement, un résultat utile identifie le déploiement, son état et l'endroit où le serveur communiquera l'avancement. Pour une mise à jour d'enregistrement, il identifie l'enregistrement et confirme les champs modifiés. Pour une suppression, il confirme la cible et indique si une récupération reste possible.

Un résultat concis pour une opération asynchrone pourrait ressembler à ceci :

```json
{
  "status": "accepted",
  "deployment_id": "dep_2388",
  "project_id": "proj_4821",
  "build_id": "build_9017",
  "target": "preview",
  "operation_status": "queued"
}
```

Cette réponse dit quelque chose de précis : le serveur a accepté le travail, mais le déploiement n'est pas terminé. L'agent ne doit pas annoncer « déployé » après l'avoir reçue. Il doit soit utiliser une action séparée de consultation de l'état, soit dire à l'utilisateur que l'opération est en file d'attente.

C'est là que de nombreux documents OpenAPI induisent les agents en erreur. Une réponse `202 Accepted` a un sens précis : le serveur a accepté la requête pour traitement, mais ce traitement peut ne pas avoir commencé ou être terminé. Traiter `202` comme une réussite équivalente à un `200` terminé crée de fausses affirmations dans les journaux et les messages aux utilisateurs.

Séparez le résultat du transport du résultat de l'action. Un `200` HTTP peut contenir un échec métier comme `{\"state\":\"rejected\",\"reason\":\"build is not eligible\"}`. À l'inverse, `409 Conflict` peut indiquer à l'agent que l'état souhaité existe déjà. L'enveloppe de l'action doit convertir ces situations en un petit ensemble d'états explicites comme `completed`, `pending`, `already_in_desired_state`, `rejected` et `unknown`.

Ne promettez pas une uniformité fictive. Certaines API ne renvoient qu'un identifiant de tâche opaque, ce qui convient si vous exposez une action d'état capable de le résoudre. L'erreur consiste à dissimuler cette lacune. Indiquez exactement ce que le premier appel établit et ce qu'il n'établit pas.

Filtrez les détails d'erreur avant de les renvoyer à l'agent. Une erreur serveur peut contenir des URL internes, des en-têtes d'autorisation, des traces d'exécution ou les données d'un autre utilisateur. L'agent a besoin d'une raison exploitable, comme « le build ID n'appartient pas au project ID », ainsi que d'un identifiant de corrélation sûr pour permettre une enquête humaine. Il n'a pas besoin de la page d'exception du service en amont.

## L'approbation intervient au moment de l'engagement

Demandez une approbation lorsque l'appel peut créer un engagement important, et faites en sorte que l'écran d'approbation décrive l'objet et l'effet. Demander une seule fois l'autorisation vague d'un ensemble de pouvoirs futurs habitue les gens à valider un avertissement qu'ils ne peuvent pas évaluer.

L'approbation de session et l'approbation d'appel répondent à des problèmes différents. L'approbation de session signifie : « Je reconnais ce processus d'agent et je l'autorise à utiliser cet ensemble d'actions pendant son exécution. » L'approbation d'appel signifie : « J'approuve maintenant cette demande précise qui a des conséquences. » Ne remplacez pas l'une par l'autre.

Un agent qui peut consulter l'état des builds peut fonctionner pendant une heure sans déranger personne. Un agent qui promeut un build doit présenter le projet, le build ID, le canal de mise en production et la raison au moment de demander le consentement. Un réviseur peut juger cette demande. « Autoriser l'outil de déploiement » ne lui donne presque aucun élément.

N'utilisez pas une invite d'approbation pour remplacer la validation des entrées. Si une action permet à l'agent de spécifier une destination ou une portée de permissions arbitraire, un réviseur doit déchiffrer une charge utile volumineuse et instable sous pression. Limitez d'abord les entrées. L'approbation confirme ensuite une action bornée.

La fréquence appropriée dépend de l'effet. Exigez une approbation à chaque appel pour les actions qui publient, modifient des accès, déclenchent un paiement externe ou touchent une large portée de production. Un consentement de session peut convenir à un ensemble d'appels en lecture seule ou à des changements réversibles limités, mais seulement après que l'identité du processus et le catalogue d'actions sont visibles par le réviseur.

Sallyport applique cette distinction avec une autorisation de session pour tout nouveau processus d'agent et une approbation facultative à chaque utilisation d'un identifiant donné. Son verrou de coffre refuse également toute action lorsque le coffre est verrouillé. L'approbation ne peut donc pas transformer un coffre de secrets verrouillé en exception accidentelle.

Ne demandez pas à une personne d'approuver des échecs que le logiciel peut empêcher. Si un build n'est pas éligible à la promotion, l'exécuteur doit le rejeter avant toute demande d'approbation. Les invites servent à trancher des choix légitimes, pas à demander à un réviseur fatigué de repérer un état mal formé.

## Un délai d'expiration crée un état inconnu, pas une instruction de nouvelle tentative

Un délai d'expiration réseau après une requête qui modifie l'état est le cas d'échec qui révèle une conception négligée des actions d'agent. L'agent a envoyé la requête, puis perdu la réponse. Le serveur peut n'avoir rien fait, avoir terminé la modification ou être encore en train de la traiter. L'agent ne peut pas découvrir la vérité en supposant la réponse qui lui convient.

Prenons un échec courant. Un agent appelle `POST /v1/invoices` avec un client, un montant et un délai d'expiration. La connexion est interrompue après que le serveur a créé la facture, mais avant l'arrivée de la réponse. L'agent constate un délai d'expiration, réessaie avec les mêmes données et le serveur crée une deuxième facture. Le journal d'audit indique alors que l'agent a suivi sa règle de nouvelle tentative, ce qui est techniquement vrai et opérationnellement inutile.

Un jeton d'idempotence ne règle le problème que si le serveur l'implémente réellement. Le client génère un jeton par action voulue, l'envoie avec la requête initiale et réutilise exactement le même jeton lors d'une nouvelle tentative. Le serveur doit associer ce jeton à la requête d'origine et renvoyer le résultat initial, ou un résultat de conflit compatible, au lieu de répéter l'effet.

```text
Idempotency-Key: act_01HZX7FQ2Z9K8M6R4T3V1W0Y
```

L'enveloppe de l'action doit empêcher l'agent d'improviser ce jeton. Générez-le au moment de l'exécution, conservez-le avec la tentative d'action et ne le réutilisez que pour cette tentative. Un jeton fourni par l'agent peut entrer en collision, être réutilisé pour des requêtes sans rapport ou devenir une nouvelle surface d'injection de consignes.

Si l'API ne définit pas de sémantique d'idempotence documentée, ne réessayez pas automatiquement une opération modificatrice après un délai d'expiration. Renvoyez `unknown` avec l'identifiant de l'action et proposez une action de consultation en lecture seule pour examiner l'état du serveur. Si aucune consultation n'existe, un humain doit enquêter avant que quiconque répète la requête. Cette réponse semble gênante parce qu'elle l'est. Feindre la certitude ne l'améliore pas.

OpenAPI peut documenter un paramètre d'en-tête nommé `Idempotency-Key`, mais la documentation seule ne garantit pas le comportement du serveur. Testez-le volontairement : envoyez deux fois le même jeton et la même charge utile, puis le même jeton avec une charge utile différente. Le serveur doit faire converger la première paire et rejeter ou traiter clairement la requête modifiée. S'il exécute silencieusement les deux changements, l'en-tête n'est qu'un élément décoratif.

Les autres échecs ont besoin de leurs propres règles. Traitez `401` et `403` comme des conditions d'arrêt, pas comme un signal pour chercher un autre identifiant. Traitez `429` comme une condition d'attente uniquement lorsque l'API communique un délai de nouvelle tentative ou que votre action dispose d'une stratégie de temporisation limitée. Traitez les erreurs de validation comme des indications exploitables par l'agent uniquement lorsqu'elles identifient une correction autorisée.

## L'authentification ne donne pas à un agent le pouvoir de juger

Une déclaration `security` OpenAPI décrit la façon dont un client prouve son identité auprès d'une API. Elle n'indique pas si un agent doit appeler l'opération, s'il peut utiliser un identifiant donné pour un objet donné ni si un humain doit examiner l'effet.

L'objet Security Requirement de la spécification associe une opération à des schémas de sécurité nommés. Un schéma bearer peut indiquer à un client d'envoyer un en-tête d'autorisation. L'authentification basic peut lui indiquer de construire un en-tête d'identifiants. Il s'agit d'authentification du transport. N'y voyez pas davantage que ce qui est écrit.

Gardez ces quatre questions séparées :

- Qui ou quoi appelle cette action ?
- Quel identifiant l'exécuteur utilise-t-il auprès de l'API en amont ?
- Quels objets et quels effets cet identifiant autorise-t-il ?
- Quelles tentatives d'action une personne approuve-t-elle ?

Lorsque les équipes mélangent ces questions, elles remettent généralement un jeton à l'agent et appellent cela une autorisation. Le jeton apparaît alors dans les résultats de l'outil, l'historique du shell, les journaux de débogage, les invites ou un fichier de configuration. Sa révocation devient un chantier de nettoyage plutôt qu'une action unique.

La forme la plus sûre conserve l'identifiant dans l'exécuteur. L'agent fournit des entrées d'action limitées. L'exécuteur sélectionne un identifiant éligible, l'injecte dans la requête HTTP, évalue la réponse et renvoie le résultat filtré. L'agent n'a jamais besoin d'accéder en clair à une clé API pour demander une action.

Pour SSH, appliquez la même règle. Un agent peut devoir demander l'exécution d'une commande sur un hôte nommé, mais une commande générique accompagnée d'une clé privée largement approuvée donne une autorité bien plus étendue que nécessaire. Limitez l'identité de l'hôte, le compte, la forme de la commande et le traitement de la sortie selon l'objectif de l'action.

Sallyport utilise ce modèle d'exécution pour les appels HTTP et les commandes SSH : les identifiants restent dans son coffre chiffré et l'agent reçoit le résultat de l'action plutôt que le secret. Cette conception n'est utile que si vous exposez toujours des actions limitées et choisissez des approbations adaptées à leurs effets.

## La description de l'action doit préciser ce que le schéma ne peut pas exprimer

Les descriptions OpenAPI comptent parce que les agents les lisent comme des instructions, mais la prose doit clarifier les limites au lieu de dissimuler un second contrat API contradictoire. Placez les limites applicables dans les schémas et les exécuteurs. Utilisez les descriptions pour expliquer l'intention, les conséquences et les conditions qu'un système de types ne peut pas exprimer.

Nommez les opérations selon le résultat attendu par l'utilisateur. `getBuildStatus` en dit plus que `getBuildById` ; `createPreviewDeployment` en dit plus que `postDeployment`. Le nom ne doit pas promettre plus que ce que l'opération fait. Si le serveur met le travail en file d'attente, n'appelez pas l'opération `deployBuild` à moins que son résultat distingue l'acceptation de l'achèvement.

Rédigez les descriptions avec les détails que l'agent devrait autrement deviner :

```yaml
operationId: createPreviewDeployment
summary: Queue one tested build for the preview environment
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/DeployPreviewRequest'
responses:
  '202':
    description: Request accepted. Deployment work may still be pending.
  '409':
    description: The build already has a preview deployment or cannot enter preview.
```

Un résumé ne suffit pas pour les opérations à conséquences élevées. Consignez la cible prévue, la classe d'effet, l'exigence d'approbation, la règle de nouvelle tentative et les états de résultat dans des métadonnées d'action placées à côté du document OpenAPI. Vous pouvez utiliser des extensions `x-` si votre outillage les gère, mais présentez-les clairement comme des conventions privées. Les analyseurs OpenAPI standard ignorent les extensions inconnues. L'exécuteur doit donc les appliquer, et pas seulement les afficher.

Ne comptez pas sur une description qui dit « à utiliser avec prudence ». La prudence est un sentiment humain, pas une règle exécutable. Remplacez-la par une limite : un projet, prévisualisation uniquement, aucune variable d'environnement arbitraire, approbation à chaque invocation et aucune nouvelle tentative automatique après un résultat inconnu.

Les descriptions doivent aussi indiquer à l'agent quand refuser l'action. Une opération de promotion peut exiger une exécution de tests terminée. Un export de données peut exiger une référence de dossier fournie par le client. Une suppression peut exiger une consultation préalable confirmant que l'objet est un brouillon. Ces préconditions réduisent les invites inutiles et rendent les journaux d'audit plus faciles à interpréter.

## Testez l'action contre un opérateur négligent mais compétent

Un test du parcours nominal prouve seulement que l'API fonctionne lorsque toutes les hypothèses sont respectées. Testez une action comme si un opérateur rapide et compétent disposait d'un contexte incomplet, d'identifiants obsolètes et d'une tendance à recommencer après une erreur. Cela ressemble suffisamment aux échecs d'agents autonomes pour être utile.

Créez un petit environnement de test avec des objets jetables et un compte dont les permissions correspondent à celles de l'exécuteur prévu. Faites ensuite passer l'action par des cas qui éprouvent ses limites :

- Envoyez un champ d'entrée inconnu et vérifiez que l'exécuteur le rejette.
- Demandez un objet situé hors du projet ou de l'espace de travail autorisé.
- Refusez l'approbation et vérifiez qu'aucune requête en amont n'est envoyée.
- Provoquez un délai d'expiration après réception par le serveur d'une requête modificatrice.
- Renvoyez une réponse contenant des informations de débogage sensibles et vérifiez que le filtrage les supprime.

N'examinez pas uniquement l'état final de l'API. Vérifiez l'invite présentée à l'humain, la requête exacte envoyée par l'exécuteur, le résultat reçu par l'agent et le journal d'audit. Une requête réussie peut tout de même enfreindre le contrat de l'action si l'invite dissimulait la cible, si le résultat annonçait trop tôt la fin de l'opération ou si le journal ne permet pas de distinguer une demande refusée d'un rejet par le service en amont.

Pour une action avec approbation à chaque appel, testez l'ordre des étapes. L'exécuteur doit valider les contraintes statiques et résoudre suffisamment de contexte sûr pour présenter une demande compréhensible avant de demander le consentement. Il ne doit pas envoyer la requête puis demander l'approbation. Il doit aussi éviter une longue chaîne d'appels de consultation cachés qui exposerait plus de données que l'action finale n'en nécessite.

Testez volontairement les identifiants révoqués et expirés. L'exécuteur doit échouer par défaut, fournir une explication sûre et éviter les appels répétés avec le même identifiant inutilisable. Une boucle de nouvelles tentatives contre un identifiant rejeté peut remplir les journaux, déclencher des limites de débit et compliquer un simple problème d'accès.

Enfin, testez l'annulation. Si un utilisateur arrête l'agent pendant l'exécution d'une tâche en amont, l'enregistrement doit préciser si la requête n'est jamais partie, si elle a atteint le serveur ou si son état est devenu inconnu. L'annulation du processus local de l'agent n'annule pas nécessairement un effet distant.

## Publiez moins d'actions et rendez chacune défendable

Un petit catalogue d'actions vaut mieux qu'un client API générique, car chaque action peut porter un contrat raisonné. Ajouter des opérations est facile. Maintenir des sémantiques de résultat honnêtes, des limites d'objet, des invites d'approbation et un comportement fiable en cas d'échec, c'est là que se trouve le travail.

Commencez par une opération qui récupère un enregistrement d'état limité. Donnez-lui un nom indiquant l'objet, limitez les identifiants à la portée prévue et ne renvoyez que les champs dont l'agent a besoin. Ajoutez ensuite une action réversible et obligez-vous à définir ses règles de nouvelle tentative et d'approbation avant de l'implémenter.

Ne transformez pas une opération en action d'agent parce qu'un générateur OpenAPI peut l'exposer en un après-midi. Faites-le lorsque vous pouvez expliquer ce qui se passe après un délai d'expiration, ce que l'humain approuve, ce que l'agent voit et comment vous prouverez plus tard quelle requête a été effectuée. Si l'une de ces réponses dépend de l'idée que « l'agent fera probablement ce qu'il faut », laissez l'endpoint hors du catalogue.