Alors que le nombre d’agents d’IA créés augmente chaque jour, les entreprises explorent des systèmes autonomes afin de soutenir la prise de décision et les workflows opérationnels. Parallèlement, les entreprises expriment souvent des préoccupations concernant l’explicabilité, la gouvernance et l’état de préparation à la production, en particulier dans les systèmes multi-agents qui s’appuient sur de grands modèles de langage (LLM) pour raisonner. Il est difficile d’utiliser des agents qui fournissent des réponses sans explication claire ou dont le comportement manque de cohérence dans un contexte professionnel.
Ces difficultés peuvent être résolues à l’aide d’IBM watsonx Orchestrate, qui fournit une plateforme structurée prenant en charge l’auto-hébergement, le raisonnement fondé sur des outils, les appels d’API et des contrôles adaptés aux entreprises, sans nécessiter de code d’orchestration personnalisé.
Dynamiq a créé pour un important client du secteur de l’assurance un assistant multi-agent de recherche juridique qui achemine les requêtes vers un classificateur IBM Granite peu coûteux avant de les transmettre, si nécessaire, à un agent de recherche plus complexe. Pour rendre viable ce workflow à fort enjeu, il était nécessaire de bénéficier d’une visibilité approfondie sur chaque étape de raisonnement et chaque appel d’outil. Grâce à l’intégration d’IBM watsonx Orchestrate, Dynamiq a veillé à ce que chaque décision reste entièrement traçable, vérifiable et accompagnée de citations. L’entreprise a ainsi réduit la durée d’examen des contrats de 90 à 45 minutes sans compromettre la gouvernance.
Dans ce tutoriel, vous apprendrez à créer un agent d’IA dans watsonx Orchestrate à l’aide de l’Agent Development Kit (ADK) de watsonx Orchestrate. Dans les systèmes d’IA reposant sur LangChain ou LangGraph, les développeurs doivent fréquemment gérer manuellement les nouvelles tentatives, la gestion des états et l’exécution asynchrone. L’ADK watsonx Orchestrate simplifie ce processus grâce à une gestion intégrée du cycle de vie, qui permet de déployer des agents cohérents et adaptés aux entreprises.
Vous utiliserez Python afin de créer la logique d’évaluation des risques, de définir le comportement de l’agent et d’intégrer Langfuse pour surveiller et améliorer ce comportement à l’aide de traces d’exécution réelles. Ce tutoriel est également disponible sur GitHub.
Langfuse est une plateforme open source d’observabilité des LLM reposant sur OpenTelemetry et destinée à surveiller les applications et les agents utilisant des LLM. Elle utilise la télémétrie (traces, indicateurs et journaux) pour surveiller les exécutions des agents, notamment les appels de LLM et d’outils, l’utilisation des tokens, les métadonnées et la latence, à l’échelle de chaque requête et de chaque session.
Elle permet aux développeurs de comprendre en profondeur les performances des agents dans des scénarios réels, de repérer les causes racines des résultats incorrects et d’optimiser systématiquement le comportement des agents afin d’améliorer leur fiabilité et leur efficacité.
L’objectif de ce tutoriel est de créer un agent d’IA destiné à la gouvernance d’entreprise, qui évalue les risques liés aux fournisseurs au moyen d’une analyse déterministe fondée sur des règles. Nous avons créé un jeu de données synthétiques contenant des fournisseurs, leurs évaluations financières, leurs certifications de sécurité et leur historique d’incidents. L’agent traite ces données et classe les fournisseurs selon différents niveaux de risque (faible, moyen ou élevé) tout en justifiant ses décisions.
Il prend également en charge les questions de suivi interactives, ce qui permet aux utilisateurs de comparer les fournisseurs ou de simuler l’effet qu’aurait la modification de certaines données sur le score de risque. Il garantit ainsi le niveau élevé d’auditabilité requis pour la conformité des entreprises.
Vous trouverez ci-dessous une démo interactive de l’agent d’évaluation des risques fournisseurs créé dans ce tutoriel. Découvrez comment l’agent classe les fournisseurs, répond aux questions et retrace son raisonnement dans Langfuse afin de comprendre clairement ce que vous allez créer avant de commencer.
Pour suivre ce tutoriel, vous avez besoin des éléments suivants :
Python 3.11 ou une version ultérieure installé sur votre système.
Un compte watsonx Orchestrate. Un compte d’essai suffit pour ce tutoriel. Si vous ne possédez pas de compte, vous pouvez utiliser IBM Cloud pour créer un essai gratuit de 30 jours.
Une clé d’API watsonx Orchestrate obtenue depuis l’interface utilisateur d’Orchestrate.
L’ADK watsonx Orchestrate installé sur votre système.
Connectez-vous à watsonx Orchestrate par l’intermédiaire d’IBM Cloud et ouvrez l’interface utilisateur de watsonx Orchestrate. Ouvrez les paramètres depuis le menu du profil, puis accédez aux détails de l’API. Créez une clé d’API, copiez-la et conservez-la en lieu sûr. Pendant le développement local, l’ADK watsonx Orchestrate est authentifié à l’aide de cette clé d’API. watsonx Orchestrate fonctionne comme un SDK local permettant de créer et de tester la logique des agents.
À cette étape, créez un environnement de développement local. Tout au long de ce tutoriel, vous exécuterez un serveur de développement local, importerez des outils, configurerez des environnements et créerez des agents à l’aide de l’interface de ligne de commande Orchestrate fournie par l’ADK dans PowerShell. Commencez par accéder au répertoire dans lequel vous souhaitez créer votre projet. Créez ensuite un environnement virtuel Python :
Un environnement Python isolé est créé dans un dossier .venv. L’utilisation d’un environnement virtuel garantit que toutes les dépendances de ce tutoriel restent séparées de l’installation Python globale de votre système.
Activez ensuite l’environnement virtuel. La commande d’activation à utiliser dépend de votre système d’exploitation.
Sous Windows :
Sous macOS et Linux :
Une fois l’environnement activé, l’invite de votre terminal affiche .venv au début afin d’indiquer que vous travaillez dans un environnement virtuel.
Une fois l’environnement virtuel actif, installez l’ADK watsonx Orchestrate sur votre machine locale. Pour utiliser l’ADK, connectez-le à votre environnement watsonx Orchestrate existant. Exécutez la commande suivante dans PowerShell :
Vous pouvez poursuivre l’installation de l’ADK en suivant les étapes présentées dans la documentation d’installation officielle.
Remarque : ce tutoriel exécute localement l’environnement d’exécution watsonx Orchestrate Developer Edition et le connecte à l’instance SaaS watsonx Orchestrate à l’aide des identifiants.
Pour utiliser cette méthode, créez un fichier appelé .env à la racine du dossier du projet et ajoutez-y les valeurs suivantes :
Ce fichier .env est nécessaire à l’exécution du serveur. Lors des étapes suivantes, vous le démarrerez à l’aide de la commande orchestrate server start -e .env -l.
Vous devez ensuite configurer l’ADK avec une clé d’API watsonx Orchestrate valide afin de connecter votre environnement local à watsonx Orchestrate.
Remarque : l’ADK watsonx Orchestrate est compatible avec plusieurs types d’environnements, notamment IBM Cloud, AWS et les déploiements sur site. Dans ce tutoriel, nous utilisons l’environnement sur site et nous nous authentifions à l’aide d’une clé d’API depuis l’interface de ligne de commande de l’ADK. L’ADK gère les identifiants de manière sécurisée en interne. Aucune configuration manuelle de variable d’environnement n’est donc nécessaire pour cette installation.
Depuis le répertoire de votre projet (avec l’environnement virtuel activé), exécutez la commande suivante afin d’ajouter votre environnement watsonx Orchestrate :
Ici, service-instance-url correspond à l’URL de votre instance watsonx Orchestrate. Vous pouvez trouver cette information dans l’onglet API details (Détails de l’API) de la section Settings (Paramètres) de l’interface utilisateur de watsonx Orchestrate.
Activez ensuite l’environnement que vous avez ajouté :
Lorsque vous y êtes invité, saisissez la clé watsonx Orchestrate obtenue à l’étape 1. Une fois l’environnement activé, toutes les commandes suivantes liées à l’ADK, par exemple l’importation d’agents et d’outils ou l’exécution du serveur, seront exécutées dans l’environnement watsonx Orchestrate.
Remarque : si vous souhaitez tout exécuter localement avec Developer Edition, vous pouvez activer l’environnement local par défaut à l’aide de la commande suivante :
Votre ADK bascule alors vers l’environnement Orchestrate local intégré, qui est utile pour les tests locaux.
À cette étape, vous allez créer le modèle de framework d’agent contenant la définition, les outils et le code source de votre Agent d’analyse des risques fournisseurs. Créez ensuite la structure de dossiers nécessaire au développement local reposant sur l’ADK :
Vous pouvez utiliser la commande fournie ici afin de créer la structure de l’agent :
Chaque dossier remplit une fonction précise :
Le dossier agents contient le fichier YAML qui définit les instructions, les règles de raisonnement et la configuration du modèle de l’agent. Il détermine la manière dont le système répond aux questions des utilisateurs. Le dossier tools contient un fichier YAML décrivant l’outil fourni à l’agent. Le dossier src contient l’implémentation Python des outils personnalisés et de la logique métier.
Démarrez le serveur watsonx Orchestrate afin qu’il puisse recevoir et stocker vos importations avant d’importer les outils et les agents. Exécutez cette commande depuis la racine du dossier du projet :
L’étape suivante porte sur l’observabilité de l’agent. Vous allez analyser son comportement pendant l’exécution, notamment les outils qu’il appelle, la latence et les endroits où des erreurs se produisent. À cette fin, activez l’observabilité Langfuse dans l’environnement de l’ADK watsonx Orchestrate.
Dans ce tutoriel, nous utilisons la version SaaS de Langfuse, qui permet de recueillir des traces sans avoir à exécuter Langfuse localement.
Avant de configurer Langfuse, vérifiez que le serveur watsonx Orchestrate est en cours d’exécution, (étape 6).
Créez ensuite un compte Langfuse à l’adresse https://cloud.langfuse.com. Après vous être connecté, créez une organisation et un projet. Dans les paramètres du projet, copiez l’ID de votre projet, votre clé publique, votre clé secrète et l’URL de votre hôte.
Configurez maintenant Langfuse dans l’ADK watsonx Orchestrate à l’aide de la commande présentée après cette section et remplacez les espaces réservés par les valeurs que vous avez copiées :
Une fois cette commande correctement exécutée, le module Langfuse est entièrement intégré à l’environnement watsonx Orchestrate. À partir de cette étape, toutes les interactions avec les agents sont automatiquement enregistrées dans le module Langfuse.
Maintenant que le serveur est en cours d’exécution, vous pouvez tester l’agent.
L’étape suivante consiste à définir l’Agent d’analyse des risques fournisseurs. Dans l’ADK watsonx Orchestrate, les agents sont déclarés au moyen de fichiers YAML qui décrivent leur objectif, leurs limites de raisonnement, la configuration de leur modèle et les outils qu’ils sont autorisés à utiliser.
Dans le répertoire agents, créez un fichier nommé vendor-risk-agent.yaml. Ce fichier constitue la couche de gestion des prompts de l’agent et garantit que toutes ses réponses reposent sur un raisonnement déterministe, plutôt que sur des déductions libres.
La définition de l’agent utilisée dans ce tutoriel est présentée ci-dessous. Copiez et collez la définition suivante dans le fichier agents/vendor-risk-agent.yaml. Enregistrez ensuite le fichier.
Cette configuration veille à ce que le comportement de l’agent reste prévisible lorsqu’il répond à des questions portant sur la nature d’un élément, ses causes, son fonctionnement ou des comparaisons. Le système empêche les hallucinations en interdisant toute hypothèse sur la signification des évaluations financières ou des niveaux de risque, sauf si la sortie de l’outil les définit explicitement.
À cette étape, implémentez l’outil Python chargé d’évaluer les risques fournisseurs. Dans l’ADK watsonx Orchestrate, la logique métier personnalisée est implémentée au moyen d’outils Python que les agents invoquent afin d’obtenir les résultats. Plutôt que d’affiner un modèle pour lui apprendre un comportement propre au domaine, ce tutoriel montre comment implémenter un raisonnement déterministe fondé sur des règles au moyen d’outils Python, afin de garantir des résultats cohérents.
Dans le dossier src, créez un fichier nommé main.py. Ce fichier contient le jeu de données des fournisseurs que nous avons créé, les règles d’évaluation des risques et un outil Python appelé evaluate_all_vendor_risks, qui fournit la logique à l’agent.
La logique d’évaluation repose sur des règles. Parmi les signaux indiquant un risque élevé, une entreprise peut obtenir un score de risque élevé en raison de mauvaises performances financières, d’incidents de sécurité antérieurs ou d’enquêtes réglementaires. Une entreprise peut obtenir un score de risque moyen en raison de l’absence de certifications, d’un incident opérationnel isolé ou d’une perturbation causée par les conditions météorologiques.
La fonction evaluate_all_vendor_risks est créée sous forme d’outil watsonx Orchestrate, ce qui permet à l’agent de l’appeler pendant l’exécution. L’outil renvoie une sortie structurée comprenant le niveau de risque final ainsi que les raisons précises ayant conduit à cette classification.
Remarque : le fichier main.py inclus dans ce tutoriel correspond à la version finale actualisée de la logique d’évaluation des risques fournisseurs. Les premières versions du code provoquaient un comportement incorrect de l’agent, qui a été analysé à l’aide des traces Langfuse. Les captures d’écran présentées plus loin dans ce tutoriel contiennent ces traces Langfuse.
L’implémentation complète du fichier main.py utilisé dans ce tutoriel est présentée ci-dessous. Copiez-la dans src/main.py. Enregistrez ensuite le fichier.
À cette étape, l’outil et l’agent doivent être mis à la disposition de watsonx Orchestrate. Pour cela, vous devez importer ces composants dans l’environnement ADK activé. Avant d’exécuter les commandes d’importation, vérifiez que vous vous trouvez dans le dossier racine de votre projet (celui qui contient les répertoires agents, src et tools).
Commencez par importer l’outil Python afin que watsonx Orchestrate puisse l’enregistrer comme fonctionnalité exécutable. Depuis la racine du répertoire de votre projet, exécutez la commande suivante :
Cette commande regroupe le code Python dans un module, enregistre l’outil evaluate_all_vendor_risks et permet aux agents de l’appeler.
L’Agent d’analyse des risques fournisseurs est alors entièrement intégré à l’outil Python dans l’environnement watsonx Orchestrate.
Maintenant que le serveur watsonx Orchestrate local est en cours d’exécution et que l’observabilité de l’agent est activée, vous pouvez tester l’agent et analyser son comportement en temps réel.
Démarrez l’interface de chat en exécutant la commande suivante :
Ouvrez maintenant l'interface utilisateur de watsonx Orchestrate dans votre navigateur. Dans le sélecteur d’agents, choisissez Vendor_Risk_Intelligence_Agent et commencez à poser des questions concernant les risques fournisseurs.
Pour vérifier que l’agent répond correctement et appelle l’outil Python de manière déterministe, vous pouvez utiliser les exemples de questions suivants :
Pendant que vous interagissez avec l’agent, ouvrez le tableau de bord Langfuse dans votre navigateur. Chaque requête utilisateur crée une trace comprenant un session_id et un ID utilisateur. Ces traces enregistrent le chemin d’exécution complet de l’agent. En sélectionnant une trace, vous pouvez analyser les éléments suivants :
l’entrée et la sortie complètes de l’agent ;
l’invocation de l’outil Python ;
les données structurées renvoyées par l’outil ;
le processus de raisonnement suivi afin de produire la réponse finale ;
la latence de chaque étape du processus ;
le déroulement de la conversation par session pour plusieurs questions.
Cette observabilité vous permet d’analyser les indicateurs de performances qui révèlent des goulets d’étranglement, tels que des hypothèses incorrectes, des règles incomplètes ou un comportement inattendu de l’agent.
Après avoir testé l’agent, utilisez les traces Langfuse afin d’identifier les réponses incorrectes. Langfuse affiche chaque invocation d’outil, chaque étape de raisonnement et la latence des réponses, ce qui permet de comprendre facilement pourquoi une réponse particulière a été produite.
Dans ce cas d’utilisation, l’analyse des traces a révélé que certaines réponses incorrectes étaient produites lorsque l’agent déduisait la signification d’une évaluation financière ou répondait sans citer explicitement des éléments issus des règles. Pour corriger ce comportement, les instructions de l’agent et le code Python correspondant ont été modifiés afin d’imposer un raisonnement strictement fondé sur des règles et l’utilisation obligatoire de l’outil.
Après la réimportation des fichiers mis à jour, l’agent a de nouveau été testé. Les nouvelles traces confirment que les réponses reposent fermement sur la sortie structurée de l’outil, que les explications sont déterministes et que toutes les questions descriptives reçoivent des réponses correctes.
Ce processus d’observation et d’amélioration montre comment Langfuse contribue au développement sûr et fiable des agents en fonction des commentaires des utilisateurs.
Explorez la démonstration interactive ci-dessous afin de découvrir l’agent d’évaluation des risques fournisseurs et le traçage Langfuse en action.
Ce tutoriel vous a guidé tout au long de la création, avec watsonx Orchestrate, d’un agent d’IA structuré et digne de confiance, adapté à la conception d’agents dédiés aux entreprises. En associant une logique Python simple fondée sur des règles, des instructions d’agent claires et des outils réutilisables, vous avez implémenté un cas d’utilisation d’évaluation des risques fournisseurs avec un minimum de code et un maximum de transparence.
L’ajout de Langfuse a facilité l’observation du comportement de l’agent et l’identification des problèmes de raisonnement, ce qui permet d’améliorer continuellement l’exactitude sans devoir procéder par approximations. Cette approche aide les entreprises à optimiser leurs systèmes d’agents de bout en bout, à automatiser des workflows complexes et à déployer des systèmes d’IA entièrement transparents.
Plus important encore, l’ADK watsonx Orchestrate et Langfuse permettent ensemble aux entreprises de concevoir, de déboguer et de mettre à l’échelle plus rapidement des workflows agentiques et des applications d’IA complexes, tout en renforçant la gouvernance, en clarifiant le raisonnement et en réduisant la durée du développement.
Créez, déployez et gérez de puissants assistants et agents IA qui automatisent les workflows et les processus grâce à l’IA générative.
Construisez l’avenir de votre entreprise avec des solutions d’IA en lesquelles vous pouvez avoir confiance.
IBM Consulting et ses services d'IA accompagnent les entreprises dans la redéfinition de leurs activités avec l'intelligence artificielle pour mener leur transformation.