Observabilité de l'API lorsque les agents IA sont vos plus gros appelants

Le tableau de bord de votre API affiche un pic de trafic multiplié par 4 à 3 heures du matin. Aucune campagne marketing. Pas de lancement de produit. Pas de nouvelles sur les hackers poste. Un agent IA a découvert vos points de terminaison via votre serveur MCP et a commencé à exécuter une sécurité en plusieurs étapes audits; Recherches DNS, vérifications SSL, analyse d'en-tête, 15 points de terminaison en rafales de 2 secondes, toutes les 10 minutes.

C'est normal maintenant. Gartner prévoit que 30 % ou plus de la croissance de la demande d'API proviendra d'agents basés sur LLM d'ici 2026. Une enquête de Cisco a révélé que 89 % des organisations surveillent déjà le comportement des agents en production. Le le trafic est là. La question est de savoir si votre pile d'observabilité peut faire la différence entre un être humain développeur testant un point de terminaison et un agent exécutant un flux de travail en 12 étapes à 3 heures du matin.

Les outils APM traditionnels regroupent les métriques par point de terminaison. Ils vous montrent que /v1/dns/lookup j'ai eu 500 demandes au cours de la dernière heure, mais ils ne vous diront pas que 480 d'entre elles provenaient de 40 agents, chacun appelant Recherche DNS, vérification SSL et analyse d'en-tête dans une séquence prévisible. Cet angle mort vous coûte cher ; tu ne peux pas définir des limites de débit appropriées, vous ne pouvez pas déboguer les pannes d'agent et vous ne pouvez pas prévoir les coûts d'infrastructure.

Cinq modèles résolvent ce problème. Chacun comble un écart spécifique entre ce que propose l'APM standard et ce que vous besoin lorsque les agents sont vos plus gros appelants.

Pourquoi l'APM traditionnel manque de trafic d'agents

Un développeur humain appelle un point de terminaison, lit la réponse et en appelle peut-être un autre quelques minutes plus tard. Un agent IA appelle 5 à 15 points de terminaison en succession rapide, analyse chaque réponse par programme, réessaye en cas d'échec et passe au flux de travail suivant. Ces deux formes de trafic semblent identiques au niveau de chaque point de terminaison niveau mais se comportent différemment dans tous les domaines importants pour les opérations.

Datadog, New Relic et Grafana vous affichent les centiles de latence et les taux d'erreur par point de terminaison. Ils ne le font pas vous montre "l'agent exécuté #a3f7 a appelé 8 outils en séquence, a échoué sur l'outil 6, a réessayé 4 fois et a brûlé via 35 appels API pour accomplir une tâche qui devrait en prendre 8." Pour cela, vous avez besoin d’un traçage spécialement conçu.

Modèle 1 : détecter les appelants des agents

Avant de pouvoir observer le trafic des agents, vous devez l'identifier. Trois signaux fonctionnent ensemble : Chaînes d'agent utilisateur, cadence de requête et en-têtes explicites.

Correspondance utilisateur-agent

Les frameworks d'agent définissent des chaînes User-Agent identifiables. LangChain, CrewAI, AutoGen et le SDK Anthropic tous incluent des noms de framework dans leurs en-têtes par défaut. Requêtes générées par le SDK à partir de bibliothèques telles que axios, node-fetch, et python-requests signaler également les non-navigateurs trafic.

Demander une détection de cadence

Les humains n'appellent pas 4 points de terminaison différents en 5 secondes. Un détecteur de cadence côté serveur signale les clients qui atteint plusieurs points de terminaison uniques dans une courte fenêtre :

Middleware de détection complet

Combinez les deux signaux dans un middleware qui marque chaque demande comme agent ou humain. Cette balise se jette dans vos couches de journalisation, de métriques et de limitation de débit :

La X-Agent-Detected l'en-tête de réponse permet aux développeurs d'agents de confirmer que leurs demandes sont être classé correctement. Les niveaux de confiance alimentent vos règles d'alerte ; une confiance "élevée" la détection (en-tête explicite) est définitive, tandis que « moyen » (correspondance UA) peut nécessiter une confirmation de cadence.

