ADK-Anwendungen mit OpenTelemetry instrumentieren

Vorschau

Diese Funktion unterliegt den „Bedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

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

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

Die standardmäßige Beobachtbarkeit, die von 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 zu erfassen, oder Ihre eigene benutzerdefinierte Instrumentierung verwenden, um anwendungsspezifische Daten zu erfassen und so eine detailliertere Beobachtbarkeit zu erhalten. In Ihrer Anwendung können Sie beispielsweise Instrumentierungscode schreiben, um Folgendes zu tun:

• Ressourcenverbrauch von von Agenten aufgerufenen Tools verfolgen.
• Anwendungsspezifische Validierungsfehler, Verstöße gegen Geschäftsregeln oder benutzerdefinierte Mechanismen zur Fehlerbehebung verfolgen.
• Qualitätsbewertungen für Agentenantworten basierend auf Ihren domainspezifischen Kriterien verfolgen.

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

Generative KI-Anwendung instrumentieren, um Telemetriedaten zu erfassen

So instrumentieren Sie Ihren KI-Agenten, um Log-, Messwert- und Tracedaten 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-Instrumentierungen und ‑Exporterpakete hinzu:

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

Log- und Messwertdaten werden über die Cloud Logging API oder die Cloud Monitoring API an Ihr Google Cloud Projekt gesendet. Die opentelemetry-exporter-gcp-logging und opentelemetry-exporter-gcp-monitoring Bibliotheken rufen Endpunkte in diesen APIs auf.

Tracedaten werden über die Telemetry (OTLP) API angesendet, die das OpenTelemetry OTLP-Protokoll implementiert. Google Cloud 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 vom OpenTelemetry OTLP-Protokoll definiert 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.

ADK-Umgebung konfigurieren

Die ADK-Framework-Versionen 1.17.0 und höher bieten integrierte Unterstützung für OpenTelemetry und das Senden von OpenTelemetry-Telemetriedaten an Google Cloud Observability. Dazu konfigurieren Sie Ihre ADK-Umgebung:

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

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

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

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

  ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false
  

  Diese Umgebungsvariable hat folgende Auswirkungen:

  • Verhindert, dass die ADK-Instrumentierung Span-Attribute anhängt, die das Größenlimit für Attribute überschreiten.
  • Verhindert, dass personenbezogene Informationen (PII) als Attribute an Spans angehängt werden.

Beispielanwendung herunterladen und ausführen

Dieser Beispielcode implementiert einen generativen KI-Agenten, der mit 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 gesendeten Telemetriedaten enthalten Prompts und Antworten der generativen KI.

ADK-Agentenpersona

Der generative KI-Agent ist als SQL-Experte definiert, der vollen Zugriff auf eine kurzlebige SQLite-Datenbank hat. Der Agent wurde 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 noch kein Konto bei Google Cloudhaben, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis zu sehen und zu bewerten. 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 Projekt 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 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 den Namen Ihres Google Cloud Projekts.

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

Aktivieren Sie die Vertex AI, 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. Rollen zuweisen.

gcloud services enable aiplatform.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 Projekt 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 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 den Namen Ihres Google Cloud Projekts.

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

Aktivieren Sie die Vertex AI, 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. Rollen zuweisen.

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

1. Wenn Sie das Beispiel in Cloud Shell, auf Google Cloud Ressourcen oder in einer lokalen Entwicklungsumgebung ausführen, reichen die in diesem Abschnitt aufgeführten Berechtigungen aus. Bei Produktionsanwendungen stellt in der Regel ein Dienstkonto die Anmeldedaten zum Schreiben von Log-, Messwert- und Tracedaten bereit.

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

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

Anwendung starten

So starten Sie die Beispielanwendung:

1. Geben Sie in Cloud Shell den folgenden Befehl ein:

   git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python.git
   

2. Gehen Sie zum Beispielverzeichnis:

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

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

   python -m venv venv/
   source venv/bin/activate
   pip install -r requirements.txt
   env $(cat opentelemetry.env | xargs) adk web --otel_to_cloud
   

   Die Anwendung zeigt eine Meldung ähnlich der folgenden an:

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

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

5. Maximieren Sie Agent auswählen und wählen Sie sql_agent aus der Liste der Agenten aus.

Mit dem Agenten interagieren

Wenn Sie mit dem Agenten interagieren möchten, stellen Sie ihm eine Frage oder geben Sie ihm einen Befehl. Sie können beispielsweise die folgende Frage stellen:

What can you do for me ?

Da der sql_agent die Persona eines SQL-Experten hat, können Sie ihn auch bitten, Tabellen für Ihre Anwendungen zu erstellen und Abfragen zu schreiben, um mit den erstellten Tabellen zu arbeiten. Der Agent kann nur eine kurzlebige Datenbank erstellen, die durch eine .db-Datei gesichert wird, die auf dem Computer erstellt wird, auf dem die Anwendung ausgeführt wird.

Das folgende Beispiel zeigt eine Interaktion zwischen dem sql_agent und dem Nutzer:

Die Aktionen von generativen KI-Agenten sind nicht deterministisch. Daher kann es sein, dass Sie für denselben Prompt eine andere Antwort erhalten.

App schließen

Wenn Sie die Anwendung beenden möchten, geben Sie in der Shell, die zum Starten der Anwendung verwendet wurde, Ctrl-C ein.

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:

• Logs Viewer (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 von der Anwendung erstellten Ereignisse der generativen KI anzusehen:

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 aus, wählen Sie Span-Name aus und wählen Sie dann call_llm aus.

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

3. Wählen Sie in der Tabelle Spans einen Span aus, um die 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. Dazu gehören:

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

     Die folgende Abbildung zeigt einen Trace, in dem ein Span den Namen call_llm hat. Dieser Span ruft das LLM (Large Language Model) auf, das diesen Agenten unterstützt. In diesem Beispiel ist es Gemini. 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 sql_agent. 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": {
         "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, aber es werden keine Messwerte generiert.