Felsök agentkonversationer med Agent Debugger i paketet för Copilot-agent

Agent Debugger är ett diagnostiskt verktyg som hjälper dig att ladda en inspelad konversation och granska varje beslut en agent fattat. För varje konversationstur kan du granska körningsvägen, tidsåtgången för varje steg, tokenanvändningen, kunskapskällorna, stegargumenten och orkestrerings resonemang.

Agent Debugger stöder två datakällor:

• Konversationstranskription (Dataverse): När en konversation körs i Copilot Studio registrerar plattformen en aktivitetslogg som en konversationstranskription i Dataverse. Agent Debugger frågar direkt efter dessa poster, så alla publicerade agenter med transkriptdata är omedelbart tillgängliga.
• Copilot Studio-ögonblicksbild (ZIP): I testpanelen i Copilot Studio finns alternativet Ladda ned ögonblicksbild, som exporterar den aktuella testkonversationen som en ZIP-fil. Att ladda upp den filen till Agent Debugger ger dig hela analysvyn utan en Dataverse-anslutning. Den här metoden är användbar när du vill felsöka konversationer i en förproduktionsmiljö, återskapa problem offline eller dela en session där ett fel har uppstått med en kollega.

Båda datakällorna matar samma analysgränssnitt. Panelerna, stegdetaljerna och visualiseringarna är desamma oavsett hur datan laddas.

Krav

För att använda Agent Debugger, se till att följande förutsättningar är uppfyllda:

• Agenten finns i Agent Inventory och minst en konversationstranskription har registrerats för agenten. Du kan verifiera detta villkor genom att öppna Agent Inventory-listvyn, välja agenten och välja Visa mer för att utöka de ytterligare fälten. Fältet Är transkript tillgängligt måste vara inställt på Ja. Agent Inventory-synkroniseringen sätter automatiskt detta fält när minst en konversationstranskription finns för agenten i Dataverse.
• Den inloggade användaren har CSK – administratör eller Systemadministratör säkerhetsrollen i paketmiljön.
• Den inloggade användaren har läsbehörighet på tabellerna conversationtranscripts, bot och botcomponents i målmiljön.

Välj en konversation

När du öppnar Agent Debugger ger filterfältet de kontroller du behöver för att hitta en konversation att analysera.

Efter att du valt ett Konversations-ID blir Analysera tillgängligt. Välj den för att öppna analysvyn.

Ladda upp en ögonblicksbild från Copilot Studio

Fliken Ladda upp ögonblicksbild ger en alternativ ingångspunkt som inte kräver tillgång till Dataverse. Istället för att välja en livekonversation från rullgardinsmenyerna laddar du upp en snapshot ZIP-fil nedladdad från Copilot Studio-testpanelen.

Så här laddar du upp en ögonblicksbild från Copilot Studio:

1. Öppna huvudagenten i Copilot Studio och gå till panelen Testa din agent.
2. Kör eller granska en konversation.
3. Välj Ladda ned ögonblicksbild i testpanelens verktygsfält.

Copilot Studio laddar ned en .zip-fil som innehåller:

• dialog.json: Alla Bot Framework-aktiviteter för konversationen (krävs).
• botContent.yml: Agentens fullständiga komponent- och flödesdefinitioner, som används för att identifiera stegnamn (valfritt; om de saknas visas de råa schemanamnen).

För att ladda upp en ögonblicksbild till Agent Debugger:

1. Byt till fliken Ladda upp ögonblicksbild i Agent Debugger-rubrik.
2. Dra och släpp .zip-filen på släppzonen, eller välj att bläddra efter den.

Agent Debugger validerar ZIP-filen, extraherar filerna och öppnar analysvyn. Inget val av miljö, agent eller samtal krävs. Alla allmänna informationsmått härleds från den uppladdade filen.

Använd läget Ladda upp ögonblicksbild när du behöver:

• Felsök en konversation som ägde rum i testpanelen innan agenten publicerades.
• Analysera en konversation från en miljö du inte kan autentisera dig mot.
• Återskapa problem offline eller dela en felande session med en kollega utan att ge Dataverse åtkomst.
• Validera agentens beteende i en lokal utvecklingsmiljö.

