Los problemen met agentgesprekken op met Agent-debugger in Copilot-agentkit.

De Agent-debugger is een diagnostisch hulpmiddel waarmee u een opgenomen gesprek kunt laden en elke beslissing die een agent heeft genomen kunt inspecteren. Voor elke gespreksronde kunt u het uitvoeringspad, de timing van de stappen, het tokengebruik, de kennisbronnen, de argumenten van de stappen en de redenering van de orchestrator bekijken.

De Agent-debugger ondersteunt twee gegevensbronnen:

• Gesprekstranscript (Dataverse): Wanneer een gesprek in Copilot Studio wordt uitgevoerd, registreert het platform een ​​activiteitenlogboek als een gesprekstranscript in Dataverse. De Agent-debugger raadpleegt deze records direct, zodat elke gepubliceerde agent met transcriptgegevens direct beschikbaar is.
• Copilot Studio-snapshot (ZIP): Het testpaneel van Copilot Studio bevat een Snapshot downloaden-optie waarmee het huidige testgesprek als een ZIP-bestand wordt geëxporteerd. Door dit bestand naar de Agent-debugger te uploaden, krijgt u de volledige analyseweergave zonder Dataverse-verbinding. Deze methode is handig voor het debuggen van preproductiegesprekken, het offline reproduceren van problemen of het delen van een mislukte sessie met een collega.

Beide gegevensbronnen voeden dezelfde analyse-interface. De panelen, stapdetails en visualisaties zijn hetzelfde, ongeacht hoe de gegevens worden geladen.

Vereisten

Om Agent-debugger te gebruiken, moet aan de volgende voorwaarden worden voldaan:

• De agent is aanwezig in Agent Inventory en heeft ten minste één gesprekstranscript dat eraan is gekoppeld. U kunt deze voorwaarde controleren door de lijstweergave Agent Inventory te openen, de agent te selecteren en Meer weergeven te selecteren om de extra velden uit te vouwen. Het veld Is Transcript beschikbaar moet zijn ingesteld op Ja. De synchronisatie van Agent Inventory stelt dit veld automatisch in wanneer er ten minste één gesprekstranscript voor de agent in Dataverse bestaat.
• De aangemelde gebruiker heeft de beveiligingsrol CSK - Beheerder of Systeembeheerder in de kitomgeving.
• De aangemelde gebruiker heeft Lees toegang tot de conversationtranscripts, bot en botcomponents tabellen in de doelomgeving.

Selecteer een gesprek

Wanneer u Agent-debugger opent, biedt de filterbalk de benodigde opties om een ​​gesprek te vinden dat u wilt analyseren.

Nadat u een Gespreks-ID hebt geselecteerd, wordt Analyseren beschikbaar. Selecteer deze optie om de analyseweergave te openen.

Een snapshot uploaden vanuit Copilot Studio

Het tabblad Snapshot uploaden biedt een alternatieve manier om toegang te krijgen zonder Dataverse-toegang. In plaats van een live gesprek te selecteren uit de dropdownmenu's, uploadt u een snapshot-ZIP-bestand dat u hebt gedownload vanuit het testvenster van Copilot Studio.

Een snapshot downloaden vanuit Copilot Studio:

1. Open uw agent in Copilot Studio en ga naar het paneel Test uw agent.
2. Voer een gesprek uit of bekijk het.
3. Selecteer Snapshot downloaden in de werkbalk van het testvenster.

Copilot Studio downloadt een bestand .zip dat het volgende bevat:

• dialog.json: Alle Bot Framework-activiteiten voor het gesprek (verplicht).
• botContent.yml: De volledige component- en stroomdefinities van de agent, gebruikt om stapnamen op te lossen (optioneel; indien afwezig, worden de onbewerkte schemanamen weergegeven).

Om een ​​snapshot te uploaden naar Agent-debugger:

1. Schakel over naar het tabblad Snapshot uploaden in de header van Agent-debugger.
2. Sleep het .zip-bestand naar de dropzone of selecteer het om ernaar te bladeren.

Agent-debugger valideert het ZIP-bestand, pakt de bestanden uit en opent de analyseweergave. Er is geen selectie van omgeving, agent of conversatie vereist. Alle algemene informatiemetrieken zijn afgeleid van het geüploade bestand.

Gebruik de modus 'Snapshot uploaden' wanneer u het volgende nodig hebt:

• Een conversatie debuggen die plaatsvond in het testvenster voordat de agent werd gepubliceerd.
• Een conversatie analyseren vanuit een omgeving waartegen u zich niet kunt authenticeren.
• Problemen offline reproduceren of een mislukte sessie delen met een collega zonder Dataverse-toegang te verlenen.
• Het gedrag van de agent valideren in een lokale ontwikkelomgeving.

