ADK-Anwendungen mit OpenTelemetry instrumentieren

In diesem Dokument wird beschrieben, wie Sie einen KI-Agenten instrumentieren, der mit dem Agent Development Kit (ADK) Framework erstellt wurde. Das ADK-Framework umfasst OpenTelemetry-Instrumentierung, mit der Telemetriedaten von wichtigen Aktionen des Agents erfasst werden. Wenn Sie die integrierte Instrumentierung aktivieren, werden Informationen wie Text-Prompts und Agent-Antworten an Ihr Google Cloud -Projekt gesendet. In diesem Dokument werden die erforderlichen Änderungen beschrieben und ein Link zu einer Beispielanwendung bereitgestellt.

Anwendungen, die das ADK 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.

Die standardmäßige Observability, die vom ADK bereitgestellt wird, reicht möglicherweise nicht für den Anwendungsfall Ihrer Anwendung aus. Sie können zusätzliche Instrumentierungsbibliotheken mit OpenTelemetry hinzufügen, um Telemetriedaten aus anderen Teilen Ihrer App oder Ihrer eigenen benutzerdefinierten Instrumentierung zu erfassen, um anwendungsspezifische Daten zu erfassen und eine detailliertere Beobachtbarkeit zu erhalten. In Ihrer Anwendung können Sie beispielsweise Instrumentierungscode schreiben, um:

• Ressourcenverbrauch von Agent-aufgerufenen Tools verfolgen.
• Anwendungsspezifische Validierungsfehler, Verstöße gegen Geschäftsregeln oder benutzerdefinierte Fehlerbehebungsmechanismen lassen sich nachverfolgen.
• Qualitätsbewertungen für Agentenantworten anhand Ihrer domainspezifischen Kriterien nachverfolgen.

Hinweis: In diesem Dokument wird davon ausgegangen, dass Sie ein ADK-Framework mit Version 1.17.0 oder höher verwenden.

Generative KI-Anwendung für die Erfassung von Telemetriedaten instrumentieren

So instrumentieren Sie Ihren KI-Agenten, um Log-, Messwert- und Trace-Daten zu erfassen:

1. OpenTelemetry-Pakete installieren
2. ADK-Umgebung konfigurieren

Im Rest dieses Abschnitts werden die vorherigen Schritte beschrieben.

OpenTelemetry-Pakete installieren

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

uv add 'google-adk>=1.17.0' \
  'opentelemetry-instrumentation-google-genai>=0.4b0' \
  'opentelemetry-instrumentation-sqlite3' \
  'opentelemetry-exporter-gcp-logging' \
  'opentelemetry-exporter-otlp-proto-grpc' \
  'opentelemetry-instrumentation-vertexai>=2.0b0'

Logdaten werden über die Cloud Logging API oder die Cloud Monitoring API an Ihr Google Cloud -Projekt gesendet. Mit der Bibliothek opentelemetry-exporter-gcp-logging werden Endpunkte in der Cloud Logging API aufgerufen.

Messwertdaten werden nicht erhoben. In Anwendungen, die keine Collector-basierte Lösung verwenden, ist in der Regel die opentelemetry-exporter-gcp-monitoring-Bibliothek enthalten. Mit dieser Bibliothek werden Endpunkte in der Cloud Monitoring API aufgerufen.

Trace-Daten werden über die Telemetry (OTLP) API an Google Cloud gesendet, die das OpenTelemetry Line Protocol implementiert. Die Bibliothek opentelemetry-exporter-otlp-proto-grpc ruft den Telemetry API-Endpunkt (OTLP) auf.

Ihre Tracedaten werden in einem Format gespeichert, das im Allgemeinen mit den Protobuf-Dateien übereinstimmt, die durch das OpenTelemetry Line Protocol definiert werden. 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 Tracedaten.

ADK-Umgebung konfigurieren

ADK-Framework-Versionen 1.17.0 und höher bieten integrierte Unterstützung für OpenTelemetry und das Senden von OpenTelemetry-Telemetriedaten anGoogle Cloud Observability. Konfigurieren Sie dazu Ihre ADK-Umgebung:

• Wenn Sie Ihre Anwendung mit dem Befehl adk web ausführen, fügen Sie das Flag --otel_to_cloud ein.

• Legen Sie in der Datei opentelemetry.env die folgenden Umgebungsvariablen fest:

  OTEL_SERVICE_NAME='adk-sql-agent'
  OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED='true'
  

• Konfigurieren Sie OpenTelemetry so, dass die neuesten semantischen Konventionen für generative KI verwendet werden.

  OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental'
  

• OpenTelemetry so konfigurieren, dass Nachrichten als Ereignisse angehängt werden

  OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT='EVENT_ONLY'
  

  Hinweis: Legen Sie den Wert dieser Variablen nicht auf true fest. Wenn Sie die neuesten semantischen Konventionen verwenden, führt das Festlegen des Werts dieser Variablen auf true zu einer ungültigen Konfiguration. Daher werden keine Log- und Trace-Daten erhoben.

  Weitere Informationen zu zulässigen aufgezählten Werten finden Sie unter genai/types.py.

• Wir empfehlen, der Datei opentelemetry.env auch die folgende Umgebungsvariable hinzuzufügen:

  ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS='false'
  

  Diese Umgebungsvariable hat folgende Funktion:

  • Verhindert, dass mit der ADK-Instrumentierung Spannenattribute angehängt werden, die das Attributgrößenlimit überschreiten.
  • Verhindert, dass personenidentifizierbare Informationen als Attribute an Spans angehängt werden.

• Möglicherweise müssen Sie weitere Umgebungsvariablen festlegen. Wenn Sie beispielsweise in der Gemini Enterprise Agent Platform bereitstellen, sollten Sie auch die folgende Umgebungsvariable festlegen:

  GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY='true'
  

Beispielanwendung herunterladen und ausführen

In diesem Beispielcode wird ein generativer KI-Agent implementiert, der mit dem ADK erstellt wurde. Der Agent ist mit OpenTelemetry instrumentiert und so konfiguriert, dass Messwerte, Traces und Logs an Ihr Google Cloud -Projekt gesendet werden. Die an Ihr Projekt gesendete Telemetrie umfasst Prompts und Antworten für generative KI.

Identität des ADK-Agents

Der KI-Agent ist als SQL-Experte definiert, der vollen Zugriff auf eine temporäre SQLite-Datenbank hat. Der Agent wird mit dem Agent Development Kit erstellt und greift über das SQLDatabaseToolkit auf eine Datenbank zu. Die Datenbank ist anfangs leer.

Hinweis

Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, 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 Sie ein Google Cloud Projekt oder wählen Sie eines aus.

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 jedes 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 Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

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 dem Projekt verknüpften Ressourcen entfernen.

• So erstellen Sie ein Google Cloud Projekt:

  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 von Ihnen erstellte Google Cloud Projekt 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 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 IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere 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

Erstellen Sie ein Google Cloud Projekt oder wählen Sie eines aus.

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 jedes 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 Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

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 dem Projekt verknüpften Ressourcen entfernen.

• So erstellen Sie ein Google Cloud Projekt:

  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 von Ihnen erstellte Google Cloud Projekt 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 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 IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere 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

1. 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 Tracedaten 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 sind ausreichend, 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 Tracedaten erforderlich sind. Weisen Sie in diesen Fällen dem Dienstkonto die vorherigen Rollen zu.

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

App starten

So starten Sie die Beispielanwendung:

1. Klonen Sie das Repository in Cloud Shell:

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

2. Gehen Sie zum Beispielverzeichnis:

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

   Das Beispiel enthält eine .env-Datei, in der zwei Umgebungsvariablen festgelegt werden. Eine Variable steuert, welche Endpunkte das SDK verwendet. Mit der anderen Variablen wird ein Standort festgelegt.

   Wenn Sie ein anderes Modell verwenden möchten, bearbeiten Sie main.py. Das ausgewählte Modell muss den in der Datei .env angegebenen Standort unterstützen. Informationen zu Modellen finden Sie unter Google-Modelle.

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

   uv run --env-file opentelemetry.env adk web --otel_to_cloud
   

   In der Anwendung wird eine Meldung ähnlich der folgenden angezeigt:

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