Analysera en konversation

Analysvyn öppnas efter att du valt Analysera eller laddar upp en ögonblicksbild. Den innehåller en sammanfattningsrad med allmän information högst upp, en hopfällbar analyssektion med fyra paneler (körväg, Prestandatidslinje, Agentdetaljer och Rekommendationer) samt en tvåpanelslayout som visar förhandsversion av konversationen tillsammans med panelen Felsökningsinformation.

Allmän information

På raden Allmän information visas paneler med sammanfattande mått för konversationen.

När en levande agent laddas visas en länk till öppen agent i rubriken för allmän information. Länken öppnar agentens konfigurationssida i Copilot Studio.

Körväg

Körvägen visar den fullständiga körningsordningen för alla konversationsturer som ett riktat flödesdiagram. Stegen flyter från vänster till höger i körningsordning. Streckade vertikala linjer markerar svänggränser, och varje användarmeddelande startar en ny sektion. Etiketter för konversationsturer visas högst upp i varje avsnitt. När du väljer en etikett för en konversationstur rullas vyn Förhandsversion av konversation till motsvarande meddelande.

Varje stegtyp har en egen färg, och en teckenförklaring längst ned i diagrammet visar vilka stegkategorier färgerna motsvarar, till exempel Ämne, Kunskap, Verktyg, Anslutningsprogram, Flöde, Kod, MCP och Ansluten agent. Varje nod visar stegnamnet och körtiden. Misslyckade steg är markerade med rött. Anslutna agenter visas som behållarrutor där de underordnade steg som respektive agent körde grupperas.

Tidslinje för prestanda

Tidslinjen för prestandavisar ett vattenfallsdiagram över stegens körningstider, grupperade efter konversationstur. Stegstaplarna skalas efter konversationsturens totala varaktighet så att den relativa tidsåtgången framgår. Färgkodningen matchar körvägens förklaring och misslyckade steg visas i rött.

Panelen omfattar följande:

• Knapparna Expandera/Dölj alla växlar alla avsnitt för konversationsturer samtidigt. Varje avsnitt för en konversationstur kan även komprimeras separat.
• Statistik per tur visar antal steg, långsammast stegnamn och längd samt antal misslyckanden.
• En global sammanfattning högst upp visar totala antal steg, total förfluten tid, det långsammaste steget i hela konversationen och totalt antal misslyckanden.
• Steg som är långsammare än 10 sekunder markeras med en varningsindikator.

Handläggarinformation

Agentens detaljpanel visar hela konfigurationen av agenten så som den såg ut vid tidpunkten för samtalet analyserades. Informationen är organiserad i sex flikar.

Rekommendationer

Rekommendationspanelen upptäcker automatiskt problem i samtalet och lyfter fram dem som handlingsbara kort med allvarlighetsgrader.

Följande typer av problem upptäcks:

Varje rekommendationskort visar en ikon och färg för allvarlighetsgraden, en kategorietikett, rubriken och beskrivningen av det identifierade problemet, ett förslag på hur problemet kan undersökas eller lösas samt knappen Gå till konversationstur, som rullar vyn Förhandsgranskning av konversation till det relevanta användarmeddelandet. När inga problem upptäcks visar panelen ett meddelande om tomt tillstånd.

Förhandsversion för konversationer

Panelen Förhandsgranskning av konversation visar hela konversationen så som den visades för användaren, inklusive meddelandebubblor för agenten och användaren, adaptiva kort som återges direkt i konversationen, valknappar med föreslagna åtgärder och uppmaningar att lämna feedback.

När du väljer en meddelandebubbla från användaren läses stegen för den konversationsturen in i panelen Felsökningsinformation. Det valda meddelandet markeras så att du kan följa vilken tur som är aktiv. Panelen kan rullas oberoende av resten av sidan. När du väljer Visa JSON i rubriken för Förhandsgranskning av konversation öppnas en dialogruta med hela konversationstranskriptionen i JSON-format.

Felsökningsinformation

