Polling d'un endpoint de statut : comment les agents attendent sans boucles

Un agent qui lance une tâche externe ne doit pas répéter « alors, c'est prêt ? » jusqu'à ce qu'un fournisseur, un budget ou une personne abandonne. Le polling d'un endpoint de statut a besoin d'un contrat explicite : ce qui compte comme une progression, le moment où la prochaine requête peut être envoyée, la fin de l'attente et la personne qui décide de la suite.

J'ai vu des vérifications de statut apparemment anodines se transformer en centaines d'appels parce qu'un identifiant de tâche était valide, que l'endpoint continuait de renvoyer HTTP 200 et que personne n'avait indiqué à l'agent que « running » ne serait plus une réponse acceptable après une certaine échéance. La solution ne consiste pas en une planification sophistiquée. Il faut faire de l'attente une action limitée, fondée sur des éléments concrets et assortie d'une voie d'escalade.

Un statut en cours autorise l'attente, pas l'action

Un état de tâche non terminal autorise une nouvelle observation plus tard. Il n'autorise pas l'agent à récupérer le résultat, à lancer une tâche dépendante, à réessayer l'envoi initial ni à élargir son autorité.

Cette distinction compte, car les API asynchrones renvoient souvent une réponse HTTP réussie pour tous les états. Une réponse comme celle-ci indique que l'endpoint de statut a fonctionné. Elle ne dit pas que la tâche a réussi.

{
  "job_id": "exp_71c",
  "state": "running",
  "updated_at": "2025-04-18T10:24:00Z"
}

Traitez le résultat HTTP et le résultat de la tâche comme deux faits distincts. Le premier répond à « Le fournisseur a-t-il répondu à cette requête ? » Le second répond à « Le workflow peut-il avancer ? » Les équipes confondent constamment les deux, puis un agent télécharge une exportation incomplète ou publie un résultat qui n'a jamais existé.

Rédigez une petite table d'états pour chaque intégration de fournisseur. N'inférez pas le sens d'un nom de champ comme status : les fournisseurs utilisent le même mot pour désigner des cycles de vie très différents. Une table utile contient les catégories suivantes :

• Les états en attente autorisent une nouvelle requête de statut, par exemple queued, running ou processing.
• Les états de réussite autorisent l'action de suivi précisément définie, comme la récupération d'une URL de résultat.
• Les états d'échec arrêtent l'exécution et conservent l'erreur du fournisseur.
• Les états d'annulation et d'expiration arrêtent l'exécution sans nouvel envoi, sauf si une personne le demande explicitement.
• Les états inconnus arrêtent l'exécution, car une intégration ne peut pas déterminer sans risque si paused, awaiting_review ou une nouvelle valeur ajoutée est inoffensive.

La réponse de statut doit aussi être vérifiée pour détecter les contradictions. Une tâche qui indique succeeded mais ne contient pas la référence de résultat requise n'est pas prête à être consommée. Une tâche qui indique running après sa propre heure d'expiration signalée nécessite une escalade, pas davantage de confiance dans le polling.

Conservez ensemble l'identifiant de la tâche, le contexte du compte fournisseur, l'empreinte de la requête d'origine et les états terminaux attendus. Si l'agent perd cette association, il peut interroger la mauvaise tâche après un redémarrage ou prendre par erreur une tâche issue d'une requête précédente pour la tâche actuelle.

Les intervalles fixes créent une pression synchronisée

Un intervalle fixe paraît propre dans le code et se comporte mal à l'échelle d'un parc. Si cinquante agents envoient du travail à peu près à la même minute et interrogent chacun le fournisseur toutes les dix secondes, ils ont tendance à le solliciter par grappes. Ces grappes persistent après une brève panne, car chaque agent réessaie selon la même horloge.

Utilisez un délai croissant avec du jitter. Commencez par un délai court uniquement lorsque le fournisseur termine généralement rapidement ou expose immédiatement un statut actualisé. Augmentez l'attente après chaque réponse en attente, plafonnez-la et faites varier le délai réel pour chaque exécution.

