Versioning d'API Agents IA : Les défis des changements majeurs

L'équipe API a renommé un champ de customer_name en customer_full_name. Ils l'ont annoncé, ils ont mis à jour la documentation, et chaque client maintenu par un humain a reçu une pull request. Votre agent n'a rien eu, car personne ne l'a considéré comme un client. Il a continué à envoyer l'ancien champ, l'API a continué à accepter la requête et à ignorer la clé inconnue, et pendant deux semaines, chaque enregistrement qu'il a créé avait un nom vide.

Les agents sont les consommateurs d'API les moins à même de remarquer un changement et les plus susceptibles de le masquer. Un client humain lève une exception. Un agent lit un 200, décide que l'appel a fonctionné et passe à autre chose. Parfois, il improvise autour du problème d'une manière qui ressemble à un succès.

Ce guide explique pourquoi les agents sont exceptionnellement fragiles face à la dérive des API, quels changements les cassent alors qu'ils ne casseraient pas les clients ordinaires, comment épingler et détecter les versions, et comment détecter la dérive en CI avant qu'une exécution ne le fasse. Notre article sur pourquoi les agents IA échouent en production couvre les modes de défaillance ; celui-ci est celui qui arrive de l'extérieur de votre codebase.

Apidog est important ici car la détection est un problème de spécification. Si vous avez la version précédente d'une définition d'API et la version actuelle, la différence est mécanique.

Pourquoi les agents remarquent moins que les clients

Quatre propriétés se combinent mal.

Tolérance silencieuse. La plupart des API ignorent les champs inconnus dans le corps d'une requête. Un champ renommé signifie que le nouveau est absent et que l'ancien est ignoré, avec un 200 en sortie. Rien n'est levé.

Improvisation. Lorsqu'une réponse manque une valeur, un modèle continuera souvent avec un substitut plausible plutôt que de s'arrêter. C'est un comportement utile en conversation et dangereux face à une API.

Descriptions dans le prompt. Les descriptions des outils d'agent encodent des hypothèses sur l'API sous forme de texte. Lorsque l'API change, les descriptions deviennent subtilement incorrectes, et des descriptions incorrectes produisent des appels erronés sans qu'aucun code ne soit impliqué. Notre article sur la conception de schémas d'outils couvre l'étendue du comportement qui repose sur ce texte.

Pas de compilateur. Un client typé échoue à la compilation lorsqu'un champ disparaît. Le contrat d'un agent réside dans des schémas JSON et du texte en prose, et rien ne le vérifie tant qu'un appel n'échoue pas, ou pire, tant qu'il ne le fait pas silencieusement.

En fin de compte : les changements qui sont sûrs pour les clients typiques ne sont pas toujours sûrs pour les agents, et vous devriez les classer séparément.

Quels changements cassent réellement les agents

La distinction habituelle entre ajout et rupture s'applique toujours, et les agents ajoutent une catégorie intermédiaire.

Véritablement cassant, pour tout le monde. Supprimer un endpoint, supprimer un champ, renommer un champ, changer un type, rendre un paramètre optionnel obligatoire, changer l'URL. Les agents échouent ici aussi, mais plus silencieusement.

Sûr pour les clients typés, risqué pour les agents :

• Un nouveau champ obligatoire. Chaque appelant existant échoue, mais un agent échoue avec une erreur de validation qu'il peut essayer de corriger en inventant une valeur. C'est pire qu'une défaillance brutale.
• Une nouvelle valeur d'énumération. Les clients ordinaires ignorent ce qu'ils ne gèrent pas. Un agent peut raisonner sur la valeur inconnue et tirer une conclusion que votre produit n'a jamais voulue.
• Une règle de validation renforcée. Un champ qui acceptait auparavant n'importe quelle chaîne de caractères nécessite désormais un modèle. L'agent n'a aucun moyen d'apprendre le modèle si ce n'est en échouant, c'est pourquoi la règle doit figurer dans le message d'erreur, comme expliqué dans notre article sur la conception des messages d'erreur d'API pour les agents IA.
• Une valeur par défaut modifiée. La pagination par défaut passe de 100 à 20 et l'agent, qui n'a jamais envoyé de limite, voit maintenant un cinquième des données et les rapporte comme si elles étaient complètes.
• Documentation reformulée. Aucun changement de comportement, mais si vos outils sont générés à partir de la spécification, comme dans notre guide sur la transformation d'une spécification OpenAPI en outils d'agent, le texte de description a changé et la sélection d'outils peut se déplacer avec lui.

