AgentOps: Überwachen und steuern Sie KI-Agenten mit IBM Telemetry mithilfe von watsonx Orchestrate

Da KI-Agenten immer ausgefeilter und autonomer werden, ist es entscheidend, ihr Verhalten, ihre Leistung und ihre Entscheidungsfindung zu verstehen, um Zuverlässigkeit und Governance zu gewährleisten. AgentOps, die Praxis der Überwachung, Beobachtung und Verwaltung von KI-Agenten in der Produktion, bietet die nötige Transparenz, um vertrauenswürdige agentische KI-Systeme zu erstellen.

Dieses Tutorial bietet eine Schritt-für-Schritt-Anleitung zur Einrichtung und Verwendung von IBM Telemetry mit watsonx Orchestrate® Developer Edition zur Überwachung und Steuerung von KI-Agenten. Sie lernen, wie Sie Observability für KI-Agenten aktivieren und ihr Verhalten eingehend analysieren können – von einzelnen LLM-Aufrufen bis hin zu kompletten mehrstufigen Workflows.

Am Ende dieses Tutorial können Sie Folgendes:

• Lokales Installieren und Konfigurieren der watsonx Developer Edition
• Aktivieren der IBM Telemetry für eine umfassende Agenten-Observability
• Importieren und Testen eines vorkonfigurierten KI-Agenten mit externer Tool-Integration
• Analysieren des Verhaltens der Agenten durch detaillierte Traces, Aufgaben, Spans und Workflows
• Beheben von Problemen und Optimieren der Agentenleistung mithilfe fortschrittlicher Analysen

IBM Telemetry ist das native Observability-Framework von watsonx Orchestrate, das detaillierte Informationen darüber erfasst, wie Ihre KI-Agenten Anfragen ausführen. Es zeichnet jeden Schritt des Agentenlebenszyklus auf, von Routing-Entscheidungen und der Prompt-Erstellung bis hin zu LLM-Aufrufen und Tool-Aufrufen, und bietet einen vollständigen Überblick über das Verhalten der Agenten.

Mit IBM Telemetry können Sie Leistungsmetriken verfolgen, LLM-Kosten überwachen, Fehler identifizieren und sicherstellen, dass Ihre Agenten wie vorgesehen funktionieren. IBM Telemetry bietet Observability der Unternehmensklasse, die für Produktionsumgebungen und KI-Systeme in großem Maßstab entwickelt wurde.

Bevor Sie beginnen, stellen Sie sicher, dass die folgenden Voraussetzungen auf Ihrem System installiert und konfiguriert sind:

• Python 3.8+ (Bei python --version prüfen)
• Mindestens 16 GB RAM
• Die watsonx Orchestrate Developer Edition über watsonx Orchestrate ADK

Dieser Leitfaden enthält Installationsschritte für das ADK.

• watsonx Orchestrate Konto Kostenlose 30-tägige Testphase verfügbar, falls Sie kein Konto haben.
• watsonx Orchestrate API-Schlüssel, generiert aus Ihrem IBM Cloud® Dashboard

Schritte zur Autorisierung werden weiter unten in diesem Leitfaden beschrieben.

Um zu starten, klonen Sie das GitHub-Repository, indem Sie https://github.com/IBM/ibmdotcom-tutorials.git als HTTPS-URL verwenden. Detaillierte Schritte zum Klonen eines Repository finden Sie in der GitHub-Dokumentation.

Öffnen Sie das Repository in Ihrer bevorzugten integrierten Entwicklungsumgebung (IDE) (zum Beispiel Visual Studio Code) und finden Sie den Projektordner dieses Tutorials: wxo-agentops . In diesem Verzeichnis werden Sie arbeiten, während Sie den Anweisungen folgen.

Das IBM watsonx orchestrate Agent Development Kit (ADK) ist ein CLI-Tool, das die Installation, Konfiguration und Verwaltung der watsonx Orchestrate Developer Edition vereinfacht.

Um das ADK nutzen zu können, müssen Sie es mit einer bestehenden Watsonx Orchestrate-Umgebung verbinden. Wenn Sie noch kein Watsonx Orchestrate-Konto haben, können Sie sich für eine kostenlose 30-tägige Testphase anmelden. Falls Sie bereits über ein Konto verfügen, können Sie dieses verwenden, um die vom ADK benötigten Umgebungszugangsdaten anzugeben.

Diese Schritte führen Sie durch die Installation mithilfe einer virtuellen Python-Umgebung. Dies ist die empfohlene Vorgehensweise, um Abhängigkeiten isoliert zu halten. Informationen zu alternativen Installationsmethoden und detaillierten Anweisungen finden Sie in der Dokumentation „Erste Schritte mit dem ADK“.

Erstellen Sie eine neue virtuelle Python-Umgebung in Ihrem Projektverzeichnis:

In diesem Schritt wird ein .venv-Ordner erstellt, der eine isolierte Python-Umgebung enthält.

Der Aktivierungsbefehl variiert je nach Betriebssystem.

macOS und Linux

Windows

Nach der Aktivierung sollte sich Ihre Terminal-Prompt ändern, um anzuzeigen, dass Sie in der virtuellen Umgebung arbeiten (normalerweise wird (.venv ) am Anfang des Prompts angezeigt).

Wenn Ihre virtuelle Umgebung aktiviert ist, installieren Sie das ADK mithilfe von pip:

Dieser Befehl lädt das ADK zusammen mit allen Abhängigkeiten herunter und installiert es. Die Installation kann einige Minuten dauern.

