Instrumenter des applications ADK avec OpenTelemetry

Ce document explique comment instrumenter un agent IA créé avec le framework Agent Development Kit (ADK). Le framework ADK inclut une instrumentation OpenTelemetry qui collecte la télémétrie à partir des actions clés de l'agent. Lorsque vous activez l'instrumentation intégrée, elle envoie des informations telles que des requêtes textuelles et des réponses d'agent à votre Google Cloud projet. Ce document décrit les modifications requises et fournit un lien vers un exemple d'application.

Les applications qui utilisent ADK peuvent également collecter des requêtes et des réponses multimodales. Ce document explique comment collecter des requêtes et des réponses textuelles. Si vous souhaitez collecter des données multimodales, une configuration supplémentaire est requise. Pour en savoir plus, consultez Collecter et afficher des requêtes et des réponses multimodales.

L'observabilité par défaut fournie par ADK peut ne pas être suffisante pour le cas d'utilisation de votre application. Vous pouvez ajouter des bibliothèques d'instrumentation supplémentaires à l'aide d'OpenTelemetry pour capturer la télémétrie à partir d'autres parties de votre application, ou votre propre instrumentation personnalisée pour capturer des données spécifiques à l'application afin d'obtenir une observabilité plus précise. Par exemple, dans votre application, vous pouvez écrire du code d'instrumentation pour :

  • suivre la consommation de ressources des outils appelés par l'agent ;
  • suivre les échecs de validation spécifiques à l'application, les violations de règles métier ou les mécanismes personnalisés de récupération des erreurs ;
  • suivre les scores de qualité des réponses de l'agent en fonction de vos critères spécifiques au domaine.

Instrumenter votre application d'IA générative pour collecter la télémétrie

Pour instrumenter votre agent IA afin de collecter des données de journal, de métrique et de trace, procédez comme suit :

  1. Installez les packages OpenTelemetry.
  2. Configurez votre environnement ADK.

Le reste de cette section décrit les étapes précédentes.

Installer les packages OpenTelemetry

Ajoutez les packages d'instrumentation et d'exportation OpenTelemetry suivants :

uv add 'google-adk>=1.17.0' \
  'opentelemetry-instrumentation-google-genai>=0.4b0' \
  'opentelemetry-instrumentation-sqlite3' \
  'opentelemetry-exporter-gcp-logging' \
  'opentelemetry-exporter-otlp-proto-grpc' \
  'opentelemetry-instrumentation-vertexai>=2.0b0'

Les données de journal sont envoyées à votre Google Cloud projet à l'aide de l' API Cloud Logging ou de l'API Cloud Monitoring. La bibliothèque opentelemetry-exporter-gcp-logging appelle des points de terminaison dans l'API Cloud Logging.

Les données de métriques ne sont pas collectées. En règle générale, les applications qui n'utilisent pas de solution basée sur un collecteur incluent la opentelemetry-exporter-gcp-monitoring bibliothèque. Cette bibliothèque appelle des points de terminaison dans l'API Cloud Monitoring.

Les données de trace sont envoyées à Google Cloud à l'aide de l' API Telemetry (OTLP), qui implémente le protocole OpenTelemetry Line. La bibliothèque opentelemetry-exporter-otlp-proto-grpc appelle le point de terminaison de l'API Telemetry (OTLP).

Vos données de trace sont stockées dans un format qui est généralement cohérent avec les fichiers proto définis par le protocole OpenTelemetry Line. Toutefois, les champs peuvent être convertis d'un type de données spécifique à OpenTelemetry en un type de données JSON avant le stockage. Pour en savoir plus sur le format de stockage, consultez Schéma des données de trace.

Configurer votre environnement ADK

Les versions 1.17.0 et ultérieures du framework ADK incluent une compatibilité intégrée avec OpenTelemetry et l'envoi de données de télémétrie OpenTelemetry à Google Cloud Observability. Pour activer cette fonctionnalité, configurez votre environnement ADK :

  • Si vous exécutez votre application avec la commande adk web, incluez l'indicateur --otel_to_cloud.

  • Dans votre fichier opentelemetry.env, définissez les variables d'environnement suivantes :

    OTEL_SERVICE_NAME='adk-sql-agent'
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED='true'

  • Configurez OpenTelemetry pour utiliser les conventions sémantiques les plus récentes pour l'IA générative.

    OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental'

  • Configurez OpenTelemetry pour joindre des messages en tant qu'événements.

    OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT='EVENT_ONLY'

    Pour en savoir plus sur les valeurs énumérées autorisées, consultez genai/types.py.

  • Nous vous recommandons également d'ajouter la variable d'environnement suivante à votre fichier opentelemetry.env :

    ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS='false'

    Cette variable d'environnement effectue les opérations suivantes :

    • Elle empêche l'instrumentation ADK de joindre des attributs de segment qui dépassent la limite de taille des attributs.
    • Elle empêche que des informations permettant d'identifier personnellement l'utilisateur soient jointes aux segments en tant qu'attributs.

  • Vous devrez peut-être définir d'autres variables d'environnement. Par exemple, si vous déployez sur Gemini Enterprise Agent Platform, vous devez également définir la variable d'environnement suivante :

    GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY='true'

