Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Instrumenter un agent LangGraph ReAct avec OpenTelemetry

Ce document décrit les étapes à suivre pour instrumenter un agent LangGraph ReAct avec OpenTelemetry, ce qui permet de collecter des données de télémétrie à partir de l'agent. Les prompts utilisateur, ainsi que les réponses et les choix de l'agent, sont inclus dans la télémétrie en tant qu'attributs associés aux segments. Les réponses de l'agent sont également incluses dans les entrées de journal corrélées aux segments 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.

Les applications qui utilisent un agent LangGraph ReAct peuvent également collecter des requêtes et des réponses multimodales. Ce document explique comment collecter des prompts textuels et des réponses. 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.

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 journaux, de métriques et de traces, procédez comme suit :

Installer les packages OpenTelemetry
Configurer OpenTelemetry pour collecter et envoyer des données de télémétrie
Tracer l'appel de l'agent d'IA générative

Installer les packages OpenTelemetry

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

uv add 'opentelemetry-instrumentation-vertexai>=2.0b0' \
  'opentelemetry-instrumentation-sqlite3' \
  'opentelemetry-exporter-otlp-proto-grpc'

Les données de journaux, de métriques et de traces sont envoyées à Google Cloud à l'aide de l'API Telemetry (OTLP), qui implémente le protocole OpenTelemetry. 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 généralement cohérent avec les fichiers proto définis par le protocole OpenTelemetry. 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 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, sélectionnez le logo GitHub dans la barre d'outils de l'exemple.

def setup_opentelemetry() -> None:
    credentials, project_id = google.auth.default()
    resource = Resource.create(
        attributes={
            SERVICE_NAME: "langgraph-sql-agent",
            CLOUD_PROVIDER: "gcp",
            CLOUD_ACCOUNT_ID: project_id,
            # The project to send spans to
            "gcp.project_id": project_id,
            CLOUD_REGION: "us-central1",
            SERVICE_NAMESPACE: "local",
            SERVICE_INSTANCE_ID: "local-instance",
        }
    )

    # 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(
            OTLPLogExporter(
                credentials=channel_creds,
                endpoint="https://telemetry.googleapis.com:443/v1/logs",
            )
        )
    )
    logs.set_logger_provider(logger_provider)

    reader = PeriodicExportingMetricReader(
        OTLPMetricExporter(
            credentials=channel_creds,
            endpoint="https://telemetry.googleapis.com:443/v1/metrics",
        )
    )
    meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
    metrics.set_meter_provider(meter_provider)

    # Load instrumentors
    SQLite3Instrumentor().instrument()
    GoogleGenAiSdkInstrumentor().instrument()

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

Pour tracer l'exécution de l'appel de l'agent LangGraph, créez un segment personnalisé autour de l'appel de l'agent :

Pour afficher l'exemple complet, sélectionnez le logo GitHub dans la barre d'outils de l'exemple.

# 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 segments et de métriques personnalisés, consultez 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 qui dispose 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

Installez la Google Cloud CLI.
Configurez la gcloud CLI afin d'utiliser votre identité fédérée.

Pour en savoir plus, consultez Se connecter à la gcloud CLI avec votre identité fédérée.
Pour initialiser la gcloud CLI, exécutez la commande suivante :
```
gcloud init
```
Créez ou sélectionnez un projet Google Cloud .
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 devez disposer du rôle "Créateur de projet" (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.
Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu d'en sélectionner un existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.
- Créez un projet Google Cloud :
```
gcloud projects create PROJECT_ID
```
  Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.
- Sélectionnez le projet Google Cloud que vous avez créé :
```
gcloud config set project PROJECT_ID
```
  Remplacez PROJECT_ID par le nom de votre projet Google Cloud .
Vérifiez que la facturation est activée pour votre projet Google Cloud .
Activez les API Vertex AI, Service Usage, Telemetry, Cloud Logging, Cloud Monitoring et Cloud Trace, si elles ne sont pas déjà activées :
Rôles requis pour activer les API
Pour activer des API, vous devez disposer 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 l'obtenir via le rôle Administrateur Service Usage (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
```

Pour obtenir les autorisations nécessaires pour que l'exemple d'application écrive des données de journaux, de métriques et de traces, 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)
Ces autorisations sont suffisantes si vous exécutez l'exemple dans Cloud Shell, sur des ressources Google Cloud ou dans un environnement de développement local.

Important : Les applications de production s'appuient généralement sur un compte de service pour fournir les identifiants requis pour écrire des données de journaux, de métriques et de traces. Dans ce cas, attribuez les rôles précédents au compte de service.
Veillez à 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
```

Exécuter l'exemple

Pour exécuter l'exemple , procédez comme suit :

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

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

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

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

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
# Set the location to one that supports gemini-3.5-flash
export GOOGLE_CLOUD_REGION=global

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

Créez un environnement virtuel et exécutez l'exemple :
```
uv run main.py
```
L'application affiche un message semblable à celui-ci :
```
Starting agent using ephemeral SQLite DB.
```

Pour créer une base de données, saisissez une valeur au prompt Talk to the SQL agent >> (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: Okay, I'll create a table to hold weather data. First, I need to decide on the schema for the table. I'll include columns for date, location, temperature, humidity, and precipitation.

CREATE TABLE weather (
  date DATE,
  location VARCHAR(255),
  temperature REAL,
  humidity REAL,
  precipitation REAL
);

🤖 Agent: I have created the weather table.
👤 User: Add altitude to the table.
🤖 Agent

ALTER TABLE weather ADD COLUMN altitude REAL;

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 un même prompt.

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 :

Visionneuse 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 Trace :

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.
Dans la barre d'outils, sélectionnez Ajouter un filtre, puis Nom du segment, puis invoke agent.

La section Exécuter l'exemple incluait un exemple d'exécution dans lequel deux requêtes sont envoyées à l'application. L'image suivante illustre la page Explorateur de traces 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.
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, où un segment porte le nom invoke_agent. Cette période appelle Gemini. La trace Gemini inclut 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 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: {
    message: {
      role: "model"
      content: [
        0: {
          text: "Okay, I'll create a table to hold weather data. First, I need to decide on the schema for the table. I'll include columns for date, location, temperature, humidity, and precipitation.

          CREATE TABLE weather (
              date DATE,
              location VARCHAR(255),
              temperature REAL,
              humidity REAL,
              precipitation REAL
          );
          "
        }
      ]
    }
  index: 0
  }
...
}
```

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.

Instrumenter un agent LangGraph ReAct avec OpenTelemetry Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

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

Installer les packages OpenTelemetry

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

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

Exécuter l'exemple

Persona de l'agent LangGraph

Avant de commencer

Exécuter l'exemple

Afficher les traces, les métriques et les journaux

Avant de commencer

Afficher la télémétrie

Instrumenter un agent LangGraph ReAct avec OpenTelemetry