> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt # Trace Intelligence sur la plateforme Mastra Trace Intelligence identifie les modèles récurrents dans les interactions de vos agents. Il analyse les traces capturées par Mastra Observability, produit des signaux de trace pour quatre dimensions et regroupe les signaux similaires en thèmes. Utilisez Trace Intelligence pour étudier des questions telles que : - Que cherchent à accomplir les utilisateurs ? - Quels objectifs réussissent généralement, restent non résolus ou se trouvent bloqués ? - Quels comportements d’agent apparaissent dans les interactions réussies et infructueuses ? - Quel est le lien entre le sentiment des utilisateurs, les objectifs et les résultats ? > **Private beta:** Trace Intelligence est disponible sur invitation pour certains projets sélectionnés de la plateforme Mastra. ## Obtenir l’accès 1. Envoyez le [formulaire de bêta privée Trace Intelligence](https://mastra.ai/trace-intelligence) pour demander l’accès. 2. Vérifiez que [Mastra Platform Observability](https://mastra.zisheng.pro/fr/docs/mastra-platform/observability) est activé et que les traces d’agent terminées apparaissent sous **Traces**. 3. Utilisez au moins `@mastra/core@1.53.0` et `mastra@1.20.2`. Mettez à niveau votre projet, puis déployez ou redéployez Studio pour le projet inscrit. Studio local et les déploiements de serveur seul ne sont pas pris en charge pendant la bêta privée. 4. Ouvrez Studio déployé et sélectionnez **Intelligence** dans la barre latérale. 5. Envoyez du trafic représentatif à votre agent et laissez le temps à l’analyse de s’exécuter. Une fois que Mastra a inscrit le projet, vous n’avez pas besoin de modifier la définition ni les appels de votre agent. ### Disponibilité des données Trace Intelligence a besoin de suffisamment de traces traitées d’un même agent pour identifier des modèles récurrents. Les thèmes initiaux sont généralement disponibles après le traitement d’au moins **100 traces terminées** de cet agent. Le nombre de traces sous **Traces** peut atteindre 100 avant que Trace Intelligence soit prêt, car le pipeline d’analyse s’exécute de façon asynchrone. Le traitement peut prendre plusieurs minutes une fois le seuil atteint. Les traces impossibles à analyser ne contribuent pas ; 100 est donc un minimum, et non un déclencheur exact de l’interface. Trace Intelligence se met automatiquement à jour à mesure que de nouvelles traces arrivent. Studio a besoin de thèmes pour au moins deux types de signaux de trace avant de pouvoir afficher le flux de relations. Utilisez un trafic représentatif. Un petit ensemble de prompts de test répétés peut produire des résultats peu représentatifs, comme un thème très large ou principalement du bruit. ## Comprendre l’analyse Chaque trace terminée analysable produit quatre signaux de trace : | Signal de trace | Signification | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Goal** | Ce que l’utilisateur cherche à atteindre ou à faire accomplir. | | **Outcome** | L’état final : terminé, partiel, bloqué, en échec, non résolu ou ambigu. | | **Behavior** | Les actions et modèles observables de l’agent, notamment l’utilisation de tools, les omissions, les nouvelles tentatives, les échecs et la récupération. | | **Sentiment** | L’état émotionnel ou l’attitude de l’utilisateur. | Les thèmes sont des groupes générés à partir de signaux de trace similaires. Le regroupement s’effectue indépendamment pour chaque type de signal de trace. Une même trace peut appartenir à un thème distinct dans chaque dimension : Goal, Outcome, Behavior et Sentiment. ### Thèmes et relations Le diagramme de flux relie les thèmes des colonnes de signaux de trace adjacentes : - Un **node** représente un thème. Son nombre est celui des traces distinctes attribuées à ce thème dans le snapshot sélectionné. - Un **ribbon** relie les traces attribuées aux thèmes des deux colonnes adjacentes. Sa largeur représente le nombre de traces partagé. - Survolez ou sélectionnez un node ou un ribbon pour isoler ses relations. Le flux montre une association, et non une causalité ou un ordre d’exécution. Par exemple, un ribbon entre un Goal et un Outcome signifie que les deux thèmes sont apparus dans les mêmes traces. Il ne montre pas que le goal a provoqué l’outcome. ### Distributions, Other et Noise Les cartes sous le flux affichent la distribution des thèmes de chaque signal de trace : - **Trace count** : le nombre de traces distinctes attribuées à un thème dans le snapshot sélectionné. - **Stage share** : le pourcentage des traces analysées pour ce signal de trace attribuées au thème. Studio affiche les thèmes les plus fréquents pour chaque type de signal de trace. Il peut combiner les thèmes plus petits dans **Other** afin de conserver les totaux sans surcharger le graphique. **Noise** contient les résumés qui ne correspondent pas de façon cohérente à un thème récurrent dans le snapshot sélectionné. Cela n’indique pas nécessairement une erreur ou une interaction de faible qualité. Noise peut inclure des requêtes rares et des modèles émergents, ainsi que des interactions ambiguës ou des cas non liés. Une part importante de Noise peut indiquer un trafic très varié ou des données insuffisantes pour obtenir des thèmes stables. ### Snapshots Un snapshot est une fenêtre d’analyse mobile sur un ensemble de traces. Les snapshots peuvent se chevaucher ; n’additionnez donc pas leurs nombres de traces. Comparez ensemble le nombre de traces et la part d’étape, car le volume de trafic peut changer entre les fenêtres. Un thème peut persister, disparaître, se diviser, fusionner ou revenir d’un snapshot à l’autre. Traitez les noms et descriptions de thèmes comme des résumés générés, et non comme des taxonomies fixes. ## Utiliser la page Trace Intelligence 1. Utilisez le sélecteur **Agent** pour passer d’un agent ayant des analyses disponibles à un autre. Un agent n’apparaît qu’une fois ses premiers thèmes prêts. 2. Sélectionnez un thème dans le flux pour filtrer chaque colonne sur les traces contenant ce thème. 3. Sélectionnez **View theme details** pour examiner sa description, son nombre de traces, sa part d’étape, ses exemples générés et son historique. 4. Sélectionnez **Clear filter** pour restaurer le flux complet. Vous pouvez également : - Sélectionner un thème dans une carte de distribution pour ouvrir ses détails et ses résumés d’exemples générés. - Sélectionner **Noise** dans une carte de distribution pour examiner sa distribution et ses résumés d’exemples générés. - Faire glisser les cartes de distribution pour réorganiser les colonnes de signaux de trace et observer les relations sous un autre angle. - Utiliser la chronologie pour sélectionner un snapshot, ou sélectionner **Play** pour observer l’évolution des thèmes au fil du temps. - Ouvrir l’historique d’un thème pour voir s’il a persisté et comment sa couverture a évolué. Le filtrage du flux par thème n’est pas disponible pour les snapshots contenant plus de 2 000 traces. Choisissez un autre snapshot ou effacez le filtre actif pour revenir au flux complet. Les détails de Theme et Noise restent disponibles depuis les cartes de distribution. ## Résolution des problèmes ### Intelligence n’apparaît pas dans la barre latérale Vérifiez que Mastra a inscrit le bon projet, que vous utilisez une version de Mastra compatible avec la bêta et que vous avez redéployé Studio. La bêta privée ne prend pas en charge Studio local. ### Un agent est absent Vérifiez que ses traces terminées sont listées sous **Traces**. L’agent n’est listé qu’une fois ses premiers thèmes prêts. S’il a récemment atteint 100 traces, laissez le temps au traitement asynchrone de s’exécuter. ### Le flux de relations est indisponible Le flux nécessite des thèmes pour au moins deux types de signaux de trace. Continuez à envoyer du trafic représentatif et attendez la fin du traitement. ### La plupart des résumés sont Noise Collectez davantage de trafic représentatif et comparez un snapshot ultérieur. Les interactions variées ou rares sont plus difficiles à regrouper, tandis que les prompts de test répétés peuvent produire une distribution peu représentative. ## Limites de la bêta privée - Trace Intelligence est disponible uniquement pour les projets inscrits dans Studio déployé. - L’analyse initiale requiert au moins 100 traces traitées par agent. Certains agents peuvent en nécessiter davantage. - Les résultats dépendent de la diversité et de la qualité des traces capturées. - Les résumés de signaux de trace, les libellés de thèmes, le regroupement, les seuils et le comportement de l’interface peuvent évoluer pendant la bêta. Lorsque vous signalez un retour, incluez l’ID de l’organisation, l’ID du projet, l’ID de l’agent, le snapshot sélectionné et les exemples de thème ou de Noise qui illustrent le problème. ## Pages connexes - [Observability sur la plateforme Mastra](https://mastra.zisheng.pro/fr/docs/mastra-platform/observability) - [Studio sur la plateforme Mastra](https://mastra.zisheng.pro/fr/docs/mastra-platform/studio)