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

Dérive d’API : rendre les agents IA capables de détecter les changements

L’équipe API a renommé customer_name en customer_full_name. Elle l’a annoncé, mis à jour la documentation et envoyé une pull request à chaque client maintenu par un humain. Votre agent, lui, n’a rien reçu : personne ne le considérait comme un client. Il a continué à envoyer l’ancien champ. L’API a accepté la requête, ignoré la clé inconnue et créé pendant deux semaines des enregistrements sans nom.

Essayez Apidog dès aujourd’hui

Les agents sont les consommateurs d’API les moins susceptibles de remarquer un changement — et les plus susceptibles de le masquer. Un client humain lève une exception. Un agent lit un code 200, considère l’appel comme réussi et continue. Si une valeur manque, il peut même improviser un substitut plausible.

Ce guide explique :

• pourquoi les agents sont particulièrement vulnérables à la dérive d’API ;
• quels changements les cassent alors qu’ils ne casseraient pas des clients ordinaires ;
• comment épingler et détecter les versions ;
• comment détecter la dérive en CI avant une exécution réelle.

Notre article sur les raisons pour lesquelles les agents IA échouent en production couvre les modes de défaillance généraux. Ici, nous nous concentrons sur les problèmes qui viennent de l’extérieur de votre codebase.

Apidog est particulièrement utile pour ce cas, car la détection est un problème de spécification : si vous disposez de la définition précédente et de la définition actuelle d’une API, la différence est mécanique.

Pourquoi les agents remarquent moins les changements

Quatre propriétés se combinent mal.

1. Tolérance silencieuse

La plupart des API ignorent les champs inconnus dans le corps d’une requête. Lorsqu’un champ est renommé, le nouveau champ est absent et l’ancien est ignoré, avec un 200 en réponse.

2. Improvisation

Lorsqu’une réponse manque une valeur, un modèle continue souvent avec un substitut plausible au lieu de s’arrêter. C’est utile en conversation, mais dangereux face à une API.

3. Descriptions présentes dans le prompt

Les descriptions des outils encodent des hypothèses sur l’API sous forme de texte. Lorsque l’API change, ces descriptions deviennent subtilement incorrectes et peuvent produire de mauvais appels sans qu’aucun code ne soit modifié.

Voir notre guide sur la conception des schémas d’outils pour les agents.

4. Absence de compilateur

Un client typé échoue à la compilation lorsqu’un champ disparaît. Le contrat d’un agent vit dans des schémas JSON et de la prose : rien ne le vérifie tant qu’un appel n’échoue pas — ou, pire, tant qu’il ne continue pas silencieusement.

Conclusion : classez séparément les changements sûrs pour les clients traditionnels et ceux qui sont sûrs pour les agents.

Quels changements cassent réellement les agents ?

La distinction habituelle entre changement additif et changement cassant reste valable, mais les agents ajoutent une catégorie intermédiaire.

Cassant pour tout le monde

• supprimer un endpoint ou un champ ;
• renommer un champ ;
• modifier un type ;
• rendre obligatoire un paramètre auparavant optionnel ;
• changer l’URL.

Les agents échouent aussi dans ces cas, mais souvent de manière moins visible.

Sûr pour un client typé, risqué pour un agent

Ajouter un champ obligatoire

Tous les appelants existants échouent. Un agent peut toutefois recevoir une erreur de validation, inventer une valeur et réessayer. Une défaillance silencieuse est pire qu’un arrêt immédiat.

Ajouter une valeur d’énumération

Un client traditionnel peut ignorer une valeur inconnue. Un agent peut raisonner dessus et tirer une conclusion que votre produit n’a jamais prévue.

Renforcer une règle de validation

Un champ qui acceptait n’importe quelle chaîne peut désormais exiger un modèle précis. L’agent ne peut l’apprendre qu’en échouant. Le format attendu doit donc apparaître dans le message d’erreur, comme expliqué dans notre article sur la conception des messages d’erreur d’API pour les agents IA.

Modifier une valeur par défaut

Si la pagination passe par défaut de 100 à 20 éléments et que l’agent n’envoie jamais limit, il ne voit plus qu’un cinquième des données, mais peut les présenter comme complètes.

Reformuler la documentation

Le comportement de l’API ne change pas, mais si les outils sont générés depuis la spécification, leur description change. La sélection d’outil du modèle peut alors changer aussi. Consultez le guide sur la transformation d’une spécification OpenAPI en outils d’agent.

Sûr pour les agents également

• ajouter un champ optionnel ;
• ajouter un endpoint ;
• ajouter un paramètre optionnel en conservant sa valeur par défaut ;
• assouplir la validation.

Cette catégorie intermédiaire mérite une surveillance particulière : une révision de changement standard ne la signale pas toujours.

Épinglez toujours la version

La première défense consiste à refuser toute mise à niveau implicite.

Envoyez une version explicite à chaque requête, selon le mécanisme proposé par le fournisseur : segment d’URL, en-tête ou épinglage au niveau du compte. La documentation de versioning de l’API GitHub utilise un en-tête de date, tandis que Stripe épingle une version par compte avec une étape de mise à niveau explicite.

