LangGraph ReAct-Agent mit OpenTelemetry instrumentieren

In diesem Dokument werden die Schritte zum Instrumentieren eines LangGraph-ReAct-Agents mit OpenTelemetry beschrieben, um Telemetriedaten vom Agenten zu erfassen. Nutzerprompts und Agentenantworten und -auswahlen sind in den Telemetriedaten als Attribute enthalten, die an Spans angehängt sind. Agentenantworten sind auch in den Logeinträgen enthalten, die mit Spans korreliert sind, die Ereignisse der generativen KI enthalten. Die Anleitung in diesem Dokument gilt, wenn der Agent ChatVertexAI von Langchain verwendet, um ein Gemini-Modell aufzurufen.

Anwendungen, die einen LangGraph-ReAct-Agenten verwenden, können auch multimodale Prompts und Antworten erfassen. In diesem Dokument wird beschrieben, wie Sie Textprompts und -antworten erfassen. Wenn Sie multimodale Daten erfassen möchten, ist eine zusätzliche Konfiguration erforderlich. Weitere Informationen finden Sie unter Multimodale Prompts und Antworten erfassen und ansehen.

Anwendung für generative KI instrumentieren, um Telemetriedaten zu erfassen

So instrumentieren Sie Ihre Anwendung für generative KI, um Log-, Messwert- und Tracedaten zu erfassen:

1. OpenTelemetry-Pakete installieren
2. OpenTelemetry so konfigurieren, dass Telemetriedaten erfasst und gesendet werden
3. Aufruf des Agents für generative KI verfolgen

OpenTelemetry-Pakete installieren

Fügen Sie die folgenden OpenTelemetry-Instrumentierungs- und -Exporterpakete hinzu:

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

Log- und Messwertdaten werden mit der Cloud Logging API oder der Cloud Monitoring API an Ihr Google Cloud Projektgesendet. Die opentelemetry-exporter-gcp-logging Bibliothek ruft Endpunkte in diesen APIs auf.

Trace- und Messwertdaten werden an Google Cloud gesendet, indem die Telemetry (OTLP) API verwendet wird, die das OpenTelemetry Line Protocol implementiert. Die opentelemetry-exporter-otlp-proto-grpc Bibliothek ruft den Telemetry (OTLP) API-Endpunkt auf.

Ihre Tracedaten werden in einem Format gespeichert, das im Allgemeinen mit den Protobuf-Dateien übereinstimmt, die durch das OpenTelemetry Line Protocoldefiniert werden. Felder können jedoch vor der Speicherung von einem OpenTelemetry-spezifischen Datentyp in einen JSON-Datentyp konvertiert werden. Weitere Informationen zum Speicherformat finden Sie unter Schema für Tracedaten.

OpenTelemetry so konfigurieren, dass Telemetriedaten erfasst und gesendet werden

Konfigurieren Sie OpenTelemetry im Initialisierungscode Ihres LangGraph-Agents so, dass Telemetriedaten erfasst und an Ihr Google Cloud Projektgesendet werden:

Wenn Sie das vollständige Beispiel sehen möchten, wählen Sie in der Symbolleiste des Beispiels das GitHub-Logo aus.

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(CloudLoggingExporter())
    )
    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()

Aufruf des Agents für generative KI verfolgen

Wenn Sie die Ausführung des LangGraph-Agentenaufrufs verfolgen möchten, erstellen Sie einen benutzerdefinierten Span um den Agentenaufruf:

Wenn Sie das vollständige Beispiel sehen möchten, wählen Sie in der Symbolleiste des Beispiels das GitHub-Logo aus.

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

Sie können den vorherigen Code an wichtigen Stellen in Ihrem Anwendungscode einfügen.

Weitere Informationen zum Hinzufügen benutzerdefinierter Spans und Messwerte finden Sie unter Benutzerdefinierte Traces und Messwerte in Ihre Anwendung hinzufügen.

Beispiel ausführen

Dieses Beispiel ist ein LangGraph-Agent, der mit OpenTelemetry instrumentiert wurde, um Traces und Logs mit Prompts und Antworten der generativen KI sowie Messwerte an Ihr Google Cloud Projekt zu senden.

