Contrat d’outil IA : séparer proposition, autorisation, exécution et vérification

L’assistant propose de créer une demande d’intervention. L’utilisateur confirme, un appel part vers le logiciel métier, puis la connexion se coupe. L’écran affiche « terminé » parce que l’appel d’outil a été lancé. Pourtant, personne ne sait si la demande existe. Une seconde tentative risque maintenant de créer un doublon : la frontière entre proposition, permission et effet a disparu.

Le risque est de croire qu’un appel correctement formé constitue une opération permise et réussie. Un contrat d’outil fixe la cible, la portée, les conditions d’autorisation, l’approbation éventuelle, le résultat vérifiable et la conduite en cas d’incertitude. Le modèle suggère une opération ; le serveur décide si elle peut partir. La preuve de réussite vient du système qui porte l’effet.

Nous concevons un outil fictif qui ouvre une demande interne de revue d’un dossier de service. Il ne commande aucune intervention physique, n’envoie aucun message client et ne déclenche aucun paiement. Le contrat JSON et les quatre traces ci-dessous sont des illustrations de conception, sans connecteur ni modèle exécuté. Les capacités requises devront être vérifiées sur votre interface réelle.

Dans votre projet d’IA sur mesure reliée aux opérations métier, décrivez d’abord ce que « créer une demande » doit établir : dossier cible, motif autorisé et référence retrouvable. La conception d’agents IA avec outils contrôlés traduit cette opération en arguments proposés, politique serveur et preuve de sortie. Le contrat ci-dessous permet de vérifier séparément un refus avant remise et un résultat inconnu après remise.

Pour qui définir un contrat d’outil agent

Commencer lorsque l’assistant peut produire un effet

Le sujet concerne responsables métier, développeurs, architectes et sécurité dès qu’un assistant peut créer, modifier, transmettre ou déclencher quelque chose. Même une demande interne mobilise une file de traitement et peut dévoiler des informations. La conséquence de l’opération détermine les contrôles utiles ; son intitulé « simple outil » ne dit rien du risque.

Notre outil ouvre une revue sur le dossier D-42 de l’établissement A, vers une file déjà configurée. La sortie attendue est une référence de demande effectivement créée avec le dossier et le motif validés. L’outil ne choisit pas librement un destinataire externe. Le métier décide quelle ouverture est légitime ; l’intégration vérifie comment l’interface peut la porter.

Garder le protocole à sa place

Une interface de function calling ou MCP décrit comment découvrir et appeler des outils. Elle ne remplace pas la politique métier. La spécification MCP des outils demande notamment validation des entrées et contrôles d’accès côté serveur ; elle distingue aussi contenu structuré d’un résultat et génération structurée par le modèle.

Le contrat proposé est indépendant du fournisseur. Il ne prétend pas être un message MCP conforme ni une extension officiellement standardisée. Les identifiants, statuts et règles illustrent notre application. Une description d’outil facilite la sélection par le modèle ; l’adaptateur, le service d’autorisation et le système métier doivent encore faire respecter les limites.

Séparer les quatre décisions du parcours

Proposer et autoriser répondent à des questions différentes

La proposition demande : « quelle opération semble utile avec ces faits ? ». L’autorisation demande : « cette identité peut-elle réaliser cette opération sur cet objet, dans cet état, maintenant ? ». Un raisonnement convaincant ne constitue pas un droit. Inversement, posséder un rôle général ne prouve pas que l’action proposée respecte la règle du dossier.

L’application conserve une proposition identifiée et versionnée. Elle distingue le motif suggéré des faits consultés et présente les paramètres utiles à l’approbateur. Une modification de cible ou de motif crée une nouvelle version. L’autorisation évalue cette version précise, avec l’identité établie par le service ; elle ne reprend pas comme vérité un rôle annoncé par le modèle.

Exécuter et vérifier ne produisent pas la même preuve

L’exécution remet une intention à l’adaptateur puis, si les contrôles passent, au système métier. La vérification établit l’effet réellement accepté ou observable : référence créée, objet lié, état pertinent. Un accusé de prise en charge peut signifier que l’opération attend encore dans une file. Le statut doit suivre le contrat de l’interface, sans élargir la portée de sa réponse.

Dans notre exemple, la demande de revue créée ne signifie pas que le dossier est revu. Une réponse transport réussie ne signifie pas non plus que la demande est créée, si le service expose seulement une acceptation asynchrone. L’application nomme séparément intention reçue, traitement en cours, création confirmée et résultat inconnu ; le modèle reformule ces faits sans inventer leur progression.

Contrat JSON : une intention et des règles serveur

