Medusa Extend · IA
Suivre ses agents IA dans Medusa
Un agent qui reformule une annonce sert de fil conducteur pour construire dans Medusa un premier suivi de ses exécutions, de leur coût estimé et de leur qualité, en prenant Langfuse pour référence.
Quand un commerce confie une tâche à un modèle de langage, les questions arrivent après coup : ce que l'agent a fait, ce qu'il a coûté, ce que vaut son texte. Des outils spécialisés y répondent déjà. Cet article montre comment en construire un premier périmètre avec le framework Medusa. L'exemple est volontairement petit, et le dispositif décrit est une conception, pas une fonction livrée par Medusa.
Une annonce, un agent, des questions
La Papeterie Alizé, commerce imaginé pour cet exemple, veut annoncer une ouverture exceptionnelle. Dans l'Admin, une personne de l'équipe colle son texte : « Chers amis de la Papeterie Alizé, nous avons le plaisir de vous annoncer qu'à l'approche des fêtes, notre boutique ouvrira exceptionnellement ses portes le dimanche 13 décembre, de 10 h à 13 h puis de 14 h 30 à 18 h. Nous serons ravis de vous accueillir pour flâner, choisir vos cartes et partager un moment chaleureux. » Elle ajoute une consigne : garder les horaires exacts, adopter un ton chaleureux, ne pas dépasser quarante mots.
L'agent chargé de cette tâche réunit un modèle de langage, une consigne système et un outil. L'outil est local : une fonction qui compte les mots du texte, sans appel à un modèle. Le déroulé est borné. Le modèle propose une reformulation ; l'outil la compte ; si elle dépasse quarante mots, le modèle reçoit ce résultat et reformule une seule fois ; l'outil compte à nouveau, et l'agent rend le dernier texte avec son statut. Il n'y a pas de dialogue : une entrée, une sortie.
Dans le déroulé fictif retenu, la première proposition dépasse la limite et la correction la respecte. Une autre exécution peut rester trop longue après sa correction : l'agent s'arrête alors et rend un texte marqué comme tel, plutôt que d'essayer indéfiniment.
Sur ce cas, les questions de l'équipe se précisent. Elle veut retrouver le texte reçu et le texte rendu, savoir combien d'appels au modèle ont eu lieu et pourquoi, connaître le coût approximatif de l'exécution. Elle veut surtout vérifier que les horaires ont survécu à la reformulation, ce qu'aucun compteur ne dit, et comparer sur les mêmes annonces la consigne actuelle avec celle qu'elle envisage.
Langfuse comme référence : une exécution et ses étapes
Langfuse est un outil spécialisé dans le suivi des applications à base de modèles de langage. Dans son modèle de données, une trace regroupe ce qui se passe pendant une opération, et chaque étape de cette opération est une observation ; une observation peut en contenir d'autres, ce qui forme un arbre. Langfuse distingue plusieurs types d'observations, dont la génération, qui représente un appel au modèle, et l'outil.
Appliqué à l'annonce, ce modèle décrit le déroulé fictif sans effort. La trace contient une première génération, un appel de l'outil de comptage, une seconde génération pour la correction, puis un second comptage. Le lien de chaque étape à son parent reconstitue l'arbre ; l'ordre des étapes et le résultat du premier comptage expliquent la correction.
Dans la suite, on parle d'exécution pour la trace et d'étape pour l'observation. Nous retenons les exécutions, leurs étapes, l'usage, les coûts et l'évaluation sur des cas de référence ; les autres outils de Langfuse restent hors de ce premier module.
L'instrumentation désigne le code qui enregistre ces opérations. Rien n'est relevé si l'appel ne passe pas par elle : cette remarque guide toute la suite.
Ce que l'on retient d'un appel au modèle
Une génération est une étape de l'agent ; mais pour l'accomplir, le serveur peut envoyer plusieurs requêtes au fournisseur du modèle. Si la première échoue sur une erreur passagère et qu'une seconde part, deux appels réels ont eu lieu, et chacun a pu consommer. Chaque requête réellement envoyée est donc une tentative, rattachée à son étape.
Trois situations se ressemblent sans être équivalentes. La correction est une nouvelle génération décidée par l'agent après le comptage : c'est une nouvelle étape. La nouvelle tentative répète le même appel après un échec : c'est une tentative de plus dans la même étape. Le rejeu d'une écriture, enfin, se produit quand le serveur enregistre une seconde fois la réponse d'un appel déjà fait, par exemple après une reprise : aucun nouvel appel n'a eu lieu, et ce relevé ne doit rien ajouter.
L'ordre d'écriture compte. Avant d'appeler le fournisseur, le serveur enregistre la tentative comme démarrée, avec son identifiant. À la réponse, il la complète : statut, identifiant de requête renvoyé par le fournisseur s'il existe, usage déclaré, texte produit. Si le serveur s'arrête entre l'envoi et la sauvegarde, la tentative reste démarrée et son usage est inconnu. Ce trou est visible, ce qui vaut mieux qu'une absence : l'équipe sait qu'un appel a peut-être consommé. Un usage inconnu n'est jamais compté comme zéro. Et aucune annulation côté serveur ne défait un appel déjà parti, ni sa facturation.
Chaque texte produit reste attaché à la tentative qui l'a rendu. Le déroulé fictif contient ainsi deux versions de l'annonce ; il faudra savoir laquelle a été rendue, et laquelle on juge.
Usage déclaré et coût estimé
Le fournisseur déclare, pour chaque réponse, l'usage consommé, en général par catégories : tokens d'entrée, tokens de sortie, tokens d'entrée servis depuis un cache. Ces catégories doivent être exclusives avant tout calcul. Certains fournisseurs incluent les tokens en cache dans le total d'entrée ; additionner les chiffres tels quels compterait deux fois la même consommation. Langfuse pose la même exigence. Il accepte un coût fourni directement ou le calcule à partir de l'usage et d'une définition tarifaire du modèle, et ne calcule rien sans l'un ou l'autre.
La conception retenue calcule un coût estimé à partir de l'usage déclaré et d'une grille tarifaire versionnée : un prix par catégorie et par modèle, avec une date de début de validité. Chaque tentative note la version de grille utilisée. Quand un tarif change, une nouvelle version s'ajoute ; les coûts déjà estimés ne bougent pas, comme chez Langfuse, où les tarifs mis à jour ne s'appliquent qu'aux nouveaux relevés.
Le coût d'une exécution est la somme de ses tentatives réellement envoyées. L'outil de comptage, local, n'y ajoute rien. Une tentative dont l'usage est inconnu rend le total incomplet, et l'affichage le dit plutôt que de présenter un chiffre trop bas. Ce montant reste une estimation : il ne remplace pas la facture du fournisseur et ne couvre pas le coût d'exploitation du serveur.
Le module de suivi sur le socle Medusa
Exécutions, étapes, tentatives et grilles tarifaires : ces faits et leurs règles forment le module de suivi des agents. Medusa fournit ce qu'il faut pour le construire comme n'importe quel module.
Les modèles de données se déclarent avec le langage de modélisation de Medusa, la DML, qui décrit propriétés, relations et index, et à partir duquel les migrations se génèrent. L'exécution devient agent_run, l'étape agent_step, la tentative agent_attempt, et chaque modèle porte la relation vers son parent. La tentative déclare son statut, l'identifiant de requête du fournisseur, une propriété par catégorie d'usage, le coût estimé et la version de grille. Les propriétés d'usage sont facultatives : une valeur absente signifie un usage inconnu, distinct d'un usage nul. Le service du module hérite de MedusaService, qui génère les opérations courantes sur chaque modèle. Les règles du domaine s'écrivent dans ce même service. Une méthode qui complète une tentative, par exemple, ignore une seconde complétion de la même tentative, ne calcule le coût que si l'usage est connu et refuse une version de grille qui n'existe pas. Le module ne se lie à aucun module commercial : l'agent, les routes et les tâches le résolvent dans le conteneur de Medusa quand ils en ont besoin.
Medusa conserve déjà, de son côté, un autre type de relevé. Son moteur de workflows suit les transactions et le statut de chaque étape pour orchestrer l'exécution. L'historique de ces exécutions n'est pas conservé par défaut, mais son stockage peut être activé et consulté dans les paramètres de l'Admin. Ce relevé décrit la coordination : quelle étape a tourné, échoué, été reprise. Il ne calcule pas de lui-même l'usage consommé chez le fournisseur, son coût ni la qualité du texte. Les deux relevés se complètent sans se remplacer.
Exécuter l'agent et relever chaque appel
Tout part d'une route d'API d'Admin, appelée depuis la page où l'équipe a collé son texte. La route lance le workflow de l'agent et renvoie l'identifiant de l'exécution.
Le workflow ouvre l'exécution dans le module, avec la version de configuration utilisée. Il enchaîne ensuite la génération, le comptage, la correction si nécessaire, puis la clôture, qui enregistre le texte rendu et son statut : dans la limite, ou trop long. La limite d'une correction est une règle de la configuration, appliquée par le workflow, et non une consigne laissée à l'appréciation du modèle.
Chaque génération passe par l'instrumentation : une fine couche autour du client du fournisseur, que tout appel au modèle traverse. C'est elle qui ouvre la tentative avant l'envoi et la complète à la réponse, par le service du module. Certains clients reprennent eux-mêmes un appel échoué, sans que la couche qui les entoure voie ces requêtes supplémentaires ; le client Node d'OpenAI, par exemple, en fait deux par défaut pour certaines erreurs. Ces reprises internes sont donc désactivées, pour que l'instrumentation pilote et compte chaque tentative. Le comptage, lui, s'enregistre comme une étape d'outil, sans tentative.
Le moteur de workflows peut reprendre une étape après un échec, selon sa configuration ; une étape reprise peut même démarrer alors que la précédente tourne encore. L'instrumentation y répond par les règles déjà posées : l'écriture d'un relevé est dédupliquée par l'identifiant de la tentative, et toute requête réellement renvoyée au fournisseur ouvre une nouvelle tentative. Un nombre maximal de tentatives par génération borne aussi la dépense. L'instrumentation ne détecte pas un appel qui la contournerait : des tests vérifient que chaque appel de l'agent la traverse.
Une fois l'exécution close dans le module, les traitements secondaires peuvent suivre. Un événement de fin d'exécution déclenche un abonné qui met à jour les totaux par agent et par version. L'émission d'un événement ne prouve pas que la collecte est durable : la vérité reste dans le module, et l'abonné ne fait qu'en dériver des agrégats. Une tâche planifiée applique la durée de conservation : les textes reçus et produits, qui peuvent contenir des informations sensibles, sont effacés plus tôt que les mesures. Aucun relevé ne contient de clé d'accès au fournisseur.
Juger le texte produit
Une exécution sans erreur peut rendre une mauvaise annonce. Le statut technique dit que l'agent a fonctionné ; il ne dit pas si le dimanche 13 décembre et ses horaires ont survécu.
Le module ajoute donc un fait : l'évaluation. Elle porte sur un texte précis, celui que l'agent a rendu, identifié par sa tentative, et non sur l'exécution en général, qui contient deux versions de l'annonce. Elle note un critère, un résultat, son auteur et sa date. Le respect des quarante mots est un contrôle automatique : le code compte, et le résultat s'enregistre comme une évaluation dont l'auteur est le contrôle. Le maintien des horaires est jugé par une personne de l'équipe, qui répond oui ou non dans l'Admin. Tant que personne n'a jugé, l'état est « non évalué », et non « réussi ».
Dans cet exemple fictif, le texte rendu après correction serait : « La Papeterie Alizé vous accueille exceptionnellement le dimanche 13 décembre, de 10 h à 13 h puis de 14 h 30 à 18 h. Venez choisir vos cartes et profiter d’un moment chaleureux. » Le contrôle de longueur compte 33 mots, en groupes séparés par des espaces, et enregistre un résultat conforme à la limite de quarante. La date, « dimanche 13 décembre », et les deux créneaux, « 10 h à 13 h » et « 14 h 30 à 18 h », y figurent tels qu'annoncés ; le formulaire permettra à la personne de confirmer ce critère, et l'état reste « non évalué » jusque-là.
Langfuse rattache de la même façon ses scores à une trace ou à une observation, sous forme numérique, catégorielle ou booléenne.
Pour comparer deux consignes, il faut les essayer sur les mêmes textes. Quelques annonces fictives, chacune avec ses horaires attendus, forment des cas de référence. Une version de configuration identifie les choix réellement utilisés par l'agent : le modèle, la consigne système, la version du code de l'agent, celle du compteur, et les limites de corrections et de tentatives. L'équipe exécute les cas sur la version actuelle, puis sur la version candidate ; ces exécutions sont marquées comme essais pour ne pas se mêler à l'usage courant. Elle compare ensuite, cas par cas, les évaluations et les coûts estimés. Pour que la comparaison tienne, les deux versions sont jugées avec la même grille d'évaluation de référence, distincte du contrôle embarqué dans l'agent, qui peut lui-même changer d'une version à l'autre.
Langfuse versionne ses jeux de cas et recommande de comparer les expériences avec les mêmes versions de cas et d'évaluateurs. Des données fixes ne rendent pas pour autant les sorties identiques d'un essai à l'autre, et une correction bornée peut encore échouer : le statut final et les évaluations le montrent. Le module enregistre la version utilisée ; il ne devient pas pour autant un outil de gestion et de déploiement des consignes.
Dans l'Admin, et au-delà du module
Le marchand consulte ses agents dans une page dédiée de l'Admin. Medusa permet d'ajouter des routes d'interface avec leur entrée de navigation, construites avec les composants de Medusa UI. La page « Agents IA » liste les exécutions, filtrables par agent, version, date et statut. Le détail d'une exécution montre le texte reçu et la consigne, l'arbre des étapes, chaque tentative avec son usage connu ou inconnu, le coût estimé et sa grille, le texte rendu et ses évaluations, avec le formulaire qui demande si les horaires sont conservés. Une troisième vue met côte à côte deux versions de configuration sur les cas de référence. Ces écrans sont une proposition de conception, pas la capture d'un outil en service.
Les routes /admin personnalisées exigent une authentification par défaut. Être connecté à l'Admin ne dit pas qui peut lire les textes, les exporter ou les évaluer. Cette politique s'ajoute dans les routes, côté serveur, car masquer un bouton dans l'interface ne protège rien.
Reste à situer ce module face à l'outil qui lui a servi de référence. Langfuse auto-hébergé repose sur une application web et des workers, PostgreSQL pour les données transactionnelles, ClickHouse pour les traces, les observations et les scores, Redis pour les files d'attente et un stockage objet pour les événements bruts. À l'ingestion, l'événement est d'abord déposé dans le stockage objet, une référence part en file, et les workers l'écrivent ensuite dans ClickHouse. Cette architecture sépare la réception des événements de leur traitement, et confie les analyses à un stockage en colonnes, conçu pour agréger de grands volumes.
Le module décrit ici n'a ni tampon d'ingestion ni moteur analytique. Il écrit ses relevés au fil des appels dans la base transactionnelle de l'application, celle qui sert aussi la boutique, et calcule ses agrégats sur cette même base. Chaque relevé y est une écriture de plus, et une analyse sur des mois de relevés y concurrence le travail courant. Sur un périmètre choisi, ce n'est pas un défaut ; ce ne sont simplement pas les mêmes propriétés.
Le choix d'un outil spécialisé dépend donc des besoins plus que d'un seuil. Le volume des relevés et la charge des analyses sur la base partagée comptent parmi ces besoins ; la recherche à travers plusieurs applications, les alertes, la gestion des consignes, les outils d'évaluation ou les intégrations en sont d'autres, et peuvent justifier Langfuse dès le départ. Les deux approches ne s'excluent pas : la couche d'instrumentation peut aussi alimenter un outil spécialisé, à condition de concevoir l'adaptateur qui traduit ses relevés.
Pour la Papeterie Alizé, le module prévoit une donnée pour répondre à chaque question du départ : l'exécution et ses deux versions du texte, les tentatives et leur usage, le coût estimé et sa grille, l'évaluation des horaires, la comparaison des versions. Un deuxième agent peut réemployer le même module : il déclare sa configuration, enregistre son entrée, ses étapes et sa sortie, puis fait passer ses appels au modèle par l'instrumentation. Les critères d'évaluation s'adaptent à sa tâche. La structure de suivi reste commune.