Des budgets d'appels externes qui arrêtent les boucles des agents

Les agents autonomes n'ont pas besoin d'un accès illimité aux services externes pour être utiles. Ils ont besoin d'une autorisation définie pour essayer, attendre, recommencer et dépenser, puis rendre la main. Sans cette limite, une petite ambiguïté, comme un résultat de recherche vide ou une tâche retardée, peut se transformer en centaines de requêtes, en effets de bord en double et en facture inattendue.

Un budget d'appels externes est un contrat d'exécution pour une seule session d'agent. Il plafonne les tentatives de requête, le temps écoulé et l'exposition financière, puis impose un arrêt visible dès qu'une limite est atteinte. Considérez-le comme une limite opérationnelle, pas comme une suggestion à placer dans le prompt de l'agent. Les prompts sont faciles à réinterpréter lorsque le modèle cherche à terminer une tâche. Le contrôle doit se trouver en dehors du modèle.

Un budget doit compter séparément les tentatives, le temps et l'argent

Une seule limite ne peut pas couvrir toutes les façons dont un agent consomme des ressources. Le nombre de requêtes détecte les boucles. Une limite de temps écoulé détecte les interrogations lentes et les pauses entre nouvelles tentatives. Une limite de dépenses détecte un petit nombre d'actions coûteuses. Chacune mesure un mode de défaillance différent et chacune peut mettre fin à l'exécution alors que les deux autres disposent encore de marge.

Comptez les tentatives, pas les réponses réussies. Une requête tentée qui expire a peut-être tout de même atteint le fournisseur. Elle a consommé une connexion, du travail côté fournisseur et souvent une entrée dans une API facturée à l'utilisation. Si vous ne comptez que les succès, un agent peut envoyer sans limite des requêtes qui échouent, à la recherche d'une réponse qui lui convient.

Suivez au moins les valeurs suivantes pour chaque exécution :

• attempts_used et attempts_remaining, y compris les nouvelles tentatives et les redirections qui déclenchent une nouvelle requête externe
• deadline_at, en utilisant une horloge monotone pour mesurer la durée écoulée plutôt que l'heure civile
• reserved_spend et settled_spend, dans la plus petite unité de facturation pratique du fournisseur
• side_effect_attempts, un compteur distinct pour les actions qui écrivent, envoient, créent ou achètent
• budget_stop_reason, qui indique la première limite ayant refusé la poursuite du travail

Ne fusionnez pas le nombre de requêtes et les dépenses en attribuant un prix fictif à chaque requête. Une recherche de métadonnées et un point d'accès de génération de modèle peuvent tous deux coûter une requête, alors que leurs factures sont très différentes. À l'inverse, une API peut n'indiquer aucun prix pour une requête qui crée tout de même une ressource cloud facturable. Utilisez un plafond de requêtes même lorsqu'une estimation de coût existe.

Un budget initial utile pour un agent qui recueille des données auprès d'un ensemble connu d'API pourrait autoriser 40 tentatives au total, 10 minutes d'exécution et une petite réservation fixe. Un agent de déploiement aura peut-être besoin de moins de requêtes, mais d'une limite plus stricte sur les effets de bord. Un agent de recherche qui suit les URL découvertes a besoin d'un périmètre accessible bien plus réduit que celui que son auteur proposera spontanément. Ce sont des hypothèses de départ, pas des réglages universels. Mesurez les exécutions normales, puis placez les limites assez près de la réalité pour interrompre un comportement anormal avant qu'il ne se transforme en tâche de nettoyage.

Le budget appartient à une exécution, pas au processus du modèle pour toute la journée. Si un agent reçoit une nouvelle tâche, il obtient un nouvel identifiant d'exécution et une nouvelle allocation explicite. Un compteur quotidien partagé dissimule l'exécution coûteuse parmi le travail normal. Il permet aussi à une tâche de consommer la capacité prévue pour une autre.

L'allocation doit être réservée avant le premier appel coûteux

