Déboguer des agents avec l’inspecteur d’agent dans Microsoft Foundry Toolkit

L’inspecteur d’agent dans Microsoft Foundry Toolkit pour Visual Studio Code vous permet d’envoyer des demandes à un agent local, d’inspecter l’activité du modèle et de l’outil et de déboguer votre code. Utilisez-la pour examiner les réponses inattendues avant de déployer une modification.

Ce flux de travail est utile pour les agents hébergés, qui exécutent votre code personnalisé dans Foundry Agent Service. L’inspection locale vous aide à déboguer ce code. Avant toute utilisation en production, testez également l’agent déployé avec son identité d’exécution, sa configuration et son accès réseau.

Dans cet article, vous vous connectez à un agent local, examinez une demande et enregistrez les événements de diagnostic. Le chemin principal utilise le protocole Responses. Les vues disponibles dépendent du protocole et des diagnostics que votre serveur d’agent fournit.

Prerequisites

  • Visual Studio Code avec l’extension publique Foundry Toolkit actuelle. Consultez Installer Foundry Toolkit.
  • Un projet d’agent local avec ses dépendances, sa configuration de modèle et ses informations d’identification configurées. Pour commencer à partir d’un exemple, suivez le guide de démarrage rapide de l’agent hébergé via les tests locaux.
  • Le débogueur requis par votre projet. L’exemple Python utilise l’extension Python et debugpy. D’autres langues et exemples ont des exigences différentes.

Pour un projet existant, les outils Foundry Toolkit Copilot peuvent vous aider à préparer la configuration. Passez en revue les fichiers générés et suivez les directives du projet README.md. Ne remplacez pas ses fichiers de lancement par une configuration générique.

Important

Un agent local peut appeler des modèles cloud et des outils en direct. Utilisez des entrées de test non sensibles, vérifiez les autorisations de l’outil et tenez compte des frais des services configurés. L’inspecteur ne remplace pas les outils par des mocks.

Connectez-vous et déboguez

Démarrez le serveur d’agent avant de vous connecter à Inspector. Utilisez la configuration de lancement générée de votre projet pour aligner le serveur, le répertoire de travail, l’interpréteur et le débogueur.

  1. Démarrez l’agent avec sa configuration de débogage documentée. Pour l’exemple Python de l’agent hébergé, sélectionnez Debug Local Agent HTTP Server, puis appuyez sur F5.
  2. Si l’inspecteur n’est pas ouvert, sélectionnez Foundry Toolkit dans la barre d’activités, puis dans Developer Tools>Build>Agent Inspector.
  3. Vérifiez le point de terminaison dans l’en-tête Inspector. La structure Python actuelle utilise http://localhost:8088. Pour un autre port de serveur, sélectionnez le bouton crayon en regard de l’endpoint, entrez le port, puis sélectionnez Se connecter.
  4. Vérifiez que l’en-tête affiche Connecté. L’inspecteur détecte automatiquement le protocole Réponses ou Invocations lorsque le point de terminaison est accessible.
  5. Définissez un point d’arrêt dans votre code d’agent et envoyez un message dans le Playground. Inspectez les variables lorsque l’exécution s’interrompt, puis poursuivez et passez en revue la réponse.

Capture d’écran de la configuration du débogage de l’agent local et de l’inspecteur d’agent connecté à localhost sur le port 8088 avec une réponse réussie.

L’ouverture de l’inspecteur seul ne lance pas de serveur ni n’attache un débogueur. La configuration de Python générée utilise le port 5679 pour le débogueur et le port 8088 pour les requêtes HTTP de l’agent. Ces ports sont distincts des ports de traçage OTLP.

Connectez-vous à un point de terminaison Responses générique

L’inspecteur peut se connecter à un point de terminaison de réponses générique local sans l’interface de diagnostic de développement complète. Vous pouvez inspecter les événements Responses envoyés par le serveur, mais le graphique de flux de travail et sa vue d’entrée et de sortie ne sont pas disponibles.

Une connexion réussie ne signifie pas que le serveur fournit des emplacements sources, une utilisation des jetons ou un raisonnement.

Envoyer une invocation HTTP

