Démarrage rapide : Suivre votre agent hébergé

Dans ce guide de démarrage rapide, vous affichez les traces de bout en bout pour l’agent hébergé que vous avez déployé dans Déployer votre premier agent hébergé. Vous appelez votre agent pour générer des données de trace et passer en revue les traces dans le portail Foundry.

Les bibliothèques d’hébergement (azure-ai-agentserver-responseset azure-ai-agentserver-invocations) intègrent en douceur la distribution Microsoft OpenTelemetry, qui fournit une instrumentation prête à l’emploi pour Microsoft Agent Framework et LangChain, et exporte les traces vers Application Insights. En outre, le service Foundry Agent génère automatiquement des données de télémétrie côté serveur lors de l’invocation de l’agent, sans nécessiter de modification du code.

Le suivi vous donne une visibilité sur la façon dont votre agent gère chaque requête afin de pouvoir déboguer des problèmes, surveiller la latence et comprendre le comportement de l’agent avant de publier des modifications aux utilisateurs.

Prerequisites

Avant de commencer, vous avez besoin des éléments suivants :

  • Un agent hébergé déployé et pouvant être invoqué à partir de Déployer votre premier agent hébergé, ainsi que le répertoire du projet azd que vous avez créé dans ce guide de démarrage rapide.

  • Le rôle Utilisateur de Foundry sur la ressource Foundry.

  • Pour utiliser le chemin d’interface utilisateur, accédez au portail Foundry. Pour le chemin d'accès azd, consultez les exigences ci-dessous.

  • Azure Developer CLI (azd) 1.36.0 ou version ultérieure avec l’extension microsoft.foundry :

    azd ext install microsoft.foundry

  • Une session authentifiée azd . Vérifiez votre état azd auth statuset exécutez azd auth login si vous n’êtes pas connecté.

    Important

    Les rôles Foundry RBAC ont été récemment renommés. Foundry User, Foundry Owner, Propriétaire du compteFoundry et Foundry Project Manager ont été précédemment nommés Azure utilisateur IA, Azure propriétaire d’IA, propriétaire Azure compte IA et Azure gestionnaire Project IA. Il se peut que vous voyiez encore les anciens noms à certains endroits pendant le déploiement de ce changement de nom. Les ID de rôle et les autorisations de base ne sont pas modifiés par ce changement de nom.

  • Ressource Application Insights Azure Monitor connectée à votre projet Foundry. Pour le configurer, consultez Configurer le suivi dans Microsoft Foundry.

  • Le rôle de lecteur Log Analytics sur la ressource Application Insights connectée à votre projet. Si les tables Log Analytics sous-jacentes sont protégées, attribuez également le rôle Lecteur de données de surveillance privilégié.

Étape 1 : Appeler votre agent

Générez des données de trace en envoyant une demande à votre agent déployé.

À partir de votre azd répertoire de projet, envoyez une invite de test :

azd ai agent invoke "Summarize the benefits of distributed tracing for AI agents."

Vous devriez voir une réponse en quelques secondes.

Chaque appel génère une trace complète. Pour obtenir des traces plus riches, envoyez des prompts qui déclenchent des appels à des outils ou un raisonnement en plusieurs tours.

Étape 2 : Afficher les traces dans le portail Foundry

Les traces peuvent être consultées dans le portail Foundry après l’invocation.

  1. Dans le portail Foundry, ouvrez votre projet.
  2. Dans le volet de navigation gauche, sélectionnez Agents.
  3. En haut, sélectionnez Traces.
  4. Recherchez votre trace dans la liste. Vous pouvez effectuer une recherche par ID de trace, ID de réponse ou filtre par intervalle de temps.

Trajectoire

Capture d'écran de la vue en cascade de la trace dans le portail Foundry montrant des spans pour invoke_agent, les complétions de conversation et les requêtes de jetons, avec les détails d'entrée et de sortie à droite.

Affichage utilisateur

Animation de l’affichage utilisateur des traces dans le portail Foundry.

Tip

Si votre agent utilise Microsoft Agent Framework, il émet automatiquement ses propres étendues OpenTelemetry. Ces spans apparaissent comme enfants des spans de la couche d'hébergement, vous offrant une arborescence de traces complète allant de la requête HTTP, en passant par l'orchestration de l'agent, jusqu'aux appels d'outils individuels et aux interactions avec le LLM.

Nettoyer les ressources

Les données de suivi sont stockées dans Application Insights et suivent les paramètres de rétention des données de votre espace de travail. Ce guide de démarrage rapide ne crée aucune ressource supplémentaire. Pour nettoyer les ressources créées lors du guide de démarrage rapide précédent, exécutez azd down à partir du répertoire de votre projet d’agent. Ce que la commande supprime dépend du fait que l’initialisation a créé ou réutilisé le projet Foundry.

Warning

Si l’environnement actuel azd a créé le projet Foundry, azd down supprime définitivement le groupe de ressources du projet et tout ce qu’il contient. Si vous avez sélectionné un projet existant lors de l’initialisation, azd down conserve le projet, son groupe de ressources, l’agent hébergé et les autres ressources du guide de démarrage rapide. Pour supprimer les ressources dont vous n’avez plus besoin à partir du projet existant, supprimez-les séparément.

Résolution des problèmes

Problème Solution
Ne pas utiliser les agents hébergés par Foundry et les traces ne s’affichent pas Ce guide de démarrage rapide couvre uniquement les agents hébergés. Pour les agents de suivi hébergés en dehors de Foundry, consultez Inscrire un agent externe.
Aucune trace n’apparaît après l’appel de l’agent Vérifiez que Application Insights est connecté à votre projet Foundry. S'il n'est pas activé, consultez Configurer le suivi dans Microsoft Foundry. Vérifiez que l’agent a répondu avec succès avec azd ai agent invoke.
Les traces s’affichent, mais les spans n’ont pas les attributs de données d’entrée/sortie. Activez l’enregistrement de contenu en définissant la variable OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true d’environnement dans votre configuration de l’agent.
AuthorizationFailed lors de l’affichage des traces Vous avez besoin du rôle Lecteur Log Analytics sur la ressource Application Insights. Si les tables sont protégées, attribuez également un lecteur de données de surveillance privilégié.
Les traces apparaissent, mais les segments d'appel d'outil sont absents Vérifiez que votre agent définit des outils et que le modèle les appelle pendant la demande. Si vous utilisez Microsoft Agent Framework, vérifiez que les outils sont inscrits auprès du Agent constructeur via le tools paramètre. Consultez Ajouter des outils à votre agent.
AuthenticationError ou DefaultAzureCredential échec Actualisez les informations d’identification avec azd auth logout , puis azd auth login.

Ce que vous avez appris

Dans ce guide de démarrage rapide, vous :

  • Nous avons appris que les bibliothèques d’hébergement intègrent la distribution OpenTelemetry de Microsoft pour une instrumentation prête à l’emploi.
  • Vous avez invoqué votre agent déployé afin de générer des données de trace.
  • Vous avez consulté des traces de bout en bout dans le portail Foundry.

Étapes suivantes

Configurer le traçage dans Microsoft Foundry

Contenu connexe

  • Dernière mise à jour :