Beobachtbarkeit für Entwickler von KI-Agenten

Wenn Sie KI-Agenten entwickeln, können Sie Ihre Anwendungen mit OpenTelemetry instrumentieren, um zu beobachten, wie Ihre Agenten Schlussfolgerungen ziehen, Tools aufrufen und auf Prompts reagieren. In diesem Leitfaden wird erläutert, wie Sie Agenten-Telemetriedaten mit Frameworks wie LangGraph und dem Agent Development Kit (ADK) erfassen und multimodale Prompts und Antworten in Cloud Trace analysieren.

Agenten instrumentieren, um ihr Verhalten zu verstehen

Wenn Sie generative KI-Anwendungen entwickeln oder verwalten, werden in den Telemetriedaten die logischen Schritte, Toolaufrufe und externen Interaktionen Ihrer autonomen Agenten erfasst. Diese Daten sind aus folgenden Gründen nützlich:

  • Nicht deterministisches Verhalten verstehen: Da der Reasoning-Prozess eines KI-Agenten nicht deterministisch ist, ist die Telemetrie die einzige zuverlässige Möglichkeit, die Entscheidungen eines KI-Agenten und die von ihm ausgewählten Tools zu prüfen.
  • Fehler beheben und diagnostizieren: Mit Traces können Sie fehlgeschlagene API-Anfragen, Endlosschleifen und Latenzengpässe in verteilten Agent-Workflows identifizieren.
  • Governance unterstützen und Traffic validieren: Mit Telemetrie können Sie Kommunikationsflüsse visualisieren, z. B. in der Anwendungstopologie, um zu prüfen, ob Ihre Agenten nur mit autorisierten Agenten, MCP-Servern und externen Endpunkten kommunizieren.
  • Ausgabequalität und Kosten bewerten: Durch das Erfassen von Prompts, Antworten und Tokennutzung können Sie die Genauigkeit des Modells bewerten, Halluzinationen erkennen und den Ressourcenverbrauch optimieren.

Wie Sie Ihre generativen KI-Anwendungen instrumentieren können

Bei der Instrumentierung Ihrer Anwendung werden Telemetriedaten generiert und an ein Ziel gesendet, an dem die Daten gespeichert, abgefragt und analysiert werden können. Wenn Ihre Instrumentierung beispielsweise Telemetriedaten an Ihr Google Cloud -Projekt sendet, können Sie diese Daten mit Google Cloud Observability ansehen und analysieren.

Cloud Trace extrahiert automatisch Ereignisse aus Spans, die von generativen KI-Anwendungen geschrieben wurden, wenn diese Spans den semantischen Konventionen für Spans und Ereignisse entsprechen. Informationen zu diesen Konventionen finden Sie in den folgenden Dokumenten:

Cloud Trace kann auch multimodale Prompts und Antworten anzeigen. In diesem Szenario werden Ihre Prompts und Antworten nicht an Ihre Trace-Daten angehängt. Stattdessen werden sie in einem Cloud Storage-Bucket gespeichert. Weitere Informationen zu dieser Konfiguration finden Sie unter Multimodale Prompts und Antworten erfassen und ansehen.

Best Practices

Wir empfehlen, Ihre Anwendung mit OpenTelemetry zu instrumentieren. OpenTelemetry ist ein Open-Source-Projekt, das ein einheitliches Framework für die Anwendungsinstrumentierung bietet. In den Instrumentierungsbeispielen in diesem Dokument wird OpenTelemetry verwendet.

Wir empfehlen außerdem, Ihre Prompts und Antworten in einem Cloud Storage-Bucket statt in einem Logeintrag zu speichern:

  • Sie haben eine detaillierte Kontrolle über den Inhalt im Cloud Storage-Bucket. Sie können beispielsweise einzelne Unterhaltungen löschen, die in einem Bucket gespeichert sind. Einzelne Logeinträge können jedoch nicht gelöscht werden.

  • In Cloud Storage-Buckets können Objekte gespeichert werden, die viel größer sind als die maximale Größe eines Logeintrags, die auf 256 KiB begrenzt ist. Cloud Logging antwortet mit einem INVALID_ARGUMENT-Fehler und verwirft Daten, wenn die empfangenen Daten die maximale Größe für Logeinträge überschreiten. Wenn der Befehl ohne Fehler abgeschlossen wird, aber einzelne Felder ihre Größenbeschränkungen überschreiten, werden diese Daten von Cloud Logging gekürzt.

Informationen zu OpenTelemetry finden Sie unter Was ist OpenTelemetry?.

Instrumentierungsbeispiele

Informationen zu den ersten Schritten mit der Agenten-Instrumentierung finden Sie in den folgenden Beispielanwendungen und Anleitungen:

  • Unter Multimodale Prompts und Antworten erfassen und ansehen wird beschrieben, wie Sie einen LangGraph ReAct-Agenten oder einen mit dem ADK erstellten generativen KI-Agenten so konfigurieren, dass multimodale Prompts und Antworten erfasst werden. Außerdem wird Folgendes beschrieben:

    • Prompts und Antworten in einem Cloud Storage-Bucket speichern.
    • Prompts und Antworten auf der Seite Trace-Explorer ansehen
    • Prompts und Antworten mit BigQuery analysieren
    • Prompts und Antworten mit dem Vertex AI SDK für Python bewerten.

  • In LangGraph-ReAct-Agent mit OpenTelemetry instrumentieren wird beschrieben, wie Sie OpenTelemetry verwenden, um eine generative KI-Anwendung zu instrumentieren, die das LangChain- oder LangGraph-Framework verwendet. Außerdem wird auf eine Beispielanwendung verwiesen, die Sie herunterladen und ausführen können. Die Beispielanwendung erfasst Text-Prompts und Antworten.

  • Unter ADK-Anwendungen mit OpenTelemetry instrumentieren wird beschrieben, wie Sie die integrierte Instrumentierung aktivieren, die Telemetriedaten zu den wichtigsten Aktionen des Agenten erfasst. Die Telemetriedaten umfassen Text-Prompts und Antworten des KI-Agenten. Außerdem enthält es einen Link zu einer Beispielanwendung, die Sie herunterladen und ausführen können. Die Beispielanwendung erfasst Text-Prompts und Antworten.

  • Unter MCP-Aufrufe mit Trace untersuchen wird beschrieben, wie Sie Ihre Anwendung so konfigurieren, dass der Trace-Kontext an Remote-Google Cloud-MCP-Server übergeben wird. Dadurch können diese Server Spans an einen Trace anhängen.