Télécharger et exécuter l'exemple d'application

Cet exemple de code implémente un agent d'IA générative créé à l'aide d'ADK. L'agent est instrumenté avec OpenTelemetry et configuré pour envoyer des métriques, des traces et des journaux à votre Google Cloud project. La télémétrie envoyée à votre projet inclut des requêtes et des réponses d'IA générative.

Personnalité de l'agent ADK

L'agent d'IA générative est défini comme un expert SQL ayant un accès complet à une base de données SQLite éphémère. L'agent est créé avec l' Agent Development Kit et accède à une base de données à l'aide de SQLDatabaseToolkit. La base de données est initialement vide.

Avant de commencer

  1. Connectez-vous à votre Google Cloud compte. Si vous n'avez jamais utilisé Google Cloud, créez un compte pour évaluer les performances de nos produits dans des scénarios réels. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

  2. Installez la Google Cloud CLI.

  3. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  4. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

  5. Créez ou sélectionnez un Google Cloud projet.

    Rôles requis pour sélectionner ou créer un projet

    • Sélectionner un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
    • Créer un projet : pour créer un projet, vous avez besoin du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

    • Créez un Google Cloud projet :

      gcloud projects create PROJECT_ID

      Remplacez PROJECT_ID par un nom pour le Google Cloud projet que vous créez.

    • Sélectionnez le Google Cloud projet que vous avez créé :

      gcloud config set project PROJECT_ID

      Remplacez PROJECT_ID par le nom de votre Google Cloud projet.

  6. Vérifiez que la facturation est activée pour votre Google Cloud projet.

  7. Activez les API Vertex AI, Service Usage, Telemetry, Cloud Logging, Cloud Monitoring et Cloud Trace :

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation via le rôle Administrateur de l'utilisation des services (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles. 

    gcloud services enable aiplatform.googleapis.com serviceusage.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

  8. Installez la Google Cloud CLI.

  9. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  10. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

  11. Créez ou sélectionnez un Google Cloud projet.

    Rôles requis pour sélectionner ou créer un projet

    • Sélectionner un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
    • Créer un projet : pour créer un projet, vous avez besoin du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

    • Créez un Google Cloud projet :

      gcloud projects create PROJECT_ID

      Remplacez PROJECT_ID par un nom pour le Google Cloud projet que vous créez.

    • Sélectionnez le Google Cloud projet que vous avez créé :

      gcloud config set project PROJECT_ID

      Remplacez PROJECT_ID par le nom de votre Google Cloud projet.

  12. Vérifiez que la facturation est activée pour votre Google Cloud projet.

  13. Activez les API Vertex AI, Service Usage, Telemetry, Cloud Logging, Cloud Monitoring et Cloud Trace :

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation via le rôle Administrateur de l'utilisation des services (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles. 

    gcloud services enable aiplatform.googleapis.com serviceusage.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com
    14.

  14. Pour obtenir les autorisations nécessaires pour que l'exemple d'application écrive des données de journal, de métrique et de trace, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

    Ces autorisations sont suffisantes si vous exécutez l'exemple dans le Cloud Shell, sur Google Cloud des ressources ou dans un environnement de développement local.

  15. Assurez-vous de spécifier un projet de quota. L'API Vertex AI (aiplatform.googleapis.com) nécessite la spécification d'un projet de quota. Pour en savoir plus, consultez Définir le projet de quota. Par exemple, la commande suivante peut définir un projet de quota.

    gcloud config set billing/quota_project PROJECT_ID

Lancer l'application