Een gesprek analyseren

De analyseweergave wordt geopend nadat u Analyseren hebt geselecteerd of een momentopname hebt geüpload. Deze bevat een Algemene informatie samenvattingsregel bovenaan, een inklapbaar analysegedeelte met vier panelen (Uitvoeringspad, Prestatietijdlijn, Agentdetails en Aanbevelingen) en een lay-out met twee panelen die de Gespreview naast het Foutopsporingsinformatie paneel toont.

Algemene informatie

De regel met algemene informatie toont samenvattende statistieken voor het gesprek.

Wanneer een live agent is geladen, verschijnt een link Agent openen in de header met algemene informatie. De link opent de configuratiepagina van de agent in Copilot Studio.

Uitvoeringspad

Het uitvoeringspad geeft de volledige uitvoeringsvolgorde van alle gespreksbeurten weer als een stroomdiagram. De stappen verlopen van links naar rechts in de uitvoeringsvolgorde. Gestippelde verticale lijnen markeren de grenzen van de beurten en elk gebruikersbericht start een nieuwe sectie. Bovenaan elke sectie verschijnen de labels van de beurten. Door een beurtlabel te selecteren, scrollt de Gesprekspreview naar dat bericht.

Elk staptype heeft een aparte kleur en een legenda onderaan het diagram koppelt kleuren aan stapcategorieën zoals Onderwerp, Kennis, Hulpmiddel, Connector, Flow, Code, MCP en Verbonden Agent. Elk knooppunt toont de stapnaam en de uitvoeringsduur. Mislukte stappen worden rood gemarkeerd. Verbonden agenten worden weergegeven als containerboxen die de onderliggende stappen groeperen die ze hebben uitgevoerd.

Prestatietijdlijn

De prestatietijdlijn toont een watervaldiagram van de uitvoeringstijden van stappen, gegroepeerd per gespreksbeurt. De stapbalken zijn geschaald naar de totale duur van de beurt om de relatieve timing zichtbaar te maken. De kleurcodering komt overeen met de legenda van het uitvoeringspad en mislukte stappen worden rood weergegeven.

Het paneel bevat de volgende functies:

• De knoppen Alles uitvouwen/inklappen tonen alle beurtsecties tegelijk. Elke beurtsectie kan ook afzonderlijk worden ingeklapt.
• Statistieken per beurt tonen het aantal stappen, de naam en duur van de langzaamste stap en het aantal mislukkingen.
• Bovenaan staat een algemeen overzicht met het totale aantal stappen, de totale verstreken tijd, de langzaamste stap in het hele gesprek en het totale aantal mislukte stappen.
• Stappen die langer dan 10 seconden duren, worden gemarkeerd met een waarschuwingsindicator.

Details van agent

Het paneel met agentdetails toont de volledige configuratie van de agent zoals die bestond op het moment dat het gesprek werd geanalyseerd. De informatie is georganiseerd in zes tabbladen.

Aanbevelingen

Het aanbevelingspaneel detecteert automatisch problemen in het gesprek en toont deze als actiekaarten met ernstclassificaties.

De volgende probleemtypen worden gedetecteerd:

Elke aanbevelingskaart toont het ernstpictogram en de kleur, een categoriebadge, de titel en beschrijving van het gedetecteerde probleem, een suggestie voor hoe het te onderzoeken of op te lossen, en een Ga naar beurt-knop waarmee de Gespreview naar het relevante gebruikersbericht wordt gescrolld. Wanneer er geen problemen worden gedetecteerd, toont het paneel een leeg statusbericht.

Gesprekspreview

Het paneel met de gesprekspreview toont de volledige gespreksuitwisseling zoals deze aan de gebruiker werd getoond, inclusief berichtballonnen van de bot en de gebruiker, inline weergegeven Adaptieve kaarten, voorgestelde actiechips en feedbackprompts.

Door een gebruikersberichtballon te selecteren, worden de stappen van die beurt in het paneel Foutopsporingsinformatie geladen. Het geselecteerde bericht wordt gemarkeerd, zodat u kunt zien welke beurt actief is. Het paneel is onafhankelijk scrollbaar. Door JSON bekijken in de koptekst van het gespreksvoorbeeld te selecteren, wordt het dialoogvenster met het volledige transcript in JSON-formaat geopend.

Foutopsporingsinformatie

Het paneel met foutopsporingsinformatie toont details op stapniveau voor de geselecteerde gebruikersberichtbeurt. Het paneel bevat een stappenlijst aan de linkerkant en een detailweergave van een stap die wordt geopend wanneer u een stap selecteert.