Un calendrier pratique peut suivre cette règle :

base_delay = 5 seconds
max_delay = 120 seconds
attempt = number of completed polls
raw_delay = min(max_delay, base_delay * 2^attempt)
actual_delay = random value between 50% and 100% of raw_delay

La plage aléatoire compte. Une suite déterministe de 5, 10, 20, 40 et 80 secondes ne fait que déplacer la synchronisation vers des vagues plus espacées. Le jitter complet, où la valeur aléatoire peut aller de zéro au plafond, fonctionne aussi dans certains systèmes. Pour le polling de tâches, je préfère une limite basse, car une exécution qui choisit à répétition des délais proches de zéro finit par ressembler à une tempête de nouvelles tentatives.

N'appliquez pas un calendrier de backoff générique sans tenir compte de la durée des tâches. Une conversion de document qui se termine généralement en moins d'une minute bénéficie de premières observations rapprochées. Une exportation par lots qui indique une estimation de fin ne doit pas recevoir une requête de statut toutes les quelques secondes simplement parce que l'agent semble inactif.

Si l'API fournit un champ next_check_at, poll_after_seconds ou équivalent, considérez-le comme une indication du fournisseur. Validez-le avant de l'accepter. Rejetez les valeurs négatives, les attentes excessivement longues qui dépassent l'échéance de votre opération et les horodatages impossibles à analyser. L'agent peut attendre jusqu'à l'heure indiquée ou jusqu'à sa propre échéance, selon la première éventualité.

Un délai ne promet pas que l'agent enverra une requête exactement à cet instant. Un processus local peut dormir, redémarrer, perdre sa connexion ou reprendre beaucoup plus tard. Au réveil, vérifiez d'abord si l'échéance est dépassée. Ne compensez pas les intervalles manqués en envoyant plusieurs appels de statut en rafale.

Une échéance et un budget de requêtes détectent des problèmes différents

Chaque exécution de polling a besoin à la fois d'une échéance basée sur l'horloge et d'un nombre maximal de requêtes de statut. Ajoutez un plafond distinct pour les erreurs de transport si le fournisseur est distant ou peu fiable.

L'échéance contrôle la durée pendant laquelle le workflow peut rester sans résolution. Elle empêche un agent de maintenir une tâche obsolète pendant tout un week-end parce que l'API indique encore queued. Choisissez-la en fonction des conséquences métier du retard, de la durée de conservation documentée par le fournisseur et du moment où une personne devrait prendre la décision. Ne la déduisez pas uniquement de la durée moyenne. Les moyennes cachent les tâches bloquées.

Un budget de requêtes contrôle la pression exercée par l'agent sur le fournisseur et sur l'identifiant qu'il utilise. Il détecte un bug de planification même lorsque le temps passe lentement et limite les coûts lorsqu'une API facture les appels. Le budget doit inclure les appels de statut effectués après une ambiguïté réseau. Si vous ne les comptabilisez pas, un agent peut épuiser le quota du fournisseur tout en se persuadant qu'il n'a effectué que quelques tentatives.

Un budget d'échecs a un rôle plus précis. Comptez les refus de connexion, les erreurs DNS, les échecs TLS et les réponses 5xx qui empêchent l'agent de connaître l'état de la tâche. Un seul délai d'attente ne prouve pas que la tâche a échoué. Répéter la même requête défaillante pendant une heure ne prouve pas la patience.

Utilisez une fiche d'opération semblable à celle-ci, enregistrée de façon durable avant le premier polling :

{
  "operation_id": "report-export-2025-04-18-01",
  "provider_job_id": "exp_71c",
  "started_at": "2025-04-18T10:20:00Z",
  "deadline_at": "2025-04-18T11:00:00Z",
  "max_status_requests": 12,
  "max_transport_failures": 3,
  "status_requests_used": 0,
  "transport_failures_used": 0,
  "last_known_state": "queued"
}