Décrire ce que la proposition peut demander

Le modèle propose une référence de dossier, sa version observée et un motif parmi les valeurs métier permises. Il n’envoie ni compte administrateur, ni jeton fournisseur, ni URL de destination. La forme des arguments sera validée séparément ; le contrôle d’autorisation détermine ensuite si leur sens et leur portée sont acceptables pour cette identité.

Le document suivant rassemble une proposition et la politique de l’outil pour faciliter la lecture. En implémentation, la politique est stockée et résolue côté serveur ; le client ne peut pas la fournir ou la remplacer. Les noms et références sont fictifs. Les fonctionnalités de version conditionnelle et de recherche d’opération sont des exigences à vérifier, pas des capacités attribuées à un ERP existant.

{
  "tool": "ouvrir_revue_dossier",
  "contract_version": "2",
  "proposal": {
    "id": "P-42",
    "revision": 1,
    "arguments": {
      "dossier_ref": "D-42",
      "expected_version": 7,
      "reason_code": "DONNEE_A_VERIFIER"
    }
  },
  "server_policy": {
    "identity_source": "verified_session",
    "scope_source": "current_access_policy",
    "target_queue": "configured_internal_review",
    "approval_binding": "proposal_and_contract_revision",
    "recheck_before_dispatch": true,
    "unknown_outcome": "reconcile_before_new_attempt"
  },
  "effect_to_verify": {
    "request_ref": "present",
    "dossier_ref": "matches_approved_target",
    "reason_code": "matches_approved_reason"
  }
}

Versionner aussi la signification de l’opération

Le contrat associe nom d’outil, version et conséquence métier. Si « ouvrir une revue » déclenche demain une notification externe, conserver le même nom ne conserve pas la même portée. L’équipe réexamine droits, approbation, données transmises et recette. Une évolution de schéma ou de politique peut aussi invalider les propositions qui attendaient leur exécution.

Les réponses structurées distinguent code de décision, référence de tentative et preuve disponible. Elles limitent les champs exposés au modèle. Un outil ne doit pas renvoyer tout le dossier parce que le système a réussi une écriture. Le contrat de sortie décide ce qui est nécessaire pour expliquer la création et reprendre une attente, avec un accès protégé aux détails de diagnostic.

Établir identité, portée et objet cible

Résoudre l’identité depuis un contexte vérifié

Le serveur récupère l’identité depuis la session ou le mécanisme d’authentification vérifié, puis la rattache aux droits courants. Un champ « utilisateur » présent dans les arguments n’établit pas ce droit. Le compte technique de l’adaptateur reste limité aux opérations prévues ; son accès large éventuel ne devient pas une délégation implicite de toutes ses permissions à l’agent.

Les bonnes pratiques de sécurité MCP décrivent notamment le risque de confused deputy et interdisent le transfert aveugle de jetons destinés à une autre ressource. Le montage d’identité et de délégation doit respecter les interfaces effectivement retenues ; une chaîne d’appels réussis ne suffit pas à prouver cette frontière.

Contrôler l’objet sans divulguer le périmètre étranger

La référence D-42 est résolue dans la portée autorisée du demandeur, puis confrontée à l’opération. Connaître une référence ne donne pas le droit d’ouvrir une revue sur le dossier. Le serveur ne laisse pas le modèle déplacer la portée vers l’établissement B en reformulant sa demande. Une note ou une pièce consultée peut contenir une instruction ; elle reste une donnée sans autorité.

Un refus doit permettre la reprise sans révéler des détails étrangers. Selon la politique de confidentialité, la réponse peut rester générique sur existence et accès. Le journal protégé garde la raison technique nécessaire à l’équipe habilitée. Les essais contrôlent aussi cette sortie : bloquer l’écriture tout en exposant le nom du dossier interdit reste une divulgation à traiter.

Autoriser selon l’opération et l’état courant

Appliquer une politique métier hors du raisonnement IA

L’autorisation relie identité, objet, opération et état. Le rôle de gestionnaire peut permettre une revue sur un dossier actif sans autoriser sa réouverture après clôture. Le motif peut être permis dans une file et interdit dans une autre. Les règles sont évaluées dans un service déterministe ou un mécanisme contrôlé, avec une décision explicable et une version de politique.

OWASP associe l’Excessive Agency à des fonctions, permissions ou degrés d’autonomie excessifs et recommande notamment le contrôle humain des actions à fort impact. Pour notre outil, cela conduit à une opération bornée et à des contrôles en aval du modèle. Une approbation reste une condition supplémentaire ; elle ne neutralise pas un refus serveur.