Dans les deux cas, la propriété importante est la même : rien ne change tant que vous ne l’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 la version. Lorsqu’un fournisseur doit prévenir les appelants d’une dépréciation, il examine son trafic. Un agent qui s’identifie reçoit l’avertissement ; un agent qui envoie la chaîne de bibliothèque par défaut peut être oublié.

Si vous possédez l’API, publiez des versions et maintenez-les. Consultez notre guide sur la meilleure stratégie de versioning d’API et celui sur la gestion du versioning d’API dans Apidog pour maintenir plusieurs versions actives simultanément.

Pour une API tierce sans versioning, épinglez ce que vous pouvez : enregistrez la forme de réponse sur laquelle vous avez construit, puis vérifiez-la.

Détectez la dérive avant l’exécution

L’épinglage vous fait gagner du temps, mais il ne remplace pas la détection. Il ne bloque pas une mise à niveau définitive et n’aide pas les API qui changent sans versioning.

Comparez régulièrement la spécification

Si le fournisseur publie un document OpenAPI, récupérez-le quotidiennement et comparez-le à la copie utilisée pour générer vos outils.

Recherchez notamment :

• les champs supprimés ;
• les types modifiés ;
• les nouvelles exigences ;
• les énumérations étendues ;
• les descriptions éditées.

Dans Apidog, conservez la définition importée dans votre projet et comparez les versions. Vous obtenez un rapport de changements plutôt qu’une enquête manuelle.

Testez le contrat des endpoints utilisés

Pour chaque outil accessible à l’agent, envoyez une requête connue et vérifiez :

• la présence des champs obligatoires ;
• les types attendus ;
• les valeurs d’énumération autorisées.

Cette méthode détecte aussi la dérive des API qui ne publient aucune spécification, ce qui représente la majorité des API. Voir les guides sur les tests de contrat d’API et le test de contrat bidirectionnel.

Validez la forme à l’exécution

Validez chaque réponse dans le wrapper de l’outil par rapport au schéma attendu :

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

La règle est simple :

• échouez sur les champs manquants ;
• avertissez sur les champs supplémentaires.

Un champ obligatoire manquant signifie que l’agent va travailler avec des données incomplètes : arrêtez l’exécution. Les nouveaux champs sont généralement additifs : signalez-les sans interrompre le traitement.

Acheminez ces événements vers votre trace d’exécution, comme dans notre article sur le traçage des appels d’outils d’agent.

Surveillez aussi le comportement

Une vérification de forme ne détecte pas tout. Une valeur par défaut peut changer, une limite de débit peut se resserrer ou une réponse peut devenir plus lente.

Suivez au minimum :

• le nombre d’appels par tâche terminée ;
• le taux de réessai par endpoint ;
• la taille moyenne des réponses par outil.

Une variation brutale indique souvent qu’un changement a eu lieu en amont.

Mettez à niveau sans casser l’agent

Traitez chaque nouvelle version comme un changement pour l’agent.

Régénérez les outils

Régénérez les outils depuis la nouvelle spécification au lieu de modifier leurs schémas manuellement. Les descriptions et les paramètres évolueront ensemble.

Lisez ensuite le diff des définitions générées. C’est le véritable rayon d’impact : il peut être plus petit ou plus grand que ce que suggère le changelog de l’API.

Utilisez un mock de la nouvelle version

Exécutez l’agent contre un mock construit à partir de la nouvelle spécification avant de l’exposer à des données réelles. Vous pouvez ainsi faire tourner votre suite complète de tâches sur les nouvelles formes sans risque.

Voir notre guide sur l’exécution d’agents contre des mocks plutôt que la production.

Testez la sélection d’outils

Une modification de description peut influencer l’outil choisi par le modèle, même si les schémas sont identiques.

Pour un ensemble fixe de prompts, vérifiez :

1. l’outil sélectionné ;
2. les paramètres générés ;
3. le résultat attendu.

Notre guide sur les tests d’agents non déterministes couvre cette régression.

Déployez progressivement

Déployez la nouvelle version derrière un feature flag et sur une partie du trafic. Conservez l’ancienne version épinglée et prête à reprendre le relais.

Pendant au moins une journée, surveillez les mêmes métriques. Les régressions d’agents se traduisent souvent par davantage d’appels et de tentatives avant qu’un utilisateur ne signale un problème.

Trois dérives arrivées en production

1. Le champ renommé

L’API renomme customer_name en customer_full_name. Chaque appel renvoie 200, mais tous les enregistrements ont un nom vide. Le problème est découvert deux semaines plus tard dans un rapport humain.

Une vérification de forme sur la réponse aurait détecté dès le premier appel la disparition du champ attendu.

2. La pagination par défaut réduite

Un fournisseur passe la taille de page par défaut de 100 à 20. L’agent n’envoie jamais limit et commence à résumer 20 enregistrements comme s’ils représentaient l’ensemble.

Aucune erreur n’est levée : les résumés sont simplement incomplets. La correction tient en une ligne — envoyer une limite explicite — mais la leçon est plus large : toute valeur par défaut est une dépendance non déclarée.