Ces valeurs sont des exemples, pas des valeurs par défaut adaptées à tous les fournisseurs. Douze vérifications en quarante minutes peuvent convenir à une exportation lente. Ce serait absurde pour une opération qui se termine normalement en trois secondes et dangereux pour une opération que le fournisseur demande de vérifier toutes les quinze minutes.

Vérifiez l'échéance avant la requête, pas seulement après. Sinon, un processus qui se réveille en retard peut effectuer un appel supplémentaire non autorisé. Vérifiez le budget de requêtes juste avant la planification, puis incrémentez-le juste avant la transmission. Cet ordre compte lorsqu'un processus tombe en panne entre la planification et l'envoi. Il vaut mieux avoir une réservation inutilisée occasionnelle qu'une requête supplémentaire invisible.

Les conditions d'arrêt doivent être exécutables, pas seulement souhaitées

« Arrêter si cela prend trop longtemps » est une note destinée à une personne, pas une condition qu'un agent peut appliquer. Définissez les conditions d'arrêt comme des prédicats portant sur la fiche actuelle et la réponse.

Arrêtez avec succès uniquement lorsque le fournisseur indique un état terminal de réussite accepté et que chaque champ nécessaire à l'action suivante passe la validation. Si l'action suivante télécharge un artefact, validez sa référence avant de déclarer la réussite. Si l'action suivante affecte un autre système, enregistrez la réponse terminale avant de l'effectuer.

Arrêtez avec un échec lorsque le fournisseur signale un échec terminal, lorsque la réponse ne peut pas être analysée ou lorsqu'un état sort de la liste autorisée par l'intégration. La gestion des états inconnus mérite la même rigueur qu'un refus d'autorisation. Un fournisseur peut ajouter sans avertissement un état needs_payment, manual_review ou blocked. Supposer qu'il signifie « attendre » transforme une modification logicielle de son côté en boucle sans fin du vôtre.

Arrêtez avec un délai d'expiration lorsque l'échéance arrive, même si le statut vient de changer. L'agent doit signaler le dernier état observé, mais il ne doit pas s'accorder un nouveau délai complet parce qu'il a constaté ce qui ressemble à un progrès. Si une attente plus longue est acceptable, faites-en une nouvelle décision d'autorisation avec une nouvelle échéance.

Arrêtez pour épuisement du budget lorsque la prochaine requête de statut dépasserait le nombre autorisé. Ne réinitialisez pas le compteur simplement parce que l'agent a redémarré, changé de session ou reçu une nouvelle instruction. Le fournisseur voit un seul appelant et une seule tâche, pas les limites de vos processus internes.

Arrêtez pour livraison ambiguë après l'expiration du délai d'une requête de statut si le budget d'échecs est épuisé. L'agent ne peut pas savoir si le fournisseur a reçu cette requête, mais les requêtes de statut doivent pouvoir être répétées sans danger. Si l'endpoint modifie l'état, facture de l'argent ou actualise un artefact à chaque GET, ce n'est pas un endpoint de statut au sens opérationnel. Traitez-le comme une action et imposez des contrôles plus stricts.

C'est ici que les équipes commettent une erreur coûteuse : elles supposent que GET est inoffensif. HTTP définit GET comme une méthode sûre au sens sémantique, ce qui signifie que le client n'a pas demandé de changement d'état. C'est un contrat que le serveur doit respecter, pas une propriété magique d'une URL. Vérifiez le comportement du fournisseur avec un compte de test et sa documentation avant de classer un appel comme une simple observation.

Respectez les signaux de protocole déjà envoyés par les fournisseurs

HTTP fournit plusieurs signaux qui doivent modifier immédiatement le comportement de polling d'un agent. Les ignorer parce que la boucle possède son propre minuteur est impoli envers le fournisseur et ralentit généralement la récupération.