Sûr pour les agents aussi. Ajouter un champ optionnel, ajouter un endpoint, ajouter un paramètre optionnel avec une valeur par défaut conservée, assouplir la validation.

Cette liste intermédiaire est celle à surveiller, car rien dans une révision de changement standard ne la signale.

Épinglez toujours la version

La première défense est de refuser d'avancer implicitement.

Envoyez une version explicite à chaque requête, quel que soit le mécanisme proposé par l'API : un segment de chemin, un en-tête ou un épinglage au niveau du compte. La documentation de versioning de l'API de GitHub utilise un en-tête de date, et Stripe épingle une version par compte avec une étape de mise à niveau explicite. Les deux vous donnent la même propriété : rien ne change sous vous tant que vous n'avez pas décidé.

DEFAULT_HEADERS = {
    "X-API-Version": "2026-06-01",
    "User-Agent": "billing-agent/1.4 (+https://example.com/agents)",
}

Le User-Agent est aussi important que l'épinglage de version. Lorsqu'un fournisseur d'API doit avertir les appelants d'une dépréciation, il examine le trafic. Un agent qui s'identifie reçoit l'e-mail ; un agent qui envoie une chaîne de bibliothèque par défaut ne le fait pas.

Si vous êtes propriétaire de l'API, publiez une version et maintenez-la. Notre guide sur la meilleure stratégie de versioning d'API couvre les options, et la gestion du versioning d'API dans Apidog couvre le maintien de plusieurs versions actives simultanément.

Pour les API tierces sans aucun versioning, épinglez ce que vous pouvez : enregistrez la forme de réponse sur laquelle vous avez construit et vérifiez-la, ce qui est la section suivante.

Détecter la dérive avant qu'une exécution ne le fasse

L'épinglage permet de gagner du temps. Il n'arrête pas la mise à niveau éventuelle, et il ne fait rien pour les API qui changent sans versioning. Alors détectez.

Comparez la spécification selon un calendrier. Si le fournisseur publie un document OpenAPI, récupérez-le quotidiennement et comparez-le à la copie à partir de laquelle vous avez généré des outils. Champs supprimés, types modifiés, exigences ajoutées, énumérations étendues, descriptions éditées. Dans Apidog, vous pouvez conserver la définition importée dans le projet et voir ce qui a bougé entre les versions, ce qui transforme « y a-t-il eu un changement » en un rapport plutôt qu'une enquête.

Testez le contrat des endpoints que vous appelez. Pour chaque outil dont dispose l'agent, envoyez une requête connue pour être bonne et affirmez la forme de la réponse : champs obligatoires présents, types corrects, valeurs d'énumération dans l'ensemble que vous attendez. Cela détecte la dérive dans les API qui ne publient aucune spécification, ce qui est la plupart d'entre elles. Notre guide de tests de contrat d'API couvre le modèle, et le test de contrat bidirectionnel couvre son exécution des deux côtés.

Affirmez la forme à l'exécution. Validez les réponses dans le wrapper de l'outil par rapport au schéma que vous attendez, et enregistrez un avertissement lorsque quelque chose d'inattendu apparaît. C'est la dernière ligne de défense, et c'est celle qui détecte le changement que personne n'a annoncé.

def check_shape(tool_name, payload, expected):
    missing = [f for f in expected["required"] if f not in payload]
    extra = [f for f in payload if f not in expected["properties"]]
    if missing:
        log.error("api_drift", tool=tool_name, missing=missing)
        raise ApiDriftError(f"{tool_name}: missing fields {missing}")
    if extra:
        log.warning("api_new_fields", tool=tool_name, fields=extra)
    return payload

Échouez sur les manquants, avertissez sur les extras. Un champ obligatoire manquant signifie que l'agent est sur le point de travailler avec des données incomplètes, ce qui est l'échec qui mérite d'être arrêté. Les nouveaux champs sont généralement additifs et méritent d'être connus sans interrompre une exécution. Acheminez les deux vers l'enregistrement de trace décrit dans notre article sur le traçage des appels d'outils d'agent.