Les plafonds de dépenses échouent lorsqu'un système ne découvre le prix qu'après avoir acheté le service. Réservez le montant maximal plausible avant l'appel, réduisez immédiatement le budget restant, puis rapprochez les comptes lorsque le fournisseur renvoie l'utilisation réelle. Si la réservation ne tient pas dans le budget, refusez l'appel avant qu'il ne quitte votre périmètre.

Prenons un agent qui peut créer une compilation hébergée. La requête du fournisseur accepte une classe de machine, une région, un délai d'expiration et une taille d'artefact, mais le montant exact n'apparaît qu'à la fin. La passerelle de l'agent a besoin d'une grille tarifaire ou d'une estimation prudente. Elle n'a pas besoin d'une comptabilité parfaite pour prendre une décision sûre.

Un enregistrement de réservation peut ressembler à ceci :

{
  "run_id": "run_7c1f",
  "budget": {
    "attempts_remaining": 18,
    "deadline_at": "2025-04-21T14:42:00Z",
    "spend_remaining_cents": 1200
  },
  "reservation": {
    "action": "create_build",
    "maximum_cents": 850,
    "provider_reference": "build-request-41"
  },
  "decision": "allow"
}

Après cette réservation, il reste 350 centimes pour toutes les autres actions. Si la facture réelle s'élève à 620 centimes, libérez 230 centimes. Si elle s'élève à 910 centimes, enregistrez le dépassement, refusez les dépenses ultérieures et cherchez pourquoi l'estimation était insuffisante. Ne laissez pas un agent emprunter librement sur un budget futur parce que le montant final est gênant.

Certains fournisseurs indiquent un prix dans la requête ou renvoient une estimation d'utilisation avant le début du travail. Utilisez-la. D'autres ne le font pas. Pour ces services, classez les actions selon leur risque. Autorisez une lecture peu coûteuse dans le budget normal de requêtes. Exigez une approbation explicite pour une action qui peut créer une ressource sans plafond, envoyer des messages payants, passer une commande ou déclencher un travail dont le coût ne peut pas être borné.

Les équipes refusent souvent les réservations parce que les estimations sont imparfaites. Cet argument confond la précision comptable et le contrôle. Une porte coupe-feu n'a pas besoin de calculer exactement la chaleur de l'incendie avant de se fermer. Une réservation prudente peut refuser une tâche qui aurait pu tenir dans le budget, mais l'agent peut demander une allocation plus importante en fournissant le contexte. C'est préférable à la découverte d'une dépense sans plafond après la disparition de l'agent.

Conservez les crédits du fournisseur et les quotas à l'échelle de l'organisation en dehors du budget de l'exécution. Ce sont des protections de dernier recours, pas un substitut. Un quota mensuel permet généralement à une seule exécution de consommer bien plus que ce que sa tâche justifie.

Les nouvelles tentatives doivent avoir une allocation plus petite que les premières tentatives

Les nouvelles tentatives doivent rester rares, limitées et classées selon la possibilité de répéter ou non l'effet de bord. Une instruction générale invitant à recommencer en cas d'erreur transforme une panne temporaire en trafic coûteux.

La RFC 9110 définit les méthodes idempotentes, comme GET, PUT et DELETE, selon l'effet recherché sur le serveur. Elle indique aussi qu'un client ne devrait pas relancer automatiquement une requête non idempotente, sauf s'il sait que la répétition est sûre. Cette réserve compte davantage avec les agents qu'avec le code applicatif ordinaire : l'agent peut modifier ses données entre deux tentatives, décider qu'une réponse précédente était incomplète et envoyer ce qui ressemble à une nouvelle requête.

La RFC 6585 définit HTTP 429, Too Many Requests, et indique qu'une réponse peut inclure Retry-After. Respectez cet en-tête lorsqu'il est présent. Ne le considérez pas comme l'autorisation de dormir jusqu'à son expiration, puis de reprendre indéfiniment. La nouvelle tentative consomme toujours le budget de temps de l'exécution, et la tâche initiale ne justifie peut-être plus l'attente.