4. Wenn Sie mit dem Agent interagieren möchten, wählen Sie die URL aus, die in der Ausgabe des vorherigen Schritts angezeigt wird.

5. Maximieren Sie App auswählen und wählen Sie sql_agent aus der Liste der Kundenservicemitarbeiter aus.

   Hinweis :Für diese Anwendung ist Cross-Origin Resource Sharing (CORS) erforderlich. Wenn Sie einen Prompt eingeben und CORS blockiert wird, zeigt die Anwendung die Meldung Failed to create session an und in der Befehlszeile wird angezeigt, dass Befehle abgelehnt wurden: POST /apps/sql_agent/users/user/sessions HTTP/1.1" 403 Forbidden.
   Sie können CORS aktivieren, indem Sie dem Befehl, mit dem das Beispiel ausgeführt wird, Folgendes anhängen:
   

   --allow_origins="regex:.*"

Mit dem Agent interagieren

Wenn Sie mit dem KI-Agenten interagieren möchten, stellen Sie ihm eine Frage oder geben Sie ihm einen Befehl. Sie könnten beispielsweise fragen:

What can you do for me ?

Da sql_agent die Rolle eines SQL-Experten hat, können Sie es auch bitten, Tabellen für Ihre Anwendungen zu erstellen und Abfragen zu schreiben, um die erstellten Tabellen zu bearbeiten. Der Agent kann nur eine temporäre Datenbank erstellen, die auf einer .db-Datei basiert, die auf dem Computer erstellt wird, auf dem die Anwendung ausgeführt wird.

Im Folgenden wird eine Beispielinteraktion zwischen dem sql_agent und dem Nutzer veranschaulicht:

Die von generativen KI-Agenten ausgeführten Aktionen sind nicht deterministisch. Sie erhalten also möglicherweise eine andere Antwort auf denselben Prompt.

App schließen

Geben Sie zum Beenden der Anwendung Ctrl-C in der Shell ein, die zum Starten der Anwendung verwendet wurde.

Traces, Messwerte und Logs ansehen

In diesem Abschnitt wird beschrieben, wie Sie Ereignisse im Zusammenhang mit generativer 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 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

So rufen Sie die von der Anwendung erstellten Ereignisse für generative KI auf:

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

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

   Das folgende Bild zeigt die Seite Trace Explorer nach dem Filtern der Daten:

   

   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. In dieser Zeit sind keine Tracedaten verfügbar.

3. Wenn Sie Ihre Spannen- und Logdaten ansehen möchten, wählen Sie in der Tabelle Spannen eine Spanne 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 Zeitraum angezeigt. Dazu gehören:

   • Auf dem Tab Ein-/Ausgaben werden Ereignisse für generative KI-Agents angezeigt. Weitere Informationen zu diesen Ereignissen

     Der folgende Screenshot zeigt einen Trace, in dem ein Span den Namen call_llm hat. Dieser Bereich ruft das LLM (Large Language Model) auf, das diesen Agenten unterstützt. In diesem Beispiel ist es Gemini. Der Gemini-Zeitraum umfasst Ereignisse im Zusammenhang mit generativer KI:

     

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

     Die Protokolldaten enthalten die Antwort von sql_agent. Für den Beispiel-Lauf enthält die JSON-Nutzlast beispielsweise den folgenden Inhalt:

     {
       "logName": "projects/my-project/logs/otel_python_inprocess_log_name_temp",
       "jsonPayload": {
         "content": {
           "parts": [
             0: {
               "text": "Now I can create the table."
             }
             1: {1}
             ],
           "role": "model"
         }
       },
       ...
     }
     

Das Beispiel ist so instrumentiert, dass Messwertdaten an Ihr Google Cloud -Projekt gesendet werden, es werden jedoch keine Messwerte generiert.