Instrumenter des applications ADK avec OpenTelemetry

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

Les applications qui utilisent l'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 les requêtes et 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 d'autres éléments 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 :

  • Suivez la consommation de ressources des outils invoqués par l'agent.
  • Suivez les échecs de validation spécifiques aux applications, les cas de non-respect des règles métier ou les mécanismes personnalisés de récupération des erreurs.
  • Suivez les scores de qualité des réponses des agents en fonction de vos critères spécifiques au domaine.

Instrumenter votre application d'IA générative pour collecter des données de télémétrie

Pour instrumenter votre agent d'IA afin de collecter des données de journaux, de métriques 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'exportateur OpenTelemetry suivants :

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

Les données de journaux et de métriques sont envoyées à votre projet Google Cloud à l'aide de l'API Cloud Logging ou de l'API Cloud Monitoring. Les bibliothèques opentelemetry-exporter-gcp-logging et opentelemetry-exporter-gcp-monitoring appellent les points de terminaison de ces API.

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

Vos données de trace sont stockées dans un format généralement cohérent avec les fichiers proto définis par le protocole OTLP OpenTelemetry. Toutefois, les champs peuvent être convertis d'un type de données spécifique à OpenTelemetry en type de données JSON avant d'être stockés. 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 ce faire, configurez votre environnement ADK :

  • Lorsque vous exécutez votre application avec la commande adk web de la CLI, incluez l'option --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
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

  • 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 :

    • Empêche l'instrumentation ADK d'associer des attributs de portée qui dépassent la limite de taille des attributs.
    • Empêche l'ajout d'informations permettant d'identifier personnellement l'utilisateur aux spans en tant qu'attributs.

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 de l'ADK. L'agent est instrumenté avec OpenTelemetry et configuré pour envoyer des métriques, des traces et des journaux à votre projet Google Cloud . La télémétrie envoyée à votre projet inclut les requêtes et les réponses de l'IA générative.

Persona d'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. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. Install the 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. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles. 

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

  8. Install the 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. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  12. Verify that billing is enabled for your Google Cloud project.

  13. Enable the Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles. 

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

  14. Si vous exécutez l'exemple dans Cloud Shell, sur des ressources Google Cloudou dans un environnement de développement local, les autorisations listées dans cette section sont suffisantes. Pour les applications de production, un compte de service fournit généralement les identifiants permettant d'écrire des données de journaux, de métriques et de trace.

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

    15. Lancer l'application

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

    1. Dans Cloud Shell, exécutez la commande suivante :

      git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python.git

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

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

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

      python -m venv venv/
source venv/bin/activate
pip install -r requirements.txt
env $(cat opentelemetry.env | xargs) adk web --otel_to_cloud

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

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

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

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

    Interagir avec l'agent

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

    What can you do for me ?

    De même, puisque 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 les utiliser. L'agent ne peut créer qu'une base de données éphémère soutenue 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 obtenir une réponse différente pour le même prompt.

    Quitter l'application

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

    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 journaux, de métriques et de traces, 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 avec 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 Trace Explorer :

    1. Dans la console Google Cloud , 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 de la portée, puis call_llm.

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

      Affichage des délais de trace.

      Si vous n'avez jamais utilisé Cloud Trace, 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 portée et de journaux, sélectionnez une portée dans le tableau Portées.

      La page Détails s'affiche. Cette page affiche la trace associée et ses spans. Le tableau sur la page affiche des informations détaillées sur la plage que vous avez sélectionnée. Voici quelques exemples :

      • 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 une portée porte le nom call_llm. Cette étendue appelle le LLM (grand modèle de langage) qui alimente cet agent. Dans cet exemple, il s'agit de Gemini. La couverture Gemini inclut les événements d'IA générative suivants :

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

      • L'onglet Journaux et événements liste les entrées de journaux et les événements associés à la portée. 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 du journal incluent la réponse de sql_agent. Par exemple, pour l'exécution de l'échantillon, 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 projet Google Cloud , mais il ne génère aucune métrique.