Utilisez un registre des nouvelles tentatives qui répond à quatre questions avant chaque répétition : qu'est-ce qui a échoué, l'action distante a-t-elle pu avoir lieu, combien de temps faut-il attendre et quel budget paiera la nouvelle tentative ? Une politique pratique peut ressembler à ceci :

request_classes:
  read:
    max_attempts: 3
    retry_on: [408, 429, 502, 503, 504]
    backoff_seconds: [2, 8]
  idempotent_write:
    max_attempts: 2
    require_idempotency_token: true
    retry_on: [408, 429, 503]
  non_idempotent_write:
    max_attempts: 1
    retry_on: []

Cette politique évite une défaillance classique. Un agent envoie POST /invoices et perd la connexion avant de recevoir une réponse. Une nouvelle tentative imprudente peut créer une deuxième facture. Un jeton d'idempotence permet à un fournisseur coopératif de reconnaître le doublon, mais seulement si l'agent réutilise le même jeton et exactement la même opération logique. Si l'agent modifie le montant, le client ou le jeton lors de la seconde tentative, la protection ne s'applique plus.

Pour une action non idempotente, préférez une recherche d'état utilisant un identifiant d'opération créé par le client. Si le fournisseur ne prend pas en charge l'idempotence ni la récupération d'état, considérez un délai d'expiration ambigu comme nécessitant un examen humain. Cela semble plus lent qu'une nouvelle tentative automatique, jusqu'à ce qu'il faille annuler des virements, commandes ou messages en double.

La temporisation aléatoire compte lorsque de nombreux agents subissent la même panne. Utilisez un délai aléatoire pour qu'ils ne recommencent pas tous en même temps. Gardez le calendrier assez court pour que l'échéance de l'exécution reste utile. Un délai exponentiel de six heures peut protéger le fournisseur tout en maintenant une session d'agent ouverte longtemps après que la tâche a perdu son intérêt.

Les boucles d'interrogation ont besoin de leur propre plafond

Un agent qui attend un travail asynchrone doit recevoir une allocation explicite pour les interrogations, car les limites normales de requêtes dissimulent ce schéma jusqu'à ce qu'il devienne coûteux. L'interrogation peut être légitime, mais elle doit avoir un intervalle, un nombre maximal de vérifications et une échéance propres à l'opération.

La mauvaise version est facile à reconnaître dans les journaux :

14:00:03 POST /exports                 202 accepted
14:00:04 GET  /exports/ea91            202 running
14:00:05 GET  /exports/ea91            202 running
14:00:06 GET  /exports/ea91            202 running
...
14:11:58 GET  /exports/ea91            202 running

L'agent a interprété « toujours en cours » comme une instruction de demander encore une fois. Ce n'est pas de la persévérance. C'est l'absence de politique.

Commencez par les recommandations documentées par le fournisseur. Si un point d'accès renvoie Retry-After, respectez-le dans la limite de l'échéance restante. S'il renvoie une estimation du moment d'achèvement, ne l'interrogez pas avant cette échéance. S'il propose un webhook ou un rappel, utilisez-le plutôt que de maintenir une exécution d'agent ouverte. Un rappel externe peut reprendre plus tard un processus contrôlé, mais il ne doit pas ressusciter une exécution expirée avec son ancienne autorité.

Un budget d'interrogation doit aussi distinguer l'état de la tâche d'une défaillance du transport. 202 running indique que la tâche existe. Un délai d'expiration ne dit rien sur l'arrivée de la requête d'état. Ne consommez pas la même allocation de nouvelles tentatives pour ces deux cas. Dans le premier, attendez la prochaine vérification prévue. Dans le second, une nouvelle tentative peut se justifier, sous réserve de la limite normale.