Utilisez des appels HTTP lorsque votre agent accepte un corps de requête personnalisé plutôt qu’un message conversationnel. Le format de requête et le protocole de réponse du serveur déterminent comment Inspector envoie et affiche le résultat.

  1. Connectez-vous à votre serveur d’invocations HTTP en cours d’exécution. Inspector détecte automatiquement le protocole.
  2. Entrez le corps de la demande requis par votre agent. Si le serveur expose une spécification OpenAPI compatible, Inspector peut renseigner un exemple. Vérifiez-le avant d’envoyer, ou suivez le format de requête de l’exemple si aucun exemple n’est disponible.
  3. Sélectionnez l’engrenage Request settings en regard de l’entrée pour définir Content-Type et Accept comme requis par le serveur. Par exemple, utilisez application/json pour un corps JSON et text/event-stream lorsque le serveur prend en charge une réponse de diffusion en continu.
  4. Sélectionnez Envoyer et inspectez l’état et le corps de la réponse.
  5. Basculez entre Aperçu pour la sortie mise en forme et Brut pour la réponse sous-jacente. Le volet d’informations inclut également les appels d’E/S et les appels LLM. Les détails du modèle, de l’outil et du jeton dépendent des événements de serveur reconnus, donc toutes les réponses ne remplissent pas chaque onglet.

L’inspecteur gère une réponse HTTP normale, un flux d’événements envoyés par le serveur ou une réponse asynchrone. Pour une réponse asynchrone 202 Accepted , elle interroge l’appel jusqu’à l’achèvement ou l’échec. La sélection d’un format de réponse n’ajoute pas de prise en charge asynchrone ou de streaming à votre serveur.

Pour une réponse de diffusion en continu, Arrêter déconnecte le flux client. Pour une invocation par interrogation, Cancel envoie une demande d’annulation au serveur. Aucune action ne garantit que le processus de l’agent ou une opération d’outil externe s’est arrêté.

Cette vue n’est pas un client WebSocket. Les exemples de protocole d’activité utilisent un autre bac à sable. Consultez Choisissez un autre protocole ou exemple pour le chemin de test local approprié.

Utiliser l’Inspecteur

Commencez par une requête qui exerce le comportement que vous souhaitez comprendre. Pour un outil météo, par exemple, demandez des informations qui nécessitent cet outil, plutôt qu’une réponse générale que le modèle peut produire sans lui.

  1. Envoyez la demande dans le Playground et passez en revue la réponse en streaming.
  2. Utilisez les onglets de détails pour rechercher l’opération lente ou défaillante.
  3. Inspectez l’événement ou l’appel d’outil approprié, modifiez votre code ou configuration, puis répétez la demande.

Appuyez sur Entrée pour envoyer ou Maj+Entrée pour ajouter une nouvelle ligne. Pour rappeler une demande antérieure, placez le curseur au début de l’entrée et appuyez sur Flèche vers le haut. Appuyez sur la touche Flèche vers le bas à la fin pour passer aux requêtes plus récentes et revenir à votre brouillon non envoyé.

Vous pouvez modifier une demande retirée avant de l’envoyer. L’historique des entrées est pratique dans Inspector, et non un stockage pérenne d’invites enregistrées.

View Utilisez-le pour
Overview Suivez la cascade de latence et la chronologie de l’exécution ordonnée. Sélectionnez toutes les exécutions ou une exécution pour distinguer l’activité du modèle et de l’outil de la durée entre les exécutions.
Jetons Passez en revue l’utilisation des tokens d’entrée et de sortie signalés. Les données d’utilisation manquantes ne sont pas un résultat à zéro jeton.
Événements Inspectez les événements Responses analysés, notamment les erreurs, les appels de fonction et les résultats. Recherchez par type d’événement ou contenu JSON et filtrez par catégorie.
Outils Inspectez les appels d’outils regroupés par exécution de réponse, notamment l’état, l’ID d’appel, les arguments et les résultats.

Le pied de page de réponse affiche les informations de modèle, de durée, d’utilisation des jetons et d’horodatage fournies. Le texte de raisonnement et les résumés de raisonnement apparaissent dans des sections réductibles distinctes lorsque l’agent les émet. L’inspecteur ne génère pas de raisonnement manquant ou n’expose pas d’informations que le fournisseur de modèles ne retourne pas.

Inspectez les outils et les autorisations

Utilisez Outils pour vérifier si l’agent a appelé l’outil attendu avec les arguments attendus et reçu un résultat. Une réponse de modèle réussie ne prouve pas qu’un outil s’est exécuté. Si votre code utilise un mock, le résultat affiché est toujours un résultat mock.