3. La nouvelle valeur d’énumération

Une API de paiement ajoute status: "disputed". Les clients typés l’ignorent. L’agent, lui, interprète un débit contesté comme un remboursement et produit des rapprochements comptables incorrects.

Une validation explicite de l’énumération aurait arrêté l’exécution au lieu de laisser le modèle interpréter la valeur inconnue.

Dans les trois cas, le fournisseur avait annoncé le changement. Chacun était additif ou mineur selon sa classification. Chacun était pourtant cassant pour l’agent.

Traitez les dépréciations comme du travail

Les avertissements arrivent généralement dans un changelog, un e-mail ou un en-tête Deprecation. Ils peuvent facilement ne jamais atteindre la personne qui maintient l’agent.

Intégrez-les à votre flux de travail habituel. Les en-têtes Deprecation et Sunset sont standardisés : une vérification générique peut donc fonctionner avec plusieurs fournisseurs.

Enregistrez ces en-têtes dès leur première apparition et déclenchez une alerte. Un en-tête présent sur 3 % des appels aujourd’hui représente une panne totale à la date de fin de vie.

Maintenez également un inventaire contenant :

• l’agent ;
• le fournisseur ;
• la version ;
• les endpoints utilisés ;
• la personne responsable.

Dix lignes dans un fichier suffisent. Lorsqu’un avis arrive, la question « sommes-nous concernés ? » doit prendre une minute, pas un après-midi.

Donnez un propriétaire à la dérive

La détection crée une file de travail :

• différence de spécification ;
• test de contrat échoué ;
• premier en-tête de dépréciation observé.

Chaque élément doit avoir un responsable et une échéance. Sinon, il restera dans un canal jusqu’au jour de la mise hors service.

Placez ces tâches dans l’outil que votre équipe utilise déjà. Si vos agents fonctionnent comme des runtimes de codage, Sharkly peut relier la tâche, l’agent ou l’équipe responsable, l’objectif, la trace d’exécution et la révision au même endroit.

Le produit importe moins que la règle : une alerte de dérive sans propriétaire est une dépréciation qui finira par provoquer une panne.

Liste de contrôle

• [ ] Chaque requête envoie une version d’API explicite et un User-Agent identifiable.
• [ ] Les spécifications tierces sont récupérées et comparées selon un calendrier.
• [ ] Chaque outil accessible à l’agent dispose d’un test de contrat.
• [ ] Les wrappers valident les réponses à l’exécution.
• [ ] Les champs manquants provoquent un échec ; les nouveaux champs déclenchent un avertissement.
• [ ] Les métriques comportementales sont suivies par endpoint.
• [ ] Les outils sont régénérés lors des mises à niveau, au lieu d’être édités manuellement.
• [ ] La suite de tâches et la suite de sélection sont testées contre un mock de la nouvelle version.
• [ ] Le déploiement est progressif et réversible.
• [ ] L’ancienne version reste épinglée comme solution de repli.
• [ ] Chaque alerte de dérive possède un responsable.

L’équipe API continuera à faire évoluer ses services, et c’est normal. Votre agent doit simplement se comporter comme un client capable de remarquer ces changements. Pour y parvenir, combinez version épinglée, tests de contrat et validation de forme à l’exécution.

Téléchargez Apidog pour comparer les spécifications et simuler la prochaine version avant qu’elle n’atteigne une exécution réelle.

Questions fréquentes

À quelle fréquence vérifier une spécification tierce ?

Une vérification quotidienne suffit pour la plupart des API et reste peu coûteuse à automatiser. Pour les API sans spécification publiée, utilisez des tests de contrat en CI : ils détectent la même dérive depuis l’extérieur.

Dois-je toujours épingler la version la plus ancienne qui fonctionne ?

Non. Épinglez une version pour rendre les mises à niveau délibérées, puis mettez-la à jour selon un calendrier. Attendre son retrait transforme un changement planifié en urgence.

Que faire si l’agent fonctionne encore après un changement ?

Vérifiez au lieu de supposer. Les résultats les plus dangereux renvoient toujours 200, comme un champ renommé silencieusement ignoré. Une validation de forme détecte ce qu’un appel « réussi » ne peut pas révéler.

Dois-je versionner ma propre API différemment pour les agents ?

Pas différemment, mais plus strictement. Considérez comme cassants pour les agents :

• les nouveaux champs obligatoires ;
• les nouvelles valeurs d’énumération ;
• les valeurs par défaut modifiées.

Annoncez-les de la même manière que les autres changements.

Comment savoir quels agents appellent quels endpoints ?

Utilisez vos traces. Le nom de l’outil et l’endpoint associés à chaque exécution fournissent la carte des dépendances et indiquent exactement qui est affecté par une dépréciation.

Un agent peut-il s’adapter seul à une API modifiée ?

Parfois, mais ne comptez pas dessus. Un modèle qui improvise autour d’un champ manquant peut produire une sortie plausible sans signaler le problème.

Échouez bruyamment, corrigez les outils et faites évoluer l’API de manière contrôlée.