Gouvernance des outils d'agent via une passerelle API AI : étendues, approbations, budgets et pistes d'audit
Une architecture de référence pratique pour gouverner les outils d'agent via une passerelle API IA : registres d'outils, clés étendues, portes d'approbation, budgets par outil, listes d'autorisation MCP et pistes d'audit de modèles/outils joints.
Le risque lié aux agents ne se limite plus à l'invite du modèle. Un agent de production peut rechercher des fichiers internes, interroger des enregistrements clients, appeler un serveur MCP, exécuter du code, ouvrir un navigateur, envoyer un e-mail, mettre à jour un CRM ou déclencher un workflow de facturation. La question de gouvernance devient : quel utilisateur, clé, modèle, agent et outil a été autorisé à effectuer quelle action, avec quel budget, quelle piste d'audit et quel chemin de restauration ?
Si chaque équipe gère l'accès aux outils dans son propre code SDK, la politique est dispersée entre les variables d'environnement, les tableaux de bord des fournisseurs, les middlewares d'application et les serveurs MCP non documentés. Un modèle plus sûr consiste à traiter l'exécution de l'outil d'agent comme un problème de plan de contrôle et à l'appliquer via une passerelle API AI ou un wrapper d'exécution d'outil standard que chaque agent doit utiliser.
Cet article sépare les faits, les recommandations et les prédictions. Les faits sont tirés des directives publiques actuelles : le Top 10 des applications LLM de l'OWASP comprend des risques tels que la divulgation d'informations sensibles, les vulnérabilités de la chaîne d'approvisionnement et l'agence excessive ; Le profil d'IA générative du NIST pour le cadre de gestion des risques d'IA met l'accent sur la cartographie, la mesure et la gestion des risques d'IA générative ; Les conseils pour les agents d'OpenAI recommandent d'évaluer les risques liés aux outils en fonction de l'accès en lecture/écriture, de la réversibilité, des autorisations et de l'impact financier ; et les directives d'autorisation MCP utilisent des concepts d'autorisation étendus pour les ressources et les opérations sensibles. Les recommandations ci-dessous sont des modèles de mise en œuvre et non des exigences universelles.
Le problème du lecteur : l'accès au modèle et l'accès aux outils sont confondus
Dans de nombreuses premières applications LLM, une clé API répondait à une question fondamentale : ce service peut-il appeler un modèle ? Les agents rendent cela trop grossier. Une clé capable d'envoyer des discussions terminées ne devrait pas être automatiquement capable d'exporter les données des clients, d'exécuter des commandes shell, de publier sur Slack, de modifier des tickets, de parcourir des sites Web arbitraires ou de soumettre des modifications de paiement.
La couche de gouvernance doit répondre à des questions plus spécifiques :
- Quel locataire, espace de travail, utilisateur, compte de service ou client revendeur a lancé l'exécution ?
- Quel modèle, modèle d'invite, version de l'agent et schéma d'outil ont été utilisés ?
- L'outil demandé était-il en lecture seule, réversible, irréversible, externe, financier ou privilégié ?
- Le demandeur disposait-il de la portée requise ?
- L'approbation a-t-elle été requise, accordée, refusée, expirée ou contournée par la politique d'urgence ?
- Combien a coûté l'outil, combien de fois a-t-il été appelé et quel budget cumulé restait-il ?
- Quelles sont les preuves disponibles pour le débogage, la vérification de la conformité et la restauration ?
L'architecture ci-dessous suppose que la passerelle reçoit déjà des appels de modèle. L'exécution de l'outil peut ensuite être acheminée via la même passerelle, via un service side-car ou via une bibliothèque standard qui rend compte à la passerelle avant et après chaque appel d'outil.
Architecture de référence : une couche de gouvernance des outils au niveau de la passerelle
Un système pratique de gouvernance des agents comporte sept éléments :
- Registre d'outils : liste faisant autorité des outils approuvés, des serveurs MCP, des fonctions hébergées, des outils d'exécution locaux et des API internes.
- Identité et couche de clé : clés de passerelle, utilisateurs, locataires, comptes de service, équipes et clients revendeurs.
- Moteur de portée : contrôles de stratégie qui décident si une clé ou un utilisateur peut invoquer une fonctionnalité d'outil spécifique.
- Classificateur de risques : métadonnées qui décrivent le rayon de l'explosion, la sensibilité des données, la réversibilité, l'impact externe et l'exposition aux coûts.
- Flux de travail d'approbation : approbation humaine ou système pour les actions à haut risque avant exécution.
- Grand livre des limites de budget et de débit : limites par outil et par agent, pas seulement limites de jetons par modèle.
- Stockage d'audit et de trace : enregistrements joints pour les appels de modèles, les appels d'outils, les approbations, les erreurs et les résultats.
La décision de conception importante est de faire de la passerelle le point de décision politique même si l'outil lui-même s'exécute ailleurs. Par exemple, un outil de navigateur peut s'exécuter dans un environnement de travail en bac à sable et une écriture CRM peut s'exécuter dans un service interne. La passerelle évalue toujours si l'appel est autorisé, enregistre la décision, suit le coût et renvoie une décision d'autorisation ou de refus signée.
Étape 1 : Créer un registre central d'outils
Un registre d'outils est l'inventaire qui empêche la « capacité d'agent inconnue » de devenir la valeur par défaut. Chaque outil doit avoir un propriétaire, un niveau de risque et des métadonnées opérationnelles. Un enregistrement de registre minimal peut ressembler à ceci :
{
"tool_id": "crm.create_ticket",
"display_name": "Créer un ticket d'assistance CRM",
"owner_team": "support-automatisation",
"execution_type": "internal_api",
"server_url": "https://tools.internal.example/crm",
"allowed_tenants": ["entreprise", "support"],"allowed_models": ["général-large", "général-rapide"],
"risk_tier": "réversible_write",
"data_classification": "client_métadonnées",
"required_scopes": ["tool:crm.create_ticket"],
"approval_policy": "not_required_under_100_tickets_per_day",
"default_timeout_ms": 8000,
"max_cost_per_call_usd" : 0,05,
"max_calls_per_run": 3,
"rollback_owner": "support-ops-oncall",
"retention_policy": "redacted_30_days"
Pour les serveurs MCP, le registre doit également inclure l'URL du serveur, les outils annoncés, la version du schéma, la méthode d'autorisation, la date de la dernière révision et si les nouveaux outils sont désactivés par défaut. MCP améliore l'interopérabilité, mais la compatibilité des protocoles n'est pas la même chose que l'autorisation de production. Les ressources et opérations sensibles nécessitent toujours des étendues explicites, des vérifications de routage et une isolation des locataires.
Champs de registre recommandés
- Nom de l'outil, identifiant canonique, propriétaire et contact de garde.
- Emplacement d'exécution : outil du fournisseur hébergé, serveur MCP, API interne, opérateur de navigateur, exécuteur de code, tâche de file d'attente ou outil SDK local.
- Titulaires, équipes, utilisateurs, versions d'agent et profils de modèle autorisés.
- Classification des données : publiques, internes, métadonnées client, contenu client, secrets, données de paiement, identifiants, données réglementées.
- Niveau de risque et réversibilité.
- Portées requises et règles d'approbation.
- Délai d'expiration, limites de débit, nombre maximal d'appels par exécution, budget d'exécution cumulé et coût maximal par appel.
- Mode de journalisation : charge utile complète interdite, expurgée, hachée, échantillonnée ou explicitement conservée.
- Instructions de restauration et chemin de remontée.
Étape 2 : Séparez les portées du modèle des portées des outils
Une clé de passerelle de production doit exprimer ce que l'appelant peut faire. L’accès au modèle et l’accès aux outils doivent être indépendants. Par exemple :
modèle:chat
modèle:incorporations
outil :docs.search_readonly
outil : crm.create_ticket
outil : email.send_requires_approval
outil : billing.refund_blocked
outil : code.execute_blockedCela empêche un chatbot à faible risque de devenir un agent d'automatisation accidentel. Il prend également en charge les modèles de rôle :
- Assistant développeur : discussion sur le modèle, recherche de documentation, explication du code, aucun outil d'écriture en production.
- Bot d'assistance : recherche de clients, création de tickets, rédaction de réponses, approbation requise pour les envois externes.
- Agent d'analyste : requêtes d'entrepôt de données en lecture seule avec limites de lignes, aucune exportation client par défaut.
- Agent administrateur : opérations privilégiées restreintes, approbation forte, clés de courte durée, audit complet.
- Agent locataire revendeur : accès au modèle au niveau du locataire, outils au niveau du locataire, plafonds budgétaires par client.
La recommandation est d'échouer la fermeture : les outils inconnus sont refusés, les portées manquantes refusent l'exécution, les outils MCP nouvellement annoncés sont inactifs jusqu'à leur approbation et les outils locaux doivent utiliser le même wrapper de stratégie que les outils hébergés.
Étape 3 : Classer les outils par rayon de souffle
Tous les appels d'outils ne nécessitent pas l'approbation humaine. La gouvernance doit être proportionnelle au risque. Un modèle de classification utile est :
Cette classification doit être visible lors de la révision du code et dans l'interface utilisateur d'administration. Les descriptions d’outils seules ne suffisent pas car les agents peuvent considérer les descriptions comme des instructions. Le moteur de stratégie doit s'appuyer sur les métadonnées et les étendues du registre, et pas seulement sur les noms d'outils en langage naturel.
Étape 4 : Ajouter des étapes d'approbation pour les actions à haut risque
L'approbation doit être ciblée. Si chaque appel d’outil nécessite une personne, l’agent devient inutilisable. Si aucun appel d'outil ne nécessite d'approbation, le système peut accorder une agence excessive.
Un processus d'approbation commun :
- L'agent demande un appel d'outil avec des arguments structurés.
- La passerelle évalue l'identité, la portée, le niveau de risque, le budget et la politique.
- Si une approbation est requise, la passerelle renvoie un événement d'approbation en attente au lieu d'exécuter l'outil.
- L'application affiche un aperçu à l'utilisateur ou envoie une notification opérationnelle à un canal d'approbation.
- L'approbateur peut approuver, refuser, modifier les arguments si la politique le permet ou demander des éclaircissements.
- La passerelle enregistre la décision et exécute uniquement la version approuvée.
La charge utile d'approbation doit montrer l'action en termes humains, pas seulement en JSON brut :
{
"approval_id": "appr_123",
"agent_run_id": "run_456",
"requested_by_user": "user_789",
"tool_id": "email.send",
"risk_tier": "communication_externe",
"summary": "Envoyer une réponse à [email protected] concernant le ticket n°4812",
"arguments_expurgés": {
"à": "[email protected]",
"subject": "Mise à jour sur le ticket #4812",
"body_hash": "sha256 :..."
},
"expires_at": "2026-08-09T12:30:00Z"
L'approbation est particulièrement utile pour la communication externe, les actions financières, les écritures irréversibles, l'administration privilégiée et les exportations de données étendues. Cela n'est généralement pas nécessaire pour la recherche de documents publics à faible volume.
Étape 5 : Suivre les budgets par outil et les limites de tarif
Les budgets symboliques ne suffisent pas. Un modèle bon marché peut déclencher des recherches coûteuses, des sessions de navigateur, des exécutions de code, des appels d'API tiers ou de longues boucles d'outils. La passerelle doit suivre au moins quatre compteurs :
- Nombre d'appels par outil : nombre maximal d'appels par exécution, utilisateur, locataire et fenêtre horaire.
- Coût par outil : frais directs de tiers, coût du navigateur/d'exécution, coût de recherche ou estimation de rétrofacturation interne.
- Coût cumulé d'exécution de l'agent : jetons de modèle plus coûts des outils.
- Profondeur de boucle : nombre maximum d'itérations modèle-outil-modèle.
Lorsqu'une limite est atteinte, la passerelle doit éviter une panne matérielle silencieuse lorsque cela est possible. Les modèles de dégradation plus sûrs incluent le renvoi d'un résumé de la progression, la demande d'approbation pour continuer, la réduction de la profondeur de récupération, la mise en file d'attente d'une tâche en arrière-plan ou le passage en mode lecture seule. Le refus définitif est toujours approprié pour les outils bloqués, les étendues manquantes, les fonctionnalités MCP inconnues et les actions dangereuses.
Étape 6 : Joindre la télémétrie du modèle et de l'outil dans un seul enregistrement d'audit
Le débogage de l'agent échoue lorsque les journaux du modèle se trouvent à un endroit et les journaux des outils ailleurs. Le dossier d'audit doit relier toute la chaîne :
- Client, espace de travail, utilisateur, compte de service et clé de passerelle.
- ID de l'agent, version de l'agent, version du modèle d'invite et ID du modèle.
- Nom de l'outil, version du registre, URL du serveur ou environnement d'exécution et hachage du schéma.
- Hash d'entrée d'outil ou entrée rédigée, jamais de charges utiles sensibles brutes par défaut.
- Statut d'approbation, identité de l'approbateur, horodatage d'approbation et hachage de l'argument approuvé.
- Latence, tentatives, erreurs du fournisseur, erreurs d'outil, coût du jeton, coût de l'outil et résultat final.
- Référence de restauration, si l'action a changé d'état.
La documentation de traçage du SDK Agents d'OpenAI comprend des traces pour les générations LLM, les appels d'outils, les transferts, les garde-fous et les événements personnalisés, qui prennent en charge un principe d'observabilité plus large : les traces d'agent doivent inclure l'activité de l'outil, et pas seulement l'utilisation et la latence des jetons. Cependant, un seul pipeline SDK peut ne pas couvrir tous les outils hébergés, chemins d'exécution locaux ou API internes. L'audit au niveau de la passerelle permet de normaliser les enregistrements entre les fournisseurs et les frameworks.
La confidentialité est importante. Les journaux détaillés améliorent le débogage et la vérification de la conformité, mais la conservation des invites brutes et de la charge utile des outils peut créer une nouvelle responsabilité en matière de sécurité. Rédigez ou hachez les entrées qui contiennent des secrets, des informations d'identification, des données de paiement, des données personnelles ou des documents exclusifs. Stockez les charges utiles brutes uniquement dans le cadre d'une politique de conservation, de contrôles d'accès et de règles de suppression explicites.
Étape 7 : Traitez les serveurs MCP et les outils tiers comme des dépendances de la chaîne d'approvisionnement
Les serveurs MCP et les outils tiers doivent être soumis au même processus d'examen que les bibliothèques, les webhooks et les dépendances d'infrastructure. Les contrôles recommandés incluent :
- Maintenir une liste verte des serveurs MCP approuvés et des origines des outils.
- Épinglez les versions lorsque cela est possible et enregistrez les hachages de schéma.
- Exiger un propriétaire pour chaque serveur et outil à haut risque.
- Examinez les noms, les descriptions, les schémas et les revendications d'autorisation des outils avant de les activer.
- Désactivez les outils récemment ajoutés jusqu'à ce qu'ils soient examinés.
- Vérifiez les étendues requises par itinéraire ou fonctionnalité.
- Séparez les identifiants des locataires et évitez les jetons partagés entre les clients.
- Exécutez des outils non fiables ou à haut risque dans des sandbox avec des restrictions de réseau et de système de fichiers.
Le fait qu'un outil soit exposé via un protocole standard ne le rend pas sûr. La couche de gouvernance a toujours besoin du moindre privilège, d'une autorisation explicite, d'un contrôle de version et d'une auditabilité.
Liste de contrôle de mise en œuvre
Conception de la politique
- Définissez des modèles de rôle pour les utilisateurs d'agents et les comptes de service courants.
- Créez des étendues distinctes pour les appels de modèle et les appels d'outils.
- Classez les outils par sensibilité des données, réversibilité, impact externe, impact financier et niveau de privilège.
- Définissez un comportement de refus par défaut pour les outils inconnus et les champs d'application manquants.
- Définissez des règles d'approbation uniquement pour les actions à haut risque.
Application de la passerelle
- Exiger que chaque agent appelle les outils via la passerelle ou un wrapper de stratégie signé.
- Vérifiez le locataire, l'utilisateur, la clé, l'agent, le modèle, l'outil, la portée, le budget et l'état d'approbation avant l'exécution.
- Imposer une profondeur maximale d'appel d'outil et un coût d'exécution cumulé.
- Enregistrer la version du registre de l'outil et le hachage du schéma pour chaque appel.
- Échec fermé lorsque le moteur de règles ne parvient pas à prendre une décision.
Audit et opérations
- Rejoignez les appels de modèle et les appels d'outils sous un seul ID de trace ou d'exécution d'agent.
- Caviarder ou hacher les entrées d'outils sensibles par défaut.
- Conservez la preuve d'approbation avec le dossier d'exécution final.
- Présentez les analyses de coût par outil et de limite de débit aux administrateurs.
- Propriétaires de restauration de documents pour les outils qui modifient l'état.
Compromis à prévoir
Cohérence par rapport aux efforts d'intégration. La gouvernance au niveau de la passerelle permet une application cohérente entre les modèles, les SDK et les équipes. Le coût est celui de l'adoption : les développeurs doivent acheminer l'exécution des outils via le chemin approuvé au lieu d'appeler les outils directement à partir du code de l'application.
Moins de privilèges versus complexité des politiques. Les étendues à granularité fine réduisent le rayon d'explosion, mais elles nécessitent des modèles, des conventions de dénomination et un nettoyage régulier. Sans modèles, les équipes peuvent accorder trop d'autorisations pour avancer plus rapidement.
Approbation versus autonomie. L'approbation humaine réduit le risque d'actions irréversibles, mais elle ajoute de la latence. Utilisez les approbations pour les outils à haut risque, et non pour toutes les recherches.
Auditabilité versus exposition des données. Des journaux riches facilitent la réponse aux incidents et le débogage. La journalisation brute des charges utiles peut exposer des secrets et des données personnelles. La rédaction, le hachage, la conservation configurable et la vérification des accès ne sont pas des détails facultatifs.
Des limites strictes par rapport à l'achèvement des tâches. Les limites de coût par outil empêchent les agents de s'emballer. Ils peuvent également interrompre un travail légitime de longue durée. Fournissez des chemins de continuation tels que l'approbation de continuer, les files d'attente en arrière-plan ou les résultats partiels résumés.
Prédictions : vers où se dirige ce modèle
Prédiction : la gouvernance des agents deviendra plus centrée sur l'identité. Les équipes demanderont moins souvent « quel modèle a-t-il utilisé ? » et plus souvent "quelle personne ou service authentifié a autorisé l'action de cet outil ?"
Prédiction : les registres d'outils deviendront aussi normaux que les registres de modèles. À mesure que les serveurs MCP, les API internes et les outils hébergés se multiplient, les équipes de production auront besoin d'un inventaire des capacités autorisées, des propriétaires, des schémas et des niveaux de risque.
Prédiction : la gouvernance des coûts passera d'un reporting basé uniquement sur les jetons à un reporting au niveau de l'action. La partie la plus coûteuse de l'exécution d'un agent peut être la récupération, l'automatisation du navigateur, l'exécution de code ou les API tierces plutôt que l'appel de modèle lui-même.
Conclusion exploitable
Commencez avec une règle : une clé de modèle n'est pas une clé d'outil. Puis construisez vers l’extérieur. Créez un registre des outils approuvés, attribuez des propriétaires et des niveaux de risque, exigez des portées explicites, ajoutez des approbations uniquement lorsque l'action a un rayon d'action significatif, appliquez des budgets par outil et joignez les événements de modèle et d'outil dans une seule piste d'audit.
Le but n’est pas de rendre les agents impuissants. L’objectif est de rendre leur pouvoir lisible, étendu, réversible lorsque cela est possible et responsable. Il s'agit du fondement pratique de la gouvernance des API d'équipe alors que les agents passent de la réponse aux questions à l'action.