Dépanner les conversations d’assistants avec Débogueur d’assistant dans le kit Copilot Agent

Le Débogueur d’assistant est un outil de diagnostic qui vous aide à charger une conversation enregistrée et à inspecter chaque décision prise par un assistant. Pour chaque tour de conversation, vous pouvez revoir le chemin d’exécution, la durée des étapes, l’utilisation des jetons, les sources de connaissances, les arguments des étapes et le raisonnement de l’orchestrateur.

Le Débogueur d’assistant prend en charge deux sources de données :

• Transcription de conversation (Dataverse) : lorsqu’une conversation s’exécute dans Copilot Studio, la plateforme enregistre un journal d’activité sous forme de transcription de conversation dans Dataverse. Le Débogueur d’assistant interroge directement ces enregistrements, donc tout assistant publié avec des données de transcription est immédiatement disponible.
• Instantané de Copilot Studio (ZIP) : le panneau de test de Copilot Studio inclut une option Téléchargement d’instantané qui exporte la conversation de test en cours sous forme de fichier ZIP. Charger ce fichier dans le Débogueur d’assistant vous donne une vue d’analyse complète sans connexion à Dataverse. Cette méthode est utile pour déboguer des conversations de préproduction, reproduire des problèmes hors ligne, ou partager une session défaillante avec un collègue.

Les deux sources de données alimentent la même interface d’analyse. Les volets, les détails des étapes et les visualisations sont identiques, quelle que soit la méthode utilisée pour charger les données.

Configuration requise

Pour utiliser le Débogueur d’assistant, assurez-vous que les prérequis suivants sont satisfaits :

• L’assistant est présent dans l’inventaire des assistants et possède au moins une transcription de conversation enregistrée à son actif. Vous pouvez vérifier cette condition en ouvrant la vue Liste d’inventaire des assistants, en sélectionnant l’assistant, puis en sélectionnant Afficher plus pour développer les champs supplémentaires. Le champ Transcription disponible doit être défini sur Oui. La synchronisation Inventaire des assistants définit automatiquement ce champ lorsqu’au moins une transcription de conversation existe pour l’assistant dans Dataverse.
• L’utilisateur connecté a le rôle de sécurité CSK - Administrateur ou Administrateur système dans l’environnement du kit.
• L’utilisateur connecté dispose d’un accès en lecture sur les tables conversationtranscripts, bot et botcomponents dans l’environnement cible.

Sélectionner une conversation

Lorsque vous ouvrez le Débogueur d’assistant, la barre de filtres fournit les contrôles nécessaires pour localiser une conversation à analyser.

Après avoir sélectionné un ID de conversation, l’option Analyser devient disponible. Sélectionnez-la pour ouvrir la vue d’analyse.

Charger un instantané depuis Copilot Studio

L’onglet Charger l’instantané offre un point d’entrée alternatif qui ne nécessite pas d’accès à Dataverse. Au lieu de sélectionner une conversation active dans les listes déroulantes, vous chargez un fichier ZIP d’instantané téléchargé à partir du volet de test de Copilot Studio.

Télécharger un instantané depuis Copilot Studio :

1. Ouvrez votre assistant dans Copilot Studio et accédez au volet Tester votre assistant.
2. Exécutez ou examinez une conversation.
3. Sélectionnez Télécharger un instantané dans la barre d’outils du panneau de test.

Copilot Studio télécharge un fichier .zip contenant :

• dialog.json : toutes les activités du Bot Framework pour la conversation (obligatoires).
• botContent.yml : les définitions complètes des composants et des flux de l’assistant, utilisées pour résoudre les noms des étapes (facultatif ; si elles sont absentes, les noms de schéma bruts sont affichés).

Pour charger un instantané dans le Débogueur d’assistant :

1. Passez à l’onglet Charger Instantané dans l’en-tête Débogueur d’assistant.
2. Glissez-déplacez le fichier .zip dans la zone de dépôt, ou sélectionnez-la pour rechercher le fichier.

Le Débogueur d’assistant valide le fichier ZIP, extrait les fichiers et ouvre la vue d’analyse. Aucune sélection d’environnement, d’assistant ou de conversation n’est requise. Toutes les métriques d’informations générales sont dérivées du fichier chargé.

Utilisez le mode Charger l’instantané lorsque vous devez :

• Déboguer une conversation qui s’est déroulée dans le panneau de test avant la publication de l’assistant.
• Analysez une conversation provenant d’un environnement auprès duquel vous ne pouvez pas vous authentifier.
• Reproduisez les problèmes hors connexion ou partagez une session ayant échoué avec un collègue sans lui accorder l’accès à Dataverse.
• Validez le comportement des assistants dans un environnement de développement local.

