Instrumenter des applications ADK avec OpenTelemetry

Preview

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités de pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Ce document explique comment instrumenter un agent d'IA créé avec le framework Agent Development Kit (ADK). Cette instrumentation, qui s'appuie sur OpenTelemetry, vous permet de collecter les requêtes des utilisateurs, les réponses de l'agent et les choix de l'agent.

Le framework ADK est lui-même instrumenté avec OpenTelemetry, qui capture la télémétrie des étapes clés de l'exécution de votre agent. Cela fournit une observabilité précieuse des applications prête à l'emploi. Toutefois, cette observabilité peut ne pas suffire pour le cas d'utilisation de votre application. Vous pouvez ajouter d'autres bibliothèques d'instrumentation à 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 niveaux de qualité des réponses des agents en fonction de vos critères spécifiques à votre 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. Installer les packages OpenTelemetry
2. Configurer OpenTelemetry pour collecter et envoyer des données de télémétrie
3. Écrire un point d'entrée personnalisé pour injecter OpenTelemetry configuré

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 'opentelemetry-instrumentation-google-genai' \
  '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 est compatible avec le format OTLP. Les données reçues via ce point de terminaison sont également stockées au format OTLP. La bibliothèque opentelemetry-exporter-otlp-proto-grpc appelle le point de terminaison de l'API de télémétrie (OTLP).

Configurer OpenTelemetry pour collecter et envoyer des données de télémétrie

Dans le code d'initialisation de votre agent ADK, ajoutez du code pour configurer OpenTelemetry afin de capturer et d'envoyer des données de télémétrie à votre projet Google Cloud  :

Pour afficher l'exemple complet, cliquez sur  Plus, puis sélectionnez Afficher sur GitHub.

def setup_opentelemetry() -> None:
    credentials, project_id = google.auth.default()
    resource = Resource.create(
        attributes={
            SERVICE_NAME: "adk-sql-agent",
            # The project to send spans to
            "gcp.project_id": project_id,
        }
    )

    # Set up OTLP auth
    request = google.auth.transport.requests.Request()
    auth_metadata_plugin = AuthMetadataPlugin(credentials=credentials, request=request)
    channel_creds = grpc.composite_channel_credentials(
        grpc.ssl_channel_credentials(),
        grpc.metadata_call_credentials(auth_metadata_plugin),
    )

    # Set up OpenTelemetry Python SDK
    tracer_provider = TracerProvider(resource=resource)
    tracer_provider.add_span_processor(
        BatchSpanProcessor(
            OTLPSpanExporter(
                credentials=channel_creds,
                endpoint="https://telemetry.googleapis.com:443/v1/traces",
            )
        )
    )
    trace.set_tracer_provider(tracer_provider)

    logger_provider = LoggerProvider(resource=resource)
    logger_provider.add_log_record_processor(
        BatchLogRecordProcessor(CloudLoggingExporter())
    )
    logs.set_logger_provider(logger_provider)

    event_logger_provider = EventLoggerProvider(logger_provider)
    events.set_event_logger_provider(event_logger_provider)

    reader = PeriodicExportingMetricReader(CloudMonitoringMetricsExporter())
    meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
    metrics.set_meter_provider(meter_provider)

    # Load instrumentors
    SQLite3Instrumentor().instrument()
    # ADK uses Vertex AI and Google Gen AI SDKs.
    VertexAIInstrumentor().instrument()
    GoogleGenAiSdkInstrumentor().instrument()

Écrire un point d'entrée personnalisé pour utiliser OpenTelemetry configuré

Pour utiliser OpenTelemetry pour l'instrumentation, créez un point d'entrée personnalisé pour votre application ADK. Le point d'entrée personnalisé doit configurer OpenTelemetry avant de lancer l'agent ADK.

Dans l'application exemple, la méthode main sert de point d'entrée personnalisé qui initialise OpenTelemetry, puis lance le serveur FastAPI qui vous permet d'interagir avec l'agent.

Pour afficher l'exemple complet, cliquez sur  Plus, puis sélectionnez Afficher sur GitHub.

def main() -> None:
    # Make sure to set:
    # OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
    # OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
    # in order to full prompts and responses and logs messages.
    # For this sample, these can be set by loading the `opentelemetry.env` file.
    setup_opentelemetry()

    # Call the function to get the FastAPI app instance.
    # Ensure that the agent director name is the name of directory containing agent subdirectories,
    # where each subdirectory represents a single agent with __init__.py and agent.py files.
    # For this example this would be the current directory containing main.py.
    # Note: Calling this method attempts to set the global tracer provider, which has already been
    # set by the setup_opentelemetry() function.
    app = get_fast_api_app(
        agents_dir=AGENT_DIR,
        session_service_uri=SESSION_DB_URL,
        allow_origins=ALLOWED_ORIGINS,
        web=SERVE_WEB_INTERFACE,
    )

    # Lauch the web interface on port 8080.
    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

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 le kit de développement d'agent et accède à une base de données à l'aide de SQLDatabaseToolkit. La base de données est initialement vide.

Avant de commencer

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

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

   Enable the APIs

3. Pour obtenir les autorisations nécessaires pour que les applications exemples puissent écrire 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 :

   • Rédacteur de traces de télémétrie cloud (roles/telemetry.tracesWriter)
   • Rédacteur de journaux (roles/logging.logWriter)
   • Rédacteur de métriques Monitoring (roles/monitoring.metricWriter)
   • Utilisateur Vertex AI (roles/aiplatform.user)

Lancer l'application

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

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Clonez le dépôt :

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

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

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

4. 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) python main.py
   

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

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

5. Pour interagir avec l'agent, ouvrez un navigateur à l'adresse indiquée à l'étape précédente.

6. 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 donnez-lui 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 l'interaction entre sql_agent et l'utilisateur :

Create a table for me to store weather data and also insert sample data in
the table. At the end show all data in the table you created.



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 :

• Lecteur de journaux (roles/logging.viewer)
• Lecteur Monitoring (roles/monitoring.viewer)
• Utilisateur Cloud Trace (roles/cloudtrace.user)

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 Explorateur de traces :

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 :

   

   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 journaux et de spans, sélectionnez un span dans le tableau Spans.

   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 IA générative 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. Le segment Gemini inclut des événements d'IA générative :

     

   • L'onglet Journaux et événements liste les entrées de journal 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": {
           "role": "model",
           "parts": [
             {
               "executable_code": null,
               "inline_data": null,
               "thought": null,
               "video_metadata": null,
               "code_execution_result": null,
               "function_response": null,
               "thought_signature": null,
               "text": "Okay, I will create a table named `weather` with columns `id`, `city`, `temperature`, and `date`. Then I will insert some sample rows into the table and display all the data in the table.\n",
               "file_data": null,
               "function_call": null
             }
           ]
         }
       },
       ...
     }
     

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.