Problemlösung von Agentenunterhaltungen mit dem Agent-Debugger im Copilot-Agent-Kit

Der Agent Debugger ist ein Diagnosetool, das Ihnen hilft, eine aufgezeichnete Unterhaltung zu laden und jede Entscheidung eines Agenten zu überprüfen. Für jede Unterhaltungsrunde können Sie den Ausführungspfad, das Schritttiming, die Verwendung von Tokens, Wissensquellen, Schrittargumente und die Begründung des Orchestrators überprüfen.

Agent Debugger unterstützt zwei Datenquellen:

• Unterhaltungstranskript (Dataverse): Wenn eine Unterhaltung in Copilot Studio läuft, zeichnet die Plattform ein Aktivitätsprotokoll als Konversationstranskript in Dataverse auf. Agent Debugger fragt diese Datensätze direkt ab, sodass jeder veröffentlichte Agent mit Transkriptdaten sofort verfügbar ist.
• Copilot Studio Snapshot (ZIP): Der Copilot Studio Testbereich enthält eine Option Download Snapshot , die die aktuelle Testkonversation als ZIP-Datei exportiert. Das Hochladen dieser Datei in Agent Debugger gibt Ihnen die vollständige Analyseansicht ohne Dataverse-Verbindung. Diese Methode ist nützlich, um Vorproduktionsunterhaltungen zu debuggen, Probleme offline zu reproduzieren oder eine fehlschlagende Sitzung mit Kollegen zu teilen.

Beide Datenquellen speisen dieselbe Analyseschnittstelle. Die Bereiche, Schrittdetails und Visualisierungen sind unabhängig davon, wie die Daten geladen werden, gleich.

Voraussetzungen

Stellen Sie zum Verwenden von Agent Debugger sicher, dass die folgenden Voraussetzungen erfüllt sind:

• Der Agent ist im Agentenbestand anwesend und hat mindestens ein Unterhaltungstranskript dagegen aufgenommen. Sie können diese Bedingung überprüfen, indem Sie die Agentenbestandslistenansicht öffnen, den Agenten auswählen und die zusätzlichen Felder erweitern. Das Feld Ist Transkript verfügbar muss auf Ja gesetzt werden. Die Agent-Bestandssynchronisierung setzt dieses Feld automatisch, wenn mindestens ein Unterhaltungstranskript für den Agenten in Dataverse existiert.
• Der angemeldete Benutzer hat in der Kit-Umgebung die Sicherheitsrolle CSK–Administrator oder Systemadministrator.
• Der angemeldete Benutzer hat Lesezugriff auf die conversationtranscripts, bot, und botcomponents-Tabellen in der Zielumgebung.

Eine Unterhaltung auswählen

Wenn Sie Agent Debugger öffnen, liefert die Filterleiste die Steuerelemente, die Sie brauchen, um eine Unterhaltung zur Analyse zu finden.

Nachdem Sie eine Konversations-ID ausgewählt haben, wird Analysieren verfügbar. Wählen Sie sie aus, um die Analyseansicht zu öffnen.

Einen Schnappschuss aus Copilot Studio hochladen

Die Registerkarte Snapshot hochladen bietet einen alternativen Einstiegspunkt, der keinen Zugriff auf Dataverse erfordert. Anstatt eine Live-Unterhaltung aus den Dropdowns auszuwählen, laden Sie eine Snapshot-ZIP-Datei hoch, die aus dem Copilot Studio Testfeld heruntergeladen wurde.

Um einen Schnappschuss aus Copilot Studio herunterzuladen:

1. Öffnen Sie Ihren Agenten in Copilot Studio und wechseln Sie zum Bereich Ihren Agenten testen.
2. Führen Sie eine Unterhaltung aus oder prüfen Sie diese.
3. Wählen Sie Snapshot herunterladen in der Symbolleiste Testbereich.

Copilot Studio lädt eine .zip Datei herunter, die Folgendes enthält:

• dialog.json: Alle Bot Framework-Aktivitäten für die Unterhaltung (erforderlich).
• botContent.yml: Die vollständigen Komponenten- und Flow-Definitionen des Agenten, die zur Auflösung von Schrittnamen verwendet werden (optional; bei Abwesenheit werden rohe Schemanamen angezeigt).