Pour lancer l'exemple d'application, procédez comme suit :

  1. Dans Cloud Shell, clonez le dépôt :

    git clone https://github.com/GoogleCloudPlatform/opentelemetry-samples.git

  2. Accédez au répertoire de l'exemple :

    cd opentelemetry-samples/python/adk-sql-agent

    L'exemple contient un fichier .env qui définit deux variables d'environnement. Une variable contrôle les points de terminaison utilisés par le SDK. L'autre variable définit un emplacement.

    Si vous préférez utiliser un autre modèle, modifiez main.py. Assurez-vous que le modèle que vous sélectionnez est compatible avec l'emplacement spécifié dans le fichier .env. Pour en savoir plus sur les modèles, consultez Modèles Google.

  3. Créez un environnement virtuel et exécutez l'exemple :

    uv run --env-file opentelemetry.env adk web --otel_to_cloud

    L'application affiche un message semblable à celui-ci :

    Appplication startup complete
Uvicorn running on http://127.0.0.1:8080

  4. Pour interagir avec l'agent, sélectionnez l'URL affichée dans la sortie de l'étape précédente.

  5. Développez Sélectionner une application , puis sélectionnez sql_agent dans la liste des agents.

Interagir avec l'agent

Pour interagir avec l'agent, posez-lui une question ou donnez-lui une commande. Par exemple, vous pouvez poser la question suivante :

What can you do for me ?

De même, étant donné que sql_agent a la personnalité d'un expert SQL, vous pouvez lui demander de créer des tables pour vos applications et d'écrire des requêtes pour opérer sur les tables créées. L'agent ne peut créer qu'une base de données éphémère sauvegardée par un fichier .db créé sur la machine exécutant l'application.

L'exemple suivant illustre une interaction entre sql_agent et l'utilisateur :

Affichage de l'interaction avec sql_agent.

Les actions effectuées par les agents d'IA générative ne sont pas déterministes. Vous pouvez donc voir une réponse différente pour la même requête.

Quitter l'application

Pour quitter l'application, saisissez Ctrl-C dans l'interface système utilisée pour lancer l'application.

Afficher les traces, les métriques et les journaux

Cette section explique comment afficher les événements d'IA générative.

Avant de commencer

Pour obtenir les autorisations nécessaires pour afficher vos données de journal, de métrique et de trace, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Afficher la télémétrie

Pour afficher les événements d'IA générative créés par l'application, utilisez la page Explorateur Trace :

  1. Dans la Google Cloud console, accédez à la page Explorateur Trace :

    Accéder à Explorateur Trace

    Vous pouvez également accéder à cette page à l'aide de la barre de recherche.

  2. Dans la barre d'outils, sélectionnez Ajouter un filtre, puis Nom du segment et enfin sélectionnez call_llm.

    L'illustration suivante montre la page Explorateur Trace après le filtrage des données :

    Affichage des spans de trace.

    Si vous n'avez jamais utilisé Cloud Trace auparavant, Google Cloud Observability doit créer une base de données pour stocker vos données de trace. La création de la base de données peut prendre quelques minutes. Pendant cette période, aucune donnée de trace n'est disponible.

  3. Pour explorer vos données de segment et de journal, sélectionnez un segment dans le tableau Segments.

    La page Détails s'affiche. Cette page affiche la trace associée et ses segments. Le tableau de la page affiche des informations détaillées sur le segment que vous avez sélectionné. Ces informations incluent les éléments suivants :

    • L'onglet Entrées/Sorties affiche les événements des agents d'IA générative. Pour en savoir plus sur ces événements, consultez Afficher les événements d'IA générative.

      La capture d'écran suivante illustre une trace, dans laquelle un segment porte le nom call_llm. Ce segment appelle le LLM (grand modèle de langage) qui alimente cet agent. Pour cet exemple, il s'agit de Gemini. Le segment Gemini inclut des événements d'IA générative :

      Affichage des événements d'IA générative.

    • L'onglet Journaux et événements répertorie les entrées de journal et les événements associés au segment. Si vous souhaitez afficher les données de journal dans l'explorateur de journaux, sélectionnez Afficher les journaux dans la barre d'outils de cet onglet.

      Les données de journal incluent la réponse de sql_agent. Par exemple, pour l'exécution de l'exemple, la charge utile JSON inclut le contenu suivant :

      {
  "logName": "projects/my-project/logs/otel_python_inprocess_log_name_temp",
  "jsonPayload": {
    "content": {
      "parts": [
        0: {
          "text": "Now I can create the table."
        }
        1: {1}
        ],
      "role": "model"
    }
  },
  ...
}

L'exemple est instrumenté pour envoyer des données de métriques à votre Google Cloud projet, mais il ne génère aucune métrique.