Sur cette page
Un exemple de code mémorisé peut rendre une mise à jour de client très simple en apparence. Dans ce cas illustratif, un agent en rédige un de mémoire. Le nom de la méthode est plausible. Les champs semblent familiers. Le jeu de test accepte la requête. Le contrat réel du fournisseur a changé depuis la rédaction de l’exemple.
L’échec a commencé avant l’appel. L’agent a fait appel à sa mémoire alors qu’il lui fallait une source actuelle.
Une présentation sur les agents et les API changeantes recommande de récupérer le passage exact qui répond à la tâche. Ce principe est particulièrement utile pour les intégrations, où une définition d’API est un contrat évolutif, pas une simple lecture de fond.
Un appel plausible n’est pas un contrat
Les grands modèles apprennent à partir de code, de documentation et de discussions produits à des dates différentes. Ces exemples restent utiles pour la structure et les usages. Ils ne prouvent pas ce qu’un fournisseur accepte aujourd’hui, dans la version utilisée par une application et dans le compte connecté à la synchronisation.
Le guide Shopify sur les versions d’API documente un calendrier de publication trimestriel et des notes de changements propres à chaque version. Une personne qui développe peut choisir une version prise en charge, puis lire les changements pertinents avant une mise à jour. La version de la requête compte plus que le souvenir du modèle de « l’API Shopify ».
La référence Brevo sur la création de contacts ajoute une autre couche : les attributs personnalisés doivent exister dans le compte, et les valeurs qui ne correspondent pas au type déclaré peuvent être ignorées. Un schéma générique d’API ne peut pas indiquer à l’agent quels attributs ce compte précis a créés. Il faut une consultation ou une validation limitée au compte.
Le contrat actuel comporte au moins deux parties : l’opération publiée par le fournisseur et les objets configurés dans le compte. L’agent a besoin des deux lorsque sa tâche dépend des deux.
La version et le périmètre du compte doivent accompagner la réponse récupérée. Une description correcte pour une version d’API peut être fausse pour une autre. Un nom d’attribut correct dans un compte Brevo peut ne pas exister dans le suivant. Incluez la version sélectionnée et l’identifiant du compte dans le jeu de test, puis faites échouer le test si l’un manque. L’assistant ne doit pas lever cette ambiguïté en devinant à partir d’un exemple voisin.
Récupérer le petit élément utilisé
Une mauvaise réparation consisterait à coller dix mille définitions d’opérations dans chaque échange avec l’agent. Le modèle aurait davantage de texte à parcourir, plus de passages périmés à confondre et moins de place pour la tâche réelle. Demandez l’opération qui déplace cet enregistrement et les contraintes qui déterminent sa réussite.
Pour une mise à jour de contact, les éléments utiles peuvent être le chemin de l’opération, les champs autorisés, l’identifiant requis, les règles de type des attributs et la version actuelle de l’API. Fournissez ces passages à l’agent avec leurs URL sources. Gardez le reste disponible pour une autre question.
Le guide Tajo de l’API Brevo peut aider à s’orienter chez ce fournisseur. Avant qu’un code de production utilise un appel précis, la référence officielle doit le confirmer. La personne qui lit doit disposer d’une source qu’elle pourra rouvrir après un changement fournisseur.
Un dépôt peut rendre cela reproductible. Notez la version fixée, l’empreinte de la spécification conservée et la date de vérification. Une empreinte différente ne prouve pas une rupture ; elle indique ce qu’il faut comparer. Un modèle peut résumer la différence pertinente. Les tests doivent néanmoins exercer les opérations dont dépend une synchronisation opérationnelle.
Traitez la requête générée comme une hypothèse soumise à trois contrôles. Premièrement, respecte-t-elle l’opération officielle et la version fixée ? Deuxièmement, les objets qu’elle suppose existent-ils dans le compte connecté ? Troisièmement, une exécution limitée laisse-t-elle l’état attendu ? Un contrôle de schéma répond au premier point, une consultation du compte au deuxième et une lecture après écriture au troisième. Aucun ne remplace les deux autres.
- Opération fournisseur version · champs
Ce que l’API publiée accepte
- Compte connecté attribut · type
Ce qui existe dans ce compte
- Exécution limitée écrire · relire
Ce qui a réellement changé
Ne pas confondre récupération et preuve d’exécution
Une objection raisonnable serait : « La documentation officielle peut être en retard sur le service réel. » C’est possible. La lire est nécessaire, pas suffisant. Un test de contrat doit envoyer une requête limitée au moyen du même code client et vérifier la réponse ainsi que l’état de la destination. Si le service agit autrement, notez l’écart et délimitez l’opération touchée.
L’agent doit aussi s’arrêter si le contrat est ambigu. Une correspondance devinée puis appliquée à de nombreux contacts coûte plus qu’un examen de la définition du champ. Le guide d’intégration de plusieurs outils d’entreprise commence par identifier la source de vérité de chaque objet de données ; la fraîcheur de l’API applique la même discipline aux opérations qui transportent cet objet.
Le coût est l’entretien de références et de tests actuels. Sinon, la même hypothèse périmée se paie sur chaque enregistrement touché par la synchronisation.
Le modèle peut se souvenir de l’idée. Il doit lire le contrat et vérifier le compte qu’il s’apprête à modifier.
Cela ne doit pas ralentir chaque interaction. Mettez en cache le passage ciblé et versionné ainsi que le schéma du compte jusqu’à un événement d’invalidation connu ou un moment de rafraîchissement choisi. Conservez la source et la date de récupération avec la décision. Le coût d’une nouvelle lecture est ainsi payé quand le contrat peut avoir changé, pas sur chaque ligne répétée d’une synchronisation déjà approuvée.
Questions fréquemment posées
Pourquoi un assistant IA peut-il se tromper sur une API ?
Son entraînement et les exemples conservés peuvent précéder le schéma, la version ou la configuration actuelle d’un compte fournisseur. Il faut consulter le contrat officiel en vigueur pour l’opération concernée.
Fixer une version d’API résout-il le problème ?
Cela stabilise le contrat pendant un temps, mais les versions vieillissent et la configuration du compte compte toujours. Suivez la version prise en charge et lisez les notes de version lors de sa mise à jour.
Que doit récupérer un agent ?
La définition ciblée de l’opération, ses champs obligatoires et les notes de version pertinentes, avec un lien vers la source et une date. Ne chargez pas tout le catalogue fournisseur pour répondre à un seul appel.