Surveillez le comportement, pas seulement les schémas. Certaines dérives sont invisibles lors d'une vérification de forme : une valeur par défaut qui a changé, une limite de débit qui s'est resserrée, une réponse qui est devenue plus lente. Suivez les appels par tâche terminée, le taux de réessai par endpoint et la taille moyenne de réponse par outil. Un changement brusque dans l'un d'eux signifie généralement que quelque chose a bougé en amont.

Mettre à niveau sans casser l'agent

Lorsque vous passez à une nouvelle version, traitez-le comme un changement pour l'agent, car c'en est un.

Régénérez les outils plutôt que de les éditer manuellement, afin que les descriptions et les schémas évoluent ensemble. Lisez ensuite la différence des définitions d'outils générées. Cette différence est le véritable rayon d'impact, et elle est souvent plus petite ou plus grande que ce qu'implique le journal des modifications de l'API.

Exécutez l'agent contre un mock de la nouvelle version avant de le pointer vers quoi que ce soit de réel. C'est l'étape la plus précieuse et celle la plus souvent ignorée : un mock construit à partir de la nouvelle spécification vous permet d'exécuter l'ensemble de votre suite de tâches contre les nouvelles formes sans risque, en suivant notre article sur l'exécution des agents contre des mocks au lieu de la production.

Réexécutez la suite de sélection. Les changements de description modifient l'outil que le modèle choisit, et cette régression est invisible à une différence de schéma. Affirmez le choix de l'outil pour un ensemble fixe de prompts, comme dans notre guide sur les tests d'agents non déterministes.

Déployez derrière un flag, sur une partie du trafic, avec l'ancienne version toujours épinglée et prête. Surveillez les mêmes quatre chiffres pendant une journée. Les régressions d'agents se manifestent par plus d'appels par tâche et plus de tentatives bien avant que quiconque ne dépose une plainte.

Trois dérives qui ont atteint la production

• Le champ renommé. L'histoire d'ouverture. Un 200 à chaque appel, des noms vides sur chaque enregistrement, découvert deux semaines plus tard par un humain lisant un rapport. Une vérification de forme à l'exécution sur la réponse l'aurait détecté dès le premier appel, car le champ que l'agent s'attendait à relire avait disparu.
• La valeur par défaut de pagination resserrée. Un fournisseur a réduit la taille de page par défaut de 100 à 20. L'agent n'a jamais envoyé de limit, il a donc commencé à voir 20 enregistrements et à les résumer comme l'ensemble complet. Rien n'a provoqué d'erreur. Les résumés étaient simplement erronés, d'une manière qui semblait confiante. La correction était d'une ligne, l'envoi d'une limit explicite, et la leçon est plus large : comptez sur les valeurs par défaut et vous avez une dépendance non déclarée à la décision de quelqu'un d'autre.
• La nouvelle valeur d'énumération. Une API de paiement a ajouté status: "disputed". Les clients typés l'ont ignorée. L'agent a raisonné à ce sujet, a décidé qu'un débit contesté comptait comme un remboursement, et a rapporté des livres comptables rapprochés qui ne l'étaient pas. Une validation explicite de l'énumération aurait levé une erreur sur la valeur inconnue au lieu de laisser le modèle l'interpréter.

Le modèle : chaque changement a été annoncé, chacun était additif ou mineur selon la classification du fournisseur, et chacun était cassant pour un agent. Cet écart est ce qu'il faut prendre en compte dans la conception.

Traitez les dépréciations comme un élément de travail

Les fournisseurs vous avertissent généralement. L'avertissement arrive dans un changelog, un e-mail ou un en-tête Deprecation sur la réponse, et il est facile qu'aucun d'entre eux n'atteigne la personne qui maintient l'agent.

Intégrez-les à votre file d'attente normale. L'en-tête Deprecation et l'en-tête Sunset sont tous deux standardisés, de sorte qu'une vérification générique fonctionne pour tous les fournisseurs. Enregistrez-les lorsqu'ils apparaissent, et alertez dès la première apparition plutôt qu'à la millième. Un en-tête qui apparaît sur 3 % des appels aujourd'hui est une panne totale à la date de fin de vie.

