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. Mit dieser Instrumentierung, die OpenTelemetry nutzt, können Sie Nutzer-Prompts, Agent-Antworten und Agent-Auswahlen erfassen.

Das ADK-Framework selbst ist mit OpenTelemetry instrumentiert, um Telemetriedaten aus wichtigen Schritten der Ausführung Ihres Agents zu erfassen. So erhalten Sie sofort wertvolle Informationen zur Anwendungsbeobachtung. Diese Beobachtbarkeit reicht jedoch 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. Alternativ können Sie Ihre eigene benutzerdefinierte Instrumentierung verwenden, um anwendungsspezifische Daten zu erfassen und so eine detailliertere Beobachtbarkeit zu erreichen.

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.
  • Sie können die Qualitätsfaktoren für Agentenantworten anhand Ihrer domainspezifischen Kriterien nachverfolgen.

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. OpenTelemetry zum Erfassen und Senden von Telemetriedaten konfigurieren
  3. Benutzerdefinierten Einstiegspunkt schreiben, um konfigurierte OpenTelemetry-Daten einzufügen

Im Rest dieses Abschnitts werden die vorherigen Schritte beschrieben.

OpenTelemetry-Pakete installieren

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

pip install 'opentelemetry-instrumentation-google-genai' \
  '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 mithilfe der Cloud Logging API oder der Cloud Monitoring API an Ihr Google Cloud -Projekt gesendet. Die Bibliotheken opentelemetry-exporter-gcp-logging und opentelemetry-exporter-gcp-monitoring rufen Endpunkte in diesen APIs auf.

Trace-Daten werden mit der Telemetry (OTLP) API, die das OTLP-Format unterstützt, an Google Cloud gesendet. Über diesen Endpunkt empfangene Daten werden ebenfalls im OTLP-Format gespeichert. Die Bibliothek opentelemetry-exporter-otlp-proto-grpc ruft den Telemetry-API-Endpunkt (OTLP) auf.

OpenTelemetry für die Erfassung und das Senden von Telemetriedaten konfigurieren

Fügen Sie dem Initialisierungscode Ihres ADK-Agents Code hinzu, um OpenTelemetry so zu konfigurieren, dass Telemetriedaten erfasst und an Ihr Google Cloud -Projekt gesendet werden:

Wenn Sie das vollständige Beispiel sehen möchten, klicken Sie auf  Mehr und wählen Sie dann Auf GitHub ansehen aus.

def setup_opentelemetry() -> None:
    credentials, project_id = google.auth.default()
    resource = Resource.create(
        attributes={
            SERVICE_NAME: "adk-sql-agent",
            # The project to send spans to
            "gcp.project_id": project_id,
        }
    )

    # 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)

    event_logger_provider = EventLoggerProvider(logger_provider)
    events.set_event_logger_provider(event_logger_provider)

    reader = PeriodicExportingMetricReader(CloudMonitoringMetricsExporter())
    meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
    metrics.set_meter_provider(meter_provider)

    # Load instrumentors
    SQLite3Instrumentor().instrument()
    # ADK uses Vertex AI and Google Gen AI SDKs.
    VertexAIInstrumentor().instrument()
    GoogleGenAiSdkInstrumentor().instrument()

Benutzerdefinierten Einstiegspunkt für die Verwendung von konfiguriertem OpenTelemetry schreiben

Wenn Sie OpenTelemetry für die Instrumentierung verwenden möchten, erstellen Sie einen benutzerdefinierten Einstiegspunkt für Ihre ADK-Anwendung. Der benutzerdefinierte Einstiegspunkt muss OpenTelemetry konfigurieren, bevor er den ADK-Agent startet.

In der Beispielanwendung fungiert die Methode main als benutzerdefinierter Einstiegspunkt, der OpenTelemetry initialisiert und dann den FastAPI-Server startet, über den Sie mit dem Agent interagieren können.

Wenn Sie das vollständige Beispiel sehen möchten, klicken Sie auf  Mehr und wählen Sie dann Auf GitHub ansehen aus.

def main() -> None:
    # Make sure to set:
    # OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
    # OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
    # in order to full prompts and responses and logs messages.
    # For this sample, these can be set by loading the `opentelemetry.env` file.
    setup_opentelemetry()

    # Call the function to get the FastAPI app instance.
    # Ensure that the agent director name is the name of directory containing agent subdirectories,
    # where each subdirectory represents a single agent with __init__.py and agent.py files.
    # For this example this would be the current directory containing main.py.
    # Note: Calling this method attempts to set the global tracer provider, which has already been
    # set by the setup_opentelemetry() function.
    app = get_fast_api_app(
        agents_dir=AGENT_DIR,
        session_service_uri=SESSION_DB_URL,
        allow_origins=ALLOWED_ORIGINS,
        web=SERVE_WEB_INTERFACE,
    )

    # Lauch the web interface on port 8080.
    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

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 gesendeten Telemetriedaten enthalten Prompts und Antworten für generative KI.

ADK-Agent-Persona

Der GenAI-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 mit dem SQLDatabaseToolkit auf eine Datenbank zu. Die Datenbank ist anfangs leer.

Hinweise

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Enable the Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

    Enable the APIs

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

    4. App starten

    So starten Sie die Beispielanwendung:

    1. In the Google Cloud console, activate Cloud Shell.

      Activate Cloud Shell

      At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    2. Klonen Sie das Repository:

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

    3. Gehen Sie zum Beispielverzeichnis:

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

    4. 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) python main.py

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

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

    5. Wenn Sie mit dem Agent interagieren möchten, öffnen Sie einen Browser und rufen Sie die im vorherigen Schritt aufgeführte Adresse auf.

    6. Maximieren Sie Agent auswählen und wählen Sie sql_agent aus der Liste der Agents aus.

      7. Mit dem Agent interagieren

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

      What can you do for me ?

      Da sql_agent die Rolle eines SQL-Experten hat, können Sie es beispielsweise 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 ein Beispiel für die Interaktion zwischen dem sql_agent und dem Nutzer veranschaulicht:

      Create a table for me to store weather data and also insert sample data in
the table. At the end show all data in the table you created.

      Anzeige der Interaktion mit dem sql_agent.

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

      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.

      Hinweise

      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:

      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 aus, dann Span-Name und schließlich call_llm.

        Das folgende Bild 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. 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 für den ausgewählten Zeitraum angezeigt. Zu diesen Informationen gehören:

        • Auf dem Tab GenAI werden Ereignisse für Agents für generative KI 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-Span enthält Ereignisse der generativen KI:

          Anzeige von Veranstaltungen zu 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 aufrufen möchten, wählen Sie in der Symbolleiste dieses Tabs Logs ansehen aus.

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

          {
  "logName": "projects/my-project/logs/otel_python_inprocess_log_name_temp",
  "jsonPayload": {
    "content": {
      "role": "model",
      "parts": [
        {
          "executable_code": null,
          "inline_data": null,
          "thought": null,
          "video_metadata": null,
          "code_execution_result": null,
          "function_response": null,
          "thought_signature": null,
          "text": "Okay, I will create a table named `weather` with columns `id`, `city`, `temperature`, and `date`. Then I will insert some sample rows into the table and display all the data in the table.\n",
          "file_data": null,
          "function_call": null
        }
      ]
    }
  },
  ...
}

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