Debuggen von Agents mit Agent Inspector in Microsoft Foundry Toolkit

Mit dem Agent Inspector in Microsoft Foundry Toolkit für Visual Studio Code können Sie Anforderungen an einen lokalen Agent senden, Modell- und Toolaktivitäten prüfen und Ihren Code debuggen. Verwenden Sie sie, um unerwartete Antworten zu untersuchen, bevor Sie eine Änderung bereitstellen.

Dieser Workflow ist nützlich für gehostete Agents, die Ihren benutzerdefinierten Code im Foundry Agent Service ausführen. Die lokale Inspektion hilft Ihnen beim Debuggen dieses Codes. Testen Sie vor der Produktionsverwendung auch den bereitgestellten Agent mit seiner Laufzeitidentität, Konfiguration und netzwerkzugriff.

In diesem Artikel stellen Sie eine Verbindung mit einem lokalen Agent her, untersuchen eine Anforderung und speichern Diagnoseereignisse. Der Hauptpfad verwendet das Responses-Protokoll. Verfügbare Ansichten hängen vom Protokoll und den Diagnosefunktionen ab, die Ihr Agentserver bereitstellt.

Prerequisites

  • Visual Studio Code mit der aktuellen öffentlichen Foundry Toolkit-Erweiterung. Siehe Foundry Toolkit installieren.
  • Ein lokales Agentprojekt mit eingerichteten Abhängigkeiten, Modellkonfiguration und Anmeldeinformationen. Um mit einem Beispiel zu beginnen, folgen Sie dem hosted-agent quickstart bis zu den lokalen Tests.
  • Der debugger, der für Ihr Projekt erforderlich ist. Im Python Beispiel werden die Python Erweiterung und debugpy verwendet. Andere Sprachen und Beispiele haben unterschiedliche Anforderungen.

Bei einem vorhandenen Projekt können die Foundry Toolkit Copilot Tools bei der Vorbereitung der Konfiguration helfen. Überprüfen Sie die generierten Dateien und befolgen Sie die README.md des Projekts. Ersetzen Sie die Startdateien nicht durch eine generische Konfiguration.

Important

Ein lokaler Agent kann Cloudmodelle und Livetools aufrufen. Verwenden Sie nicht vertrauliche Testeingaben, überprüfen Sie Die Toolberechtigungen und berücksichtigen Sie Gebühren von konfigurierten Diensten. Der Inspektor ersetzt keine Tools durch Mocks.

Verbinden und debuggen

Starten Sie den Agentserver, bevor Sie eine Verbindung mit Inspector herstellen. Verwenden Sie die generierte Startkonfiguration Ihres Projekts, um den Server, das Arbeitsverzeichnis, den Interpreter und den Debugger abzustimmen.

  1. Starten Sie den Agent mit der dokumentierten Debugkonfiguration. Wählen Sie für das Beispiel für gehostete Agent-Python den Lokalen Agent-HTTP-Server debuggen aus, und drücken Sie F5.
  2. Wenn "Inspector" nicht geöffnet ist, wählen Sie " Foundry Toolkit " in der Aktivitätsleiste und dann " Developer Tools>Build>Agent Inspector" aus.
  3. Überprüfen Sie den Endpunkt im Inspektorheader. Das aktuelle Python-Gerüst verwendet http://localhost:8088. Wählen Sie für einen anderen Serverport die Schaltfläche mit dem Stiftsymbol neben dem Endpunkt aus, geben Sie den Port ein, und wählen Sie "Verbinden" aus.
  4. Vergewissern Sie sich, dass in der Kopfzeile Connected angezeigt wird. Der Inspektor erkennt automatisch das Antwort- oder Aufrufprotokoll, wenn der Endpunkt erreichbar ist.
  5. Legen Sie einen Haltepunkt in Ihrem Agentcode fest, und senden Sie eine Nachricht im Playground. Überprüfen Sie Variablen, wenn die Ausführung angehalten wird, fahren Sie dann fort und überprüfen Sie die Antwort.

Screenshot der Debug-Konfiguration des lokalen Agenten und des mit localhost an Port 8088 verbundenen Agent Inspector mit einer erfolgreichen Antwort.

Durch das Öffnen von Inspector allein wird kein Server gestartet oder ein Debugger angefügt. Die generierte Python-Konfiguration verwendet Port 5679 für den Debugger und Port 8088 für AGENT-HTTP-Anforderungen. Diese Ports sind von den OTLP-Ablaufverfolgungsports getrennt.