De stappenlijst toont elke orchestratorstap die voor de geselecteerde beurt is uitgevoerd, met een stapicoon en kleur die het staptype aangeven, de stapnaam (waar mogelijk omgezet naar een gebruiksvriendelijke weergavenaam), de uitvoeringsduur en een indicator voor succes of mislukking. Stappen die bij een verbonden agent horen, worden gegroepeerd in een inklapbare containerkaart die de agentnaam en de totale uitvoeringstijd weergeeft. Een knop Details van verbonden agent laden op de container laadt het volledige transcript van de onderliggende agent op aanvraag.

De volgende staptypen worden ondersteund:

Door een stap te selecteren, wordt een detailvenster geopend met de volgende secties, die worden weergegeven wanneer de gegevens in het transcript aanwezig zijn:

• Denkproces: De redeneertekst van de orchestrator die is vastgelegd voordat de stap werd aangeroepen. Laat zien hoe het model heeft besloten deze stap aan te roepen en wat het ervan verwachtte.
• Staptype: Geclassificeerd label voor de stap.
• Argumenten: Een inklapbare JSON-boomstructuurweergave van de invoerparameters die aan de stap zijn doorgegeven. Bevat een kopieeroptie om de JSON vast te leggen voor supporttickets.
• Observatie: De uitvoer- of retourwaarde van de stap. Ook weergegeven als een inklapbare JSON-boom met kopieerondersteuning.
• Codevoorbeeld: Voor Python-codestappen wordt de broncode weergegeven met syntaxmarkering.
• Tokengebruik: Aantal prompttokens, aantal voltooiingstokens en het totaal voor de stap, samen met de gebruikte modelnaam.
• Kennisbronnen: Bronnen die zijn doorzocht, geretourneerde resultaten (uitvoer) en bronnen die daadwerkelijk in het uiteindelijke antwoord worden geciteerd. Elke vermelding toont de bronnaam, het type, de URL (indien beschikbaar) en een link om de bron te openen.
• MCP-serverinfo: Voor MCP-stappen wordt de protocolversie van de server, de gedeclareerde mogelijkheden en de lijst met tools die de server tijdens de initialisatie heeft geleverd, weergegeven.
• Foutinformatie: Wanneer een stap is mislukt, wordt de foutcode, het foutbericht en (voor Responsible AI-blokken) de categorie voor inhoudsveiligheid die het filter heeft geactiveerd, weergegeven.
• Adaptieve kaarten: Wanneer de stap een reactie met een adaptieve kaart heeft opgeleverd, wordt de kaart inline in het detailvenster weergegeven, precies zoals de gebruiker deze zou hebben gezien.

Transcript-JSON

Wanneer u JSON bekijken selecteert in de koptekst van het gespreksvoorbeeld, wordt een dialoogvenster geopend met de volledige onbewerkte transcriptactiviteiten, inclusief syntaxmarkering, zoeken in de volledige tekst binnen de JSON-structuur en een optie om de volledige payload naar het klembord te kopiëren.

Gebruik deze weergave wanneer:

• U moet een gebeurtenistype inspecteren dat niet wordt weergegeven in het paneel Foutopsporingsinformatie.
• U wilt specifieke velden kopiëren voor een supportticket.
• U onderzoekt onverwacht gedrag in de geparseerde weergaven.

Probleemoplossing

De volgende secties beschrijven veelvoorkomende problemen en hoe u deze kunt oplossen.

De agent verschijnt niet in de vervolgkeuzelijst Omgeving of Agent

De agent is niet gesynchroniseerd met Agent Inventory of heeft geen gesprekstranscripten.

Ga als volgt te werk om het probleem op te lossen:

1. Voer een handmatige synchronisatie van Agent Inventory uit voor de omgeving.
2. Controleer of het agentrecord bestaat in de tabel Agentdetails in Dataverse.
3. Controleer of de kolom Is transcript beschikbaar is ingesteld op Ja in het record. De synchronisatie stelt dit veld in wanneer er ten minste één transcript bestaat.

Voor meer informatie, zie Agenten bewaken met Agent Inventory in Copilot-agentkit.

Gespreks-ID niet gevonden in de dropdown

Om de prestaties te verbeteren, laadt de dropdown alleen de 50 meest recente gesprekken binnen het actieve tijdsbereik. Oudere transcripten bestaan ​​nog steeds in Dataverse, maar worden standaard niet weergegeven. Het kan ook zijn dat het transcript nog niet is geschreven als het gesprek net is beëindigd.

Ga als volgt te werk om het probleem op te lossen:

1. Typ de gespreks-ID rechtstreeks in het veld Gespreks-ID. Het typen activeert een volledige zoekopdracht in alle transcripten voor die agent, waarbij het tijdsbereik wordt genegeerd.
2. Als het tijdsbereik smal is (bijvoorbeeld Afgelopen 30 minuten), breid het dan uit of schakel over naar een aangepast bereik dat de gespreksdatum omvat.
3. Als het gesprek net is beëindigd, wacht dan 35-40 minuten totdat het transcript naar Dataverse is geschreven en vernieuw vervolgens de pagina.

