AgentOps : surveiller et gouverner les agents d’IA avec IBM Telemetry à l’aide de watsonx Orchestrate

Alors que les agents d’IA deviennent plus sophistiqués et autonomes, il est essentiel de comprendre leur comportement, leurs performances et leurs processus décisionnels afin de garantir leur fiabilité et leur gouvernance. AgentOps, la pratique qui consiste à surveiller, observer et gérer les agents d’IA en production, fournit la visibilité nécessaire pour créer des systèmes d’IA agentiques dignes de confiance.

Ce tutoriel propose un guide détaillé expliquant comment configurer et utiliser IBM Telemetry avec watsonx Orchestrate Developer Edition afin de surveiller et de gouverner les agents d’IA. Vous apprendrez à activer l’observabilité des agents d’IA et à analyser leur comportement en profondeur, depuis les différents appels de LLM jusqu’aux workflows complets à plusieurs étapes.

À l’issue de ce tutoriel, vous saurez comment :

• installer et configurer localement watsonx Developer Edition ;
• activer IBM Telemetry afin de bénéficier d’une observabilité complète des agents ;
• importer et tester un agent d’IA préconfiguré intégrant un outil externe ;
• analyser le comportement des agents à l’aide de traces, de tâches, de segments et de workflows détaillés ;
• déboguer les problèmes et optimiser les performances des agents grâce à des analyses avancées.

IBM Telemetry est le cadre d’observabilité natif de watsonx Orchestrate. Il recueille des informations détaillées sur la manière dont vos agents d’IA exécutent les requêtes. Il enregistre chaque étape du cycle de vie de l’agent, depuis les décisions de routage et la création des prompts jusqu’aux invocations de LLM et aux appels d’outils, ce qui offre une visibilité complète sur le comportement de l’agent.

IBM Telemetry vous permet de suivre les indicateurs de performances, de surveiller le coût des LLM, d’identifier les erreurs et de vérifier que vos agents fonctionnent comme prévu. IBM Telemetry fournit une observabilité adaptée aux entreprises, conçue pour les environnements de production et les systèmes d’IA à grande échelle.

Avant de commencer, vérifiez que les prérequis suivants sont installés et configurés sur votre système :

• Python 3.8 ou version ultérieure (vérifiez la version à l’aide de python --version)
• 16 Go de RAM au minimum
• watsonx Orchestrate Developer Edition par l’intermédiaire de l’ADK watsonx Orchestrate

Ce guide comprend les étapes d’installation de l’ADK.

• Un compte watsonx Orchestrate (un essai gratuit de 30 jours est disponible si vous ne possédez pas encore de compte)
• Une clé d’API watsonx Orchestrate générée depuis votre tableau de bord IBM Cloud

Les étapes d’autorisation sont présentées plus loin dans ce guide.

Pour commencer, clonez le dépôt GitHub en utilisant https://github.com/IBM/ibmdotcom-tutorials.git comme URL HTTPS. Pour obtenir des instructions détaillées sur le clonage d’un dépôt, consultez la documentation GitHub.

Ouvrez le référentiel dans l’environnement de développement intégré de votre choix (par exemple Visual Studio Code), puis localisez le dossier de projet de ce tutoriel : wxo-agentops. Vous travaillerez dans ce répertoire tout au long du tutoriel.

L’Agent Development Kit (ADK) d’IBM watsonx Orchestrate est un outil d’interface de ligne de commande qui simplifie l’installation, la configuration et la gestion de watsonx Orchestrate Developer Edition.

Pour utiliser l’ADK, vous devez le connecter à un environnement watsonx Orchestrate existant. Si vous ne possédez pas encore de compte watsonx Orchestrate, vous pouvez vous inscrire à un essai gratuit de 30 jours. Si vous disposez déjà d’un compte, vous pouvez l’utiliser pour fournir les identifiants d’environnement nécessaires à l’ADK.

Les étapes suivantes vous guideront tout au long de l’installation à l’aide d’un environnement virtuel Python, l’approche recommandée pour isoler les dépendances. Pour découvrir d’autres méthodes d’installation et obtenir des instructions détaillées, consultez la documentation de prise en main de l’ADK.

Créez un environnement virtuel Python dans le répertoire de votre projet :

Cette étape crée un dossier .venv contenant un environnement Python isolé.

La commande d’activation varie en fonction de votre système d’exploitation.

macOS et Linux

Windows

Une fois l’environnement activé, l’invite de votre terminal doit changer afin d’indiquer que vous travaillez dans l’environnement virtuel. Affiche généralement (.venv) au début de l’invite.

Une fois l’environnement virtuel activé, installez l’ADK à l’aide de pip :