Persona für einen LangGraph-Agenten

Der LangGraph-Agent ist als SQL-Experte definiert, der vollen Zugriff auf eine temporäre SQLite-Datenbank hat. Der Agent wird mit dem vorgefertigten ReAct-Agenten von LangGraph implementiert und greift mit dem SQLDatabaseToolkit auf die Datenbank zu, die anfangs leer ist.

Hinweis

Melden Sie sich in Ihrem Google Cloud Kontoan. Wenn Sie noch kein Konto bei Google Cloudhaben, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

Installieren Sie die Google Cloud CLI.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Erstellen oder wählen Sie ein Google Cloud Projektaus.

Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

• Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können ein beliebiges Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
• Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die resourcemanager.projects.create Berechtigung enthält. Rollen zuweisen.

Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit ihm verknüpften Ressourcen entfernen.

• Projekt erstellen: Google Cloud

  gcloud projects create PROJECT_ID

  Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud Projekt, das Sie erstellen.

• Wählen Sie das Google Cloud Projekt aus, das Sie erstellt haben:

  gcloud config set project PROJECT_ID

  Ersetzen Sie PROJECT_ID durch Ihren Google Cloud Projektnamen.

Prüfen Sie, ob die Abrechnung für Ihr Google Cloud Projektaktiviert ist.

Aktivieren Sie die Vertex AI, Service Usage, Telemetry, Cloud Logging, Cloud Monitoring und Cloud Trace APIs:

Rollen, die zum Aktivieren von APIs erforderlich sind

Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Rollen zuweisen.

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

Installieren Sie die Google Cloud CLI.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Erstellen oder wählen Sie ein Google Cloud Projektaus.

Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

• Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können ein beliebiges Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
• Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die resourcemanager.projects.create Berechtigung enthält. Rollen zuweisen.

Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit ihm verknüpften Ressourcen entfernen.

• Projekt erstellen: Google Cloud

  gcloud projects create PROJECT_ID

  Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud Projekt, das Sie erstellen.

• Wählen Sie das Google Cloud Projekt aus, das Sie erstellt haben:

  gcloud config set project PROJECT_ID

  Ersetzen Sie PROJECT_ID durch Ihren Google Cloud Projektnamen.

Prüfen Sie, ob die Abrechnung für Ihr Google Cloud Projektaktiviert ist.

Aktivieren Sie die Vertex AI, Service Usage, Telemetry, Cloud Logging, Cloud Monitoring und Cloud Trace APIs:

Rollen, die zum Aktivieren von APIs erforderlich sind

Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Rollen zuweisen.

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

1. Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die die Beispielanwendung zum Schreiben von Log-, Messwert- und Tracedaten benötigt:

   • Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)
   • Logautor (roles/logging.logWriter)
   • Monitoring-Messwert-Autor (roles/monitoring.metricWriter)
   • Vertex AI-Nutzer (roles/aiplatform.user)

   Diese Berechtigungen reichen aus, wenn Sie das Beispiel in der Cloud Shell, in Google Cloud Ressourcen oder in einer lokalen Entwicklungsumgebung ausführen.

   Wichtig: Produktionsanwendungen verwenden in der Regel ein Dienstkonto, um die Anmeldedaten bereitzustellen, die zum Schreiben von Log-, Messwert, und Tracedaten erforderlich sind. Weisen Sie in diesen Szenarien dem Dienstkonto die vorherigen Rollen zu.

2. Achten Sie darauf, dass Sie ein Kontingentprojekt angeben. Für die Vertex AI API (aiplatform.googleapis.com) muss ein Kontingentprojekt angegeben werden. Weitere Informationen finden Sie unter Kontingentprojekt festlegen. Mit dem folgenden Befehl kann beispielsweise ein Kontingentprojekt festgelegt werden.

   gcloud config set billing/quota_project PROJECT_ID

Beispiel ausführen

So führen Sie das Beispiel aus:

1. Klonen Sie in Cloud Shell das Repository:

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

2. Gehen Sie zum Beispielverzeichnis:

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