Réévaluer les conditions juste avant la remise

Exemple concret : D-42 passe de v7 à v8 entre proposition et exécution. Le serveur vérifie à nouveau rôle, état et version utile avant la remise ; dans notre contrat, ce changement impose une nouvelle préparation. Un simple contrôle initial ne protège pas le temps passé en attente d’approbation. Le journal conserve la réserve de version, sans attribuer une nouvelle décision au premier accord.

Le contrôle local laisse encore un intervalle avant l’écriture distante. Une précondition réellement appliquée par l’interface métier peut protéger la version pendant l’opération. Si cette capacité manque, l’équipe ne prétend pas rendre le parcours atomique par un contrôle local. Elle réduit la conséquence, change la mission ou organise une vérification/reprise compatible avec la limite identifiée.

Lier une approbation à une proposition exacte

Montrer la cible et la conséquence au bon responsable

L’approbateur voit dossier, motif, file, conséquence et informations qui justifient la proposition. Une phrase générale « accepter l’action de l’agent » masque ce qu’il valide. Son droit d’approbation est contrôlé indépendamment du droit d’accès du demandeur. Le parcours précise qui pourra traiter la demande créée ; approuver une ouverture ne garantit pas la capacité disponible dans la file.

Une correction du motif crée P-42 révision 2 et exige une décision adaptée à cette nouvelle proposition. L’accord sur la révision 1 n’est pas recyclé. Le serveur conserve référence d’approbation, identité, moment, proposition et version de contrat liées. Il évite de placer secrets et copie intégrale des sources dans ce dossier de preuve lorsque des références suffisent.

Borner la validité sans inventer une durée universelle

Dans les traces pédagogiques, l’approbation expire à 10 h 05 UTC. Cette heure n’est ni une recommandation de durée ni un standard MCP. Le métier fixe la validité selon fraîcheur, conséquence et cadence des changements. L’expiration est contrôlée par le serveur au point prévu dans le contrat ; une indication visuelle de compte à rebours ne l’applique pas.

La décision peut être révoquée avant départ. L’état local doit alors empêcher une nouvelle remise, avec un contrôle cohérent avec la prise en charge de la tentative. Après départ, retirer l’approbation ne prouve pas que l’opération distante est annulée. Le parcours distingue révocation avant envoi, demande d’annulation et résultat effectivement constaté, au lieu d’afficher le même message dans les trois cas.

Exécuter sans transformer une attente en doublon

Identifier l’intention et rendre sa remise observable

Le serveur crée une intention durable I-42 liée à la proposition approuvée. La responsabilité de l’orchestrateur porte sur sa prise en charge, son journal et sa fin ; l’adaptateur porte sur l’appel contractuel et sa réponse. Le mécanisme doit empêcher deux workers locaux d’envoyer simultanément la même intention. Un identifiant dans un log ne remplit pas seul cette fonction.

Une garantie distante d’idempotence doit être vérifiée dans la documentation et sur l’interface retenue, avec sa portée et sa durée. Si elle existe, la même intention utilise la même clé selon ce contrat. Si elle n’existe pas, une table locale évite certains doublons locaux mais ne prouve pas une création distante unique après une coupure réseau. La limite reste écrite.

Traiter le résultat inconnu comme un état à résoudre

Cas concret : une coupure survient après remise de I-45. Ce timeout ne permet pas de conclure « rien n’a été créé ». L’intention passe à résultat inconnu, avec tentative, cible et instant enregistrés. Le système bloque la répétition automatique. Un rapprochement utilise une référence d’opération, une recherche fiable ou une intervention habilitée selon les capacités vérifiées, avant de décider si une autre remise est permise.

Le budget de reprise borne nombre de tentatives, temps d’attente et escalade ; il ne sert pas à forcer une deuxième écriture pour obtenir une réponse. Si aucune observation fiable n’est possible, la sortie reste incertaine et le dossier est transmis au responsable. Une absence dans une recherche éventuellement retardée n’est pas la preuve immédiate d’une absence d’effet.

Prouver l’effet et présenter le bon statut

Vérifier ce que le système confirme réellement

La preuve de création rapproche référence de demande, dossier et motif approuvés. Selon le contrat distant, elle peut venir d’une réponse définitive ou d’une lecture de confirmation. Le service documente les champs probants, leur fraîcheur et leurs limites. Une réponse qui contient seulement « accepted » ne peut pas être reformulée en « revue créée et traitée ».