Herstellen einer Verbindung mit einem generischen Responses-Endpunkt

Der Inspektor kann eine Verbindung mit einem lokalen generischen Responses-Endpunkt herstellen, ohne die vollständige Entwicklungsdiagnoseschnittstelle zu verwenden. Sie können die Antwortereignisse überprüfen, die der Server sendet, aber das Workflowdiagramm und dessen Eingabe- und Ausgabeansicht sind nicht verfügbar.

Eine erfolgreiche Verbindung bedeutet nicht, dass der Server Quellorte, Tokenverwendung oder Schlussfolgerungen bereitstellt.

HTTP-Aufruf senden

Verwenden Sie HTTP-Invocations, wenn Ihr Agent anstelle einer Unterhaltungsnachricht einen benutzerdefinierten Request-Body akzeptiert. Das Anforderungsformat und das Antwortprotokoll des Servers bestimmen, wie Inspector das Ergebnis sendet und anzeigt.

  1. Stellen Sie eine Verbindung mit dem laufenden Server für HTTP-Aufrufe her. Inspector erkennt das Protokoll automatisch.
  2. Geben Sie den Request-Body ein, der von Ihrem Agenten benötigt wird. Wenn der Server eine kompatible OpenAPI-Spezifikation verfügbar macht, kann inspector ein Beispiel ausfüllen. Überprüfen Sie es vor dem Senden, oder folgen Sie dem Anforderungsformat des Beispiels, wenn kein Beispiel verfügbar ist.
  3. Wählen Sie das Zahnrad „Anforderungseinstellungen“ neben der Eingabe aus, um Content-Type und Accept wie vom Server gefordert festzulegen. Verwenden Sie application/json z. B. für einen JSON-Body und text/event-stream, wenn der Server eine Streamingantwort unterstützt.
  4. Wählen Sie "Senden" aus, und überprüfen Sie den Antwortstatus und den Textkörper.
  5. Wechseln Zwischen Vorschau für formatierte Ausgabe und Raw für die zugrunde liegende Antwort. Der Detailbereich enthält auch E/A und LLM-Aufrufe. Modell-, Tool- und Tokendetails hängen von erkannten Serverereignissen ab, sodass nicht jede Antwort jede Registerkarte ausfüllt.

Der Inspektor verarbeitet eine normale HTTP-Antwort, einen Datenstrom von vom Server gesendeten Ereignissen oder eine asynchrone Antwort. Bei einer asynchronen 202 Accepted Antwort fragt sie den Aufruf regelmäßig bis zum Abschluss oder bis ein Fehler auftritt ab. Wenn Sie ein Antwortformat auswählen, wird Ihrem Server keine Streaming- oder asynchrone Unterstützung hinzugefügt.

Bei einer Streamingantwort trennt Stop den Clientdatenstrom. Bei einem abgefragten Aufruf sendet Cancel eine Abbruchanforderung an den Server. Keine der beiden Aktionen garantiert, dass der Agentprozess oder ein externer Toolvorgang beendet wurde.

Diese Ansicht ist kein WebSocket-Client. Aktivitätsprotokollbeispiele verwenden eine andere Testumgebung. Siehe Anderes Protokoll oder Beispiel auswählen für den entsprechenden lokalen Testpfad.

Inspektor verwenden

Beginnen Sie mit einer Anforderung, die das gewünschte Verhalten testet, das Sie verstehen möchten. Für ein Wettertool fragen Sie z. B. nach Informationen, die dieses Tool erfordern, anstatt nach einer allgemeinen Antwort zu fragen, die das Modell ohne dieses Tool erzeugen kann.

  1. Senden Sie die Anforderung im Playground, und überprüfen Sie die Streamingantwort.
  2. Verwenden Sie die Registerkarten "Details", um den langsamen oder fehlerhaften Vorgang zu finden.
  3. Überprüfen Sie das relevante Ereignis oder den Toolaufruf, ändern Sie Den Code oder die Konfiguration, und wiederholen Sie die Anforderung.

Drücken Sie EINGABETASTE, um zu senden, oder UMSCHALT+EINGABETASTE, um eine neue Zeile hinzuzufügen. Wenn Sie eine frühere Eingabe erneut aufrufen möchten, platzieren Sie das Caret am Anfang der Eingabe, und drücken Sie die Pfeiltaste nach oben. Drücken Sie am Ende die Nach-unten-Taste, um zu neueren Anfragen zu wechseln und zu Ihrem nicht gesendeten Entwurf zurückzukehren.

