Contrôles de l'AI Agent Gateway : Utilisation d'outils, budgets, journaux et conditions d'arrêt

Les contrôles de la passerelle d'agent IA sont les règles de fonctionnement qui décident quels outils un agent peut appeler, combien il peut dépenser, quelles preuves doivent être consignées et quand l'exécution doit être mise en pause, basculer vers une solution de repli ou s'arrêter. Sans ces contrôles, une passerelle d'agent devient un moyen plus rapide de dissimuler la prolifération d'outils, les dépenses de jetons incontrôlées et les échecs de production peu clairs.

L'objectif n'est pas d'envelopper chaque agent dans un processus. L'objectif est de rendre le comportement de l'agent inspectable avant qu'il n'atteigne les utilisateurs en production. Un agent de support capable de rechercher des commandes, un agent de codage capable de modifier des fichiers et un agent financier capable de comparer des factures ne devraient pas partager la même politique d'accès aux outils, de budget, de journalisation ou d'arrêt.

Utilisez ce guide pour concevoir les contrôles de la passerelle d'agent IA sous forme de politiques, de champs de preuve et de tests d'acceptation. Validez ensuite le modèle Flatkey actuel, le routage, l'utilisation et les preuves de facturation sur la page des tarifs de Flatkey avant le déploiement.

Les contrôles de la passerelle d'agent IA commencent par une délimitation de politique

Une passerelle d'agent se situe entre les runtimes d'agent, les API de modèle, les outils internes et la revue financière. Cela en fait un bon endroit pour normaliser quatre décisions :

Ces contrôles de la passerelle d'agent IA doivent être examinés comme une politique d'infrastructure, et non comme le texte d'un prompt. Le prompt peut expliquer l'intention, mais la politique de la passerelle doit imposer ce qui se passe lorsque le modèle demande un outil sensible, dépasse un budget, reçoit un résultat d'outil inattendu ou entre dans une boucle.

Contrôles d'utilisation des outils : autoriser moins d'outils que ce que l'agent connaît

L'appel d'outils est puissant car il connecte les modèles à des systèmes réels. C'est aussi là qu'un agent passe de la suggestion à l'action. La documentation sur l'appel de fonctions d'OpenAI décrit les appels d'outils comme un flux en plusieurs étapes : le modèle demande un outil, votre application l'exécute et le résultat de l'outil est renvoyé au modèle. La documentation sur l'utilisation d'outils d'Anthropic fait de même avec Claude qui renvoie des blocs tool_use, le code de l'application étant responsable de l'exécution. L'appel de fonctions de Google Gemini dépend également de fonctions déclarées et d'appels de fonctions générés par le modèle.

Ce modèle commun est important pour les contrôles de la passerelle d'agent IA : le modèle ne doit pas exécuter l'outil directement. Votre passerelle ou votre runtime doit décider si l'outil demandé est autorisé, si les arguments correspondent à la politique, si une approbation est requise et si le résultat de l'outil peut être renvoyé en toute sécurité.

Utilisez une politique d'outils à trois niveaux :

1. Catalogue d'outils : l'ensemble complet des outils qui existent dans l'organisation.
2. Liste d'autorisation du workflow : l'ensemble plus restreint d'outils qu'une route d'agent spécifique peut appeler.
3. Restriction au niveau du tour : les outils disponibles pour cette requête après les vérifications de rôle, de locataire, d'environnement, de budget et de risque.

Par exemple, un agent de support client peut avoir accès à lookup_order, search_policy et open_ticket en mode normal. Il ne devrait pas recevoir issue_refund, cancel_contract ou delete_account tant que le workflow n'a pas atteint un chemin d'escalade approuvé.

Le contrôle doit être explicite :

workflow: support_resolution_agent
tool_policy:
  default_mode: deny
  allowed_tools:
    - lookup_order
    - search_policy
    - open_ticket
  approval_required:
    - issue_refund
    - cancel_subscription
  blocked_tools:
    - export_customer_database