Cette commande télécharge et installe l’ADK ainsi que toutes ses dépendances. L’installation peut prendre quelques minutes.

Remarque : si une version antérieure de l’ADK est installée (>2.0), exécutez pip install --upgrade ibm-watsonx-orchestrate. Vous devrez peut-être également suivre les étapes de résolution des problèmes décrites à l’étape 4b.

L’ADK utilise un fichier .env pour authentifier vos identifiants utilisateur et configurer watsonx Orchestrate Developer Edition. Les variables d’environnement nécessaires dépendent de la méthode d’authentification choisie. Ce tutoriel utilise la méthode de compte watsonx Orchestrate, qui constitue l’approche la plus simple pour commencer.

Pour découvrir d’autres méthodes d’authentification et obtenir des instructions de configuration détaillées, consultez la documentation relative à la configuration du fichier d’environnement.

Dans le répertoire wxo-agentops, créez un fichier .env en copiant le modèle fourni :

Ouvrez le fichier .env dans votre éditeur de texte et configurez les deux champs essentiels suivants :

• WO_INSTANCE : cette URL correspond à votre instance watsonx Orchestrate. Vous pouvez trouver cette information en vous connectant à votre compte watsonx Orchestrate et en accédant aux détails de votre instance. Cliquez sur l’icône de votre profil > Settings (Paramètres), puis sélectionnez l’onglet API details (Détails de l’API). Pour obtenir des instructions détaillées sur la prise en main de l’API, consultez la documentation watsonx Orchestrate.

L’URL respecte le format suivant :

Copiez et collez l’URL de votre instance de service afin de remplacer la valeur du modèle dans votre fichier .env. La région (par exemple us-south) dépend de votre emplacement géographique.

• WO_API_KEY : cette clé correspond à la clé d’interface de programmation d’application (API) de watsonx Orchestrate. Elle authentifie votre connexion aux services IBM Cloud. Vous pouvez générer ou récupérer cette clé depuis le tableau de bord de votre compte IBM Cloud. Remplacez <your-api-key> par votre clé d’API réelle. Pour obtenir des instructions détaillées sur la création d’une clé d’API, consultez la documentation de prise en main.

Conservez votre clé d’API en lieu sûr et ne la validez jamais dans un système de gestion de versions. Le fichier .env doit déjà être inclus dans votre fichier .gitignore afin d’éviter toute exposition accidentelle. 

Vous êtes maintenant prêt à installer watsonx Orchestrate Developer Edition, qui exécutera une instance locale du serveur watsonx Orchestrate sur votre machine. Cette étape active également IBM Telemetry, ce qui vous donne immédiatement accès aux fonctionnalités d’observabilité.

Comprendre la commande d’installation

L’ADK fournit une seule commande qui prend en charge l’intégralité du processus d’installation :

Examinons en détail les opérations effectuées par cette commande :

• orchestrate server start : initialise et démarre le serveur watsonx Orchestrate Developer Edition.
• -e <path-.env-file> : pointe vers le fichier de configuration contenant vos identifiants.
• --with-ibm-telemetry : active le cadre d’observabilité natif IBM Telemetry.

Exécutez la commande depuis le répertoire wxo-agentops :

La commande suivante démarre le serveur watsonx Orchestrate Developer Edition en initialisant l’environnement du serveur : orchestrate server start -e <path-.env-file>. L’ajout de l’option --with-ibm-telemetry active IBM Telemetry, son cadre d’observabilité natif.

Exécutez la commande suivante pour installer le serveur watsonx Orchestrate avec IBM Telemetry :

Cette commande crée des conteneurs internes gérés par l’ADK pour les éléments suivants :

• Le serveur watsonx Orchestrate
• Les bases de données PostgreSQL et Redis
• Les services IBM Telemetry
• Les dépendances connexes

L’ADK configure automatiquement un réseau virtuel qui permet à ces conteneurs de communiquer entre eux sur http://localhost:3000.

Le processus d’installation peut prendre plusieurs minutes, en particulier lors de la première exécution, car les images nécessaires doivent être téléchargées. Une installation réussie produit une sortie semblable à l’exemple suivant :

Si ce message s’affiche, félicitations ! Votre environnement watsonx Orchestrate local avec IBM Telemetry est maintenant en cours d’exécution.

Si l’installation échoue ou se bloque, essayez les étapes suivantes :

1.    Réinitialisez le serveur :

Cette commande arrête et supprime tous les conteneurs créés pour watsonx Orchestrate, ce qui vous permet de repartir sur une base propre.

2.    Relancez l’installation :

Après la réinitialisation, exécutez de nouveau la commande de démarrage :