Um einen Schnappschuss in Agent Debugger hochzuladen:

1. Wechseln Sie zur Registerkarte Snapshot hochladen im Agent Debugger-Header.
2. Ziehen Sie die .zip-Datei auf die Drop-Zone zum Ablegen oder wählen Sie sie zum Durchsuchen aus.

Agent Debugger validiert die ZIP, extrahiert die Dateien und öffnet die Analyseansicht. Eine Auswahl von Umgebung, Agenten oder Unterhaltungen ist nicht erforderlich. Alle allgemeinen Informationsmetriken stammen aus der hochgeladenen Datei.

Nutzen Sie den Upload-Snapshot-Modus, wenn Sie Folgendes brauchen:

• Debuggen Sie eine Unterhaltung, die im Testfenster stattfand, bevor der Agent veröffentlicht wurde.
• Analysieren Sie eine Unterhaltung aus einer Umgebung, gegen die Sie sich nicht authentifizieren können.
• Reproduzieren Sie Probleme offline oder teilen Sie eine fehlerhafte Sitzung mit einem Kollegen, ohne Zugang zu Dataverse zu gewähren.
• Validieren Sie das Agentenverhalten in einer lokalen Entwicklungsumgebung.

Analysieren einer Unterhaltung

Die Analyseansicht öffnet sich, nachdem Sie Analysieren gewählt oder einen Snapshot hochgeladen haben. Sie enthält oben eine Zusammenfassungsreihe Allgemeine Informationen, einen zusammenklappbaren Analysebereich mit vier Bereichen (Ausführungspfad, Leistungszeitplan, Agentendetails und Empfehlungen) sowie ein zweiteiliges Layout, das die Unterhaltungsvorschau neben dem Bereich Debug-Informationen zeigt.

Allgemeine Angaben

Die Zeile für allgemeine Informationen zeigt Zusammenfassungsmetrik-Kacheln für die Unterhaltungen.

Wenn ein Live-Agent geladen wird, erscheint im allgemeinen Informationsheader ein Link Agent öffnen . Der Link öffnet die Konfigurationsseite des Agenten in Copilot Studio.

Ausführungspfad

Der Ausführungspfad stellt die vollständige Ausführungsreihenfolge über alle Konversationsrunden als gerichtetes Flussdiagramm dar. Die Schritte fließen von links nach rechts in der Ausführungsreihenfolge. Gestrichelte vertikale Linien markieren Rundengrenzen, und jede Benutzernachricht beginnt einen neuen Abschnitt. Dialogrunden-Beschriftungen erscheinen oben in jedem Abschnitt. Wenn man eine Dialogrunden-Beschriftung auswählt, scrollt die Konversationsvorschau zu dieser Nachricht.

Jeder Schritttyp verwendet eine eigene Farbe, und eine Legende am unteren Rand des Diagramms weist Farben auf Schrittkategorien wie Thema, Wissen, Werkzeug, Connector, Flow, Code, MCP und verbundener Agent zu. Jeder Knoten zeigt den Schrittnamen und die Ausführungsdauer an. Fehlgeschlagene Schritte sind rot markiert. Verbundene Agenten erscheinen als Containerboxen, die die von ihnen ausgeführten untergeordneten Schritte gruppieren.

Leistungszeitachse

Die Leistungszeitachse zeigt ein Wasserfalldiagramm der Schrittausführungszeiten, gruppiert nach Unterhaltungsrunde. Die Stufenbalken werden an die Gesamtdauer der Dialogrunde angepasst, um das relative Timing sichtbar zu machen. Die Farbcodierung entspricht der Ausführungspfad-Legende, und fehlgeschlagene Schritte erscheinen rot.

Dieser Bereich unterstützt folgende Features:

• Erweitern/Reduzieren Alle-Buttons schalten alle Rundenabschnitte gleichzeitig um. Jeder Rundenabschnitt ist zudem einzeln reduzierbar.
• Die Statistiken pro Runde zeigen die Schrittanzahl, den Namen und die Dauer des langsamsten Schrittes sowie die Anzahl der Fehlschläge an.
• Eine globale Zusammenfassung oben zeigt die Gesamtzahl der Schritte, die gesamte vergangene Zeit, den langsamsten Schritt in der gesamten Unterhaltung und die Gesamtzahl der Fehler.
• Schritte, die langsamer als 10 Sekunden sind, werden mit einer Warnmeldung markiert.