Capture d’écran de l’onglet Outils avec des appels regroupés par exécution et un appel d’outil développé montrant ses arguments et résultats.

Lorsqu’une réponse s’interrompt pour l’approbation MCP (Model Context Protocol) ou le consentement OAuth, les demandes en attente s’affichent au-dessus de l’entrée du message. Accordez uniquement l’accès que vous avez l’intention d’autoriser.

Pour un appel d’outil MCP, sélectionnez Afficher les arguments, passez en revue les entrées, puis sélectionnez Approuver ou Refuser. Tout approuver et Tout refuser s’appliquent aux demandes en attente, et non à une stratégie permanente d’approbation des outils.

Pour le consentement OAuth, complétez l’autorisation du navigateur et la confirmation de l’inspecteur :

  1. Sélectionnez Ouvrir le consentement pour la demande en attente.
  2. Complétez l’autorisation dans le navigateur, revenez à Inspector, puis sélectionnez Consent done. Pour refuser l’autorisation, sélectionnez Annuler à la place.
  3. Résolvez les demandes de consentement restantes. Utilisez Tout est terminé, lorsqu’il est disponible, uniquement après avoir terminé l’autorisation pour toutes les demandes ouvertes.

L’ouverture d’une page de consentement seule ne permet pas de reprendre la requête. L’inspecteur attend une décision sur chaque consentement en attente avant de vérifier à nouveau le serveur. Les demandes peuvent réapparaître si le serveur a encore besoin d’une autorisation.

Vérifiez le résultat de l’outil suivant, non seulement l’approbation, pour confirmer l’achèvement. Pour la configuration de la connexion et de l’authentification, consultez Catalogue d’outils. Ne modifiez pas les informations d’identification ou les autorisations de l’outil uniquement pour faire disparaître une erreur de diagnostic.

Inspectez les flux de travail et le code source

Pour les flux de travail Microsoft Agent Framework pris en charge, le serveur de développement peut fournir des diagnostics de flux de travail et des emplacements sources. L’inspecteur utilise ces informations pour afficher le graphique d’exécution et vous aider à accéder à votre code.

  1. Sélectionnez un nœud de flux de travail pour inspecter les entrées et sorties disponibles.
  2. Double-cliquez sur le nœud pour ouvrir son emplacement d’origine.
  3. Définissez un point d’arrêt et répétez la requête pour inspecter l’opération dans le débogueur.

Vous pouvez tester les flux de travail LangGraph dans le Playground, mais la visualisation de flux de travail n’est pas prise en charge pour ces flux de travail. Un serveur sans métadonnées de flux de travail peut toujours retourner des événements de réponse utiles.

Analyser les défaillances avec Copilot

Utilisez les actions d’erreur dans Les événements pour préparer une demande ciblée pour GitHub Copilot au lieu de copier l’intégralité de la conversation.

  1. Recherchez l’événement ayant échoué et passez en revue ses détails pour le contenu sensible avant de les partager.
  2. Sélectionnez Fix en regard de l’événement ayant échoué pour préparer une invite pour cet échec. Pour plusieurs échecs, réduisez la liste avec des filtres de recherche et de catégorie, puis sélectionnez Résoudre avec Copilot. Cette action inclut les échecs visibles.
  3. Passez en revue l’invite préparée dans GitHub Copilot Chat avant de l’envoyer. Passez en revue les modifications proposées, puis réexécutez la demande de l’agent d’origine pour confirmer le résultat.

Ces actions ne nécessitent pas le collecteur OTLP. La préparation d’une invite de diagnostic ne corrige pas l’agent ni ne réexécute l’opération ayant échoué.

Capture d’écran de l’onglet Événements avec des réponses ayant échoué, des contrôles de recherche et de filtre, des actions d’exportation et des détails de diagnostic préparés dans Copilot Chat.

Enregistrer les événements de diagnostic

Enregistrez une capture d’instantané d’événement pour comparer une défaillance à une exécution ultérieure ou partager un cas de reproduction ciblé.

  1. Dans Événements, limitez la liste avec le champ de recherche et le filtre de catégorie.
  2. Sélectionnez Copier les événements visibles pour copier les événements filtrés en tant que JSONL. Vous pouvez également sélectionner Télécharger les événements visibles pour ouvrir l’exportation dans VS Code.
  3. Pour l’export ouvert, utilisez Fichier> pour enregistrer une copie dans un emplacement que vous contrôlez avant de fermer le document. L’export ouvert est un fichier temporaire, et non un téléchargement permanent.