Sie können eine zurückgerufene Anfrage bearbeiten, bevor Sie sie senden. Der Eingabeverlauf ist eine Komfortfunktion innerhalb von Inspector, kein dauerhafter Speicher gespeicherter Prompts.

Anzeigen Verwenden Sie es, um
Overview Folgen Sie dem Latenz-Wasserfall und der geordneten Ausführungszeitleiste. Wählen Sie alle Ausführungen oder eine Ausführung aus, um Modell- und Toolaktivitäten von der Zeit zwischen den Läufen zu unterscheiden.
Token Überprüfen Sie die gemeldete Eingabe- und Ausgabetokenverwendung. Fehlende Nutzungsdaten sind kein Nulltokenergebnis.
Ereignisse Untersuchen Sie analysierte Responses-Ereignisse, einschließlich Fehlern, Funktionsaufrufen und Ergebnissen. Suchen Sie nach Ereignistyp oder JSON-Inhalt, und filtern Sie nach Kategorie.
Werkzeuge Überprüfen Sie die nach Ausführung der Antwort gruppierten Toolaufrufe, einschließlich Status, Aufruf-ID, Argumente und Ergebnisse.

Die Antwortfußzeile zeigt Modell-, Dauer-, Tokenverwendungs- und Zeitstempelinformationen an, wenn angegeben. Begründungstext und Begründungszusammenfassungen werden in getrennten, reduzierbaren Abschnitten angezeigt, wenn der Agent sie ausgibt. Der Inspektor generiert keine fehlenden Begründungen oder macht Informationen verfügbar, die der Modellanbieter nicht zurückgibt.

Werkzeuge und Berechtigungen überprüfen

Verwenden Sie Tools , um zu überprüfen, ob der Agent das erwartete Tool mit den erwarteten Argumenten aufgerufen und ein Ergebnis erhalten hat. Eine erfolgreiche Modellantwort beweist nicht, dass ein Tool ausgeführt wurde. Wenn Ihr Code ein Mock verwendet, ist das angezeigte Ergebnis immer noch ein simuliertes Ergebnis.

Screenshot der Registerkarte

Wenn eine Antwort für die Genehmigung des Model Context Protocol (MCP) oder der OAuth-Zustimmung angehalten wird, werden ausstehende Anfragen oberhalb der Nachrichteneingabe angezeigt. Gewähren Sie nur den Zugriff, den Sie zulassen möchten.

Wählen Sie für einen MCP-Toolaufruf Argumente anzeigen aus, überprüfen Sie die Eingaben, und wählen Sie dann Genehmigen oder Ablehnen aus. Genehmigen Sie alle und Verweigern Sie alle gelten für die ausstehenden Anfragen, nicht für eine dauerhafte Genehmigungsrichtlinie für Tools.

Für die OAuth-Zustimmung schließen Sie sowohl die Browserautorisierung als auch die Bestätigung des Inspektors ab:

  1. Wählen Sie "Open consent" für die ausstehende Anforderung aus.
  2. Schließen Sie die Autorisierung im Browser ab, kehren Sie zu Inspektor zurück, und wählen Sie "Zustimmung abgeschlossen" aus. Um die Autorisierung abzulehnen, wählen Sie stattdessen Abbrechen aus.
  3. Lösen Sie die verbleibenden Einwilligungsanfragen. Verwenden Sie Alles erledigt, sofern verfügbar, nur nach Abschluss der Autorisierung für alle geöffneten Anforderungen.

Wenn Sie eine Zustimmungsseite allein öffnen, wird die Anforderung nicht fortgesetzt. Der Inspektor wartet auf eine Entscheidung für jede ausstehende Zustimmung, bevor er den Server erneut überprüft. Anfragen können wieder angezeigt werden, wenn der Server weiterhin eine Autorisierung benötigt.

Überprüfen Sie das nachfolgende Toolergebnis, nicht nur die Genehmigung, um den Abschluss zu bestätigen. Informationen zum Einrichten von Verbindungen und Authentifizierung finden Sie im Toolkatalog. Ändern Sie die Anmeldeinformationen oder Berechtigungen des Tools nicht nur, um einen Diagnosefehler zu beseitigen.

Prüfen von Workflows und Quellcode