Agent-Details

Der Bereich Agentendetail zeigt die vollständige Konfiguration des Agenten, wie er zum Zeitpunkt der Analyse der Unterhaltung existierte. Die Informationen sind in sechs Registerkarten organisiert.

Empfehlungen

Der Empfehlungsbereich erkennt Probleme in der Unterhaltung automatisch und stellt sie als umsetzbare Karten mit Schweregradbewertungen dar.

Folgende Problemtypen werden erkannt:

Jede Empfehlungskarte zeigt das Schweregrad-Symbol und die Farbe, ein Kategorie-Badge, den Titel und die Beschreibung des erkannten Problems, einen Vorschlag, wie man es untersuchen oder lösen kann, sowie eine Schaltfläche Umdrehen, die die Konversationsvorschau zur relevanten Benutzernachricht scrollt. Wenn keine Probleme festgestellt werden, zeigt der Bereich eine Leerzustandsmeldung an.

Vorschau einer Unterhaltung

Der Bereich Unterhaltungsvorschau zeigt den vollständigen Unterhaltungsaustausch, wie er dem Benutzer erschien, einschließlich Bot- und Nutzer-Nachrichtenblasen, adaptiven Karten in der Reihenfolge, vorgeschlagenen Aktionschips und Feedback-Eingaben.

Die Auswahl einer Benutzernachrichtenblase lädt die Schritte dieser Runde in den Bereich Informationen debuggen. Die ausgewählte Nachricht ist hervorgehoben, damit Sie verfolgen können, welche Runde aktiv ist. Der Bereich ist unabhängig scrollbar. Wenn Sie im Unterhaltungsvorschau-Header JSON anzeigen auswählen, öffnet sich der vollständige Transkript-JSON-Dialog.

Debuginformationen

Der Bereich Debug-Informationen zeigt Schrittebene-Details für die ausgewählte Benutzernachrichtrunde. Der Bereich enthält links eine Schrittliste und eine Schritt-Detailansicht, die sich öffnet, wenn Sie einen Schritt auswählen.

Die Schrittliste zeigt jeden Orchestrator-Schritt, der für die ausgewählte Runde ausgeführt wurde, mit einem Schritt-Symbol und einer Farbe, die den Schritttyp, den Schrittnamen (wo möglich in einen freundlichen Anzeigenamen umgewandelt), die Ausführungsdauer sowie einen Erfolgs- oder Fehlschlagindikator angibt. Schritte, die zu einem verbundenen Agenten gehören, sind in einer reduzierbaren Containerkarte gruppiert, die den Agentennamen und die gesamte Ausführungszeit anzeigt. Eine Schaltfläche Laden verbundener Agentendetails am Container lädt das vollständige Transkript des untergeordneten Agenten bei Bedarf.

Folgende Schritttypen werden unterstützt:

Wenn man einen Schritt auswählt, öffnet sich ein Detailbereich mit den folgenden Abschnitten, die angezeigt werden, wenn die Daten im Transkript vorhanden sind:

• Gedankengang: Der Argumentationstext des Orchestrators wurde vor dem Aufruf des Schrittes aufgezeichnet. Zeigt, wie das Modell diesen Schritt genannt hat und was es davon erwartet hat.
• Schritttyp: Klassifizierte Beschriftung für den Schritt.
• Argumente: Eine reduzierbare JSON-Baumansicht der Eingabeparameter, die an den Schritt übergeben wird. Enthält eine Kopieroption, um das JSON für Support-Tickets zu erfassen.
• Beobachtung: Der Ausgabe- oder Rückgabewert des Schritts. Ebenfalls als reduzierbarer JSON-Baum mit Kopierunterstützung angezeigt.
• Code-Vorschau: Bei Python-Codeschritten wird der Quellcode mit Syntaxhervorhebung angezeigt.
• Token-Verwendung: Prompt-Token-Anzahl, Abschluss-Token und Gesamtzahl für den Schritt zusammen mit dem verwendeten Modellnamen.
• Wissensquellen: Quellen, die durchsucht wurden, Ergebnisse (Output) und tatsächlich in der endgültigen Antwort zitierte Quellen. Jeder Eintrag zeigt den Quellnamen, den Typ, die URL, wo verfügbar, sowie einen Link zum Öffnen der Quelle.
• MCP-Serverinfo: Für MCP-Schritte zeigt es die Protokollversion des Servers, deklarierte Fähigkeiten und die Liste der Tools, die der Server während der Initialisierung bereitgestellt hat.
• Fehlerinformation: Wenn ein Schritt fehlgeschlagen ist, werden der Fehlercode, die Fehlermeldung und (bei verantwortungsvolle AI-Sperren) die Inhaltssicherheitskategorie angezeigt, die den Filter ausgelöst hat.
• Adaptive Karten: Wenn der Schritt eine adaptive Karte-Antwort erzeugt, wird die Karte im Detailbereich exakt so dargestellt, wie der Benutzer sie gesehen hätte.

