ADK-Anwendungen mit OpenTelemetry instrumentieren

In diesem Dokument wird beschrieben, wie Sie einen KI-Agenten instrumentieren, der mit dem Agent Development Kit (ADK) erstellt wurde. Das ADK-Framework enthält OpenTelemetry-Instrumentierung, die Telemetriedaten zu den wichtigsten Aktionen des Agenten erfasst. 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 Beobachtbarkeit, die das ADK bietet, ist für den Anwendungsfall Ihrer Anwendung möglicherweise nicht ausreichend. Sie können zusätzliche Instrumentierungsbibliotheken mit OpenTelemetry hinzufügen, um Telemetriedaten aus anderen Teilen Ihrer Anwendung zu erfassen, oder Ihre eigene benutzerdefinierte Instrumentierung verwenden, um anwendungsspezifische Daten zu erfassen und so eine detailliertere Beobachtbarkeit zu erhalten. Sie können beispielsweise Instrumentierungscode in Ihre Anwendung schreiben, um:

  • Ressourcenverbrauch von Tools verfolgen, die vom KI-Agenten aufgerufen werden.
  • Anwendungsspezifische Validierungsfehler, Verstöße gegen Geschäftsregeln oder benutzerdefinierte Mechanismen zur Fehlerbehebung verfolgen.
  • Verfolgen Sie die Qualitätsbewertungen für KI-Agentenantworten anhand Ihrer domainspezifischen Kriterien.

Anwendung mit generativer KI 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 weiteren Verlauf dieses Abschnitts werden die vorherigen Schritte beschrieben.

OpenTelemetry-Pakete installieren

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

uv add 'google-adk>=2.12.0' \
  'opentelemetry-instrumentation-google-genai>=0.7b1' \
  'opentelemetry-instrumentation-sqlite3>=0.63b1' \
  'opentelemetry-exporter-otlp-proto-grpc>=1.42.1' \
  'opentelemetry-exporter-otlp-proto-http>=1.42.1' \
  'opentelemetry-instrumentation-vertexai>=2.0b0'

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.

ADK-Umgebung konfigurieren

ADK-Framework-Versionen ab 1.17.0 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'

  • Konfigurieren Sie OpenTelemetry so, dass Nachrichten als Ereignisse angehängt werden.

    OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT='EVENT_ONLY'

    Weitere Informationen zu zulässigen Aufzählungswerten 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 bewirkt Folgendes:

    • Verhindert, dass die ADK-Instrumentierung Span-Attribute anhängt, die das Limit für die Attributgröße überschreiten.
    • Verhindert, dass personenidentifizierbare Informationen als Attribute an Spans angehängt werden.

  • Möglicherweise müssen Sie weitere Umgebungsvariablen festlegen. Wenn Sie beispielsweise auf 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 er Messwerte, Traces und Logs an Ihr Google Cloud -Projekt sendet. Die an Ihr Projekt gesendeten Telemetriedaten enthalten Prompts und Antworten der generativen KI.

Persona für einen ADK-Agenten

Der generative KI-Agent ist als SQL-Experte definiert, der vollen Zugriff auf eine sitzungsspezifische 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

  1. Installieren Sie die Google Cloud CLI.

  2. Konfigurieren Sie die gcloud CLI für die Verwendung Ihrer föderierten Identität.

    Weitere Informationen finden Sie unter Mit Ihrer föderierten Identität in der gcloud CLI anmelden.

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

    gcloud init

  4. 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 Google Cloud aus:

      gcloud config set project PROJECT_ID

      Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

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

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

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

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

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

Anwendung starten

So starten Sie die Beispielanwendung:

  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/adk-sql-agent

    Das Beispiel enthält eine .env-Datei, in der zwei Umgebungsvariablen festgelegt werden. Eine Variable steuert, welche Endpunkte das SDK verwendet. Die andere Variable legt einen Standort fest.

    Wenn Sie ein anderes Modell verwenden möchten, bearbeiten Sie main.py. Achten Sie darauf, dass das ausgewählte Modell den in der Datei .env angegebenen Standort unterstützt. 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

    Die Anwendung zeigt eine Meldung ähnlich der folgenden an:

    Application startup complete
Uvicorn running on http://127.0.0.1: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 App auswählen und wählen Sie sql_agent aus der Liste der Agenten aus.

Mit dem KI-Agenten interagieren

Wenn Sie mit dem KI-Agenten interagieren möchten, stellen Sie ihm eine Frage oder geben Sie ihm einen Befehl. Sie könnten zum Beispiel 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 für die erstellten Tabellen zu schreiben. Der Agent kann nur eine sitzungsspezifische Datenbank erstellen, die durch eine .db-Datei unterstützt wird, 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 dargestellt:

Anzeige der Interaktion mit dem sql_agent.

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.

Anwendung beenden

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

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:

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 der generativen KI auf der Seite Trace Explorer 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, dann Span-Name und anschließend call_llm aus.

    Die folgende Abbildung zeigt die Seite Trace-Explorer nach dem Filtern der Daten:

    Anzeige von Trace-Spans.

    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.

  3. 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 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:

      Anzeige von Ereignissen mit generativer 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. 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": {
    "content": {
      "parts": [
        0: {
          "text": "Now I can create the table."
        }
        1: {1}
        ],
      "role": "model"
    }
  },
  ...
}