schema_rules:
  require_strict_arguments: true
  reject_unknown_fields: true
  log_redacted_arguments: true
on_violation:
  action: stop
  user_message: ask_for_human_review

Le guide sur l'appel de fonctions d'OpenAI recommande des descriptions de fonctions claires, des schémas JSON, un mode strict lorsque cela est pris en charge, et de garder un petit nombre de fonctions initialement disponibles. Ce n'est pas seulement un conseil sur les performances du modèle. C'est aussi un contrôle de la passerelle d'agent : moins d'outils exposés signifie moins d'états invalides à examiner après un incident.

Contrôles budgétaires : plafonner l'ensemble de l'exécution, pas seulement un appel de modèle

Le coût d'un agent provient rarement d'une seule requête nette. Il provient des schémas d'outils, de l'historique de la conversation, du contexte de récupération, des jetons de raisonnement, des résultats d'outils, des nouvelles tentatives, des modèles de repli et des tentatives répétées après des échecs partiels.

Les contrôles budgétaires de la passerelle d'agent IA devraient couvrir l'ensemble de l'exécution :

La passerelle doit se fermer en cas d'échec lorsqu'une limite stricte est dépassée. Elle peut résumer, demander une réduction de la portée, mettre en file d'attente un examen humain ou renvoyer une erreur contrôlée. Elle ne doit pas envoyer silencieusement une invite plus grande, passer à un itinéraire plus coûteux ou continuer à réessayer.

Utilisez cette forme de budget :

budget_policy:
  workflow: invoice_reconciliation_agent
  owner_key: finance_ops
  per_request:
    max_input_tokens: 32000
    max_output_tokens: 4000
    max_model_calls: 4
    max_tool_calls: 5
  per_session:
    max_total_tokens: 90000
    max_total_cost_usd: reviewed_threshold
  retry:
    max_attempts: 2
    retryable_statuses: [408, 409, 429, 500, 502, 503, 504]
  fallback:
    max_fallbacks: 1
    require_reason: true
  on_over_budget:
    action: stop_or_request_scope_reduction

C'est là que la surface publique du produit Flatkey est pertinente. La page d'accueil actuelle de Flatkey positionne la plateforme autour de l'accès unifié aux modèles, du routage, de la facturation, de l'analyse de l'utilisation et des contrôles opérationnels. La page de tarification actuelle décrit les recharges prépayées, l'analyse de l'utilisation, les contrôles des coûts, les journaux de requêtes, une facture unique pour tous les fournisseurs et les parcours d'approvisionnement pour les équipes. Considérez ces éléments comme des preuves de planification publique actuelles, puis effectuez votre propre preuve dans le tableau de bord avant la production.

Journaux : enregistrer des preuves, pas seulement des invites brutes

Les journaux d'agent doivent répondre à deux questions : que s'est-il passé à l'exécution et qui peut prouver que la politique a fonctionné ?

La documentation sur l'observabilité de l'AI Gateway de Vercel décrit les journaux de la passerelle pour les dépenses, l'utilisation des modèles, les métriques d'observabilité, les résumés de requêtes, les clés API et les journaux de requêtes. La documentation sur l'observabilité du SDK Agents d'OpenAI décrit des traces qui peuvent inclure des appels de modèle, des appels d'outils, des transferts, des garde-fous et des spans personnalisés. Ces exemples pointent vers la même exigence opérationnelle : les passerelles d'agent ont besoin de journaux qui relient le comportement du modèle aux décisions d'itinéraire, d'outil, de budget et d'arrêt.

Pour les contrôles de la passerelle d'agent IA, consignez au minimum ces champs :

Ne consignez pas tout indéfiniment simplement parce que c'est facile. Les données des clients, les invites, les résultats des outils et les fichiers peuvent contenir des informations sensibles. Une conception de journal durable doit définir l'expurgation, la rétention, la révision des accès, les besoins d'exportation et les procédures d'incident. La passerelle doit stocker suffisamment de preuves pour déboguer et rapprocher l'utilisation sans transformer chaque requête en une archive de données incontrôlée.