Hinweis: Wenn Sie eine frühere Version des ADK installiert haben (>2.0 ) ), führen Sie pip install --upgrade ibm-watsonx-orchestrate aus . Möglicherweise müssen Sie auch die Schritte zur Fehlerbehebung in Schritt 4b durchführen.

Das ADK verwendet eine .env-Datei, um Ihre Benutzerdaten zu authentifizieren und die watsonx Orchestrate Developer Edition zu konfigurieren. Die benötigten Umgebungsvariablen hängen von der gewählten Authentifizierungsmethode ab. Dieses Tutorial verwendet die watsonx Orchestrate-Kontomethode, die einfachste Methode für den Einstieg.

Alternative Authentifizierungsmethoden und detaillierte Konfigurationsanweisungen finden Sie in der Dokumentation zur Konfiguration Ihrer Umgebungsdatei.

Erstellen Sie im Verzeichnis wxo-agentops eine .env-Datei, indem Sie die bereitgestellte Vorlage kopieren:

Öffnen Sie die Datei .env in Ihrem Texteditor und konfigurieren Sie die folgenden beiden wichtigen Felder:

• WO_INSTANCE Diese URL ist Ihre watsonX Orchestrate-Instanz. Diese Informationen finden Sie, indem Sie sich in Ihr watsonx Orchestrate-Konto einloggen und zu Ihren Instanzdaten navigieren. Klicken Sie auf Ihr Profilsymbol > Einstellungen und wählen Sie dann die Registerkarte API-Details aus. Detaillierte Anleitungen zum Einstieg in die API finden Sie in der Dokumentation von watsonx Orchestrate.

Die URL hat dieses Format:

Kopieren Sie die URL Ihrer Service-Instanz und fügen Sie sie ein, um den Vorlagenwert in Ihrer Datei.env zu ersetzen. Die Region (zum Beispiel us-south, hängt von Ihrem geografischen Standort ab).

• WO_API_KEY : Dieser Schlüssel ist Ihr watsonx Orchestrate Programmierschnittstelle (API)-Schlüssel, der Ihre Verbindung zu IBM Cloud Services authentifiziert. Sie können diesen Schlüssel aus Ihrem IBM Cloud Konto-Dashboard generieren oder abrufen. Ersetzen Sie <your-api-key> durch Ihren tatsächlichen API-Schlüssel. Schritt-für-Schritt-Anweisungen zur Generierung eines API-Schlüssels finden Sie in der Dokumentation für den Einstieg.

Bewahren Sie Ihren API-Schlüssel sicher auf und speichern Sie ihn niemals in der Versionskontrolle. Die Datei.env  sollte bereits in Ihrem .gitignore enthalten sein, um eine versehentliche Offenlegung zu vermeiden. 

Jetzt sind Sie bereit, die watsonx Orchestrate Developer Edition zu installieren, die eine lokale Instanz des watsonx Orchestrate-Servers auf Ihrem Rechner ausführt. Dieser Schritt aktiviert auch IBM Telemetry und ermöglicht Ihnen so den sofortigen Zugriff auf Observability-Funktionen.

Den Installationsbefehl verstehen

Das ADK bietet einen einzigen Befehl, der den gesamten Installationsvorgang abwickelt:

Lassen Sie uns aufschlüsseln, was dieser Befehl bewirkt:

• orchestrate server start : Initialisiert und startet den watsonx Orchestrate Developer Edition Server
• -e <path-.env-file> : Verweist auf Ihre Konfigurationsdatei mit Anmeldeinformationen
• --with-ibm-telemetry : Aktiviert das native Observability-Framework von IBM Telemetry

Führen Sie den Befehl von Ihrem wxo-agentops-Verzeichnis aus:

Der folgende Befehl startet den watsonx Orchestrate Developer Edition-Server durch Initialisierung der Serverumgebung: orchestrate server start -e <path-.env-file> . Hinzufügen der --with-ibm-telemetry Kennzeichnung aktiviert IBM Telemetry, sein natives Observability-Framework.

Führen Sie diesen Befehl aus, um den watsonx Orchestrate Server mit IBM Telemetry zu installieren:

Dieser Befehl erstellt interne Container, die vom ADK verwaltet werden, für:

• watsonx Orchestrate-Server
• PostgresSQL- und Redis-Datenbanken
• IBM Telemetry-Services
• Unterstützung von Abhängigkeiten

Das ADK konfiguriert automatisch ein virtuelles Netzwerk, das es diesen Containern ermöglicht, auf http://localhost:3000 miteinander zu kommunizieren.

Der Installationsvorgang kann mehrere Minuten dauern, insbesondere beim ersten Mal, da die notwendigen Bilder heruntergeladen werden müssen. Eine erfolgreiche Installation erzeugt eine Ausgabe, die dem folgenden Beispiel ähnelt:

Wenn Sie diese Nachricht sehen, herzlichen Glückwunsch! Ihre lokale watsonx Orchestrate-Umgebung mit IBM Telemetry wird jetzt ausgeführt.

Wenn die Installation fehlschlägt oder hängen bleibt, versuchen Sie die folgenden Schritte:

1. Server zurücksetzen:

Dieser Befehl stoppt und entfernt alle für watsonx Orchestrate erstellten Container und gibt Ihnen so eine saubere Ausgangsbasis.

2. Installation neu starten:

Führen Sie nach dem Zurücksetzen den Startbefehl erneut aus:

3. Den Status des Server-Logs-Containers überprüfen:

Sie können die Service-Protokolle des Orchestrate-Servers einsehen, um nach Warnungen oder Fehlern zu suchen:

Wenn die vorherigen Schritte nicht funktionieren, setzen Sie den Server zurück und entfernen Sie die Serverumgebung vollständig: orchestrate server purge und neu installieren.

Nachdem der watsonx Orchestrate-Server erfolgreich installiert wurde, müssen Sie nun Ihre lokale Umgebung aktivieren und die Chat-Oberfläche starten, über die Sie mit Ihren KI-Agenten interagieren werden.

Das watsonx Orchestrate ADK unterstützt mehrere Umgebungen (lokal, Entwicklung, Produktion usw.). Sie müssen die von Ihnen erstellte lokale Umgebung explizit aktivieren:

Sie sollten eine Bestätigung erhalten, dass die Umgebung aktiv ist:

Dadurch wird die lokale Umgebung als Standardkontext für alle nachfolgenden ADK-Befehle festgelegt. Alle Agenten, Tools oder Konfigurationen, mit denen Sie arbeiten, zielen nun auf diese lokale Instanz ab.

Starten Sie den watsonx Orchestrate Chat-UI-Service mit folgendem Befehl:

Dieser Befehl initialisiert die webbasierte Chat-Oberfläche und öffnet sie automatisch in Ihrem Standardbrowser. Die Ausgabe sollte in etwa so aussehen:

Die Chat-Oberfläche bietet eine einfache Möglichkeit zur Interaktion mit Ihren KI-Agenten. Falls sich der Browser nicht automatisch öffnet, können Sie manuell zu folgender Adresse navigieren: http://localhost:3000/chat-lite.

Sobald die Chat-Oberfläche geladen ist, sollte ein leeres Chatfenster zur Interaktion bereitstehen. Zu diesem Zeitpunkt haben Sie noch keine Agenten importiert, sodass die Benutzeroberfläche größtenteils leer sein wird. Dieses Ergebnis ist zu erwarten; im nächsten Schritt fügen Sie Ihren ersten Agenten hinzu.

Nachdem Ihre Umgebung nun eingerichtet ist, ist es an der Zeit, einen vorkonfigurierten KI-Agenten zu importieren, der die Überwachungsfunktionen von IBM Telemetry demonstriert. Dieser Wetteragent verwendet ein externes API-Tool, um Wetterdaten in Echtzeit abzurufen und bietet Ihnen so ein praktisches Beispiel zum Beobachten und Analysieren.

Der Wetteragent ist ein idealer Ausgangspunkt, weil er:

• die Nutzung des Tools zeigt: Zeigt, wie Agenten externe APIs aufrufen
• klares, beobachtbares Verhalten bietet: Jede Anfrage folgt einem vorhersehbaren Muster
• aussagekräftige Telemetriedaten erzeugt: Erstellt umfangreiche Traces, die Sie in IBM Telemetry analysieren können.
• Fehlerszenarien enthält: Hilft Ihnen zu verstehen, wie Telemetry mit Fehlern umgeht
• die Automatisierung veranschaulicht: Beseitigt die manuelle Datensuche durch Agentenaktionen

Navigieren Sie von Ihrem Projektstammverzeichnis (wxo-agentops ) aus zum Ordner Wetteragent:

Dieses Verzeichnis enthält zwei YAML-Konfigurationsdateien:

• get_weather.yaml : Definiert das Wetter-API-Tool
• weather_agent.yaml : Definiert den Agenten, der dieses Tool verwendet

Tools sind wiederverwendbare Funktionen, die Agenten aufrufen können, um bestimmte Aktionen durchzuführen. Importieren Sie zuerst die get_weather  Tools:

Die Kennzeichnung --kind openapi zeigt an, dass dieses Tool eine OpenAPI-Spezifikation verwendet, um seine Schnittstelle zu definieren. Sie sollten eine Bestätigung sehen, dass das Tool erfolgreich importiert wurde.

Importieren Sie nun den Agenten, der dieses Tool verwenden soll:

Dieser Befehl registriert den Wetteragenten in Ihrer lokalen watonsx Orchestrate-Umgebung. Der Agent ist vorkonfiguriert mit:

• Anleitungen zur Interpretation von Wetterdaten
• Berechtigung zum Aufrufen des get_weather  Tools
• Ausweichverhalten für ungültige Standorte

Kehren Sie zu Ihrem Browser zurück, in dem die Chat-Oberfläche ausgeführt wird. Möglicherweise müssen Sie die Seite aktualisieren, um den neu importierten Agenten zu sehen.

Klicken Sie auf das Agenten-Dropdown-Menü (normalerweise oben in der Chat-Oberfläche) und wählen Sie Weather_Agent aus der Liste aus.

Stellen Sie bei Auswahl des Wetteragenten einige Fragen, um Telemetriedaten zu generieren:

Beispielanfragen:

• „Wie ist das Wetter in New York City?“
• „Können Sie mir die aktuelle Temperatur in London nennen?“
• „Wie ist das Wetter in Tokio?“
• „Regnet es gerade in Seattle?“

Der Agent bearbeitet jede Anfrage wie folgt:

1. Ihre Anfrage verstehen
2. Den Standort extrahieren
3. Aufrufen des Tools get_weather  mit entsprechenden Koordinaten
4. Interpretation der Wetterdaten
5. Antworten in natürlicher Sprache

Jede Interaktion mit dem Wetteragenten wird von IBM Telemetry erfasst. Das System zeichnet Folgendes auf:

• Der vollständige Gesprächskontext
• Jeder LLM-Aufruf und die verwendeten Token
• Toolaufrufe mit ihren Eingaben und Ausgaben
• Routing-Entscheidungen und Workflow-Schritte
• Ausführungszeiten und Leistungskennzahlen
• Alle auftretenden Fehler oder Ausnahmen
• Interaktionen mit externen Anbietern und deren Reaktionszeiten

Im nächsten Schritt erkunden Sie diese Telemetriedaten im Detail, um genau zu verstehen, wie sich Ihr Agent verhält.

Nun kommt der wichtigste Teil dieses Tutorials: die Nutzung von IBM Telemetry, um detaillierte Einblicke in das Verhalten Ihres Agenten zu gewinnen. IBM Telemetry bietet vielfältige Ansichten und Analysetools, mit denen Sie jeden Aspekt der Anfrageverarbeitung durch Ihre Agenten verstehen können.

Öffnen Sie Ihren Browser und navigieren Sie zu https://localhost:8765/?serviceName=wxo-server. Die Benutzeroberfläche bietet Sitzungswiederholungen, mit denen Sie vergangene Interaktionen von Agenten zur Analyse erneut aufrufen können.

Hinweis: Die URL verwendet https, da es sich bei diesem Bereich jedoch um eine lokale Entwicklungsumgebung handelt, kann Ihr Browser eine Sicherheitswarnung bezüglich eines selbstsignierten Zertifikats anzeigen. Diese Nachricht wird erwartet und kann in Ihrer lokalen Umgebung sicher ausgeführt werden.

Wenn der Anmeldebildschirm erscheint, geben Sie einen beliebigen Namen ein (um Ihre lokale Sitzung zu identifizieren) und klicken Sie auf Anmelden.

Sie werden zum Haupt-Dashboard von IBM Telemetry weitergeleitet.

Das Dashboard zeigt eine Liste der letzten Traces, die jeweils eine einzelne Benutzerinteraktion mit einem Agenten repräsentieren. Klicken Sie im Bereich Trace- und Gruppenauswahl auf die erste Trace-Datei, um detaillierte Analysen zu Ihrem letzten Chat mit dem Wetteragenten anzuzeigen.

Dieser Schritt führt Sie zum Bildschirm Agentenanalyse, der als zentrale Anlaufstelle zum Verständnis des Agentenverhaltens dient.

Der Bildschirm „Agentenanalyse“ bietet eine Übersicht über den ausgewählten Trace, einschließlich:

• Zusammenfassende Statistiken: Gesamtausführungszeit, Token-Nutzung, Kostenschätzungen und Benchmarking-Daten
• Agenteninformationen: Welcher Agent hat die Anfrage bearbeitet
• Benutzeranfrage: Die ursprünglich gestellte Frage
• Reaktionsvorschau: Die endgültige Antwort des Agenten
• Statusindikatoren: Erfolg, Warnungen oder Fehler

In dieser Übersicht erhalten Sie sofort Erkenntnisse darüber, ob der Agent wie erwartet funktioniert hat und wie effizient er gearbeitet hat.

Im Abschnitt Aufgaben werden Sie den größten Teil Ihrer Zeit mit der Analyse des Agentenverhaltens verbringen. Er bietet eine visuelle, schrittweise Zeitleiste aller Aktionen des Agenten während einer Anfrage (jeder LLM-Anruf, jeder Tool-Aufruf, jede Routing-Entscheidung und jede Ausgabegenerierung).

Die Aufgaben sind hierarchisch organisiert, um widerzuspiegeln, wie der Agent den Workflow tatsächlich ausgeführt hat. Dadurch wird es leicht, die Abfolge der Operationen und ihre Beziehungen zu verstehen.

Betrachten wir den Standardausführungspfad für eine watsonX Orchestrate Agentenanfrage. Ihr Wetteragent-Trace sollte eine Struktur aufweisen, die diesem Beispiel ähnelt:

Dieser Workflow zeigt den gesamten Lebenszyklus einer einzelnen Benutzeranfrage. Die einzelnen Aufgaben stellen Folgendes dar:

• 0:_ROOT : Der oberste Span, der alle untergeordneten Aufgaben enthält. Sehen Sie diesen Ordner als den Ordner, der die gesamte Agentenausführung enthält. Er definiert den Start- und Endzeitpunkt des gesamten Trace, vom Zeitpunkt des Eingangs der Anfrage im System bis zur Zustellung der endgültigen Antwort.

Dieser Ansatz ist wichtig, weil die Dauer der Hauptaufgabe die gesamte Latenzzeit angibt, die der Benutzer erlebt hat. Wenn die Zahl zu hoch ist, können Sie die untergeordneten Aufgaben analysieren, um Engpässe zu identifizieren.

• 0.0:agent_style_router : Die Routing-Aufgabe bestimmt, welcher Agent die Nachricht bearbeiten soll, und klassifiziert die Anfrage in einen Verarbeitungsstil. Der Router analysiert die eingehende Anfrage und entscheidet, ob sie dialogbasierte Verarbeitung, toolgesteuerte Ausführung, Retrieval-Augmented Generation (RAG) oder Multi-Agenten-Orchestrierung erfordert.

Der Router stellt sicher, dass die richtige Downstream-Logik aufgerufen wird. Falls Anfragen falsch weitergeleitet werden, können Sie hier das Problem identifizieren.