La RFC 9110 définit Retry-After comme une indication du délai minimal qu'un client doit attendre avant d'effectuer une nouvelle requête. Le champ peut contenir un délai en secondes ou une date HTTP. Analysez les deux formats. Pour une requête de statut qui reçoit un 503 avec Retry-After: 120, n'utilisez pas votre backoff habituel de trente secondes pour réessayer plus tôt. Attendez au moins deux minutes, si l'échéance de l'opération le permet.

La RFC 6585 définit HTTP 429, Too Many Requests, et précise qu'une réponse peut inclure Retry-After. Cette formulation laisse aux fournisseurs la possibilité d'omettre l'en-tête, raison pour laquelle l'agent a tout de même besoin de son propre backoff. Un 429 sans indication doit augmenter fortement le délai et être comptabilisé dans le budget d'échecs ou de limitation de débit que vous avez défini. Une exécution qui reçoit continuellement des 429 doit être escaladée. Elle ne doit pas étirer son minuteur indéfiniment.

Pour 202 Accepted, examinez le corps de la réponse et les en-têtes afin d'y trouver un emplacement, un identifiant de tâche et la ressource de statut indiquée. Ne construisez pas une URL supposée à partir de l'endpoint d'envoi. Certains fournisseurs utilisent un emplacement de résultat, d'autres un emplacement de statut et d'autres encore renvoient la représentation finale plus tard. Suivez le contrat documenté.

Pour 404, ne supposez pas toujours que la tâche n'a jamais existé. Une tâche envoyée récemment peut être soumise à une cohérence éventuelle, et une tâche terminée peut disparaître après l'expiration de la durée de conservation. Le contrat initial du fournisseur détermine l'explication plausible. Si le comportement documenté ne l'explique pas, classez-le comme une défaillance d'intégration et faites remonter l'identifiant de tâche ainsi que les horodatages.

Pour 401 ou 403, arrêtez le polling. Réessayer des échecs d'autorisation avec le même identifiant ajoute du bruit et peut déclencher les défenses du fournisseur. L'action humaine consiste à vérifier les accès, la rotation des identifiants, le périmètre du compte ou la configuration de la passerelle. L'action de polling est terminée.

Pour les réponses 5xx et les erreurs réseau, utilisez le budget d'échecs de transport. Conservez le code de réponse, l'heure de la requête et tout identifiant de requête du fournisseur. Ces détails sont utiles lorsqu'une équipe d'assistance ou une personne doit distinguer une réponse perdue d'un échec de tâche.

L'escalade doit demander une décision, pas déverser un journal

Un agent doit avoir un moment défini où il cesse d'attendre et transmet la situation à une personne ou à un autre workflow explicitement autorisé. L'escalade n'est pas une notification décorative envoyée après que l'agent a déjà tenté toutes les possibilités.

Rendez la raison de l'escalade lisible par une machine. Utilisez des catégories comme deadline_exceeded, request_budget_exhausted, rate_limited, unknown_state, authorization_denied ou provider_failure. Chaque catégorie doit déterminer l'action suivante autorisée. Une personne qui voit unknown_state peut approuver une pause temporaire pendant qu'une autre vérifie les changements du fournisseur. Une personne qui voit authorization_denied ne doit pas approuver une nouvelle requête identique.

Le message d'escalade doit contenir suffisamment de contexte pour permettre une décision sans exposer de secrets :

External job needs a decision
Operation: report-export-2025-04-18-01
Provider job: exp_71c
Last state: running
Elapsed time: 40 minutes
Status requests: 12 of 12
Last HTTP result: 200 at 10:58 UTC
Stopped because: request_budget_exhausted
Safe options: extend waiting once, cancel at provider, inspect provider console

