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 dieser Anleitung wird erläutert, wie Sie Agententelemetrie 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 Anwendungen für generative KI entwickeln oder verwalten, werden mit Telemetriedaten die Schritte zur Schlussfolgerung, Toolaufrufe und externen Interaktionen Ihrer autonomen Agenten erfasst. Diese Daten sind aus folgenden Gründen nützlich:

  • Nicht deterministisches Verhalten verstehen:Da der Schlussfolgerungsprozess eines Agenten nicht deterministisch ist, ist Telemetrie die einzige zuverlässige Möglichkeit, die Entscheidungen eines 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 Agenten-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:Wenn Sie Prompts, Antworten und die Tokennutzung erfassen, können Sie die Genauigkeit des Modells bewerten, Halluzinationen erkennen und den Ressourcenverbrauch optimieren.

Anwendungen für generative KI instrumentieren

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 Anwendungen für generative KI 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 Fall sind Ihre Prompts und Antworten nicht an Ihre Tracedaten 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 Instrumentierung von Anwendungen bietet. In den in diesem Dokument aufgeführten Instrumentierungsbeispielen wird OpenTelemetry verwendet.

Außerdem empfehlen wir, Ihre Prompts und Antworten in einem Cloud Storage-Bucket und nicht in einem Logeintrag zu speichern:

  • Sie haben detaillierte Kontrolle über die Inhalte 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 des Logeintrags überschreiten. Wenn der Befehl ohne Fehler abgeschlossen wird, einzelne Felder jedoch ihre Größenbeschränkungen überschreiten, werden diese Daten von Cloud Logging abgeschnitten.

Informationen zu OpenTelemetry finden Sie unter Was ist OpenTelemetry?.

Instrumentierungsbeispiele

Informationen zu den ersten Schritten mit der Agenteninstrumentierung finden Sie in den folgenden Beispielanwendungen und Anleitungen:

  • Multimodale Prompts und Antworten erfassen und ansehen beschreibt, wie Sie einen LangGraph ReAct-Agenten oder einen mit ADK erstellten generativen KI-Agenten konfigurieren, um multimodale Prompts und Antworten zu erfassen. Außerdem wird beschrieben, wie Sie Folgendes tun:

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

  • Unter LangGraph ReAct-Agenten mit OpenTelemetry instrumentieren wird beschrieben, wie Sie mit OpenTelemetry eine Anwendung für generative KI instrumentieren, die das LangChain- oder LangGraph-Framework verwendet. Außerdem wird auf eine Beispielanwendung verlinkt, 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, mit der Telemetriedaten von den wichtigsten Aktionen des Agenten erfasst werden. Die Telemetriedaten umfassen Text-Prompts und Agentenantworten. Außerdem wird auf eine Beispielanwendung verlinkt, 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- MCP-Server von Google Cloud übergeben wird. So können diese Server Spans an einen Trace anhängen.