• 0.1:agent : Der Hauptkontext für die Ausführung des Agenten, der die gesamte Anfrage orchestriert. Diese Aufgabe stellt den Prompt aus Systeminteraktionen, Gesprächshistorie und Tool-Antworten zusammen. Sie wendet Orchestrierungsregeln und -richtlinien an und bereitet Eingaben für das LLM vor. Diese Aufgabe bestimmt, welche Art von LLM-Aufruf gemacht werden soll.

In diesem Schritt findet die „Intelligenz“ der Orchestrierung statt. Die Agentenaufgabe stellt sicher, dass das LLM alle Kontextinformationen erhält, die es benötigt, um fundierte Entscheidungen treffen zu können.

• 0.1.0:WatsonxChatModel.chat : Der eigentliche Aufruf des LLM, bei dem es den vollständigen Prompt erhält und entscheidet, ob es ein Tool aufrufen, um Klarstellung bitten oder eine direkte Antwort geben soll. Es erzeugt die Antwort, entweder in Textform oder in strukturierten Tool-Aufrufen.

Dieser Schritt ist der „Denkschritt“, in dem das Modell Informationen verarbeitet und Entscheidungen trifft. Token-Nutzung, Latenz- und Qualitätsprobleme sind alle auf diese Aufgabe zurückzuführen. Wenn Ihr Agent langsam oder teuer ist, leistet dieser Schritt in der Regel den größten Beitrag.

• 0.2:answer Im letzten Schritt der Kette wird die Ausgabe des LLMs für die Auslieferung formatiert. Diese Aufgabe konvertiert die Ausgabe des LLM in das endgültige Antwortformat und wendet alle Nachbearbeitungs- oder Formatierungsregeln an. Schließlich wird die Antwort an die Chat-Oberfläche zurückgesendet.

Diese Aufgabe stellt sicher, dass der Benutzer eine korrekt formatierte Antwort erhält. Falls Antworten abgeschnitten oder falsch formatiert werden, sollten Sie in diesem Schritt Nachforschungen anstellen.

Aufgaben-Workflow-Zusammenfassung

Um den gesamten Workflow zusammenzufassen:

1. Der Router entscheidet, wie die Anfrage behandelt wird
2. Der Agent bereitet den Kontext und die Orchestrierungslogik vor
3. LLM generiert die Antwort oder Tool-Aufrufe
4. Antwort formatiert und gibt die endgültige Ausgabe zurück

Der gesamte Workflow ist unter dem ROOT Anforderungscontainer zusammengefasst, sodass Sie ein vollständiges Bild der Agentenausführung von Anfang bis Ende erhalten. Dieses Maß an Observability ist unerlässlich für MLOps- und DevOps-Teams, die Agentenoperationen und komplexe Pipelines in großem Maßstab verwalten.

Jede Aufgabe in der Hierarchie enthält drei Kategorien von Attributen, die detaillierte Metadaten darüber liefern, was die Aufgabe verbraucht und produziert hat:

1. Eingabeattribute: Zeigt alles an, was die Aufgabe vor der Ausführung empfangen hat: Nachrichten, Tool-Antworten, Systemanweisungen, den internen Zustand.

Beispiel: Für die WatsonxChatModel.chat Aufgabe enthalten die Eingabeattribute den vollständig zusammengestellten Prompt mit Systemanweisungen, Gesprächshistorie und allen zu interpretierenden Ergebnissen.

2. Ausgabeattribute: Zeigen an, was die Aufgabe erzeugt hat, einschließlich: LLM-Abschlüsse, Tool-Aufrufe und Entscheidungen.

Beispiel: Die gleiche WatsonxChatModel.chat Aufgabe kann entweder eine natürliche Sprachantwort oder einen strukturierten Tool-Aufruf wie get_weather(latitude=40, longitude=-74) ausgeben.

3. Allgemeine Attribute: Bereitstellung von Telemetrie-Metadaten: Token-Nutzung, Zeitinformationen, Kennungen wie eindeutige IDs und Modellinformationen.

Beispiel: Sie könnten sehen, dass eine Aufgabe 450 Eingabe-Tokens und 120 Ausgabe-Tokens verwendete, 1,2 Sekunden zur Ausführung benötigte und ibm/granite-3.1-8b-instruct model verwendete.

So verwenden Sie Aufgabenattribute

Zusammengenommen lassen diese Attribute genau nachvollziehen, was das Modell gesehen hat, welche Entscheidungen es getroffen hat und wie es reagiert hat.

Dieser Detaillierungsgrad ist für Fehlersuche, Optimierung und Validierung von unschätzbarem Wert.

Jede Aufgabe enthält Leistungs- und kostenbezogene Metriken, die zusammenfassen, wie die Aufgabe ausgeführt wurde. Diese Metriken liefern quantitative Daten zur Leistung der Agenten.

Zu den wichtigsten Metriken gehören:

• Gesamtausführungszeit: Wie lange die Aufgabe von Anfang bis Ende gedauert hat
• Anzahl der LLM-Aufrufe: Wie oft wurde das Sprachmodell aufgerufen
• Anzahl der Tool-Aufrufe: Wie oft wurden externe Tools gerufen?
• Token-Verwendung: Eingabe-Tokens, Ausgabe-Tokens und insgesamt verbrauchte Token
• Kostenschätzungen: Ungefähre Kosten basierend auf der Token-Nutzung (wenn Preisdaten verfügbar sind)
• Verteilung von Unteraufgaben: Wie die Arbeit auf untergeordnete Aufgaben verteilt wurde