Définissez une action terminale lorsque l'allocation d'interrogation expire : enregistrez le dernier état connu, conservez l'identifiant de l'opération distante et renvoyez une instruction de reprise. N'annulez pas automatiquement, sauf si la tâche initiale indique que l'annulation est sûre. Certains travaux laissent un résultat utilisable après que l'agent a cessé d'attendre, et certaines demandes d'annulation ont leurs propres effets de bord.

Cette conception rend le travail retardé visible pour une personne. « L'export est toujours en cours après six vérifications ; l'opération ea91 pourra être vérifiée plus tard » est une transmission utile. « Agent terminé » après une boucle en arrière-plan invisible ne l'est pas.

Une échéance doit couvrir les attentes, les outils et le temps en file d'attente

L'échéance d'une exécution doit mesurer toute la période pendant laquelle l'agent peut provoquer un travail externe. Elle doit inclure la réflexion du modèle entre les appels, le sommeil des nouvelles tentatives, l'exécution des outils locaux, le délai en file d'attente, les blocages DNS et le temps d'attente d'une approbation. Un minuteur placé uniquement autour du client HTTP laisse de grands intervalles pendant lesquels une boucle peut continuer.

Utilisez un minuteur monotone pour imposer cette limite. Les horloges civiles peuvent avancer ou reculer lorsqu'un ordinateur portable se met en veille, reprend son activité ou reçoit une correction horaire. Enregistrez les horodatages civils pour l'audit, mais calculez l'expiration à partir d'une durée écoulée qui ne peut pas reculer.

Transmettez le temps restant à chaque opération. S'il reste 40 secondes à une exécution, elle ne doit pas démarrer une requête HTTP avec un délai d'expiration client de 90 secondes ni lancer une commande SSH sans aucun délai. L'opération enfant reçoit la plus petite valeur entre sa limite locale et la durée restante de l'exécution.

remaining = run_deadline_monotonic - now_monotonic
if remaining \u003c= 0:
    deny("run_deadline_exhausted")
else:
    operation_timeout = min(remaining, endpoint_timeout)
    execute(operation_timeout)

Traitez les attentes d'approbation avec prudence. Une personne peut répondre dans cinq minutes, mais il peut ne rester que 30 secondes à l'exécution de l'agent. Lorsque l'approbation arrive après l'expiration, refusez l'action et expliquez pourquoi. Autoriser l'approbation à réactiver une exécution expirée crée une faille : l'agent peut mettre en file un nombre quelconque d'actions coûteuses avant son échéance, puis les exécuter plus tard au fil des clics sur les cartes.

Les tâches longues nécessitent une autre structure. Divisez-les en points de contrôle avec de nouveaux budgets et une transition d'état enregistrée. Par exemple, un agent peut soumettre un export dans une exécution, puis une exécution ultérieure peut inspecter l'export terminé et décider quoi en faire. Chaque exécution reçoit un objectif, un petit ensemble d'autorisations et une heure de fin claire. C'est moins magique qu'une session d'agent immortelle, et c'est précisément pour cela que c'est plus facile à auditer.

Les limites de périmètre empêchent l'agent de dépenser son budget au mauvais endroit

Un budget répond à la question de la quantité d'activité externe qu'une exécution peut effectuer. Le périmètre indique où et quoi elle peut toucher. Sans périmètre, un agent peut dépenser une allocation de requêtes parfaitement raisonnable à sonder des hôtes sans rapport, à suivre un lien malveillant ou à sélectionner un point d'accès coûteux qui ne faisait pas partie de la tâche.

Définissez le périmètre en termes concrets : hôtes approuvés, identités d'identifiants, méthodes HTTP, destinations SSH, chemins ou familles de commandes autorisés et taille maximale du corps de requête. La définition doit rester assez étroite pour qu'un évaluateur puisse la comprendre. N'essayez pas d'écrire un mini-langage de programmation pour chaque condition possible. Les systèmes de politiques complexes accumulent des exceptions jusqu'à ce que plus personne ne puisse prévoir leur résultat sous pression.