Analyser une conversation

La vue d’analyse s’ouvre après que vous sélectionnez Analyser ou que vous chargez un instantané. Il contient une ligne de résumé Informations générales en haut, une section d’analyse réductible comportant quatre volets (Chemin d’exécution, Chronologie des performances, Détails de l’assistant et Recommandations), ainsi qu’une disposition à deux volets qui affiche l’Aperçu de la conversation à côté du volet Informations de débogage.

Informations générales

La ligne d’informations générales affiche des vignettes de métriques récapitulatives pour la conversation.

Lorsqu’un conseiller est chargé, un lien Ouvrir l’assistant apparaît dans l’en-tête des informations générales. Le lien ouvre la page de configuration de l’assistant dans Copilot Studio.

Chemin d’exécution

Le chemin d’exécution affiche l’ordre d’exécution complet sur tous les tours de conversation sous forme de diagramme de flux dirigé. Les étapes s’enchaînent de gauche à droite dans l’ordre d’exécution. Des lignes verticales en pointillés indiquent les limites entre les tours de conversation, et chaque message utilisateur marque le début d’une nouvelle section. Les libellés des tours de conversation apparaissent en haut de chaque section. La sélection du libellé d’un tour de conversation fait défiler l’Aperçu de la conversation jusqu’au message correspondant.

Chaque type d’étape utilise une couleur distincte, et une légende en bas du diagramme associe les couleurs à des catégories d’étapes telles que Rubrique, Connaissance, Outil, Connecteur, Flux, Code, MCP et Assistant connecté. Chaque nœud affiche le nom de l’étape et la durée d’exécution. Les étapes en échec sont surlignées en rouge. Les assistants connectés apparaissent sous forme de zones conteneurs qui regroupent les étapes enfants qu’ils ont exécutées.

Chronologie des performances

La chronologie des performances affiche un graphique en cascade des temps d’exécution des étapes, regroupés par tour de conversation. Les barres des étapes sont mises à l’échelle en fonction de la durée totale du tour de conversation afin de visualiser les temps d’exécution relatifs. Le code couleur correspond à la légende du chemin d’exécution, et les étapes en échec apparaissent en rouge.

Le volet inclut les fonctionnalités suivantes :

• Les boutons Développer/Réduire tout basculent toutes les sections de tour en même temps. Chaque section de tour de conversation peut également être réduite individuellement.
• Les statistiques par tour de conversation indiquent le nombre d’étapes, le nom et la durée de l’étape la plus lente, ainsi que le nombre d’échecs.
• Un résumé global en haut indique le nombre total d’étapes, le temps écoulé total, l’étape la plus lente de l’ensemble de la conversation et le nombre total d’échecs.
• Les étapes dont l’exécution prend plus de 10 secondes sont signalées par un indicateur d’avertissement.

Détails de l’agent

Le volet Détails de l’assistant affiche la configuration complète de l’assistant telle qu’elle existait au moment de l’analyse de la conversation. Les informations sont organisées en six onglets.

Recommandations

Le volet Recommandations détecte automatiquement les problèmes dans la conversation et les présente sous forme de cartes exploitables assorties d’un niveau de gravité.

Les types de problèmes suivants sont détectés :

Chaque carte de recommandation affiche l’icône et la couleur correspondant au niveau de gravité, un badge de catégorie, le titre et la description du problème détecté, une suggestion pour l’examiner ou le résoudre, ainsi qu’un bouton Accéder au tour de conversation qui fait défiler l’Aperçu de la conversation jusqu’au message utilisateur concerné. Lorsqu’aucun problème n’est détecté, le volet affiche un message d’état vide.

Aperçu d’une conversation

Le volet d’aperçu de la conversation affiche l’intégralité de l’échange tel qu’il est apparu à l’utilisateur, notamment les bulles de messages du bot et de l’utilisateur, les cartes adaptatives affichées en ligne, les pastilles d’actions suggérées et les invites de commentaires.

La sélection d’une bulle de message utilisateur charge les étapes de ce tour de conversation dans le volet Informations de débogage. Le message sélectionné est surligné pour que vous puissiez suivre quel tour est actif. Le volet peut défiler indépendamment. Sélectionner Afficher JSON dans l’en-tête de prévisualisation de conversation ouvre la boîte de dialogue JSON de transcription complète.

Informations de débogage

Le volet d’information de débogage affiche les détails au niveau de l’étape pour le tour de message utilisateur sélectionné. Le volet comprend une liste d’étapes à gauche et une vue détaillée qui s’ouvre lorsque vous sélectionnez une étape.