3.    Vérifiez les journaux du serveur et l’état des conteneurs :

Vous pouvez afficher les journaux de service du serveur Orchestrate afin de rechercher d’éventuels avertissements ou erreurs :

Si les étapes précédentes ne fonctionnent pas, réinitialisez le serveur et supprimez entièrement son environnement à l’aide de la commande orchestrate server purge, puis recommencez l’installation.

Une fois le serveur watsonx Orchestrate correctement installé, vous devez activer votre environnement local et lancer l’interface de chat dans laquelle vous interagirez avec vos agents d’IA.

L’ADK watsonx Orchestrate prend en charge plusieurs environnements (par exemple des environnements locaux, de développement ou de production). Vous devez activer explicitement l’environnement local que vous avez créé :

Un message doit confirmer que l’environnement est actif :

L’environnement local devient ainsi le contexte par défaut de toutes les commandes ADK suivantes. Les agents, les outils et les configurations que vous utiliserez cibleront désormais cette instance locale.

Démarrez le service de l’interface de chat watsonx Orchestrate à l’aide de la commande suivante :

Cette commande initialise l’interface de chat Web et l’ouvre automatiquement dans votre navigateur par défaut. Une sortie semblable à la suivante doit s’afficher :

L’interface de chat permet d’interagir facilement avec vos agents d’IA. Si le navigateur ne s’ouvre pas automatiquement, vous pouvez accéder manuellement à l’adresse suivante : http://localhost:3000/chat-lite.

Une fois l’interface de chat chargée, une fenêtre de conversation épurée et prête à être utilisée doit s’afficher. À cette étape, vous n’avez encore importé aucun agent. L’interface sera donc essentiellement vide. Ce résultat est normal : vous ajouterez votre premier agent à l’étape suivante.

Maintenant que votre environnement est configuré, vous pouvez importer un agent d’IA préconfiguré illustrant les fonctionnalités de surveillance d’IBM Telemetry. Cet agent météo utilise un outil d’API externe afin de récupérer des données météorologiques en temps réel. Il fournit ainsi un exemple pratique que vous pourrez observer et analyser.

L’agent météo constitue un excellent point de départ pour les raisons suivantes :

• Démonstration de l’utilisation des outils : il montre comment les agents appellent des API externes.
• Comportement clair et observable : chaque requête suit une structure prévisible.
• Génération de données de télémétrie pertinentes : il produit des traces riches que vous pouvez analyser dans IBM Telemetry.
• Présence de scénarios d’erreur : il vous aide à comprendre comment la télémétrie traite les échecs.
• Illustration de l’automatisation : les actions de l’agent évitent la recherche manuelle des données.

À partir de la racine de votre projet (wxo-agentops), accédez au dossier Weather Agent :

Ce répertoire contient deux fichiers de configuration YAML :

• get_weather.yaml : définit l’outil d’API météo.
• weather_agent.yaml : définit l’agent qui utilise cet outil.

Les outils sont des fonctionnalités réutilisables que les agents peuvent invoquer pour effectuer des actions précises. Commencez par importer les outils get_weather :

L’option --kind openapi indique que cet outil utilise une spécification OpenAPI pour définir son interface. Un message doit confirmer que l’outil a bien été importé.

Importez maintenant l’agent qui utilisera cet outil :

Cette commande enregistre le Weather Agent dans votre environnement watsonx Orchestrate local. L’agent est préconfiguré avec les éléments suivants :

• des instructions indiquant comment interpréter les données météorologiques ;
• Autorisation d’appeler l’outil get_weather
• un comportement de secours pour les lieux non valides.

Revenez dans le navigateur où l’interface de chat est ouverte. Vous devrez peut-être actualiser la page pour afficher l’agent que vous venez d’importer.

Cliquez sur le menu déroulant des agents (généralement situé en haut de l’interface de chat), puis sélectionnez Weather_Agent dans la liste.

Une fois Weather Agent sélectionné, posez-lui quelques questions afin de générer des données de télémétrie.

Exemples de requêtes :

• « Quel temps fait-il à New York ? »
• « Peux-tu me donner la température actuelle à Londres ? »
• « Quel temps fait-il à Tokyo ? »
• « Pleut-il actuellement à Seattle ? »

L’agent traite chaque requête en effectuant les opérations suivantes :

1. Compréhension de votre requête
2. Extraction du lieu
3. Appel de l’outil get_weather avec les coordonnées appropriées
4. Interprétation des données météorologiques
5. Réponse en langage naturel

Toutes vos interactions avec Weather Agent sont enregistrées par IBM Telemetry. Le système enregistre les éléments suivants :