Für unterstützte Microsoft Agent Framework-Workflows kann der Entwicklungsserver Workflowdiagnosen und Quellcodepositionen bereitstellen. Der Inspektor verwendet diese Informationen, um das Ausführungsdiagramm anzuzeigen und Sie beim Navigieren zu Ihrem Code zu unterstützen.

  1. Wählen Sie einen Workflowknoten aus, um die verfügbaren Eingaben und Ausgaben zu überprüfen.
  2. Doppelklicken Sie auf den Knoten, um den Quellspeicherort zu öffnen.
  3. Legen Sie einen Haltepunkt fest, und wiederholen Sie die Anfrage, um den Vorgang im Debugger zu prüfen.

Sie können LangGraph-Workflows im Playground testen, die Workflowvisualisierung wird jedoch für sie nicht unterstützt. Ein Server ohne Workflowmetadaten kann weiterhin nützliche Antwortereignisse zurückgeben.

Fehler mit Copilot untersuchen

Verwenden Sie die Fehleraktionen in Events, um eine fokussierte Anforderung für GitHub Copilot vorzubereiten, anstatt die gesamte Unterhaltung zu kopieren.

  1. Suchen Sie das fehlgeschlagene Ereignis, und überprüfen Sie die Details auf vertrauliche Inhalte, bevor Sie sie freigeben.
  2. Wählen Sie "Fix" neben dem fehlgeschlagenen Ereignis aus, um eine Aufforderung für diesen Fehler vorzubereiten. Bei mehreren Fehlern schränken Sie die Liste mit Such- und Kategoriefiltern ein, und wählen Sie dann Mit Copilot beheben aus. Diese Aktion enthält die sichtbaren Fehler.
  3. Überprüfen Sie die vorbereitete Eingabeaufforderung in GitHub-Copilot Chat, bevor Sie sie senden. Überprüfen Sie alle vorgeschlagenen Änderungen, und führen Sie dann die ursprüngliche Agentanforderung erneut aus, um das Ergebnis zu bestätigen.

Für diese Aktionen ist der OTLP-Sammler nicht erforderlich. Durch das Vorbereiten einer Diagnoseaufforderung wird der Agent nicht behoben oder der fehlgeschlagene Vorgang erneut ausgeführt.

Screenshot der Registerkarte „Ereignisse“ mit fehlgeschlagenen Antworten, Such- und Filtersteuerelementen, Exportaktionen und Diagnosedetails, vorbereitet in Copilot Chat.

Diagnoseereignisse speichern

Speichern Sie einen Ereignis-Snapshot, um einen Fehler mit einer späteren Ausführung zu vergleichen oder eine gezielte Reproduktion freizugeben.

  1. Schränken Sie in Ereignisse die Liste mit dem Suchfeld und dem Kategoriefilter ein.
  2. Wählen Sie "Sichtbare Ereignisse kopieren" aus, um die gefilterten Ereignisse als JSONL zu kopieren. Alternativ können Sie Download visible events auswählen, um den Export in VS Code zu öffnen.
  3. Verwenden Sie bei geöffnetem Export die Datei>Speichern unter, um eine Kopie an einem von Ihnen kontrollierten Speicherort zu speichern, bevor Sie das Dokument schließen. Der geöffnete Export ist eine temporäre Datei und kein dauerhafter Download.

Die Momentaufnahme enthält die Ereignisse, die angezeigt werden, wenn Sie die Aktion auswählen, nicht zukünftige Ereignisse vom laufenden Agenten. Es speichert keine Agentversion, stellt keinen Code bereit und erstellt keinen Cloud Trace-Verlauf.

Vorsicht

Ereignisse können Eingabeaufforderungen, Antworten, Toolargumente, Ergebnisse und Fehlerdetails enthalten. Überprüfen und schwärzen Sie vertrauliche Inhalte, bevor Sie einen Export speichern oder freigeben.

Neue Unterhaltung starten

Wählen Sie „Chat löschen“, um eine neue Unterhaltung zu starten und den Status von „Chat“, „Ereignisse“ und „Details“ zurückzusetzen. Exportieren Sie zunächst alle Diagnoseereignisse, die Sie benötigen. Durch das Aktualisieren desselben verbundenen Agenten wird der Inspektionszustand beibehalten, während ein Agentenwechsel den veralteten Zustand löscht.