Transkript-JSON

Wenn Sie im Gesprächsvorschau-Header JSON anzeigen auswählen, öffnet sich ein Dialog, der die vollständigen Roh-Transkript-Aktivitäten mit Syntax-Hervorhebung, Volltextsuche im JSON-Baum und einer Kopier-zu-Zwischenablage-Option für die gesamte Nutzlast anzeigt.

Verwenden Sie diese Ansicht wenn:

• Sie einen Ereignistyp inspizieren müssen, der nicht im Bereich Debug-Informationen angezeigt wird.
• Sie möchten bestimmte Felder für ein Support-Ticket kopieren.
• Sie untersuchen unerwartetes Verhalten in den geparsten Ansichten.

Problembehandlung

Die folgenden Abschnitte beschreiben die häufigsten Problem und deren Lösung.

Agent erscheint nicht in der Umgebung im Agent-Dropdown-Menü

Der Agent ist nicht mit dem Agentenbestand synchronisiert oder hat keine Unterhaltungstranskripte.

So beheben Sie dieses Problem:

1. Führen Sie eine manuelle Agent-Bestandsynchronisierung für die Umgebung aus.
2. Überprüfen Sie, ob der Agenteneintrag in der Agentendetails-Tabelle in Dataverse existiert.
3. Überprüfen Sie, ob die Spalte Ist Transkript verfügbar auf Ja im Bericht gesetzt ist. Die Synchronisierung setzt dieses Feld, wenn mindestens ein Transkript existiert.

Weitere Informationen finden Sie unter Agentüberwachung mittels Agentenbestand im Copilot-Agent-Kit.

Die Konversations-ID ist im Dropdown-Menü nicht zu finden

Für die Leistung lädt das Dropdown-Menü nur die 50 aktuellen Unterhaltungen im aktiven Zeitbereich vor. Ältere Transkripte existieren noch in Dataverse, erscheinen aber nicht standardmäßig. Alternativ kann es sein, dass das Transkript noch nicht geschrieben ist, wenn die Unterhaltung gerade beendet ist.

So beheben Sie dieses Problem:

1. Geben Sie die Konversations-ID direkt in das Feld Konversations-ID ein. Das Tippen löst eine vollständige Suche in allen Transkripten nach diesem Agenten aus, wobei der Zeitbereich ignoriert wird.
2. Wenn der Zeitbereich eng ist (zum Beispiel letzte 30 Minuten), erweitern Sie ihn oder wechseln Sie zu einem benutzerdefinierten Bereich, der das Unterhaltungsdatum abdeckt.
3. Wenn die Unterhaltung gerade beendet ist, warten Sie 35–40 Minuten, bis das Transkript in Dataverse geschrieben wird, und aktualisieren Sie es dann.

Analysieren von Lasten, aber im Debug-Informationsbereich erscheinen keine Schritte

Das Transkript existiert, enthält jedoch nur Nachrichtenaktivitäten ohne diagnostische Spuren. Dieses Problem tritt typischerweise auf, wenn die Konversation von einem Kanal stammt, der keine Überwachungsdaten ausliefert, wie bestimmte benutzerdefinierte Kanäle oder ältere Schema-Versionen.

So beheben Sie dieses Problem:

1. Wählen Sie in der Konversationsvorschau-Kopfzeile JSON anzeigen aus, um sicherzustellen, dass Aktivitäten vorhanden sind.
2. Suchen Sie nach type: "trace" oder type: "event"-Einträgen. Wenn sie fehlen, gibt der Kanal möglicherweise keine Überwachungsdaten aus.

Zugriff verweigert oder leere Seite beim Laden

Rollen oder Berechtigungen fehlen in einer oder beiden Umgebungen.

So beheben Sie dieses Problem:

1. Stellen Sie in der Kit-Umgebung sicher, dass der Benutzer Rolle CSK–Administrator oder Systemadministrator hat.
2. Stellen Sie in der Zielumgebung sicher, dass der angemeldete Benutzer Lesezugriff auf die Tabellen conversationtranscripts, bot und botcomponents hat.

Transkripte erscheinen unvollständig (fehlende frühe Nachrichten)

Lange Unterhaltungen werden auf mehrere Dataverse-Datensätze verteilt (1 MB Limit pro Datensatz). Wenn die Aufbewahrungsrichtlinie einige Unterlagen entfernt, gibt es Lücken im zusammengeführten Transkript.

So beheben Sie dieses Problem:

1. Dataverse löscht standardmäßig Unterhaltungstranskripte, die älter als 30 Tage sind. Wenn die Aufbewahrung das Problem ist, aktualisieren Sie den Massenlösch-Jobplan in Power Apps>Einstellungen>Erweiterte Einstellungen>Datenverwaltung>Löschung von Massendatensätzen.
2. Wenn die Aufbewahrung nicht der Grund ist, überprüfen Sie, ob alle Transkriptaufzeichnungen für die Unterhaltung in der conversationtranscripts-Tabelle in Dataverse vorhanden sind.

Schritte zeigen ungefähre Schemanamen statt lesbarer Themennamen

Die botcomponents Tabellensuche schlug fehl oder der Komponenteneintrag wurde gelöscht.

So beheben Sie dieses Problem:

1. Überprüfen Sie, ob der angemeldete Benutzer Lesezugriff auf die botcomponents-Tabellen in der Zielumgebung hat.
2. Wenn die Komponente aus Copilot Studio gelöscht wurde, existiert kein übereinstimmender Datensatz und Agent Debugger greift auf den rohen Schemanamen zurück, wie zum Beispiel cr123_mytopic. Dieses Verhalten ist bei gelöschten Themen oder Aktionen zu erwarten.

Der Agenteninformationsbereich zeigt keine Daten an

Der Agent-Konfigurationsabruf ist fehlgeschlagen, oder die Verbindung des angemeldeten Benutzers hat keinen Lesezugriff auf die bot und botcomponents-Tabellen in der Zielumgebung.

So beheben Sie dieses Problem:

1. Überprüfen Sie den Lesezugriff auf die bot und botcomponents-Tabellen für die von der App verwendete Verbindungsreferenz.
2. Wenn der Agent nach der Aufzeichnung der Unterhaltung gelöscht oder unveröffentlicht wurde, könnten seine Konfigurationsdatensätze nicht mehr existieren. In diesem Fall bleibt der Bereich Agent-Detail leer, aber die Transkript- und Debugbereiche sind weiterhin voll funktionsfähig.

Das Empfehlungspanel zeigt keine Probleme, aber die Unterhaltung scheiterte

Empfehlungen stammen aus Mustern in den Transkript-Überwachungsereignissen. Wenn das Transkript keine Überwachungsdaten enthält oder der Fehler außerhalb der Unterhaltung auftritt (zum Beispiel ein stilles Netzwerk-Timeout, das das Transkript nicht aufzeichnet), erstellt das System keine Empfehlungen.

So beheben Sie dieses Problem:

1. Öffnen Sie das Transkript-JSON, um nach rohen Fehlernutzlasten zu suchen, die nicht als Empfehlung angezeigt werden.
2. Überprüfen Sie den Ausführungspfad auf alle Schritte, die rot angezeigt sind. Diese Schritte weisen auf Fehler hin, die nicht mit einem bekannten Empfehlungsmuster übereinstimmen.

Verwandte Informationen

• Agenten mit Agent-Bestand im Copilot-Agent-Kit überwachen
• Agenten im Copilot-Agent-Kit konfigurieren
• Übersicht über Copilot-Agent-Kit