• Le contexte complet de la conversation
• Chaque invocation du LLM et les tokens utilisés
• Les appels d’outils, avec leurs entrées et leurs sorties
• Les décisions de routage et les étapes du workflow
• Les temps d’exécution et les indicateurs de performances
• Les éventuelles erreurs ou exceptions
• Les interactions avec les fournisseurs externes et leurs temps de réponse

À l’étape suivante, vous examinerez ces données de télémétrie en détail afin de comprendre précisément le comportement de votre agent.

Nous arrivons maintenant à la partie la plus puissante de ce tutoriel : l’utilisation d’IBM Telemetry afin de bénéficier d’une visibilité approfondie sur le comportement de votre agent. IBM Telemetry fournit plusieurs vues et outils d’analyse qui vous permettent de comprendre chaque aspect du traitement des requêtes par votre agent.

Ouvrez votre navigateur et accédez à https://localhost:8765/?serviceName=wxo-server. L’interface fournit des relectures de session qui permettent de revenir sur les interactions passées des agents afin de les analyser.

Remarque : l’URL utilise https, mais comme cet espace est un environnement de développement local, votre navigateur peut afficher un avertissement de sécurité concernant un certificat autosigné. Ce message est normal et vous pouvez continuer en toute sécurité dans votre environnement local.

Lorsque l’écran de connexion s’affiche, saisissez le nom de votre choix (afin d’identifier votre session locale), puis cliquez sur Login (Se connecter).

Le tableau de bord principal d’IBM Telemetry s’affiche.

Le tableau de bord présente une liste des traces récentes, chacune correspondant à une interaction unique entre un utilisateur et un agent. Cliquez sur la première trace du panneau Trace and Group Selection (Sélection des traces et des groupes) afin d’afficher les analyses détaillées de votre conversation la plus récente avec Weather Agent.

Vous accédez alors à l’écran Agent Analytics, qui constitue le centre principal d’analyse du comportement des agents.

L’écran Agent Analytics fournit une vue d’ensemble de la trace sélectionnée, notamment les informations suivantes :

• Statistiques récapitulatives : temps d’exécution total, utilisation des tokens, estimation des coûts et données d’analyse comparative.
• Informations sur l’agent : agent ayant traité la requête.
• Requête de l’utilisateur : question initialement posée.
• Aperçu de la réponse : réponse finale de l’agent.
• Indicateurs d’état : réussite, avertissements ou erreurs.

Cette vue générale permet de déterminer immédiatement si l’agent a fonctionné comme prévu et avec quel niveau d’efficacité.

La section Tasks (Tâches) est celle dans laquelle vous passerez le plus de temps à analyser le comportement de l’agent. Elle fournit une chronologie visuelle et détaillée de toutes les opérations effectuées par l’agent au cours d’une requête (appels du LLM, invocations d’outils, décisions de routage et génération des sorties).

Les tâches sont organisées de manière hiérarchique afin de refléter l’exécution réelle du workflow par l’agent, ce qui facilite la compréhension de la séquence des opérations et de leurs relations.

Examinons le chemin d’exécution standard d’une requête d’agent watsonx Orchestrate. La trace de votre Weather Agent doit présenter une structure semblable à celle de l’exemple suivant :

Ce workflow représente l’intégralité du cycle de vie d’une requête utilisateur. Voici ce que représente chaque tâche :

• 0:_ROOT : segment de niveau supérieur contenant toutes les tâches enfant. Vous pouvez le considérer comme le dossier qui contient l’intégralité de l’exécution de l’agent. Il définit l’heure de début et l’heure de fin de la trace complète, depuis l’entrée de la requête dans le système jusqu’à la transmission de la réponse finale.

Cet élément est important, car la durée de la tâche racine correspond à la latence totale subie par l’utilisateur. Si cette valeur est trop élevée, vous pouvez analyser ses tâches enfant afin d’identifier les goulets d’étranglement.

• 0.0:agent_style_router : la tâche de routage détermine l’agent qui doit traiter le message et classe la requête en fonction du mode de traitement nécessaire. Le routeur analyse la requête entrante et détermine si elle exige un traitement conversationnel, une exécution pilotée par des outils, une génération augmentée de récupération (RAG) ou une orchestration multi-agent.

Le routeur veille à invoquer la logique en aval appropriée. Si des requêtes sont incorrectement routées, vous pourrez identifier le problème à cette étape.

• 0.1:agent : contexte principal d’exécution de l’agent qui orchestre l’intégralité de la requête. Cette tâche assemble le prompt à partir des interactions système, de l’historique de la conversation et des réponses des outils. Elle applique les règles et les politiques d’orchestration, puis prépare les entrées destinées au LLM. Cette tâche détermine le type d’appel de LLM à effectuer.

