Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

LangGraph ReAct-Agent mit OpenTelemetry instrumentieren

In diesem Dokument werden die Schritte zur Instrumentierung eines LangGraph-ReAct-Agenten mit OpenTelemetry beschrieben, um Telemetriedaten vom Agenten zu erfassen. Nutzer-Prompts sowie Antworten und Auswahlmöglichkeiten des KI-Agenten sind in der Telemetrie als Attribute enthalten, die an Spans angehängt sind. Die Antworten des KI-Agenten 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 Text-Prompts 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 mit generativer KI für die Erfassung von Telemetriedaten instrumentieren

So instrumentieren Sie Ihre generative KI-Anwendung, um Log-, Messwert- und Trace-Daten zu erfassen:

OpenTelemetry-Pakete installieren
OpenTelemetry zum Erfassen und Senden von Telemetriedaten konfigurieren
Aufruf des generativen KI-Agenten verfolgen

OpenTelemetry-Pakete installieren

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

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

Log-, Messwert- und Trace-Daten werden mithilfe der Telemetry (OTLP) API, die das OpenTelemetry Protocol implementiert, an Google Cloud gesendet. Die Bibliothek opentelemetry-exporter-otlp-proto-grpc ruft den Telemetrie-API-Endpunkt (OTLP) auf.

Ihre Trace-Daten werden in einem Format gespeichert, das im Allgemeinen mit den Proto-Dateien des OpenTelemetry-Protokolls übereinstimmt. Felder können jedoch vor dem Speichern von einem OpenTelemetry-spezifischen Datentyp in einen JSON-Datentyp konvertiert werden. Weitere Informationen zum Speicherformat finden Sie unter Schema für Trace-Daten.

OpenTelemetry für das Erfassen und Senden von Telemetriedaten konfigurieren

Konfigurieren Sie im Initialisierungscode Ihres LangGraph-Agents OpenTelemetry so, dass Telemetriedaten erfasst und an Ihr Google Cloud -Projekt gesendet 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(
            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()

Aufruf des generativen KI-Agenten 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 Ihren Anwendungscode einfügen.

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

Beispiel ausführen

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

LangGraph-Agenten-Persona

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

Hinweis

Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie einfach 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

Google Cloud -Projekt erstellen oder auswählen.

Erforderliche Rollen zum Auswählen oder Erstellen eines Projekts

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

Erstellen Sie ein Projekt in Google Cloud :
```
gcloud projects create PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch einen Namen für das Projekt in Google Cloud , das Sie erstellen.
Wählen Sie das von Ihnen erstellte Projekt in Google Cloud aus:
```
gcloud config set project PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

Prüfen Sie, ob die Abrechnung für Ihr Google Cloud -Projekt aktiviert ist.

Aktivieren Sie die APIs für Vertex AI, Service Usage, Telemetrie, Cloud Logging, Cloud Monitoring und Cloud Trace, falls sie noch nicht aktiviert sind:

Erforderliche Rollen zum Aktivieren von APIs

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 Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

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

Google Cloud -Projekt erstellen oder auswählen.

Erforderliche Rollen zum Auswählen oder Erstellen eines Projekts

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

Erstellen Sie ein Projekt in Google Cloud :
```
gcloud projects create PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch einen Namen für das Projekt in Google Cloud , das Sie erstellen.
Wählen Sie das von Ihnen erstellte Projekt in Google Cloud aus:
```
gcloud config set project PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

Prüfen Sie, ob die Abrechnung für Ihr Google Cloud -Projekt aktiviert ist.

Aktivieren Sie die APIs für Vertex AI, Service Usage, Telemetrie, Cloud Logging, Cloud Monitoring und Cloud Trace, falls sie noch nicht aktiviert sind:

Erforderliche Rollen zum Aktivieren von APIs

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

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie benötigen, damit die Beispielanwendung Log-, Messwert- und Trace-Daten schreiben kann:
- Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)
- Log-Autor (roles/logging.logWriter)
- Monitoring-Messwert-Autor (roles/monitoring.metricWriter)
- Vertex AI-Nutzer (roles/aiplatform.user)
Diese Berechtigungen reichen aus, wenn Sie das Beispiel in Cloud Shell, auf 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 Trace-Daten erforderlich sind. Weisen Sie dem Dienstkonto in diesen Szenarien die vorherigen Rollen zu.
Geben Sie ein Kontingentprojekt an. 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:

Klonen Sie in Cloud Shell das Repository:

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

Gehen Sie zum Beispielverzeichnis:

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

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 von Ihnen angegebenen Standort unterstützt. Informationen zu Modellen finden Sie unter Google-Modelle.

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.
```

Geben Sie zum Erstellen einer Datenbank einen Wert in den Prompt Mit dem SQL-Agenten sprechen >> ein und drücken Sie die Eingabetaste.

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

Im Folgenden werden Beispielinteraktionen zwischen einem Nutzer und der Anwendung veranschaulicht:

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;

Zum Beenden geben Sie Ctrl-C ein.

Die von generativen KI-Agenten 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 aufrufen 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 Ihrer Log-, Messwert- und Trace-Daten benötigen:

Loganzeige (roles/logging.viewer)
Monitoring-Betrachter (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

Wenn Sie sich die Ereignisse der generativen KI ansehen möchten, verwenden Sie die Seite Trace Explorer:

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

Sie können diese Seite auch über die Suchleiste finden.
Wählen Sie in der Symbolleiste Filter hinzufügen, dann Span-Name und anschließend invoke agent aus.

Der Abschnitt Beispiel ausführen enthielt eine Beispielausführung, bei der zwei Prompts an die Anwendung gesendet werden. Im Folgenden wird die Seite Trace Explorer nach dem Filtern der Daten dargestellt:

Wenn Sie Cloud Trace noch nie verwendet haben, muss Google Cloud Observability eine Datenbank zum Speichern Ihrer Trace-Daten erstellen. Das Erstellen der Datenbank kann einige Minuten dauern. Während dieser Zeit sind keine Trace-Daten verfügbar.
Wenn Sie Ihre Span- und Logdaten untersuchen möchten, wählen Sie in der Tabelle Spans einen Span aus.

Die Seite Details wird geöffnet. Auf dieser Seite werden der zugehörige Trace und seine Spans angezeigt. In der Tabelle auf der Seite werden detaillierte Informationen zum ausgewählten Span angezeigt. Dazu gehören:
- Auf dem Tab Eingaben/Ausgaben werden Ereignisse für generative KI-Agenten angezeigt. Weitere Informationen zu diesen Ereignissen finden Sie unter Ereignisse der generativen KI ansehen.
  
  Der folgende Screenshot zeigt einen Trace, bei 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. Für die Beispielausführung enthält die JSON-Nutzlast beispielsweise den folgenden Inhalt:
```
{
  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 -Projekt gesendet werden, aber es werden keine Messwerte generiert.

LangGraph ReAct-Agent mit OpenTelemetry instrumentieren Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Anwendung mit generativer KI für die Erfassung von Telemetriedaten instrumentieren

OpenTelemetry-Pakete installieren

OpenTelemetry für das Erfassen und Senden von Telemetriedaten konfigurieren

Aufruf des generativen KI-Agenten verfolgen

Beispiel ausführen

LangGraph-Agenten-Persona

Hinweis

Beispiel ausführen

Traces, Messwerte und Logs ansehen

Hinweis

Telemetriedaten ansehen

LangGraph ReAct-Agent mit OpenTelemetry instrumentieren