Instrumenter un agent ReAct LangGraph 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 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 décrit les étapes à suivre pour instrumenter un agent ReAct LangGraph avec OpenTelemetry, ce qui permet de collecter des données de télémétrie à partir de l'agent. Les requêtes des utilisateurs, les réponses et les choix des agents sont inclus dans la télémétrie en tant qu'attributs associés aux plages. Les réponses de l'agent sont également incluses dans les entrées de journal qui sont corrélées avec les plages contenant des événements d'IA générative. Les instructions de ce document s'appliquent lorsque l'agent utilise ChatVertexAI de Langchain pour appeler un modèle Gemini.

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

Pour instrumenter votre application d'IA générative afin de collecter des données de journal, de métrique 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. Suivre l'appel de l'agent d'IA générative

Installer les packages OpenTelemetry

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

pip install 'opentelemetry-instrumentation-vertexai>=2.0b0' \
  'opentelemetry-instrumentation-sqlite' \
  'opentelemetry-exporter-gcp-logging' \
  'opentelemetry-exporter-gcp-monitoring' \
  'opentelemetry-exporter-otlp-proto-grpc'

Les données de journal et de métrique sont envoyées à votre Google Cloud projet à 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 des points de terminaison dans 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 LangGraph, configurez OpenTelemetry pour capturer et 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: "langgraph-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()
    VertexAIInstrumentor().instrument()

Suivre l'appel de l'agent d'IA générative

Pour suivre l'exécution de l'appel de l'agent LangGraph, créez une étendue personnalisée autour de l'appel de l'agent:

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

# Invoke the agent within a span
with tracer.start_as_current_span("invoke agent"):
    result = agent.invoke({"messages": [prompt]}, config=config)

Vous pouvez inclure le code précédent à des endroits clés du code de votre application.

Pour en savoir plus sur l'ajout de portées et de métriques personnalisées, consultez la section Ajouter des traces et des métriques personnalisées à votre application.

Exécuter l'exemple

Cet exemple est un agent LangGraph instrumenté avec OpenTelemetry pour envoyer des traces et des journaux avec des requêtes et des réponses d'IA générative, ainsi que des métriques à votre projetGoogle Cloud .

Persona de l'agent LangGraph

L'agent LangGraph est défini comme un expert SQL disposant d'un accès complet à une base de données SQLite éphémère. L'agent est implémenté avec l'agent ReAct prédéfini LangGraph et accède à la base de données, qui est initialement vide, à l'aide de SQLDatabaseToolkit.

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:

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

3. Pour obtenir les autorisations dont les applications exemple ont besoin pour écrire 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:

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

Exécuter l'exemple

Pour exécuter l'exemple , 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/langgraph-sql-agent
   

4. Configurer les variables d'environnement :

   # Capture GenAI prompts and responses
   export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
   # Capture application logs automatically
   export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
   

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

   python -m venv venv/
   source venv/bin/activate
   pip install -r requirements.txt
   python main.py
   

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

   Starting agent using ephemeral SQLite DB.
   

6. Pour créer une base de données, saisissez une valeur à l'invite Parler à l'agent SQL >>, puis appuyez sur Entrée.

   Les actions effectuées par l'agent s'affichent ensuite dans Cloud Shell.

   Voici des exemples d'interactions entre un utilisateur et l'application:

   Talk to the SQL agent >> Create a new table to hold weather data.
   👤 User: Create a new table to hold weather data.
   🤖 Agent: I need to know what columns the table should have. What information about the weather do you want to store? For example, I could include columns for date, location, temperature, humidity, and precipitation.
   
   Talk to the SQL agent >> Create a new table to hold weather data. Include date, location, temperature, humidity, and precipitation.
   👤 User: Create a new table to hold weather data. Include date, location, temperature, humidity, and precipitation.
   🤖 Agent
   
   CREATE TABLE weather (
     date DATE,
     location VARCHAR(255),
     temperature REAL,
     humidity REAL,
     precipitation REAL
   );
   
   

7. Pour quitter, saisissez Ctrl-C.

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 la même requête.

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:

• 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, 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, Nom de l'intervalle, puis invoke agent.

   La section Exécuter un exemple inclut un exemple d'exécution dans lequel deux requêtes sont envoyées à l'application. La capture d'écran suivante illustre la page Trace Explorer après le filtrage des données:

   

   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 à l'affichage.

3. Pour explorer votre période et vos données de journal, sélectionnez une période dans le tableau Périodes.

   La page Détails s'affiche. Cette page affiche la trace associée et ses périodes. Le tableau de la page affiche des informations détaillées sur la période que vous avez sélectionnée. Ces informations incluent les suivantes:

   • L'onglet GenAI 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 intervalle porte le nom invoke_agent. Cette période appelle Gemini. La période Gemini inclut des événements d'IA générative:

     

   • L'onglet Logs & Events (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 l'agent LangGraph. Par exemple, pour l'exemple d'exécution, la charge utile JSON inclut le contenu suivant:

     {
       logName: "projects/my-project/logs/otel_python_inprocess_log_name_temp"
       jsonPayload: {
         finish_reason: "stop"
         message: {
           role: "model"
           content: [
             0: {
               text: "I need to know what columns the table should have. What information about the weather do you want to store? For example, I could include columns for date, location, temperature, humidity, and precipitation."
             }
           ]
         }
       index: 0
       }
     ...
     }
     

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