C’est à cette étape qu’intervient l’« intelligence » de l’orchestration. La tâche de l’agent veille à fournir au LLM tout le contexte dont il a besoin pour prendre des décisions éclairées.

• 0.1.0:WatsonxChatModel.chat : appel effectif du LLM, qui reçoit le prompt complet et détermine s’il doit appeler un outil, demander des précisions ou produire directement une réponse. Il génère la réponse, sous forme de texte ou d’appels d’outils structurés.

Il s’agit de l’étape de « réflexion », pendant laquelle le modèle traite les informations et prend des décisions. L’utilisation des tokens, la latence et les problèmes de qualité proviennent tous de cette tâche. Si votre agent est lent ou coûteux, cette étape constitue généralement le principal facteur en cause.

• 0.2:answer : dernière étape de la chaîne, qui reçoit la sortie du LLM et la met en forme afin de pouvoir la transmettre. Cette tâche convertit la sortie brute du LLM au format de réponse final et applique les éventuelles règles de post-traitement ou de mise en forme. Elle transmet enfin la réponse à l’interface de chat.

Cette tâche garantit que l’utilisateur reçoit une réponse correctement mise en forme. Si les réponses sont tronquées ou incorrectement formatées, c’est cette étape qu’il convient d’examiner.

Récapitulatif du workflow des tâches

Pour résumer l’intégralité du workflow :

1. Le routeur détermine comment traiter la requête.
2. L’agent prépare le contexte et la logique d’orchestration.
3. Le LLM génère la réponse ou les appels d’outils.
4. La tâche de réponse met en forme et renvoie la sortie finale.

L’ensemble de ce workflow est encapsulé dans le conteneur de requête ROOT, ce qui vous donne une vue complète de l’exécution de l’agent, du début à la fin. Ce niveau d’observabilité est essentiel pour les équipes MLOps et DevOps qui gèrent les opérations des agents et des pipelines complexes à grande échelle.

Chaque tâche de la hiérarchie contient trois catégories d’attributs qui fournissent des métadonnées détaillées concernant les éléments qu’elle a reçus et produits :

1.    Attributs d’entrée : ils indiquent tout ce que la tâche a reçu avant son exécution, notamment les messages, les réponses des outils, les instructions système et l’état interne.

Exemple : pour la tâche WatsonxChatModel.chat, les attributs d’entrée comprendraient le prompt intégralement assemblé, avec les instructions système, l’historique de la conversation et les éventuels résultats d’outils devant être interprétés.

2.    Attributs de sortie : ils indiquent ce que la tâche a produit, notamment les réponses générées par le LLM, les appels d’outils et les décisions.

Exemple : cette même tâche WatsonxChatModel.chat pourrait produire soit une réponse en langage naturel, soit un appel d’outil structuré tel que get_weather(latitude=40, longitude=-74).

3.    Attributs généraux : ils fournissent des métadonnées de télémétrie, notamment l’utilisation des tokens, les informations temporelles, les identifiants uniques et les informations sur le modèle.

Exemple : vous pourriez constater qu’une tâche a utilisé 450 tokens en entrée et 120 tokens en sortie, qu’elle a pris 1,2 seconde à s’exécuter et qu’elle a utilisé le ibm/granite-3.1-8b-instruct model.

Comment utiliser les attributs des tâches

Ensemble, ces attributs vous permettent de comprendre précisément les informations reçues par le modèle, la décision qu’il a prise et la manière dont il a répondu.

Ce niveau de détail est extrêmement précieux pour le débogage, l’optimisation et la validation.

Chaque tâche comprend des indicateurs relatifs aux performances et aux coûts qui résument les conditions de son exécution. Ces indicateurs fournissent des données quantitatives sur les performances de l’agent.

Les principaux indicateurs sont les suivants :

• Temps d’exécution total : temps nécessaire pour exécuter la tâche du début à la fin.
• Nombre d’appels du LLM : nombre d’invocations du modèle de langage.
• Nombre d’appels d’outils : nombre d’appels d’outils externes.
• Utilisation des tokens : tokens d’entrée, tokens de sortie et nombre total de tokens consommés.
• Estimation des coûts : coûts approximatifs calculés en fonction de l’utilisation des tokens, (lorsque les données tarifaires sont disponibles).
• Répartition des sous-tâches : manière dont le travail a été réparti entre les tâches enfant.

Ces indicateurs vous aident à optimiser les performances et à déboguer le comportement de l’agent. Ils peuvent également faciliter l’identification des tâches lentes susceptibles d’être exécutées en parallèle ou mises en cache. Cette vue est indispensable à la planification des capacités, car elle permet de comprendre les ressources nécessaires à la mise à l’échelle et de suivre l’utilisation des tokens afin de maîtriser les dépenses.