Modèle 2 : tracer des chaînes multi-outils avec OpenTelemetry

Un agent appelant le serveur MCP de Botoi pour auditer un domaine frappera /v1/dns/lookup, alors /v1/ssl-cert/certificate, alors /v1/headers en quelques secondes. En norme APM, ce sont trois demandes distinctes et sans rapport. Avec un partage X-Agent-Run-ID en-tête et OpenTelemetry, ils deviennent un flux de travail traçable.

Chaque workflow d'agent obtient une étendue parent. Chaque appel d'outil devient un span enfant imbriqué en dessous. Dans Jaeger, Grafana Tempo ou tout autre backend compatible OTEL, vous voyez la chaîne complète : la recherche DNS a pris 45 ms, La vérification SSL a pris 120 ms, les en-têtes 30 ms et la durée totale du flux de travail 210 ms. Lorsque l'outil 6 sur 8 échoue et que le L'agent réessaye 4 fois, vous le voyez dans la trace au lieu de rechercher dans des journaux de points de terminaison distincts.

Modèle 3 : limite de débit pour les charges de travail en rafale

La limitation du débit à fenêtre fixe punit les agents. Un agent envoie 15 requêtes en 2 secondes pour terminer une flux de travail, puis reste silencieux pendant 58 secondes. Une fenêtre fixe de « 60 requêtes par minute » offre de nombreuses possibilités de place, mais une fenêtre fixe de "5 requêtes toutes les 5 secondes" bloque l'agent sur la requête 6, même bien que le taux soutenu soit bien en dessous de la limite.

Le compartiment à jetons résout ce problème. La capacité du compartiment contrôle la taille de la rafale (combien de requêtes un agent peut feu en rafale) et le taux de remplissage contrôle le débit soutenu (la vitesse à laquelle le seau récupère). Deux paramètres qui correspondent au fonctionnement des agents.

L’idée clé : les agents ont besoin d’une capacité de rafale plus élevée et d’un rythme soutenu comparable. Un utilisateur humain avec un seau de 5 jetons et un taux de recharge de 0,5 jeton/seconde, vous pouvez effectuer 5 requêtes rapides, puis une toutes les 2 secondes. Un agent avec un bucket de 20 jetons et une recharge de 2 jetons/seconde peut lancer un workflow à 15 points de terminaison. en une seule fois et remplissez le seau pour le prochain cycle 10 secondes plus tard.

C'est ainsi que l'API de Botoi gère le trafic mixte. Les requêtes anonymes (pas de clé API) reçoivent une rafale de 5 req/min avec un plafond de 100 req/jour, suivi par IP. Les requêtes authentifiées sur les forfaits payants utilisent le compartiment de jetons d'Unkey à la limite avec des rafales plus élevées et des limites soutenues par niveau.

Modèle 4 : enregistrer le contexte d'utilisation de l'outil avec les en-têtes de corrélation

Une demande à /v1/dns/lookup isolément ne vous dit rien sur l'intention. La même demande que l'étape 1 d'un audit de sécurité en 8 étapes vous dit tout. Les en-têtes de corrélation comblent cette lacune.

Deux en-têtes contiennent tout le contexte dont vous avez besoin :

• X-Agent-Run-ID: un UUID qui regroupe toutes les requêtes dans un seul workflow
• X-Agent-Tool-Index: la position de cet appel dans la chaîne d'outils (1, 2, 3...)

Côté client, l'agent attache les deux en-têtes à chaque requête d'un workflow :

Côté serveur, vous enregistrez les deux en-têtes à chaque requête. Reconstruire ce qu'un agent a fait devient une seule requête : "montre-moi toutes les demandes avec X-Agent-Run-ID = abc-123 commandé par X-Agent-Tool-Index" Pas de corrélation d'horodatage, pas de correspondance IP, pas de conjectures.