Conditions d'arrêt : définir la fin de l'exécution avant que le modèle ne démarre

Les conditions d'arrêt ne sont pas seulement des séquences d'arrêt de modèle. Ce sont les règles qui terminent une exécution d'agent en toute sécurité.

Les API des fournisseurs exposent différentes surfaces de réponse et d'arrêt. L'API Messages d'Anthropic expose des champs stop_reason tels que l'utilisation d'outils, la fin du tour, le nombre maximum de jetons et les séquences d'arrêt dans sa documentation. La documentation sur les garde-fous du SDK Agents d'OpenAI présente les garde-fous et l'examen humain comme des contrôles qui décident quand une exécution se poursuit, s'interrompt ou s'arrête. En production, votre passerelle doit normaliser ces états spécifiques au fournisseur en un état de flux de travail que votre équipe comprend.

Utilisez une matrice d'arrêt :

Le point important est que chaque état terminal a un nom. Si les seuls états sont « succès » et « erreur », les équipes ne peuvent pas savoir si l'agent a respecté la politique ou s'il s'est simplement arrêté par accident.

Un modèle pratique de contrôles pour la passerelle d'agent IA

Utilisez un fichier de politique que l'ingénierie, la sécurité, la finance et le produit peuvent examiner ensemble :

policy_name: ai_agent_gateway_controls_v1
owner:
  team: ai_platform
  reviewers:
    - engineering
    - finance
    - security
workflow_classes:
  support_agent:
    route: balanced_text_tool_route
    allowed_tools: [lookup_order, search_policy, open_ticket]
    approval_tools: [issue_refund, cancel_subscription]
    max_tool_calls: 5
    max_model_calls: 4
  code_agent:
    route: code_review_route
    allowed_tools: [read_repo, search_repo, propose_patch]
    approval_tools: [apply_patch, run_shell_command]
    max_tool_calls: 12
    max_model_calls: 8
budget_rules:
  require_owner_key: true
  block_when_owner_budget_exceeded: true
  require_fallback_reason: true
log_rules:
  capture_request_id: true
  capture_requested_and_served_model: true
  capture_tool_call_status: true
  redact_sensitive_arguments: true
stop_rules:
  max_steps: 12
  max_retries_per_tool: 1
  on_policy_violation: stop
  on_approval_required: pause
acceptance_tests:
  - blocked_tool_is_not_executed
  - over_budget_request_fails_closed
  - approval_tool_pauses_run
  - fallback_records_reason
  - request_log_contains_usage_and_stop_condition

Ce fichier ne remplace pas le code de l'application. Il donne au code un contrat à appliquer et aux réviseurs un artefact concret à inspecter.

Tests d'acceptation avant la production

Exécutez des tests d'acceptation pour chaque classe de flux de travail avant que le trafic ne soit mis en service :

1. Envoyez une requête normale et confirmez que seuls les outils autorisés sont exposés.
2. Demandez un outil bloqué et confirmez que l'outil n'est pas exécuté.
3. Demandez un outil nécessitant une approbation et confirmez que l'exécution se met en pause avec un état reprenable.
4. Envoyez une invite surdimensionnée et confirmez que la passerelle s'arrête ou demande une réduction de la portée.
5. Déclenchez une erreur d'outil et confirmez que le nombre de tentatives, la raison de la solution de repli et l'état final sont consignés.
6. Forcez un délai d'attente du fournisseur et confirmez que la solution de repli reste dans les limites du budget de repli.
7. Déclenchez le nombre maximal d'étapes et confirmez que l'exécution ne boucle pas.
8. Confirmez que les journaux de requêtes affichent la clé du propriétaire, le modèle demandé, le modèle servi, l'utilisation, le statut de l'outil, le résultat du budget et la condition d'arrêt.
9. Échantillonnez le rapprochement financier des journaux de requêtes à la facture ou au mouvement du solde prépayé.
10. Réexécutez le même test après avoir modifié les modèles, les outils, les invites ou la politique de routage.