La distinction entre une limite d'identifiants et une limite budgétaire compte. La première détermine si un agent peut utiliser un secret pour appeler un service. La seconde détermine si cette exécution peut effectuer un appel supplémentaire après avoir obtenu cette autorisation. Les équipes installent souvent la première et supposent qu'elle fournit la seconde. Ce n'est pas le cas. Un jeton API parfaitement protégé peut tout de même financer mille requêtes inutiles.

Pour HTTP, refusez les redirections qui quittent l'ensemble des hôtes approuvés, sauf si une personne a explicitement autorisé la destination. La gestion des redirections est facile à oublier, car de nombreux clients les suivent automatiquement. Une requête qui commence à une URL approuvée peut finir sur un autre hôte, emporter des en-têtes ou consommer un budget auprès d'un service que la tâche n'a jamais désigné.

Pour SSH, évitez de donner à un agent un shell général simplement parce que sa première tâche implique une commande. Limitez la destination et l'interface de commande lorsque c'est possible. Définissez un délai d'expiration de commande et comptez chaque tentative de connexion. Une boucle de connexions échouées reste une activité externe, même si elle ne s'authentifie jamais.

Séparez les périmètres de lecture et d'écriture. Une tâche de collecte de données peut avoir besoin d'un large ensemble de points d'accès en lecture sans pouvoir créer de fiches. Une tâche de modification peut avoir besoin d'un seul point d'accès en écriture et d'une lecture préalable limitée. Cette séparation rend le budget plus utile, car un simple nombre de requêtes ne peut pas distinguer à lui seul une répétition sans risque d'effets de bord répétés.

Les refus doivent laisser assez de preuves pour reconstituer la boucle

Un arrêt budgétaire n'est utile que si vous pouvez l'expliquer après coup. Enregistrez chaque décision avant le début de l'appel externe, le résultat après sa fin et les refus avec le même soin que les appels réussis. Sinon, un événement manquant peut sembler identique à une requête bloquée.

Utilisez un identifiant d'exécution immuable dans les messages du modèle, les outils locaux, les requêtes HTTP, les connexions SSH, les approbations et les enregistrements d'audit. Chaque tentative externe doit inclure un numéro de séquence. En cas de nouvelle tentative, reliez-la à l'opération logique initiale et indiquez si l'action était idempotente, ambiguë ou confirmée comme absente.

Un enregistrement d'événement compact contient assez d'informations pour enquêter sans conserver de données sensibles :

{
  "run_id": "run_7c1f",
  "attempt": 17,
  "logical_operation": "fetch_export_status:ea91",
  "channel": "http",
  "destination_class": "approved-export-api",
  "outcome": "denied",
  "reason": "poll_allowance_exhausted",
  "attempts_remaining": 0,
  "elapsed_ms": 598244,
  "reserved_spend_cents": 0
}

Par défaut, n'enregistrez pas les jetons bearer, mots de passe, clés privées ou corps complets des requêtes. Un audit budgétaire a besoin d'identifiants, de catégories, de hachages lorsque c'est utile et du contexte de la décision. Il n'a pas besoin d'un deuxième coffre de secrets rempli des mêmes identifiants que vous essayez de protéger.

Rendez la séquence des événements résistante aux altérations. Une chaîne de hachage donne à chaque enregistrement une dépendance envers celui qui le précède, de sorte que toute suppression ou modification puisse être détectée. Lorsque c'est possible, stockez séparément le matériel de vérification, à l'écart de l'agent actif. Un agent capable d'écrire son propre historique ne doit pas pouvoir modifier la preuve de son dépassement de budget.

Sallyport enregistre les sessions des agents et les appels individuels dans un journal d'audit chiffré, chaîné par hachage et aveugle à l'écriture. Sa commande sp audit verify peut vérifier la chaîne hors ligne sur le texte chiffré. Cette conception est utile pour faire respecter les budgets, car une action refusée reste dans les preuves au lieu de disparaître comme une simple décision interne.

L'approbation humaine doit concerner les exceptions, pas chaque lecture