Analyseer de gegevens, maar er verschijnen geen stappen in het paneel met foutopsporingsinformatie.

Het transcript bestaat, maar bevat alleen activiteiten van het type bericht, zonder diagnostische traceergebeurtenissen. Dit probleem treedt meestal op wanneer het gesprek afkomstig is van een kanaal dat geen traceergegevens verzendt, zoals bepaalde aangepaste kanalen of oudere schemaversies.

Ga als volgt te werk om het probleem op te lossen:

1. Selecteer JSON bekijken in de koptekst van het gespreksvoorbeeld om te controleren of er activiteiten aanwezig zijn.
2. Zoek naar type: "trace" of type: "event" vermeldingen. Als deze ontbreken, verzendt het kanaal mogelijk geen traceergegevens.

Toegang geweigerd of lege pagina bij het laden

Rollen of machtigingen ontbreken in een of beide omgevingen.

Ga als volgt te werk om het probleem op te lossen:

1. Zorg ervoor dat de gebruiker in de kitomgeving de rol CSK - Beheerder of Systeembeheerder heeft.
2. Zorg ervoor dat de aangemelde gebruiker in de doelomgeving leesrechten heeft voor de tabellen conversationtranscripts, bot en botcomponents.

Transcripten lijken onvolledig (vroege berichten ontbreken)

Lange gesprekken worden verdeeld over meerdere Dataverse-records (limiet van 1 MB per record). Als het bewaarbeleid sommige records verwijdert, bevat het samengevoegde transcript hiaten.

Ga als volgt te werk om het probleem op te lossen:

1. Dataverse verwijdert standaard gesprekstranscripten die ouder zijn dan 30 dagen. Als het bewaarbeleid het probleem is, werk dan het schema voor bulkverwijdering bij in Power Apps>Instellingen>Geavanceerde instellingen>Gegevensbeheer>Bulkrecordverwijdering.
2. Als het probleem niet wordt veroorzaakt door het bewaren van gegevens, controleer dan of alle transcriptrecords voor het gesprek aanwezig zijn in de conversationtranscripts-tabel in Dataverse.

De stappen tonen onbewerkte schemanamen in plaats van leesbare onderwerpnamen.

De opzoeking in de botcomponents-tabel is mislukt of het componentrecord is verwijderd.

Ga als volgt te werk om het probleem op te lossen:

1. Controleer of de aangemelde gebruiker leesrechten heeft voor de botcomponents-tabel in de doelomgeving.
2. Als het component is verwijderd uit Copilot Studio, bestaat er geen overeenkomend record en gebruikt Agent-debugger de onbewerkte schemanaam, zoals cr123_mytopic. Dit gedrag is te verwachten voor verwijderde onderwerpen of acties.

Het paneel met agentdetails toont geen gegevens.

Het ophalen van de agentconfiguratie is mislukt of de verbinding van de aangemelde gebruiker heeft geen leesrechten voor de bot- en botcomponents-tabellen in de doelomgeving.

Ga als volgt te werk om het probleem op te lossen:

1. Controleer de leesrechten voor de bot en botcomponents tabellen voor de verbindingsreferentie die door de app wordt gebruikt.
2. Als de agent is verwijderd of gedeactiveerd nadat het gesprek is opgenomen, bestaan ​​de configuratiegegevens mogelijk niet meer. In dit geval blijft het paneel Agentdetails leeg, maar de panelen voor transcriptie en debuggen zijn nog steeds volledig functioneel.

Het paneel met aanbevelingen toont geen problemen, maar het gesprek is mislukt.

Aanbevelingen zijn gebaseerd op patronen in de traceergebeurtenissen van de transcriptie. Als de transcriptie geen traceergegevens bevat, of als de fout buiten het gesprek optreedt (bijvoorbeeld een stille netwerktime-out die niet in de transcriptie wordt vastgelegd), genereert het systeem geen aanbevelingen.

Ga als volgt te werk om het probleem op te lossen:

1. Open de JSON van de transcriptie om te zoeken naar onbewerkte foutpayloads die niet als aanbeveling worden weergegeven.
2. Controleer het uitvoeringspad op stappen die in het rood worden weergegeven. Deze stappen duiden op fouten die niet overeenkomen met een bekend aanbevelingspatroon.

Gerelateerde informatie

• Agenten monitoren met Agent Inventory in Copilot Agent Kit
• Agenten configureren in Copilot-agentkit
• Overzicht van Copilot Agent Kit