Diese Metriken helfen Ihnen, die Leistung zu optimieren und das Verhalten der Agenten zu debuggen. Sie können auch dabei helfen, langsame Aufgaben zu identifizieren, die parallelisiert oder zwischengespeichert werden könnten. Diese Sichtweise ist für die Kapazitätsplanung unerlässlich, da sie es Ihnen ermöglicht, den Ressourcenbedarf für die Skalierung zu verstehen und die Token-Nutzung zu verfolgen, um die Kosten zu kontrollieren.

Wenn Sie beispielsweise feststellen, dass ein Trace 8 Sekunden dauerte, aber nur 0,5 Sekunden für LLM-Aufrufe aufgewendet wurden, wissen Sie, dass der Engpass woanders liegt (wahrscheinlich bei der Tool-Ausführung oder der Netzwerklatenz).

Während Aufgaben Ihnen den logischen Workflow Ihres Agenten zeigen, stellen Spans die zugrunde liegenden Operationen auf Systemebene dar, die während der Ausführung ablaufen. Wenn Sie auf die Registerkarte Spans klicken, wird angezeigt, was die Plattform intern tut, um jede Anfrage zu bearbeiten.

Spans ermöglichen die Einsicht in die vom Orchestrierungs-Framework (in diesem Fall LangGraph, ein Open-Source-Framework, das im wxo-Server läuft) aufgezeichneten Low-Level-Ausführungsschritte. Jede Span stellt eine diskrete Operation dar, wie zum Beispiel:

• Weiterleitung der Anfrage an den richtigen Agenten (agent_style_router )
• Aufruf des Agenten und Initialisierung seines Kontexts (agent.task )
• Prompts und Kontext aus Vorlagen erstellen (ChatPromptTemplate.task )
• Aufruf des LLM mit dem zusammengesetzten Prompt (WatsonxChatModel.chat )
• Ergebnisse an den Benutzer zurückgeben (answer.task )

Während Aufgaben die logischen Schritte der Agentenausführung aufzeigen (was der Agent erreichen will), zeigen Spans die technischen Schritte (wie das System dies erreicht). Diese duale Ansicht bietet Ihnen sowohl ein übergeordnetes Verständnis als auch eine Debugging-Funktion auf niedriger Ebene.

Beispiel: Eine einzelne Aufgabe wie 0.1:agent könnte mehrere Spannen enthalten, die Datenbankabfragen, Cache-Abfragen und das Laden von Konfigurationen repräsentieren. Diese Vorgänge finden im Hintergrund statt, um die Ausführung des Agenten zu unterstützen.

Jeder Bereich enthält Tags, die zusätzliche Metadaten und Kontext bereitstellen. Diese Tags sind unerlässlich für das Filtern, Debuggen und die Analyse der Agentenleistung.

Zu den gängigen Span-Tags gehören:

• Agentenidentifikation: agent_id , agent_name
• Sitzungsverfolgung: thread_id , session_id , conversation_id
• Workflow-Kontext: step_number , workflow_path , parent_span_id
• Leistungsdaten: token_count , duration_ms , model_name
• Anforderungsdetails: tool_calls , input_preview , output_preview

Spans sind nützlich, um die Latenz aufzuspüren, Fehler zu verstehen, indem man sieht, welche interne Komponente ausgefallen ist, Muster zu analysieren, indem man Spans nach Tags filtert, um Trends zu erkennen und Querverweise herzustellen, indem man Spans über mehrere Traces hinweg mithilfe von Session-IDs verknüpft.

Wenn Ihr Agent zum Beispiel gelegentlich hängt, können Sie Spans nach Dauer filtern, um zu erkennen, welche internen Operationen unerwartet lange dauern, vielleicht eine Datenbankanfrage oder ein Netzwerkaufruf zu einem externen Dienst.

Die Registerkarte Workflows bietet eine hierarchische Visualisierung namens Runnables Tree, die die komplette Ausführungsstruktur Ihres Agenten-Workflows zeigt. Diese Ansicht ist besonders nützlich, um komplexe Multi-Agenten-Systeme und verschachtelte Ausführungsmuster zu verstehen.

Im watsonx Orchestrate-Framework ist ein Runnable eine Arbeitseinheit oder Aufgabe, die ausgeführt werden kann. Runnables können sein:

• Einfache Operationen: Ein einzelner LLM-Aufruf oder Tool-Aufruf
• Composite-Workflows: Mehrere Runnables, die miteinander verkettet sind
• Bedingte Verzweigungen: Unterschiedliche Ausführungspfade basierend auf Bedingungen
• Parallele Ausführungen: Mehrere Runnables laufen gleichzeitig

Der Runnable-Baum zeigt über- und untergeordnete Beziehungen an, sodass Folgendes leicht zu erkennen ist:

• Welche Aufgaben lösen andere aus: Die Ausführungskette verfolgen
• Parallele vs. sequentielle Ausführung: Workflow-Gleichzeitigkeit verstehen
• Verzweigungslogik: Wie Entscheidungen zu unterschiedlichen Ausführungspfaden führen
• Workflow-Tiefe: Wie tief verschachtelt ist Ihre Agentenlogik

Bei einfachen Agenten wie dem Wetteragenten spiegelt die Workflow-Ansicht die Aufgabenansicht genau wider. Workflows erweisen sich jedoch als unschätzbar wertvoll, wenn Sie mit Folgendem arbeiten:

• Multi-Agenten-Systeme: Mehrere spezialisierte Agenten, die an einer Aufgabe zusammenarbeiten.
• Komplexe Orchestrierung: Agenten, die dynamisch zwischen verschiedenen Tools oder Unteragenten wählen
• Iterative Verfeinerung: Agenten, die Schritte in einer Schleife durchlaufen, bis eine Bedingung erfüllt ist
• Bedingtes Routing: Workflows, die sich basierend auf Zwischenergebnissen verzweigen
• Skalierbare Architekturen: Gestaltung von Workflows, die reale Lasten effizient verarbeiten

Stellen Sie sich beispielsweise einen Agenten vor, der zuerst prüft, ob eine Anfrage eine Websuche erfordert, dann entscheidet, ob er ein Taschenrechner-Tool oder ein Datenbankabfrage-Tool verwendet, und schließlich das Ergebnis validiert, bevor er antwortet. Der Runnables-Baum würde diese gesamte Verzweigungsstruktur deutlich darstellen.

Sie können mit dem Baum interagieren, indem Sie:

• Knoten erweitern/reduzieren: Fokus auf spezifische Workflow-Abschnitte
• Knoten anklicken: Zu detaillierten Aufgabeninformationen springen
• Folgende Ausführungspfade: Verfolgen Sie, wie die Daten durch das Fenster fließen.
• Engpässe identifizieren: Erkennen Sie, wo Workflows ineffizient werden.

Die Visualisierung erleichtert das Debuggen von Workflows erheblich, im Vergleich zum alleinigen Verfolgen von Textprotokollen oder Trace-Daten.

Die Registerkarte Eval (Evaluierung) bietet eine Ansicht zur Qualitätssicherung und -überwachung, die die Korrektheit und Zuverlässigkeit der Ausführung Ihres Agenten misst. In diesem Schritt wechseln Sie vom Beobachten, was passiert ist, zu der Evaluierung davon, wie gut es passiert ist.

Die Registerkarte „Eval“ zeigt Evaluierungsergebnisse, die die Qualität anhand von Leitplanken bewerten:

• Erfolg der Aufgabe: Welche Aufgaben sind erledigt oder gescheitert
• Qualität der Ausgabe: Ob die Ausgaben den erwarteten Ergebnissen oder Qualitätskriterien entsprachen
• Leistung: Quantitative Metriken, die das Erfolgsniveau angeben
• Fehleranalyse: Kategorisierung und Schweregrad von Ausfällen
• Anwendungsfallvalidierung: Ob das Verhalten der Agenten mit den beabsichtigten Anwendungsfällen übereinstimmt

Evaluierungen helfen Ihnen dabei, die Zuverlässigkeit zu überwachen, indem sie verfolgen, wie konsistent Ihr Agent korrekte Ergebnisse erzielt, erkennen, wann Änderungen die Leistung der Agenten beeinträchtigen, Verbesserungen priorisieren und Vertrauen aufbauen, indem Sie vor der Bereitstellung überprüfen, ob die Agenten korrekt arbeiten.

Mithilfe von Evaluierungsmessungen können Sie Warnmeldungen einrichten, Verbesserungen verfolgen, Muster erkennen und Feedback nutzen, um die Entwicklung zu steuern und so Prompts oder Tools zu verbessern.

Wenn Sie bemerken, dass 15 % der Wetteranfragen die Auswertung nicht bestehen, können Sie diese spezifischen Traces untersuchen, um herauszufinden, ob das Problem an schlechter Eingabeverarbeitung, API-Ausfällen oder falscher Antwortformatierung liegt.

Die Registerkarte Probleme bietet eine zentrale Übersicht über alles, was während der Workflow-Ausführung schiefgelaufen ist. Diese Registerkarte ist Ihre erste Anlaufstelle bei der Fehlersuche in Agentensystemen oder bei unerwartetem Verhalten.

Die Registerkarte „Probleme“ listet beispielsweise folgende Probleme auf:

• Fehlgeschlagene API-Aufrufe: Externe Dienste geben Fehler zurück
• Fehler bei der Tool-Ausführung: Tools, die abgestürzt sind oder das Zeitlimit überschritten hat
• Fehlende Eingaben: Erforderliche Daten sind bei Bedarf nicht verfügbar
• Modell-Ausnahmen: LLM-Fehler wie Tokenlimits oder ungültige Eingaben
• Validierungsfehler: Daten, die nicht den erwarteten Formaten entsprechen
• Timeout-Fehler: Operationen, die Zeitlimits überschritten haben
• Unbehandelte Laufzeitfehler: Unerwartete Ausnahmen im Agentencode

Im obigen Screenshot sieht man einen Tool-Fehler, der auftrat, als die Wetter-API einen Fehler 424 (Fehlgeschlagene Abhängigkeit) oder 404 (Nicht gefunden) zurückgab. In der Registerkarte „Probleme“ wird Folgendes angezeigt:

1. Der Fehlertyp: „Tool-Fehler“
2. Das spezifische Tool: get_weather
3. Fehlermeldung: Vollständige API-Antwort, die den Fehler anzeigt
4. Direct Link: Klicken Sie hier, um direkt zu der Aufgabe zu springen, bei der der Fehler aufgetreten ist.

Dieser Ansatz macht es einfach zu verstehen, was schiefgelaufen ist, ohne Protokolle oder Trace-Daten durchforsten zu müssen.

Die Registerkarte „Probleme“ ist besonders wertvoll, weil sie Fehler zusammenfasst, anstatt dass man einzelne Aufgaben durchsuchen muss. Sie bietet einen vollständigen Kontext durch die Einbeziehung aller Fehlerdetails und zugehöriger Daten, während Schweregrade eine schnelle Priorisierung ermöglichen, sodass Sie festlegen können, welche Probleme zuerst angegangen werden müssen. Die Direct Links zu den Quellaufgaben bedeuten, dass Sie mit einem Klick genau zu dem Punkt in der Ausführung gelangen, an dem der Fehler aufgetreten ist.