La sortie du contrat distingue refus avant remise, traitement en cours, effet confirmé et inconnu. La responsabilité de l’adaptateur est d’associer preuve et tentative. Une erreur de lecture après création confirmée n’efface pas la preuve obtenue ; elle signale la difficulté de vérification supplémentaire. Le rapprochement conserve les événements au lieu de remplacer le parcours par le dernier code HTTP rencontré.

Contrôler la phrase finale autant que l’écriture

L’assistant reçoit le statut établi et la référence utile. Il peut expliquer « demande R-98 créée sur D-42 », mais pas « problème résolu ». Le dossier protège contre une réponse rassurante qui dépasserait l’effet. Lorsque le résultat est inconnu, l’écran montre l’attente et le responsable de reprise ; il n’incite pas l’utilisateur à cliquer de nouveau comme si le premier essai avait échoué sans conséquence.

Le journal de décision associe proposition en entrée, identité, politique, approbation, intention, tentative et preuve finale en sortie. Les accès et la conservation des traces sont définis pour le service. Le support reçoit les références nécessaires à l’enquête, sans secrets fournisseur ni données hors portée. La journalisation sert la reprise, avec une personne capable de constater ou corriger l’effet.

Quatre traces : accepté, refusé, expiré et inconnu

Lire des parcours attendus, sans les confondre avec des essais

Ces traces sont construites sur quatre intentions distinctes. Elles n’attestent aucun appel réel ni résultat de sécurité. Les heures sont fictives et exprimées en UTC. Chaque ligne expose le dernier fait établi, la remise éventuelle et le statut permis. Le vrai dossier de recette ajoutera événement observé, preuve et écart pour chacun de ces chemins.

Éprouver les frontières qui pourraient invalider ces traces

La recette teste aussi changement de motif après accord, rôle retiré, dossier passant à v8, double prise en charge locale et résultat distant tardif. Elle cherche la preuve de non-remise lorsque le contrôle doit bloquer, puis la preuve d’effet pour la réussite. Un refus verbal du modèle n’est pas un résultat suffisant : l’adaptateur doit être testé directement.

Les seuils d’ouverture du pilote séparent critères bloquants et qualité des propositions. Écriture hors portée, réutilisation d’un accord invalide ou reprise créant un doublon ne se compensent pas par un taux élevé de bonnes suggestions. Le dossier conserve les inconnus et les abandons dans son dénominateur ; les retirer rendrait le taux de réussite de l’outil artificiellement rassurant.

Erreurs fréquentes dans les outils d’agents

Confondre arguments conformes et opération permise

Un JSON conforme peut viser un dossier étranger, un état interdit ou une décision expirée. Le risque est de croire qu’un schéma ferme la frontière métier. La validation de forme facilite l’interprétation ; l’autorisation vérifie la portée et la conséquence. Les deux contrôles ont leurs preuves et leurs responsables, même si l’implémentation les appelle dans le même parcours.

Autre erreur : faire confiance à une annotation « lecture seule » ou « non destructif » pour éviter l’examen de l’outil. Les annotations décrivent un comportement annoncé, elles n’établissent pas seules une permission ni l’absence d’effet. Une opération nommée « préparer » peut enregistrer une pièce ou déclencher un traitement ; l’intégration doit observer sa conséquence réelle.

Prendre l’accord humain pour une garantie d’exécution

Le gestionnaire peut approuver une mauvaise cible si le parcours lui présente trop peu de contexte. Il peut aussi approuver une cible correcte avant que le dossier change. L’accord doit être intelligible, lié et réévalué selon le contrat ; il ne remplace ni le contrôle serveur ni une précondition distante. La responsabilité ne se résout pas par une case « confirmé ».

Paradoxalement, un outil qui expose honnêtement un résultat inconnu est plus exploitable qu’un outil qui transforme toute coupure en échec à relancer. La reprise peut prendre davantage de temps, mais conserve la possibilité de constater le premier effet. Le bon objectif est une opération maîtrisable, pas une conversation qui donne toujours une impression de réussite.

Plan d’action : livrer un contrat vérifiable

Réunir le métier et l’intégration sur une opération

Le responsable métier choisit une opération utile, ses exclusions et ses conditions d’approbation. La sécurité fixe identité et portée. L’intégration vérifie interface, préconditions, codes de résultat, idempotence éventuelle et moyen de rapprochement. Le dossier distingue fonctions documentées, observations d’essai et capacités encore inconnues ; une hypothèse favorable ne passe pas silencieusement dans le contrat accepté.

Les premiers livrables sont définition versionnée de l’outil, politique d’autorisation, écran d’accord, intention durable et réponse structurée. Le journal et le repli sont conçus avec la recette. Pour une opération ERP, Dawap coordonne les vérifications avec l’éditeur ou l’intégrateur ERP du client lorsque cela est nécessaire ; le choix d’un modèle ne débloque pas une interface métier absente.