L'approbation humaine doit gérer les changements de conséquence ou de périmètre qu'un budget numérique ne peut pas évaluer. Elle ne doit pas devenir un tampon appliqué à chaque appel courant. Si une personne voit une carte d'approbation pour chaque requête, elle approuvera la dixième avec la même attention que la première.

Demandez une approbation lorsqu'une action crée un nouveau bénéficiaire, dépense davantage que la réservation, écrit dans un système de production, envoie une communication visible à l'extérieur, modifie l'ensemble des destinations approuvées ou reprend après une modification importante des données de la tâche. L'approbation doit présenter l'action en termes simples, la destination, son effet sur le budget et l'identité du processus qui la demande.

Ne présentez pas l'approbation comme un remède à un budget faible. Une personne distraite peut autoriser une mauvaise action, et une exécution sans surveillance peut ne jamais recevoir de réponse. Le budget doit continuer à expirer pendant l'attente de l'approbation. Une personne peut accorder une nouvelle allocation pour une nouvelle exécution si la tâche en vaut toujours la peine.

Évitez de demander aux personnes d'approuver « continuer » sans contexte. Continuer quoi ? Vers quel service ? Pour quel montant estimé ? Combien d'appels l'exécution a-t-elle déjà effectués ? Une bonne demande d'approbation rend ces faits visibles. Une demande vague pousse l'évaluateur à faire confiance au résumé de l'agent, qui est précisément la partie ayant intérêt à poursuivre le travail.

La répartition des rôles est utile. La passerelle applique systématiquement les limites fixes. La personne décide si une action exceptionnelle justifie davantage d'autorité. Gardez ces responsabilités séparées afin qu'aucune ne prétende résoudre le problème de l'autre.

L'épuisement du budget doit produire une transmission pouvant être reprise

Lorsqu'une limite arrête une exécution, l'agent doit renvoyer un court état permettant à une personne ou à une exécution ultérieure de poursuivre sans risque. Un message d'échec vague incite à relancer toute la tâche, ce qui répète les appels déjà effectués et peut répéter les effets de bord.

La transmission doit contenir l'objectif de la tâche, les identifiants des opérations terminées, le travail distant en attente, la raison exacte de l'arrêt et une recommandation pour la prochaine allocation. Elle doit préciser si une nouvelle tentative est sûre. Elle ne doit jamais dissimuler qu'une action s'est terminée dans un état ambigu.

Par exemple :

Stopped: elapsed-time budget exhausted.
Completed: submitted export job ea91; downloaded no files.
Last observed state: running at 14:09:58 UTC.
External attempts: 14 of 14; spend reserved: 0 cents.
Safe resume: check status of ea91 once after 14:20 UTC.
Unsafe action: do not submit another export request.

Ce message évite la forme de reprise la plus coûteuse : recommencer parce que personne ne sait ce qui s'est passé. Il rend aussi possible l'ajustement des budgets. Si de nombreuses exécutions normales s'arrêtent après une seule vérification d'état, la durée autorisée est trop courte. Si les exécutions consomment souvent toute leur allocation dans des recherches sans progrès, la décomposition de la tâche ou le périmètre sont mal définis.

Ne réapprovisionnez pas automatiquement un budget épuisé. Une règle de réapprovisionnement n'est qu'un budget illimité écrit en plusieurs petites tranches, sauf si une autorité distincte décide de son application. Exigez une nouvelle exécution ou une action humaine explicite, conservez l'ancien enregistrement et demandez à la prochaine tentative d'expliquer pourquoi elle mérite davantage de marge.

La première politique à appliquer est simple : chaque exécution autonome reçoit un nombre fini de requêtes, une échéance ferme et une réservation de dépenses avant d'atteindre un service externe. Ajoutez immédiatement des restrictions de périmètre et de bons enregistrements. Dès qu'un agent sait qu'il ne peut pas essayer indéfiniment, ses échecs deviennent des tâches circonscrites plutôt que des incidents survenus pendant la nuit.