3. Konfigurieren Sie Umgebungsvariablen:

   # 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
   

   Wenn Sie ein anderes Modell verwenden möchten, bearbeiten Sie main.py. Achten Sie darauf, dass Ihr Modell den angegebenen Standort unterstützt. Informationen zu Modellen finden Sie unter Google-Modelle.

4. Erstellen Sie eine virtuelle Umgebung und führen Sie das Beispiel aus:

   uv run main.py
   

   Die Anwendung zeigt eine Meldung ähnlich der folgenden an:

   Starting agent using ephemeral SQLite DB.
   

5. Wenn Sie eine Datenbank erstellen möchten, geben Sie einen Wert in die Eingabeaufforderung Talk to the SQL agent >> ein und drücken Sie die Eingabetaste.

   Die vom Agenten ausgeführten Aktionen werden dann in Cloud Shell angezeigt.

   Das folgende Beispiel zeigt Interaktionen zwischen einem Nutzer und der Anwendung:

   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;
   
   

6. Zum Beenden geben Sie Ctrl-C ein.

Die von Agents für generative KI ausgeführten Aktionen sind nicht deterministisch. Daher kann es sein, dass Sie für denselben Prompt eine andere Antwort erhalten.

Traces, Messwerte und Logs ansehen

In diesem Abschnitt wird beschrieben, wie Sie Ereignisse der generativen KI ansehen können.

Hinweis

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Aufrufen von Log-, Messwert- und Tracedaten benötigen:

• Loganzeige (roles/logging.viewer)
• Monitoring Viewer (roles/monitoring.viewer)
• Cloud Trace User (roles/cloudtrace.user)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Telemetriedaten ansehen

Verwenden Sie die Seite Trace Explorer, um die Ereignisse der generativen KI anzusehen:

1. Rufen Sie in der Google Cloud Console die Seite Trace Explorer auf:

   Trace Explorer aufrufen

   Sie können diese Seite auch über die Suchleiste finden.

2. Wählen Sie in der Symbolleiste Filter hinzufügen und dann Span-Name und wählen Sie invoke agent aus.

   Im Abschnitt Beispiel ausführen wurde eine Beispielausführung beschrieben, bei der zwei Prompts an die Anwendung gesendet werden. Die folgende Abbildung zeigt die Seite Trace Explorer nach dem Filtern der Daten:

   

   Wenn Sie Cloud Trace noch nie verwendet haben, muss Google Cloud Observability eine Datenbank erstellen, um Ihre Tracedaten zu speichern. Das Erstellen der Datenbank kann einige Minuten dauern. Während dieser Zeit sind keine Tracedaten verfügbar.

3. Wählen Sie in der Tabelle Spans einen Span aus, um Ihre Span- und Logdaten zu untersuchen.

   Die Seite Details wird geöffnet. Auf dieser Seite werden der zugehörige Trace und seine Spans angezeigt. Die Tabelle auf der Seite enthält detaillierte Informationen zum ausgewählten Span. Zu diesen Informationen gehören:

   • Auf dem Tab Ein-/Ausgaben werden Ereignisse für Agents für generative KI angezeigt. Weitere Informationen zu diesen Ereignissen finden Sie unter Ereignisse der generativen KI ansehen.

     Der folgende Screenshot zeigt einen Trace, in dem ein Span den Namen invoke_agent hat. Dieser Span ruft Gemini auf. Der Gemini-Span enthält Ereignisse der generativen KI:

     

   • Auf dem Tab Logs und Ereignisse werden Logeinträge und Ereignisse aufgeführt, die mit dem Span verknüpft sind. Wenn Sie die Logdaten im Log-Explorer ansehen möchten, wählen Sie in der Symbolleiste dieses Tabs Logs ansehen aus.

     Die Logdaten enthalten die Antwort des LangGraph-Agents. Bei der Beispielausführung enthält die JSON-Nutzlast beispielsweise die folgenden Inhalte:

     {
       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
       }
     ...
     }
     

Das Beispiel ist so instrumentiert, dass Messwertdaten an Ihr Google Cloud Projektgesendet werden, aber es werden keine Messwerte generiert.