Bei Antworten wird Clear Chat deaktiviert, während eine Antwort aktiv streamt. Sie bleibt verfügbar, wenn der Vorgang zur Genehmigung oder Zustimmung angehalten wird. Es handelt sich nicht um einen allgemeinen Befehl, um Ihren Agenten zu stoppen.

Verlassen Sie sich nicht auf den lokalen Inspector-Status als dauerhaftes Konversationsarchiv. Der Server verwaltet die Persistenz von Unterhaltungen, die sich zwischen der lokalen Entwicklung und einem bereitgestellten gehosteten Agent unterscheiden kann. Durch das Löschen des Inspector werden Traces nicht gelöscht, die bereits lokal erfasst oder in Application Insights gespeichert wurden.

Unterschiede zwischen Inspector und Ablaufverfolgung

Inspector kommuniziert mit Ihrem lokalen Server über HTTP und streamt Antwortereignisse. Ein kompatibler Entwicklungsserver stellt außerdem einen separaten Diagnosedatenstrom für Workflowdetails und die Quellnavigation bereit. Der Debugger stellt unabhängig eine Verbindung mit Ihrem laufenden Prozess her.

Für diese Live-Diagnosen ist der lokale OTLP-Sammler nicht erforderlich. Die Registerkarte " Ablaufverfolgungen " des Inspektors öffnet die separate Ablaufverfolgungsanzeige. Es wandelt protokollbezogene Ereignisse nicht in gespeicherte OpenTelemetry-Spans um.

Um Spans für eine spätere Analyse zu sammeln, konfigurieren Sie lokales Tracing. Verwenden Sie für bereitgestellte Agenten gehostete Traces.

Stellen Sie nach dem lokalen Testen den gehosteten Agent bereit. Testen Sie sie separat, da sich ihre Identität, ihre Umgebung und ihr Netzwerkzugriff von Ihrem lokalen Prozess unterscheiden.

Troubleshooting

Issue Was soll überprüft werden?
Der Inspector kann keine Verbindung herstellen. Überprüfen Sie das Agent-Terminal auf Startfehler. Bestätigen Sie den Interpreter, die Abhängigkeiten und den HTTP-Port, und stellen Sie dann die Verbindung mit dem Port wieder her, den der Server meldet. Beim Öffnen des Inspektors wird der Prozess nicht gestartet.
Eine Anfrage wird erfolgreich ausgeführt, aber Haltepunkte werden nicht erreicht. Vergewissern Sie sich, dass der Debugger an den Prozess angefügt ist, der die Anforderung verarbeitet, und das richtige Quellverzeichnis verwendet. Informationen zu Python finden Sie unter Debugging-Fehlerbehebung.
Das Diagramm oder die Quellennavigation fehlt. Stellen Sie sicher, dass der Server und der Workflow Entwicklungsdiagnosen und Quellpositionen bereitstellen. Die Überprüfung generischer Antworten bietet diese Funktionen nicht. LangGraph-Workflows funktionieren im Playground ohne Workflowvisualisierung.
Toolergebnisse fehlen. Überprüfen Sie Events auf Fehler und ausstehende Genehmigungen. Vergewissern Sie sich, dass für die Anforderung ein Tool erforderlich ist und dass das Tool konfiguriert und erreichbar ist.
Token- oder Begründungsdetails fehlen. Überprüfen Sie, was das Modell und der Server ausgeben. Der Inspektor kann nur die Informationen anzeigen, die bereitgestellt werden.
Externe Bilder werden blockiert. Wählen Sie „Entfernte Bilder laden“ nur aus, wenn Inspektor sie von Remotehosts abrufen soll. Diese Anzeigeberechtigung ist keine Toolgenehmigung. Nicht unterstützte URLs oder Inhalte können weiterhin nicht geladen werden. Ein fehlendes Bild bedeutet nicht unbedingt, dass die Agentanforderung fehlgeschlagen ist.
Der Antwortdatenstrom wird unterbrochen. Überprüfen Sie die Details zur Teilantwort und zu Fehlern. Stellen Sie bei Bedarf erneut eine Verbindung her, und überprüfen Sie die ausstehenden Genehmigungen, bevor Sie es erneut versuchen. Ein Wiederholungsversuch kann Livetoolaktionen wiederholen.
Der Inspektor enthält Ereignisse, der Tracing-Viewer ist jedoch leer. Protokollereignisse und OTLP-Spans unterscheiden sich. Konfigurieren Sie die Instrumentierung, und starten Sie den Sammler.

Verwandte Inhalte

  • Zuletzt aktualisiert um