Par exemple, si une trace a nécessité 8 secondes, mais que seulement 0,5 seconde a été consacrée aux appels de LLM, vous savez que le goulet d’étranglement se situe ailleurs (probablement dans l’exécution d’un outil ou dans la latence du réseau).

Alors que les tâches présentent le workflow logique de votre agent, les segments représentent les opérations sous-jacentes effectuées au niveau du système pendant l’exécution. Cliquez sur l’onglet Spans (Segments) pour afficher les opérations effectuées en interne par la plateforme afin de traiter chaque requête.

Les segments fournissent une visibilité sur les étapes d’exécution de bas niveau enregistrées par le framework d’orchestration (en l’occurrence LangGraph, un cadre open source exécuté dans wxo-server). Chaque segment représente une opération distincte, par exemple :

• Routage de la requête vers l’agent approprié (agent_style_router)
• Invocation de l’agent et initialisation de son contexte (agent.task)
• Création des prompts et du contexte à partir de modèles (ChatPromptTemplate.task)
• Appel du LLM à l’aide du prompt assemblé (WatsonxChatModel.chat)
• Renvoi des résultats à l’utilisateur (answer.task)

Alors que les tâches représentent les étapes logiques de l’exécution de l’agent (ce que l’agent cherche à accomplir), les segments présentent les étapes techniques (la manière dont le système y parvient). Cette double vue vous offre à la fois une compréhension générale et des fonctions de débogage de bas niveau.

Exemple : une tâche unique telle que 0.1:agent peut contenir plusieurs segments représentant des requêtes de base de données, des recherches dans le cache et le chargement de configurations. Ces opérations ont lieu en arrière-plan afin de permettre l’exécution de l’agent.

Chaque segment comprend des balises qui fournissent des métadonnées et un contexte supplémentaires. Ces balises sont essentielles pour filtrer, déboguer et analyser les performances des agents.

Les balises de segment courantes comprennent les éléments suivants :

• Identification de l’agent : agent_id, agent_name
• Suivi de la session : thread_id, session_id, conversation_id
• Contexte du workflow : step_number, workflow_path, parent_span_id
• Données de performances : token_count, duration_ms, model_name
• Détails de la requête : tool_calls, input_preview, output_preview

Les segments permettent de repérer les causes de latence, de comprendre les échecs en identifiant le composant interne concerné, d’analyser les tendances en filtrant les segments par balise et d’établir des correspondances entre les segments de plusieurs traces au moyen des ID de session.

Par exemple, si votre agent cesse occasionnellement de répondre, vous pouvez filtrer les segments en fonction de leur durée afin d’identifier les opérations internes qui prennent anormalement longtemps, par exemple une requête de base de données ou un appel réseau vers un service externe.

L’onglet Workflows fournit une visualisation hiérarchique appelée Runnables Tree (Arborescence des éléments exécutables), qui présente la structure d’exécution complète du workflow de votre agent. Cette vue est particulièrement utile pour comprendre les systèmes multi-agents complexes et les modèles d’exécution imbriqués.

Dans le framework watsonx Orchestrate, un élément exécutable est une unité de travail ou une tâche pouvant être exécutée. Les éléments exécutables peuvent prendre les formes suivantes :

• Opérations simples : un seul appel de LLM ou une seule invocation d’outil.
• Workflows composites : plusieurs éléments exécutables reliés les uns aux autres.
• Branches conditionnelles : différents chemins d’exécution sélectionnés en fonction de conditions.
• Exécutions parallèles : plusieurs éléments exécutables exécutés simultanément.

L’Arborescence des éléments exécutables présente les relations parent-enfant, ce qui permet d’identifier facilement les éléments suivants :

• Tâches qui en déclenchent d’autres : suivi de la chaîne d’exécution.
• Exécution parallèle ou séquentielle : compréhension de la simultanéité au sein du workflow.
• Logique de ramification : manière dont les décisions conduisent à différents chemins d’exécution.
• Profondeur du workflow : niveau d’imbrication de la logique de votre agent.

Pour les agents simples comme Weather Agent, la vue du workflow ressemble étroitement à celle des tâches. Les workflows deviennent cependant extrêmement précieux lorsque vous travaillez avec les éléments suivants :

• Systèmes multi-agents : plusieurs agents spécialisés collaborant sur une même tâche.
• Orchestration complexe : agents choisissant dynamiquement entre différents outils ou sous-agents.
• Amélioration itérative : agents répétant différentes étapes jusqu’à ce qu’une condition soit satisfaite.
• Routage conditionnel : workflows qui créent des branches en fonction de résultats intermédiaires.
• Architectures évolutives : conception de workflows capables de traiter efficacement des charges réelles.