Die Registerkarte Trajectory bietet eine chronologische, dialogähnliche Ansicht der Agenteninteraktion zwischen dem Benutzer und allen Tools, die der Agent aufruft. Diese Ansicht ist von unschätzbarem Wert, um den gesamten Kontext und Ablauf des Agentenverhaltens zu verstehen.

Die Trajectory-Ansicht ist nützlich, weil Sie so genau sehen können, wie der Agent Anfragen von Anfang bis Ende bearbeitet, sodass Sie einen vollständigen Überblick über das Verhalten des Agenten haben. Sie können die Tool-Integration validieren, indem Sie sicherstellen, dass Tools mit korrekten Parametern aufgerufen werden und angemessene Antworten erhalten. Beim Debuggen unerwarteter Antworten hilft Ihnen die Ablaufverfolgung dabei, nachzuvollziehen, wo die Logik von Ihren Erwartungen abgewichen ist. Sie können auch analysieren, wie sich der Kontext über mehrere Gesprächsrunden hinweg entwickelt und dabei die natürliche Entwicklung des Workflows beobachten. Neben dem Debuggen dient das Trajectory auch als Dokumentation, sodass Sie Beispiele für korrektes Verhalten festhalten können, die mit Teammitgliedern geteilt oder als Referenzfälle für zukünftige Entwicklungen verwendet werden können. Diese Ansicht ist besonders wertvoll für Teams, die mit generativer KI arbeiten und die Anpassungsfähigkeit von Agenten in verschiedenen Szenarien validieren müssen.

Lassen Sie uns das im Screenshot dargestellte Trajectory des Wetteragenten durchgehen:

1. Die Benutzeranfrage

Das Gespräch beginnt mit einer klaren, spezifischen Anfrage zum Wetter in New York City.

2. Der Agent macht einen Tool-Aufruf

Der Agent erkennt, dass er externe Daten benötigt und ruft das Wetter-Tool auf:

Dieses Beispiel zeigt, dass der Agent die ungefähren Koordinaten von NYC korrekt identifiziert, die Anfrage für die API richtig strukturiert und die entsprechende Kennzeichnung für das aktuelle Wetter gesetzt hat.

IBM Telemetry zeigt dieses Ergebnis sowohl als unformatiertes JSON als auch als übersichtlich aufbereitete, erweiterbare Baumansicht an.

3. Das Tool liefert Daten zurück

Die Wetter-API antwortet mit strukturierten Wetterdaten:

Dieses Beispiel zeigt, dass das Tool die Daten erfolgreich abgerufen hat und die Antwort dem erwarteten Schema folgt und alle erforderlichen Felder vorhanden sind. Die Möglichkeit, die Reaktion des Raw Tools zu überprüfen, ist entscheidend für das Debugging von Problemen, bei denen der Agent Tool-Ausgaben falsch interpretiert.

4.  Der Agent fasst das Ergebnis zusammen

Schließlich verarbeitet der Agent die strukturierten Daten und reagiert natürlich:

Der Agent extrahierte korrekt den Temperatur- und Wettercode und wandelte die strukturierten Daten in natürliche Sprache um. Die Antwort ist prägnant und beantwortet die Frage des Nutzers.

Die Registerkarte „Trajectory“ unterstützt auch das Filtern nach Rolle, um nur Benutzernachrichten, Agentennachrichten oder Tool-Interaktionen anzuzeigen. Sie können auch Teile längerer Gespräche ein- und ausblenden, um sich auf die für Sie wichtigen Details zu konzentrieren. Zur weiteren Analyse oder Fehlersuche können Sie die Daten als JSON exportieren, um von den Trajectory-Schritten zu den verknüpften Aufgaben zu springen und die entsprechenden Details anzuzeigen.

Herzlichen Glückwunsch! Sie haben IBM Telemetry erfolgreich mit watsonx Orchestrate eingerichtet und gelernt, wie Sie das Verhalten von KI-Agenten eingehend überwachen und analysieren können. IBM Telemetry bietet mehrere Ebenen der Transparenz, um Ihnen vollständige Einblicke in das Denken, Entscheiden und Handeln Ihrer KI-Agenten zu ermöglichen. Diese von Ihnen untersuchten Fähigkeiten sind entscheidend für ein effektives Lebenszyklusmanagement von Agentenoperationen in der Produktion oder für die Integration mit anderen Agenten-Frameworks in Ihrer Umgebung.

Sollten Sie auf Probleme stoßen oder Fragen haben, schauen Sie sich die Dokumentation an. Die häufigsten Probleme werden im Fehlerbehebungshandbuch behandelt. Sie können auch GitHub-Probleme prüfen, um zu sehen, ob andere ähnliche Probleme hatten.

Die Überwachung von Agenten über Plattformen wie IBM Telemetry hat ein robustes Ökosystem für AgentOps geschaffen und ist unerlässlich geworden, da autonome Agenten immer komplexere Aufgaben übernehmen, die die Integration von SDKs, Tools und externen APIs erfordern. Der Einblick, den Sie über das Verhalten von Agenten gewonnen haben, ermöglicht es Ihnen, zuverlässigere, effizientere und vertrauenswürdigere KI-Systeme zu entwickeln.