Ne formulez pas le choix par « continuer ? ». Cela incite la personne à approuver une boucle indéfinie. Proposez des options limitées. « Prolonger de quinze minutes avec quatre vérifications supplémentaires » indique le coût et crée une nouvelle limite. « Annuler auprès du fournisseur » ne doit apparaître que si l'intégration dispose d'une action d'annulation documentée et que l'opérateur en comprend les effets.

Faites remonter la situation plus tôt lorsque le résultat final n'a qu'une courte fenêtre d'utilité. Une validation de déploiement reçue après la fermeture de la fenêtre de déploiement ne mérite peut-être pas davantage de polling. Une exportation de document fiscal peut justifier une attente pendant un incident fournisseur. L'état technique seul ne peut pas déterminer cette priorité. Encodez donc séparément l'échéance métier du workflow et l'échéance de la tâche chez le fournisseur lorsqu'elles diffèrent.

Évitez le nouvel envoi automatique après un délai d'expiration, sauf si le fournisseur propose l'idempotence et que vous conservez le jeton d'idempotence. Un échec du polling ne prouve pas que la tâche initiale a échoué. Un nouvel envoi peut créer des factures, des e-mails, des déploiements ou des exportations en double. On parle de « réparation automatique » jusqu'au moment où il faut tout nettoyer.

Un contrôleur de polling a besoin d'un état durable et d'un seul responsable

Un contrôleur de polling fiable conserve sa fiche et garantit qu'un seul worker possède une tâche à la fois. Sans ces deux propriétés, la récupération après redémarrage et les agents parallèles produiront des vérifications en double ou des actions de suivi contradictoires.

Le responsable peut être un bail de processus, un verrou de base de données ou un autre mécanisme durable adapté à votre environnement. Le mécanisme doit expirer si le worker meurt, et le nouveau responsable doit recharger la fiche complète avant d'envoyer quoi que ce soit. Un simple booléen en mémoire ne constitue plus une propriété exclusive dès qu'un second processus d'agent existe.

Enregistrez chaque événement important : envoi de la tâche, planification de la prochaine vérification, envoi de la requête de statut, réception de la réponse, changement d'état et escalade. Il n'est pas nécessaire de conserver un journal distinct pour chaque détail de débogage, mais vous devez pouvoir récupérer les faits qui affectent l'autorité et les budgets.

Ce pseudo-code montre l'ordre qui empêche la plupart des boucles accidentelles :

load operation
if operation is terminal or escalated:
    exit
if current_time >= operation.deadline_at:
    record timeout and escalate
    exit
if operation.status_requests_used >= operation.max_status_requests:
    record budget exhaustion and escalate
    exit
if current_time < operation.next_poll_at:
    schedule wakeup and exit

acquire ownership lease
reload operation
increment status_requests_used and persist
send one status request
persist response metadata

if response has terminal success and required result fields are valid:
    record success
else if response has terminal failure or unknown state:
    record stop reason and escalate
else if response requires waiting:
    calculate next_poll_at with provider guidance, backoff, and jitter
    persist next_poll_at
else:
    record integration failure and escalate

Le second chargement après l'acquisition de la propriété est volontaire. Un autre worker peut avoir terminé la tâche pendant que celui-ci attendait le bail. Si vous le négligez, vous finirez par voir deux agents récupérer ou publier le même résultat.

Ne conservez pas un bail pendant le sommeil. Gardez-le seulement pendant la mise à jour de la fiche et l'envoi de l'unique requête, si votre conception de la propriété le permet sans danger. Un bail conservé pendant toute la durée d'une tâche externe lente devient un problème d'orphelin lorsqu'un ordinateur portable se met en veille ou qu'un processus meurt.

Un endpoint de statut doit rester en lecture seule du point de vue de l'agent. Séparez la récupération du résultat, l'annulation et la publication en aval, avec leurs propres actions et fiches. Les réunir dans une seule fonction de polling transforme un minuteur inoffensif en moteur de workflow caché.

L'approbation humaine appartient à la frontière d'escalade