Imaginez, par exemple, un agent qui commence par déterminer si une requête nécessite une recherche Web, choisit ensuite entre un outil de calcul et un outil d’interrogation de base de données, puis valide le résultat avant de répondre. L’Arborescence des éléments exécutables présenterait clairement l’intégralité de cette structure à plusieurs branches.

Vous pouvez interagir avec l’arborescence de différentes façons :

• Développer ou réduire les nœuds : concentrez-vous sur des sections précises du workflow.
• Cliquer sur les nœuds : accédez directement aux informations détaillées sur les tâches.
• Suivre les chemins d’exécution : suivez le flux des données dans la fenêtre.
• Identifier les goulets d’étranglement : repérez les endroits où les workflows perdent en efficacité.

Cette visualisation facilite considérablement le débogage des workflows par rapport à l’analyse de simples journaux textuels ou données de trace.

L’onglet Eval (évaluation) fournit une vue de contrôle qualité et de surveillance qui mesure l’exactitude et la fiabilité de l’exécution de votre agent. À cette étape, vous ne vous contentez plus d’observer ce qui s’est produit : vous évaluez la qualité de l’exécution.

L’onglet Eval présente des résultats d’évaluation qui mesurent la qualité à l’aide de garde-fous :

• Réussite des tâches : tâches terminées et tâches ayant échoué.
• Qualité des sorties : conformité des sorties avec les résultats attendus ou les critères de qualité.
• Scores de performances : indicateurs quantitatifs représentant les niveaux de réussite.
• Analyse des erreurs : catégorisation et gravité des échecs.
• Validation des cas d’utilisation : conformité du comportement de l’agent avec les cas d’utilisation prévus.

Les évaluations vous aident à surveiller la fiabilité en suivant la régularité avec laquelle votre agent produit des résultats corrects, à détecter les modifications qui dégradent ses performances, à hiérarchiser les améliorations et à renforcer la confiance en vérifiant que les agents fonctionnent correctement avant leur déploiement en production.

Vous pouvez utiliser les mesures d’évaluation pour configurer des alertes, suivre les améliorations, identifier des tendances et exploiter les commentaires afin d’orienter le développement et d’améliorer les prompts ou les outils.

Si vous constatez, par exemple, que 15 % des requêtes météorologiques échouent à l’évaluation, vous pouvez examiner les traces correspondantes afin de déterminer si le problème provient d’une mauvaise gestion des entrées, d’échecs de l’API ou d’une mise en forme incorrecte des réponses.

L’onglet Issues (Problèmes) fournit une vue centralisée de tous les problèmes survenus pendant l’exécution du workflow. Cet onglet constitue le premier endroit à consulter lorsque vous déboguez des échecs ou un comportement inattendu de l’agent.

L’onglet Issues (Problèmes) répertorie notamment les problèmes suivants :

• Échecs des appels d’API : services externes ayant renvoyé des erreurs.
• Échecs d’exécution des outils : outils ayant cessé de fonctionner ou dépassé le délai imparti.
• Entrées manquantes : données obligatoires indisponibles au moment où elles étaient nécessaires.
• Exceptions du modèle : erreurs du LLM telles que le dépassement de la limite de tokens ou la présence d’entrées non valides.
• Erreurs de validation : données ne respectant pas les formats attendus.
• Erreurs de délai d’attente : opérations ayant dépassé les limites de temps.
• Échecs d’exécution non gérés : exceptions inattendues dans le code de l’agent.

Dans la capture d’écran précédente, une erreur Tool Error s’est produite lorsque l’API météo a renvoyé une erreur 424 (Failed Dependency, échec de dépendance) ou 404 (Not Found, ressource introuvable). L’onglet Issues (Problèmes) affiche les éléments suivants :

1. Type d’erreur : « Tool Error » (Erreur d’outil).
2. Outil concerné : get_weather
3. Réponse d’erreur : réponse complète de l’API présentant l’échec.
4. Lien direct : cliquez dessus pour accéder à la tâche précise au cours de laquelle l’échec s’est produit.

Cette approche permet de comprendre facilement ce qui s’est mal passé sans devoir examiner les journaux ou les données de trace.

L’onglet Issues (Problèmes) est particulièrement utile, car il regroupe les échecs au lieu de vous obliger à les rechercher dans chaque tâche. Il fournit le contexte complet, notamment les détails des erreurs et les données associées, tandis que les niveaux de gravité permettent d’effectuer rapidement un tri afin de traiter en priorité les problèmes les plus importants. Grâce aux liens directs vers les tâches sources, un seul clic vous conduit au point d’exécution précis où le problème s’est produit.