La liste des étapes affiche chaque étape de l’orchestrateur exécutée pour le tour de conversation sélectionné, avec une icône et une couleur indiquant le type d’étape, le nom de l’étape (remplacé, dans la mesure du possible, par un nom d’affichage convivial), la durée d’exécution et un indicateur de réussite ou d’échec. Les étapes appartenant à un assistant connecté sont regroupées dans une carte conteneur réductible qui affiche le nom de l’assistant et le temps d’exécution total. Un bouton Charger les détails de l’assistant connecté sur le conteneur charge la transcription complète de l’assistant enfant à la demande.

Les types d’étape suivants sont pris en charge :

La sélection d’une étape ouvre un volet de détails comportant les sections suivantes, affichées lorsque les données correspondantes sont présentes dans la transcription :

• Processus de réflexion : le texte de raisonnement de l’orchestrateur enregistré avant que l’étape ne soit invoquée. Montre comment le modèle a décidé d’appeler cette étape et ce qu’il attendait de celle-ci.
• Type d’étape : étiquette classée pour l’étape.
• Arguments : une arborescence JSON réductible des paramètres d’entrée transmis à l’étape. Inclut une option de copie pour capturer le JSON pour les tickets de support.
• Observation : la valeur de sortie ou de retour de l’étape. Également affichée sous forme d’arborescence JSON réductible avec prise en charge de la copie.
• Aperçu du code : pour les étapes de code Python, le code source est affiché avec la coloration syntaxique.
• Utilisation des jetons : nombre de jetons de la requête, nombre de jetons de complétion et nombre total de jetons pour l’étape, ainsi que le nom du modèle utilisé.
• Sources de connaissances : sources recherchées, résultats retournés (sorties) et sources effectivement citées dans la réponse finale. Chaque entrée affiche le nom de la source, le type, l’URL si celle-ci est disponible, ainsi qu’un lien pour ouvrir la source.
• Informations sur le serveur MCP : pour les étapes MCP, affiche la version du protocole du serveur, les fonctionnalités déclarées et la liste des outils fournis par le serveur lors de l’initialisation.
• Informations sur l’erreur : lorsqu’une étape a échoué, affiche le code et le message d’erreur ainsi que, pour les blocages par l’IA responsable, la catégorie de sécurité du contenu qui a déclenché le filtrage.
• Cartes adaptatives : lorsque l’étape a généré une réponse sous forme de carte adaptative, celle-ci est affichée en ligne dans le volet de détails, exactement telle que l’utilisateur l’aurait vue.

JSON de transcription

Lorsque vous sélectionnez Afficher le JSON dans l’en-tête de l’aperçu de la conversation, une boîte de dialogue s’ouvre et affiche l’ensemble des activités brutes de la transcription avec coloration syntaxique, une recherche en texte intégral dans l’arborescence JSON et une option permettant de copier l’intégralité de la charge utile dans le Presse-papiers.

Utilisez cette vue quand :

• Vous devez inspecter un type d’événement qui n’apparaît pas dans le panneau Informations de débogage.
• Vous souhaitez copier des champs spécifiques pour un ticket de support.
• Vous examinez un comportement inattendu dans les vues analysées.

Paramètres de résolution des problèmes

Les sections suivantes décrivent les problèmes courants et expliquent comment les résoudre.

L’assistant n’apparaît pas dans la liste déroulante Environnement ou Assistant

L’assistant n’est pas synchronisé avec l’Inventaire des assistants, ou il n’y a aucune transcription de conversation.

Pour résoudre ce problème :

1. Effectuez une synchronisation manuelle de l’inventaire des assistants pour l’environnement.
2. Vérifiez que l’enregistrement de l’assistant existe dans la table des détails de l’assistant dans Dataverse.
3. Vérifiez que la colonne Transcription disponible est définie sur Oui sur l’enregistrement. La synchronisation définit ce champ lorsqu’au moins une transcription existe.

Pour plus d’informations, voir Surveiller les assistants à l’aide de l’inventaire des assistants dans le kit Copilot Agent.

L’ID de conversation n’apparaît pas dans le menu déroulant

Pour des raisons de performances, la liste déroulante précharge uniquement les 50 conversations les plus récentes dans la plage de temps active. Les transcriptions plus anciennes existent toujours dans Dataverse, mais ne s’affichent pas par défaut. Il se peut également que la transcription n’ait pas encore été enregistrée si la conversation vient de se terminer.

Pour résoudre ce problème :