Si vos agents utilisent le serveur MCP de Botoi, le protocole MCP regroupe déjà les appels d'outils en sessions. Le Serveur MCP sur api.botoi.com/mcp transmet la clé API via les en-têtes, et vous pouvez étendre pour transmettre un ID d'exécution qui persiste dans les 49 outils disponibles.

Modèle 5 : alerte sur les anomalies spécifiques à l'agent

Les alertes standard se déclenchent sur les taux d'erreur HTTP et les centiles de latence. Les alertes spécifiques à l'agent se déclenchent des modèles de comportement qui indiquent que quelque chose ne va pas avec l'agent lui-même, et non avec votre API.

Trois types d'alerte détectent les échecs d'agent les plus courants :

• Ordre d'outils inattendu : un agent appelé vérification SSL avant recherche DNS, suggérant un bug logique dans l'étape de planification de l'agent
• Boucle de nouvelle tentative détectée : le même point de terminaison a été touché 5 fois ou plus en 10 secondes après l'exécution d'un agent, ce qui indique que l'agent ne lit pas les réponses d'erreur
• Augmentation des coûts : l'exécution d'un agent a dépassé 50 appels d'API, ce qui signifie qu'une boucle ou une hallucination entraîne une consommation galopante

L’alerte de nouvelle tentative de boucle est le signal de valeur la plus élevée. Un agent qui obtient une erreur 400 (mauvaise entrée) et réessaye la même requête 20 fois, dépasse les limites de débit et ne produit aucune sortie utile. Attraper cela en quelques secondes au lieu de quelques minutes permet d'économiser à la fois votre budget d'infrastructure et celui de l'opérateur de l'agent. Quota d'API.

Assembler le tout : une pile d'observabilité pour le trafic mixte

Voici la pile qui couvre les cinq modèles :

Si vous exécutez déjà Datadog ou Grafana pour votre API, vous n'avez pas besoin de les remplacer. Ajoutez le Couche d'instrumentation OTEL au-dessus, canalisez les traces marquées par l'agent vers un tableau de bord dédié et construire des règles d'alerte sur les attributs spécifiques à l'agent. Les métriques existantes par point de terminaison restent utile pour la surveillance des infrastructures. Les nouvelles traces orientées agent répondent aux questions que vous vous posez. l'ingénieur de garde demande à 3 heures du matin : "que fait cet agent, pourquoi réessaye-t-il et dois-je le bloquer ?"

Points clés à retenir

• Détectez d’abord, observez ensuite. Marquez chaque demande en tant qu'agent ou humain en utilisant Modèles d'agent utilisateur, détection de cadence et en-têtes explicites. Tout en aval dépend sur ce classement.
• Tracez les flux de travail, pas les points finaux. L'unité de travail d'un agent est un multi-outil chaîne, pas un seul appel API. Les étendues parent/enfant OpenTelemetry créent des flux de travail d'agent objets de première classe dans votre backend de traçage.
• Seau à jetons sur fenêtre fixe. Les agents éclatent. Le compartiment à jetons s'adapte aux rafales tout en imposant des limites soutenues. Adaptez la capacité du godet à votre chaîne d’outils la plus longue prévue.
• Les en-têtes de corrélation sont bon marché et puissants. X-Agent-Run-ID et X-Agent-Tool-Index transformez les journaux de requêtes opaques en flux de travail d'agent lisibles avec une seule requête de base de données.
• Alerte sur le comportement, pas sur le volume. Réessayez les boucles, l'ordre inattendu des outils et Un nombre incontrôlé d'appels détecte les problèmes réels avant qu'ils ne se transforment en incidents.

L'API de Botoi gère à la fois le trafic humain et celui des agents sur plus de 150 points de terminaison et un serveur MCP de 49 outils. Chaque réponse comprend X-RateLimit en-têtes. Si vous créez un agent qui appelle API externes, passez un X-Agent-Run-ID en-tête, respecter les en-têtes de limite de débit, et donnez à votre fournisseur d'API les signaux dont il a besoin pour assurer le bon fonctionnement de votre agent. Essayez le documentation API interactive ou connectez votre assistant IA via le Serveur MCP voir ces modèles dans la pratique.