L’onglet Trajectory (Trajectoire) fournit une vue chronologique, présentée sous la forme d’une conversation, de l’interaction entre l’utilisateur, l’agent et les éventuels outils invoqués par celui-ci. Cette vue est extrêmement précieuse pour comprendre l’intégralité du contexte et le déroulement du comportement de l’agent.

La vue Trajectory (Trajectoire) vous permet d’observer précisément comment l’agent traite les requêtes du début à la fin, ce qui vous offre une visibilité complète sur son comportement. Vous pouvez valider l’intégration des outils en vérifiant qu’ils sont appelés avec les paramètres appropriés et reçoivent les réponses attendues. Lorsque vous déboguez des réponses inattendues, la trajectoire vous aide à repérer l’étape à laquelle la logique s’est écartée de vos attentes. Vous pouvez également analyser la manière dont le contexte se développe au cours de plusieurs tours de conversation et observer l’évolution naturelle du workflow. Au-delà du débogage, la trajectoire sert de documentation : elle permet de recueillir des exemples de comportements corrects pouvant être communiqués aux membres de l’équipe ou utilisés comme cas de référence lors de développements ultérieurs. Cette vue est particulièrement utile pour les équipes qui créent des solutions reposant sur l’IA générative et doivent vérifier la capacité d’adaptation des agents à différents scénarios.

Examinons la trajectoire de Weather Agent présentée dans la capture d’écran :

1.    Requête de l’utilisateur

La conversation commence par une demande claire et précise concernant la météo à New York.

2.    Appel d’un outil par l’agent

L’agent comprend qu’il a besoin de données externes et invoque l’outil météo :

Cet exemple montre que l’agent a correctement déterminé les coordonnées approximatives de New York, structuré la requête adressée à l’API et défini l’indicateur approprié pour obtenir les conditions météorologiques actuelles.

IBM Telemetry affiche le résultat à la fois sous forme de données JSON brutes et dans une arborescence analysée, facile à lire et à développer.

3.    Renvoi des données par l’outil

L’API météo renvoie des données météorologiques structurées :

Cet exemple montre que l’outil a correctement récupéré les données, que la réponse respecte le schéma attendu et que tous les champs obligatoires sont présents. La possibilité d’examiner la réponse brute de l’outil est essentielle pour déboguer les problèmes dans lesquels l’agent interprète incorrectement les sorties d’un outil.

4.    Récapitulatif du résultat par l’agent

Enfin, l’agent traite les données structurées et répond en langage naturel :

L’agent a correctement extrait la température et le code météorologique, puis converti les données structurées en langage naturel. La réponse est concise et répond à la question de l’utilisateur.

L’onglet Trajectory (Trajectoire) permet également de filtrer les données par rôle afin d’afficher uniquement les messages des utilisateurs, les messages de l’agent ou les interactions avec les outils. Vous pouvez également développer et réduire certaines parties des conversations longues afin de vous concentrer sur les détails qui vous intéressent. Pour effectuer des analyses ou un débogage supplémentaires, vous pouvez exporter les données au format JSON ou accéder aux tâches liées depuis les différentes étapes de la trajectoire afin d’en afficher les détails correspondants.

Félicitations ! Vous avez correctement configuré IBM Telemetry avec watsonx Orchestrate et appris à surveiller et à analyser en profondeur le comportement des agents d’IA. IBM Telemetry fournit plusieurs niveaux de visibilité afin de vous offrir une observabilité complète sur la manière dont vos agents d’IA réfléchissent, prennent des décisions et agissent. Les fonctionnalités que vous avez explorées sont essentielles pour gérer efficacement le cycle de vie des opérations des agents en production ou pour intégrer d’autres frameworks d’agents dans votre environnement.

Si vous rencontrez des difficultés ou avez des questions, consultez la documentation. La plupart des problèmes courants sont abordés dans le guide de dépannage. Vous pouvez également consulter les problèmes signalés sur GitHub afin de déterminer si d’autres personnes ont rencontré des difficultés similaires.

La surveillance des agents au moyen de plateformes comme IBM Telemetry a permis de créer un solide écosystème pour AgentOps. Cette pratique devient essentielle à mesure que les agents autonomes prennent en charge des tâches plus complexes nécessitant l’intégration de SDK, d’outils et d’API externes. La visibilité que vous avez acquise sur le comportement des agents vous permet de créer des systèmes d’IA plus fiables, plus efficaces et plus dignes de confiance.