L’instantané contient les événements visibles lorsque vous sélectionnez l’action, et non les événements futurs de l’agent en cours d’exécution. Il n’enregistre pas une version de l’agent, ne déploie pas de code ni ne crée l’historique des traces cloud.

Caution

Les événements peuvent inclure des invites, des réponses, des arguments d’outil, des résultats et des détails d’erreur. Passez en revue et caviardez le contenu sensible avant d’enregistrer ou de partager une exportation.

Démarrer une nouvelle conversation

Sélectionnez Effacer la conversation pour démarrer une nouvelle conversation et effacer l’état Conversation, Événements et Détails. Exportez d’abord les événements de diagnostic dont vous avez besoin. L’actualisation du même agent connecté conserve son état d’inspection, tandis que changer d’agent efface l’état obsolète.

Pour les réponses, Clear Chat est désactivé alors qu’une réponse est en cours de diffusion. Il reste disponible lorsque l’interaction s’interrompt pour approbation ou consentement. Ce n’est pas une commande générale pour arrêter votre agent.

Ne vous fiez pas à l’état local de l’Inspector en tant qu’archive de conversation durable. Le serveur possède la persistance des conversations, qui peut différer entre le développement local et un agent hébergé déployé. Clearing Inspector ne supprime pas les traces déjà collectées localement ou stockées dans Application Insights.

Différences entre Inspector et le traçage

L’inspecteur communique avec votre serveur local via HTTP et transmet en continu les événements de réponse. Un serveur de développement compatible fournit également un flux de diagnostic distinct pour les détails du flux de travail et la navigation source. Le débogueur se connecte à votre processus en cours d’exécution de manière indépendante.

Ces diagnostics en direct ne nécessitent pas le collecteur OTLP local. L’onglet Traces de l’inspecteur ouvre la visionneuse de suivi distincte. Il ne transforme pas les événements de protocole en spans OpenTelemetry stockés.

Pour collecter des spans pour une analyse ultérieure, configurez le suivi local. Pour les agents déployés, utilisez hosted-agent traces.

Après les tests locaux, déployez l’agent hébergé. Testez-le séparément, car son identité, son environnement et son accès réseau diffèrent de votre processus local.

Troubleshooting

Problème Que vérifier
Inspector ne peut pas se connecter. Vérifiez le terminal de l’agent pour détecter des erreurs de démarrage. Confirmez l’interpréteur, les dépendances et le port HTTP, puis reconnectez-vous au port que le serveur signale. L’Inspecteur d’ouverture ne lance pas le processus.
Une requête réussit, mais les points d’arrêt ne sont pas interceptés. Vérifiez que le débogueur est attaché au processus qui traite la requête et qu’il utilise le répertoire source approprié. Pour Python, consultez la résolution des problèmes de débogage.
Le graphique ou la navigation source est manquante. Vérifiez que le serveur et le flux de travail fournissent des diagnostics de développement et des emplacements sources. L’inspection des réponses génériques ne fournit pas ces fonctionnalités. Les flux de travail LangGraph fonctionnent dans le playground sans visualisation de flux de travail.
Les résultats de l’outil sont manquants. Vérifiez Events pour les échecs et les approbations en attente. Vérifiez que la demande nécessite un outil et que l’outil est configuré et accessible.
Les détails du jeton ou du raisonnement sont manquants. Vérifiez ce que le modèle et le serveur émettent. L’inspecteur ne peut afficher que les informations qu’il fournit.
Les images distantes sont bloquées. Sélectionnez Charger des images distantes uniquement si vous souhaitez que Inspector les récupère à partir d’hôtes distants. Cette autorisation d’affichage n’est pas une approbation d’outil. Les URL ou contenus non pris en charge peuvent malgré tout ne pas se charger. Une image manquante ne signifie pas nécessairement que la demande de l’agent a échoué.
Le flux de réponse est interrompu. Passez en revue la réponse partielle et les détails de l’échec. Reconnectez-vous si nécessaire et passez en revue les approbations en attente avant de réessayer. Une nouvelle tentative peut répéter des actions d’outil en direct.
L’inspecteur a des événements, mais la visionneuse de suivi est vide. Les événements de protocole et les spans OTLP sont différents. Configurez l’instrumentation et démarrez le collecteur.

Contenu connexe

  • Dernière mise à jour :