1. Saisissez l’ID de conversation directement dans le champ ID de conversation. La saisie déclenche une recherche complète dans toutes les transcriptions de cet assistant, sans tenir compte de la plage de temps.
2. Si la plage de temps est restreinte (par exemple, Les 30 dernières minutes), élargissez-la ou sélectionnez une plage personnalisée couvrant la date de la conversation.
3. Si la conversation vient de se terminer, attendez 35 à 40 minutes que la transcription soit écrite sur Dataverse, puis rafraîchissez.

L’analyse se charge, mais aucune étape n’apparaît dans le volet Informations de débogage

La transcription existe mais ne contient que des activités de type message sans événements de trace diagnostique. Ce problème survient généralement lorsque la conversation provient d’un canal qui n’émet pas de données de trace, comme certains canaux personnalisés ou d’anciennes versions de schéma.

Pour résoudre ce problème :

1. Sélectionnez Afficher JSON dans l’en-tête de prévisualisation de la conversation pour confirmer que les activités sont présentes.
2. Recherchez des entrées type: "trace" ou type: "event". Si elles sont absentes, il est possible que le canal n’émette pas de données de trace.

Accès refusé ou page blanche au chargement

Des rôles ou des autorisations manquent dans un ou les deux environnements.

Pour résoudre ce problème :

1. Dans l’environnement de kit, assurez-vous que l’utilisateur a le rôle de sécurité CSK - Administrateur ou Administrateur système.
2. Dans l’environnement cible, vérifiez que l’utilisateur connecté dispose d’un accès en lecture aux tables conversationtranscripts, bot et botcomponents.

Les transcriptions semblent incomplètes (messages anciens manquants)

Les longues conversations sont réparties sur plusieurs enregistrements Dataverse (limite de 1 Mo par enregistrement). Si la stratégie de rétention supprime certains enregistrements, la transcription fusionnée comporte des lacunes.

Pour résoudre ce problème :

1. Dataverse efface par défaut les transcriptions de conversations datant de plus de 30 jours. Si le problème est lié à la conservation, mettez à jour la planification de la tâche de suppression en bloc dans Power Apps>Paramètres>Paramètres avancés>Gestion des données>Suppression d’enregistrements en bloc.
2. Si la rétention n’est pas la cause, vérifiez que tous les enregistrements de transcription pour la conversation existent dans la table conversationtranscripts de Dataverse.

Les étapes affichent les noms bruts des schémas au lieu de noms de rubriques lisibles

La recherche dans la table botcomponents a échoué, ou l’enregistrement composant a été supprimé.

Pour résoudre ce problème :

1. Vérifiez que l’utilisateur connecté dispose d’un accès en lecture à la table botcomponents dans l’environnement cible.
2. Si le composant a été supprimé de Copilot Studio, aucun enregistrement correspondant n’existe et le Débogueur d’assistant revient au nom brut du schéma, comme cr123_mytopic. Ce comportement est attendu pour les rubriques ou actions supprimées.

Le volet des détails de l’assistant n’affiche aucune donnée

La récupération de configuration de l’assistant a échoué, ou bien la connexion de l’utilisateur connecté n’a pas d’accès en lecture aux tables bot et botcomponents dans l’environnement cible.

Pour résoudre ce problème :

1. Vérifiez l’accès en lecture aux tables bot et botcomponents pour la référence de connexion utilisée par l’application.
2. Si l’assistant a été supprimé ou dépublié après l’enregistrement de la conversation, il se peut que ses enregistrements de configuration n’existent plus. Dans ce cas, le volet Détails de l’assistant reste vide, mais les volets de transcription et de débogage restent entièrement fonctionnels.

Le volet Recommandations n’affiche aucun problème alors que la conversation a échoué

Les recommandations reposent sur des modèles détectés dans les événements de trace de la transcription. Si la transcription ne contient pas de données de trace, ou si l’échec se produit en dehors de la conversation (par exemple, un délai d’expiration réseau silencieux qui n’est pas enregistré dans la transcription), le système ne génère aucune recommandation.

Pour résoudre ce problème :

1. Ouvrez le JSON de la transcription pour rechercher les charges utiles d’erreur brutes qui ne sont pas présentées sous forme de recommandations.
2. Vérifiez si des étapes apparaissent en rouge dans le chemin d’exécution. Ces étapes indiquent des échecs qui ne correspondent à aucun modèle de recommandation connu.

Informations associées

• Surveillez les assistants à l’aide de l’Inventaire des assistants dans le kit Copilot Agent
• Configurer des assistants dans le kit Copilot Agent
• Vue d’ensemble du kit Copilot Agent