Gardez également un inventaire : quel agent, quel fournisseur, quelle version, quels endpoints, et qui en est le propriétaire. Dix lignes dans un fichier suffisent. Lorsqu'un avis de dépréciation arrive, la question « est-ce que cela nous affecte » devrait prendre une minute, pas un après-midi de recherche.

La dérive est un travail, donnez-lui un propriétaire

La détection produit une file d'attente : une différence de spécification, un test de contrat échoué, un en-tête de dépréciation vu pour la première fois. Chacun est un petit travail avec une date limite, et le mode d'échec est qu'il reste dans un canal sans propriétaire jusqu'à la date de fin de vie.

Placez-les là où votre équipe suit déjà le travail. Si vos agents fonctionnent comme des runtimes de codage plutôt que comme un service que vous avez déployé, la plateforme qui les gère peut boucler la boucle : Sharkly attribue une tâche à un agent ou à une équipe et conserve l'objectif, la trace d'exécution et la révision en un seul endroit, de sorte que « l'API de paiement a déprécié cet endpoint » devient une tâche assignée avec un résultat plutôt qu'un message dans un fil de discussion. Quoi que vous utilisiez, la règle est la même. Une alerte de dérive sans propriétaire est une dépréciation que vous retrouverez le jour où elle causera une panne.

Une liste de contrôle

• Chaque requête envoie une version d'API explicite et un User-Agent identifiant.
• Les documents de spécification tiers sont récupérés et comparés selon un calendrier.
• Chaque outil que l'agent peut appeler a un test de contrat affirmant la forme de la réponse.
• Les wrappers d'outils valident les réponses à l'exécution : échouez sur les manquants, avertissez sur les nouveaux.
• Les métriques comportementales sont suivies par endpoint afin que les dérives silencieuses fassent surface.
• Les mises à niveau de version régénèrent les outils plutôt que de les éditer manuellement.
• La suite de tâches et la suite de sélection s'exécutent toutes deux d'abord contre un mock de la nouvelle version.
• Le déploiement est signalisé et réversible, avec la version précédente toujours épinglée.

L'équipe API continuera à livrer des changements, et c'est très bien. Ce dont vous avez besoin, c'est que votre agent soit un client qui remarque, ce qui nécessite un épinglage de version, un test de contrat et une vérification de forme à l'exécution. Téléchargez Apidog pour comparer la spécification et simuler la prochaine version avant qu'elle n'atteigne une exécution réelle.

Questions fréquentes

• À quelle fréquence dois-je vérifier les modifications d'une spécification tierce ? Quotidiennement est suffisant pour la plupart, et peu coûteux à automatiser. Pour les API sans spécification publiée, comptez plutôt sur les tests de contrat exécutés en CI, car ils détectent la même dérive de l'extérieur.
• Dois-je toujours épingler la version la plus ancienne fonctionnelle ? Non. Épinglez afin que les mises à niveau soient délibérées, puis mettez à niveau selon un calendrier. Rester sur une ancienne version jusqu'à ce qu'elle soit retirée transforme un changement planifié en urgence.
• Que faire si l'agent fonctionne bien après un changement ? Vérifiez plutôt que de supposer. Les résultats dangereux sont ceux qui renvoient toujours un 200, comme un champ renommé silencieusement ignoré. Une affirmation de forme vous indique ce qu'une exécution réussie ne peut pas.
• Dois-je versionner ma propre API différemment pour les agents ? Non pas différemment, mais plus strictement. Traitez les nouveaux champs obligatoires, les nouvelles valeurs d'énumération et les valeurs par défaut modifiées comme cassants pour les consommateurs d'agents, même lorsqu'ils sont additifs pour les clients typés, et annoncez-les de la même manière.
• Comment savoir quels agents appellent quels endpoints ? À partir de vos traces. Le nom de l'outil plus l'endpoint par exécution vous donne la carte des dépendances, et cela vous indique exactement qui est affecté par une dépréciation. Notre article sur le traçage des appels d'outils d'agent couvre la forme de l'enregistrement.
• L'agent peut-il s'adapter seul à une API modifiée ? Parfois, et vous ne devriez pas vous y fier. Un modèle qui improvise autour d'un champ manquant produit une sortie plausible sans aucun signal que quelque chose a mal tourné. Échouez bruyamment et corrigez les outils à la place.