La plupart des pollings courants n'ont pas besoin d'un clic humain s'ils restent dans le cadre de l'opération approuvée d'origine, du périmètre des identifiants, de l'échéance et du budget de requêtes. Exiger une approbation pour chaque lecture apprend aux gens à approuver sans lire et ralentit le travail sans gain de sécurité.

L'approbation devient nécessaire lorsque l'agent demande une nouvelle autorité : plus de temps que l'échéance initiale, un budget de requêtes supérieur, un appel d'annulation, un nouvel envoi, un identifiant différent ou l'utilisation d'un résultat qui a échoué à la validation. Il s'agit de modifications de l'opération, pas d'observations ordinaires.

Sallyport peut garder l'identifiant API hors d'un agent compatible MCP pendant que l'application effectue l'appel de statut et renvoie le résultat. Son paramètre de clé par appel convient aux opérations où chaque utilisation d'un identifiant donné, y compris une requête de statut, nécessite une approbation explicite, mais ce paramètre ne peut pas corriger une conception de polling sans limite.

Choisissez le modèle d'approbation en fonction des conséquences. Un appel de statut à faible risque peut rester couvert par une autorisation par session. Une API de statut privilégiée qui révèle des métadonnées sensibles de tâche peut nécessiter une approbation par appel ou un identifiant aux droits plus restreints. Dans les deux cas, définissez les limites du contrôleur avant de décider comment autoriser une requête.

Ne laissez pas une instruction décider qu'une extension d'échéance est inoffensive. La requête doit indiquer l'état actuel, le temps écoulé, les appels tentés, le budget supplémentaire proposé et l'effet attendu de la poursuite. Une personne chargée de la vérification peut alors refuser une extension qui ferait manquer une fenêtre de mise en production ou produirait des données obsolètes.

Auditez la décision d'attendre, pas seulement la requête

Un journal de requêtes vous indique qu'un agent a appelé /jobs/exp_71c. Il ne dit pas si l'appel était autorisé par le plan de polling, si l'agent a ignoré Retry-After ou si la tâche avait déjà dépassé son échéance.

Enregistrez la décision du contrôleur avec chaque appel : état actuel, heure prévue suivante, source du délai, nombre de requêtes, échéance, code de réponse, état de tâche analysé et décision résultante. La source du délai peut être provider_retry_after, provider_poll_hint, local_backoff ou manual_extension. Ce petit champ évite de longues discussions après un incident.

Une séquence d'audit utile se lit comme une histoire :

10:20:00 submitted job exp_71c, deadline 11:00:00, budget 12
10:20:05 polled, state queued, next poll 10:20:14 from local backoff
10:20:14 polled, state running, next poll 10:20:31 from local backoff
10:20:31 received 503, Retry-After 120, next poll 10:22:31 from provider guidance
10:22:31 polled, state running, next poll 10:23:48 from local backoff
10:58:00 polled, state running, request budget exhausted, escalated

Cet enregistrement rend un mauvais contrôleur évident. Si les horodatages montrent une requête par seconde malgré un délai imposé par le fournisseur, vous en avez la preuve. Si un agent affirme qu'une tâche a expiré alors que son dernier état était succeeded, vous disposez d'un élément concret à corriger.

Sallyport place les sessions d'agent et les appels individuels dans un journal d'audit chiffré et chaîné par hachage, et sp audit verify peut vérifier cette chaîne hors ligne sur le texte chiffré. Ce type de preuve est surtout utile lorsque votre propre fiche d'opération explique pourquoi chaque appel observé a eu lieu.

Ne mesurez pas la qualité du polling au fait que les tâches finissent par aboutir. Vérifiez plutôt que chaque tâche atteint un résultat terminal ou une escalade limitée, que les agents respectent les consignes d'attente du fournisseur et qu'une personne peut reconstituer une décision contestée. La première modification que j'apporterais à une boucle incontrôlée est simple : enregistrer une échéance et un budget de requêtes avant le premier appel de statut de l'agent.