Associez cet article aux guides de Flatkey sur l'architecture de passerelle d'API IA, l'architecture de passerelle d'API LLM, l'équilibrage de charge et le basculement d'API IA, et la conception de politiques de routage de modèles. L'architecture de la passerelle décide où se trouvent les contrôles ; les tests d'acceptation prouvent qu'ils fonctionnent.

Où Flatkey s'intègre

Flatkey ne devrait pas être le seul endroit où votre politique d'agent existe. Conservez la politique dans le code, la configuration ou un référentiel de contrôle interne. Utilisez Flatkey comme surface de passerelle où les équipes peuvent centraliser l'accès aux modèles, l'examen des routes, la visibilité de l'utilisation, les journaux de requêtes, les contrôles des coûts, le solde prépayé et l'examen de la facturation.

Un déploiement pratique de Flatkey ressemble à ceci :

1. Choisissez un flux de travail d'agent avec des outils et des propriétaires connus.
2. Définissez les outils autorisés, les outils d'approbation, les plafonds budgétaires, les champs de journalisation et les conditions d'arrêt.
3. Vérifiez les options de modèles et de tarification actuelles sur la page Tarifs de Flatkey.
4. Exécutez les tests d'acceptation avec une clé de non-production.
5. Examinez les journaux pour le modèle demandé, le modèle servi, l'utilisation, la décision de routage, la raison de la solution de repli et la condition d'arrêt.
6. Ne déplacez que le flux de travail testé en production.
7. Ajoutez de nouveaux outils et de nouvelles routes de repli, une ligne de politique à la fois.

Lorsque la preuve est concluante, obtenez une clé et maintenez le premier déploiement restreint. Les contrôles de passerelle d'agent IA les plus robustes sont sans surprise en production : chaque appel d'outil a une raison, chaque décision budgétaire a une trace, chaque échec a une condition d'arrêt nommée, et chaque réviseur peut voir ce qui s'est passé.

FAQ

Que sont les contrôles de passerelle d'agent IA ?

Les contrôles de l'AI agent gateway sont des politiques qui régissent l'accès aux outils, les budgets, les journaux, le comportement de repli et les conditions d'arrêt pour les flux de travail d'agent qui appellent des modèles et des outils via une passerelle.

Les contrôles de l'AI agent gateway sont-ils la même chose que le routage de modèles ?

Non. Le routage de modèles décide quel modèle ou fournisseur doit traiter une requête. Les contrôles de l'AI agent gateway décident si l'agent peut appeler un outil, dépenser plus de budget, réessayer, se replier, faire une pause pour approbation ou s'arrêter.

Que faut-il journaliser pour l'utilisation des outils par l'agent ?

Journalisez l'ID de la requête, la classe du flux de travail, la clé du propriétaire, le modèle demandé, le modèle servi, le nom de l'outil, la version du schéma, les arguments expurgés, l'état du résultat, l'utilisation, le résultat du budget, la raison du repli et la condition d'arrêt.

Les outils sensibles doivent-ils être disponibles pour le modèle en permanence ?

Non. Gardez le catalogue complet des outils séparé de la liste d'autorisation du flux de travail. Les outils sensibles devraient nécessiter une approbation, une portée plus restreinte ou une voie d'escalade distincte.

Comment les dépassements de budget doivent-ils être gérés ?

Les dépassements de budget stricts doivent entraîner un échec fermé. La passerelle peut demander une réduction de la portée, résumer, mettre en file d'attente pour examen ou renvoyer une erreur contrôlée, mais elle ne doit pas basculer silencieusement vers une voie plus coûteuse.

Comment Flatkey aide-t-il avec les contrôles de l'AI agent gateway ?

Flatkey offre aux équipes une surface de passerelle unique pour l'accès aux modèles, l'examen du routage, la visibilité de l'utilisation, les journaux de requêtes, les contrôles des coûts, le solde prépayé et l'examen de la facturation. Utilisez cette surface en parallèle avec la politique en tant que code (policy-as-code) et les tests d'acceptation pour les flux de travail d'agent en production.