• Nommer l’opération et l’effet à prouver ; exclure les conséquences que l’interface ne permet pas de maîtriser.
• Relier identité, portée et version de dossier à la décision serveur ; attribuer la politique au responsable compétent.
• Conserver l’accord sur les paramètres exacts ; refuser sa réutilisation après une modification ou son expiration.
• Tester le repli sur résultat inconnu ; ouvrir le pilote seulement avec une reprise attribuée et exercée.

Fermer les réserves avant d’étendre les effets

La recette commence sans effet opérationnel sur des données de test isolées. Elle confronte les quatre traces aux événements réels et ajoute les changements de version, les doubles remises et les coupures. L’équipe attribue chaque écart : mauvaise proposition, politique incorrecte, adaptateur défaillant, interface distante ambiguë ou phrase finale trompeuse. Le propriétaire doit pouvoir démontrer sa correction.

Avant le pilote, l’exploitation exerce la reprise d’un inconnu et l’arrêt de nouvelles admissions. Elle vérifie qui peut rechercher la demande, qui peut la corriger et quelles informations sont disponibles. Le budget de reprise et la capacité humaine de la file entrent dans la décision. Le pilote conserve les intentions non terminées dans le suivi, avec le délai et le travail laissés au support.

Une nouvelle opération ou une nouvelle conséquence réouvre la revue du contrat. Ajouter un envoi client à la création interne change destinataires, preuves et possibilité de correction. L’équipe évite de réutiliser les accords ou les conclusions de recette de l’ancienne version. L’extension avance lorsque l’accès, le journal, l’effet et le repli correspondent à ce qui a été réellement testé.

Guides complémentaires pour la mission et le SI

Relier le contrat d’outil à une mission bornée

Le contrat de mission d’un agent support définit les sources, sorties, limites et conditions d’arrêt de l’agent entier. Le contrat d’un outil approfondit une opération disponible dans cette mission. Accorder le droit d’appeler un outil ne donne pas automatiquement le droit de poursuivre toute recherche ou d’étendre la mission.

La qualification et la création restent deux livrables distincts. Une mission qui produisait seulement une fiche interne doit être revue avant de recevoir l’outil d’ouverture. Les tickets d’évaluation incluent alors la décision de proposer l’action, les cas où elle doit être refusée et la charge de traitement ajoutée à la file, au-delà de la qualité du texte.

Raccorder les preuves au contexte et au dossier durable

Le contexte ERP/CRM et les actions contrôlées approfondit les sources d’autorité et la cohérence des lectures avant une proposition. Le présent contrat utilise ces faits sans supposer qu’ils restent vrais jusqu’à l’écriture. La version et la fraîcheur doivent avoir un sens partagé entre proposition et contrôle d’exécution.

Les états et exceptions d’un dossier métier avec IA prennent le relais après la fin de l’appel. Une intention inconnue reste rattachée au dossier ; un résultat tardif est rapproché sans écraser l’histoire. La sortie du modèle, l’état du travail et l’effet du système métier demeurent consultables séparément.

Conclusion : rendre l’action vérifiable hors du modèle

Un contrat d’outil utile relie une proposition précise à une identité, une portée et des conditions d’exécution. Il définit ce qui établit l’effet et ce qui reste inconnu. Le serveur applique les règles ; l’approbateur décide sur une cible intelligible ; le système métier porte la preuve de l’opération réellement acceptée.

Le JSON, les traces et les scénarios doivent pouvoir être contredits par une recette. Refus, expiration, changement de version et réponse perdue sont des parcours de première importance. Une opération supplémentaire n’est ouverte qu’avec ses propres droits, son résultat vérifiable et une reprise compatible avec les capacités réelles de l’interface.

La conception d’agents IA sur mesure et de leurs outils métier transforme ces exigences en contrats, adaptateurs et preuves de recette. Le niveau d’autonomie suit ce que les équipes peuvent autoriser, vérifier et reprendre, avec la conséquence métier en vue.

Pour construire cette IA métier sur mesure reliée à vos logiciels, Dawap accompagne votre équipe dans la qualification d’une opération et de son interface avant de l’exposer à l’agent. Le dossier de recette conserve les paramètres approuvés, le refus sur une cible étrangère et le parcours de rapprochement après réponse perdue. Si l’effet ne peut pas être retrouvé automatiquement, la mission prévoit une vérification attribuée ; elle ne promet pas une réussite que le connecteur ne peut établir.