Panelen Felsökningsinformation visar information på stegnivå för den konversationstur som hör till det valda användarmeddelandet. Panelen innehåller en steglista till vänster och en stegdetaljvy som öppnas när du väljer ett steg.

Steglistan visar alla steg som orkestrering körde för den valda konversationsturen. För varje steg visas en ikon och färg som anger stegtypen, stegnamnet (med ett användarvänligt visningsnamn där det är möjligt), körningstiden och en indikator som visar om steget lyckades eller misslyckades. Steg som tillhör en ansluten agent grupperas på ett behållarkort som kan expanderas och komprimeras och som visar agentens namn och den totala körningstiden. Knappen Läs in information om ansluten agent i behållaren läser in den underordnade agentens fullständiga konversationstranskription på begäran.

Följande stegtyper stöds:

Genom att välja ett steg öppnas en detaljpanel med följande avsnitt, som visas när dessa data förekommer i transkriptionen:

• Tankeprocess: orkestreringens resonemangstext inspelad innan steget åberopades. Visar hur modellen valde att kalla detta steg och vad den förväntade sig av det.
• Stegtyp: Klassificerad etikett för stegen.
• Argument: En JSON-trädvy som kan expanderas och komprimeras och som visar de indataparametrar som skickades till steget. Inkluderar ett kopieringsalternativ för att fånga JSON för supportärenden.
• Observation: Utgångs- eller returvärdet från steget. Visas också som ett hopfällbart JSON-träd med kopieringsstöd.
• Kodförhandsversion: För Python-kodsteg visas källkoden med syntaxmarkering.
• Tokenanvändning: Antalet prompttoken och slutförandetoken, det totala antalet token för steget samt namnet på den modell som användes.
• Kunskapskällor: De källor som genomsöktes, de resultat som returnerades (utdata) och de källor som faktiskt citerades i det slutliga svaret. Varje post visar källnamn, typ, URL där det finns tillgängligt och en länk för att öppna källan.
• MCP-serverinformation: För MCP-steg visas serverns protokollversion, deklarerade funktioner och listan över verktyg som servern tillhandahöll under initieringen.
• Felinformation: När ett steg misslyckades visas felkoden, felmeddelandet och (för Responsible AI-block) innehållssäkerhetskategorin som utlöste filtret.
• Adaptiva kort: Om steget genererade ett svar med ett anpassningsbart kort återges kortet direkt i informationspanelen, precis som det visades för användaren.

Transkription JSON

När du väljer Visa JSON i rubriken för Förhandsversion av konversation öppnas en dialogruta som visar alla obearbetade aktiviteter i transkriptionen, med syntaxmarkering, fulltextsökning i JSON-trädet samt alternativet Kopiera till Urklipp för hela nyttolasten.

Använd den här vyn när du:

• Du behöver granska en händelsetyp som inte visas i panelen Felsökningsinformation.
• Du vill kopiera specifika fält för ett supportärende.
• Du undersöker oväntat beteende i de tolkade vyerna.

Felsökning

Följande avsnitt beskriver vanliga problem och hur man löser dem.

Agent visas inte i rullgardinsmenyn Miljö eller Agent

Agenten är inte synkroniserad med Agentinventering eller saknar konversationstranskriptioner.

Lös problemet så här:

1. Kör en manuell synkronisering av Agentinventering för miljön.
2. Verifiera att agentposten finns i tabellen Agentdetaljer i Dataverse.
3. Kontrollera att kolumnen Är transkript tillgänglig är inställd på Ja i registret. Synkroniseringen sätter detta fält när minst ett transkript finns.

För mer information, se Övervaka agenter genom att använda Agent Inventory i Copilot Agent Kit.

Konversations-ID finns inte i rullgardinsmenyn

För prestanda förladdar rullgardinsmenyn endast de 50 senaste konversationerna inom det aktiva tidsintervallet. Äldre transkriptioner finns fortfarande i Dataverse men visas inte som standard. Om konversationen precis har avslutats kan det också vara så att transkriptionen ännu inte har sparats.

Lös problemet så här:

1. Skriv konversations-ID:t direkt i fältet Konversations-ID. Att skriva utlöser en fullständig sökning i alla transkriptioner efter den agenten, utan att ta hänsyn till tidsintervallet.
2. Om tidsintervallet är smalt (till exempel Sista 30 minuterna), utöka det eller byt till ett anpassat intervall som täcker samtalsdatumet.
3. Om samtalet just avslutats, vänta 35–40 minuter tills transkriptet skrivs till Dataverse, och uppdatera sedan.

Vyn Analysera läses in, men inga steg visas i panelen Felsökningsinformation

Transkriptionen finns men innehåller endast meddelandeliknande aktiviteter utan diagnostiska spårhändelser. Detta problem uppstår vanligtvis när konversationen kommer från en kanal som inte sänder spårdata, såsom vissa anpassade kanaler eller äldre schemaversioner.

Lös problemet så här:

1. Välj Visa JSON i rubriken för Förhandsversion av konversation för att kontrollera att det finns aktiviteter.
2. Leta efter poster som type: "trace" eller type: "event". Om de saknas kanske kanalen inte sänder spårdata.

Åtkomst nekad eller tom sida vid laddning

Roller eller behörigheter saknas i en eller båda miljöerna.

Lös problemet så här:

1. I paketmiljön, se till att användaren har tollen CSK – administratör eller Systemadministratör.
2. Kontrollera i målmiljön att den inloggade användaren har läsbehörighet till tabellerna conversationtranscripts, bot och botcomponents.

Transkriptionerna är ofullständiga (tidiga meddelanden saknas)

Långa konversationer delas upp över flera Dataverse-poster (1 MB per post). Om kvarhållningsprincipen rensar vissa register har det sammanslagna transkriptet luckor.

Lös problemet så här:

1. Dataverse rensar konversationstranskriptioner som är äldre än 30 dagar som standard. Om problemet beror på kvarhållningsperioden uppdaterar du schemat för massborttagningsjobbet i Power Apps>Inställningar>Avancerade inställningar>Datahantering>Masspostradering.
2. Om kvarhållningsperioden inte är orsaken kontrollerar du att alla transkriptionsposter för konversationen finns i tabellen conversationtranscripts i Dataverse.

Stegen visar råa schemanamn istället för läsbara ämnesnamn

Tabelluppslagningen botcomponents misslyckades, eller så raderades komponentposten.

Lös problemet så här:

1. Kontrollera att den inloggade användaren har läsbehörighet till tabellen botcomponents i målmiljön.
2. Om komponenten raderades från Copilot Studio finns ingen matchande post och Agent Debugger återgår till det råa schemanamnet, såsom cr123_mytopic. Detta beteende förväntas för borttagna ämnen eller åtgärder.

Agentens informationspanel visar inga data

Det gick inte att hämta agentkonfigurationen, eller så saknar den inloggade användarens anslutning läsbehörighet till tabellerna bot och botcomponents i målmiljön.

Lös problemet så här:

1. Verifiera läsåtkomst till tabellerna bot och botcomponents för anslutningsreferensen som appen använder.
2. Om agenten raderades eller inte publicerades efter att konversationen spelats in, kan dess konfigurationsposter inte längre existera. I det här fallet förblir panelen Agentinformation tom, men panelerna Transkription och Felsökningsinformation fungerar fortfarande fullt ut.

Rekommendationspanelen visar inga problem men samtalet misslyckades

Rekommendationerna baseras på mönster i transkriptionens spårningshändelser. Om transkriptionen saknar spårningsdata eller om felet inträffar utanför konversationen (till exempel en nätverkstimeout utan synligt fel som inte registreras i transkriptionen) genererar systemet inga rekommendationer.

Lös problemet så här:

1. Öppna transkriptionens JSON-data och leta efter felnyttolaster i råformat som inte visas som rekommendationer.
2. Kontrollera om några steg visas i rött i körningsvägen. Dessa steg indikerar fel som inte motsvarar ett känt rekommendationsmönster.

Relaterad information

• Övervaka agenter genom att använda Agent Inventory i Copilot Agent Kit
• Konfigurera agenter i Copilot-agentpaket
• Copilot Agent Kit – översikt