Felsöka agenter med Agent Inspector i Microsoft Foundry Toolkit

Med Agent Inspector i Microsoft Foundry Toolkit för Visual Studio Code kan du skicka begäranden till en lokal agent, inspektera modell- och verktygsaktivitet och felsöka koden. Använd den för att undersöka oväntade svar innan du distribuerar en ändring.

Det här arbetsflödet är användbart för värdagenter, som kör din anpassade kod i Foundry Agent Service. Med lokal inspektion kan du felsöka koden. Testa även den distribuerade agenten före produktionsanvändning med dess körningsidentitet, konfiguration och nätverksåtkomst.

I den här artikeln ansluter du till en lokal agent, undersöker en begäran och sparar diagnostikhändelser. Huvudsökvägen använder Responses-protokollet. Tillgängliga vyer beror på vilket protokoll och diagnostik som agentservern tillhandahåller.

Prerequisites

  • Visual Studio Code med det aktuella offentliga Foundry Toolkit-tillägget. Se Installera Foundry Toolkit.
  • Ett lokalt agentprojekt med dess beroenden, modellkonfiguration och autentiseringsuppgifter konfigurerade. Börja med ett exempel genom att följa snabbstarten hosted-agent genom lokal testning.
  • Felsökaren som projektet kräver. I det Python exemplet används tillägget Python och debugpy. Andra språk och exempel har olika krav.

För ett befintligt projekt kan Foundry Toolkit Copilot verktyg hjälpa till att förbereda konfigurationen. Granska de genererade filerna och följ projektets README.md. Ersätt inte dess startfiler med en allmän konfiguration.

Important

En lokal agent kan anropa molnmodeller och liveverktyg. Använd icke-känsliga testindata, kontrollera verktygsbehörigheter och ta hänsyn till avgifter från konfigurerade tjänster. Inspector ersätter inte verktyg med mocks.

Anslut och felsök

Starta agentservern innan du ansluter till Inspector. Använd projektets genererade startkonfiguration för att justera servern, arbetskatalogen, tolken och felsökningsprogrammet.

  1. Starta agenten med dess dokumenterade felsökningskonfiguration. För exemplet hosted-agent Python väljer du Felsöka HTTP-server för lokal agent och trycker på F5.
  2. Om Inspector inte är öppen väljer du Foundry Toolkit i aktivitetsfältet och sedan Utvecklarverktyg>Skapa>Agent Inspector.
  3. Kontrollera endpointen i Inspector-rubriken. Den aktuella Python-mallen använder http://localhost:8088. För en annan serverport väljer du pennknappen bredvid ändpunkten, anger porten och väljer Anslut.
  4. Bekräfta att rubriken visar Ansluten. Inspector identifierar automatiskt protokollet Svar eller anrop när slutpunkten kan nås.
  5. Ange en brytpunkt i agentkoden och skicka ett meddelande i Playground. Granska variabler när körningen pausar och fortsätt sedan och granska svaret.

Skärmbild av konfigurationen för felsökning av lokal agent och Agent Inspector ansluten till localhost på port 8088 med ett lyckat svar.

Att öppna Inspector ensam startar inte en server eller bifogar ett felsökningsprogram. Den genererade Python-konfigurationen använder port 5679 för felsökningsprogrammet och port 8088 för agent-HTTP-begäranden. Dessa portar är separata från OTLP-spårningsportarna.

Anslut till en generisk Responses-slutpunkt

Inspector kan ansluta till en lokal allmän Responses-slutpunkt utan det fullständiga gränssnittet för utvecklingsdiagnostik. Du kan granska de Responses-händelser som servern skickar, men arbetsflödesdiagrammet och dess indata- och utdatavy är inte tillgängliga.

En lyckad anslutning innebär inte att servern tillhandahåller källpositioner, tokenanvändning eller resonemang.

Skicka ett HTTP-anrop

Använd HTTP-anrop när din agent accepterar en anpassad begärandetext i stället för ett konversationsmeddelande. Serverns format för begäran och svarsprotokoll avgör hur Inspector skickar och visar resultatet.

  1. Anslut till servern för pågående HTTP-anrop. Inspector identifierar protokollet automatiskt.
  2. Ange brödtexten i begäran som krävs av din agent. Om servern exponerar en kompatibel OpenAPI-specifikation kan Inspector fylla i ett exempel. Granska det innan du skickar det, eller följ formatet i exemplet för begäran om det inte finns något exempel.
  3. Välj kugghjulet Förfrågningsinställningar bredvid indata för att ange Content-Type och Accept enligt serverns behov. Använd till exempel application/json för ett JSON-innehåll och text/event-stream när servern stöder ett strömningssvar.
  4. Välj Skicka och kontrollera svarsstatusen och brödtexten.
  5. Växla mellan Förhandsgranskning för formaterade utdata och Raw för det underliggande svaret. Informationsfönstret innehåller även I/O och LLM-anrop. Information om modell, verktyg och token är beroende av identifierade serverhändelser, så inte varje svar fyller varje flik.

Inspector hanterar ett normalt HTTP-svar, en ström av server-skickade händelser eller ett asynkront svar. För ett asynkront 202 Accepted svar övervakar det anropet tills det har slutförts eller misslyckats. Att välja ett svarsformat ger inte servern stöd för direktuppspelning eller asynkronitet.

För ett strömmande svar kopplar Stop från klientströmmen. För ett pollat anrop skickar Avbryt en begäran om annullering till servern. Ingen av åtgärderna garanterar att agentprocessen eller en åtgärd i ett externt verktyg har stoppats.

Den här vyn är inte en WebSocket-klient. Exempel på aktivitetsprotokoll använder en annan sandbox. Se Välj ett annat protokoll eller test för lämplig lokal testsökväg.

Använd Inspektorn

Börja med en begäran som utför det beteende som du vill förstå. För ett väderverktyg kan du till exempel be om information som kräver det verktyget, i stället för ett allmänt svar som modellen kan producera utan det.

  1. Skicka begäran i Playground och granska strömningssvaret.
  2. Använd informationsflikarna för att hitta den långsamma eller misslyckade åtgärden.
  3. Granska relevant händelse- eller verktygsanrop, ändra din kod eller konfiguration och upprepa begäran.

Tryck på Retur för att skicka eller Skift+Retur för att lägga till en ny rad. Om du vill återkalla en tidigare begäran placerar du caret i början av indata och trycker på Uppåtpil. Tryck på nedåtpilen i slutet för att gå mot nyare begäranden och återgå till ditt oskickade utkast.

Du kan redigera en återkallad begäran innan du skickar den. Indatahistorik är en bekvämlighet i Inspector, inte ett varaktigt lager med sparade promptar.

View Använd den för att
Overview Följ vattenfallet för svarstid och ordnad körningstidslinje. Välj alla körningar eller en körning för att särskilja modell- och verktygsaktivitet från tiden mellan körningar.
Token Granska rapporterad användning av in- och utdatatoken. Avsaknad av användningsdata är inte ett resultat med noll token.
Events Inspektera tolkade svarshändelser, inklusive fel, funktionsanrop och resultat. Sök efter händelsetyp eller JSON-innehåll och filtrera efter kategori.
Arbetsredskap Granska verktygsanrop grupperade efter svarskörning, inklusive status, anrops-ID, argument och resultat.

Svarssidfoten visar information om modell, varaktighet, tokenanvändning och tidsstämpel när den tillhandahålls. Resonemangstext och sammanfattningar av resonemang visas i separata komprimerbara avsnitt när agenten genererar dem. Inspektören genererar inte saknade resonemang eller exponerar information som modellprovidern inte returnerar.

Granska verktyg och behörigheter

Använd Tools för att kontrollera om agenten anropade det förväntade verktyget med de förväntade argumenten och tog emot ett resultat. Ett lyckat modellsvar bevisar inte att ett verktyg kördes. Om koden använder en mock är det visade resultatet fortfarande ett mockresultat.

Skärmbild av fliken Verktyg med anrop grupperade efter körning och ett expanderat verktygsanrop som visar dess argument och resultat.

När ett svar pausar för MCP-godkännande (Model Context Protocol) eller OAuth-medgivande visas väntande begäranden ovanför meddelandeinmatningen. Bevilja endast den åtkomst som du tänker tillåta.

För ett MCP-verktygsanrop väljer du Visa argument, granskar indata och väljer sedan Godkänn eller Neka. Godkänn alla och Neka alla gäller för väntande begäranden, inte en permanent princip för godkännande av verktyg.

För OAuth-medgivande slutför du både webbläsarauktorisering och Kontrollbekräftelse:

  1. Välj Open consent för den utestående begäran.
  2. Slutför auktoriseringen i webbläsaren, gå tillbaka till Inspector och välj Consent done. Om du vill neka auktorisering väljer du Avbryt i stället.
  3. Lös återstående begäranden om samtycke. Använd All done, när det är tillgängligt, endast efter att du har slutfört auktorisering för alla öppnade begäranden.

Om du bara öppnar en medgivandesida återupptas inte begäran. Inspektören väntar på ett beslut om varje väntande medgivande innan inspektören kontrollerar servern igen. Begäranden kan visas igen om servern fortfarande behöver auktorisering.

Kontrollera det efterföljande verktygsresultatet, inte bara godkännandet, för att bekräfta slutförandet. Information om konfiguration av anslutning och autentisering finns i Verktygskatalog. Ändra inte autentiseringsuppgifter eller behörigheter enbart för att få ett diagnostikfel att försvinna.

Granska arbetsflöden och källkod

För Microsoft Agent Framework-arbetsflöden som stöds kan utvecklingsservern tillhandahålla arbetsflödesdiagnostik och källpositioner. Inspector använder den här informationen för att visa körningsdiagrammet och hjälpa dig att navigera till din kod.

  1. Välj en arbetsflödesnod för att granska tillgängliga indata och utdata.
  2. Dubbelklicka på noden för att öppna dess källäge.
  3. Ställ in en brytpunkt och upprepa begäran för att inspektera operationen i felsökningsprogrammet.

Du kan testa LangGraph-arbetsflöden i Playground, men arbetsflödesvisualisering stöds inte för dem. En server utan arbetsflödesmetadata kan fortfarande returnera användbara svarshändelser.

Undersök fel med Copilot

Använd felåtgärderna i Händelser för att förbereda en fokuserad begäran för GitHub Copilot i stället för att kopiera hela konversationen.

  1. Hitta den misslyckade händelsen och granska dess information för känsligt innehåll innan du delar den.
  2. Välj Åtgärda bredvid den misslyckade händelsen för att förbereda en prompt för det felet. För flera fel begränsar du listan med sök- och kategorifilter och väljer sedan Lös med Copilot. Den här åtgärden omfattar de synliga felen.
  3. Granska den förberedda prompten i GitHub-Copilot Chat innan du skickar den. Granska eventuella föreslagna ändringar och kör sedan den ursprungliga agentbegäran igen för att bekräfta resultatet.

Dessa åtgärder kräver inte OTLP Collector. Att förbereda en diagnostikprompt åtgärdar inte agenten eller kör den misslyckade åtgärden igen.

Skärmbild av fliken Händelser med misslyckade svar, sök- och filterkontroller, exportåtgärder och diagnostikinformation som förberetts i Copilot Chat.

Spara diagnostikhändelser

Spara en ögonblicksbild av en händelse för att jämföra ett fel med en senare körning eller dela en avgränsad reproduktion.

  1. I Händelser kan du begränsa listan med sökfältet och kategorifiltret.
  2. Välj Kopiera synliga händelser för att kopiera de filtrerade händelserna som JSONL. Du kan också välja Ladda ned synliga händelser för att öppna exporten i VS Code.
  3. För den öppnade exporten använder du File> för att spara en kopia på en plats som du styr innan du stänger dokumentet. Den öppnade exporten är en tillfällig fil, inte en permanent nedladdning.

Ögonblicksbilden innehåller de händelser som visas när du väljer åtgärden, inte framtida händelser från agenten som körs. Den sparar inte en agentversion, distribuerar kod eller skapar molnspårningshistorik.

Caution

Händelser kan vara frågor, svar, verktygsargument, resultat och felinformation. Granska och maskera känsligt innehåll innan du sparar eller delar en export.

Starta en ny konversation

Välj Rensa chatt för att starta en ny konversation och rensa tillståndet för chatt, händelser och detaljer. Exportera eventuella diagnostikhändelser som du behöver först. När samma anslutna agent uppdateras bevaras inspektionstillståndet, medan när man byter agent rensas inaktuellt tillstånd.

För Responses inaktiveras Clear Chat medan ett svar aktivt strömmar. Den är fortfarande tillgänglig när turen pausar för godkännande eller medgivande. Det är inte ett generellt kommando för att stoppa din agent.

Förlita dig inte på lokal Inspector-status som ett beständigt konversationsarkiv. Servern äger konversationspersistence, vilket kan skilja sig mellan lokal utveckling och en distribuerad värdbaserad agent. Clearing Inspector tar inte bort spårningar som redan samlats in lokalt eller lagras i Application Insights.

Så skiljer sig Inspector och spårningen åt

Inspector kommunicerar med din lokala server via HTTP och strömmar svarshändelser. En kompatibel utvecklingsserver tillhandahåller också en separat diagnostikström för arbetsflödesinformation och källnavigering. Felsökaren ansluter till den process som körs självständigt.

Den här livediagnostiken kräver inte den lokala OTLP-insamlaren. Fliken Spårningar i inspektören öppnar det separata spårningsvisningsprogrammet. Det omvandlar inte protokollhändelser till lagrade OpenTelemetry-span.

Konfigurera lokal spårning för att samla in spann för senare analys. För driftsatta agenter använder du spårningar för värdbaserad agent.

Efter lokal testning distribuera värdagenten. Testa den separat eftersom dess identitet, miljö och nätverksåtkomst skiljer sig från din lokala process.

Troubleshooting

Issue Vad du bör kontrollera
Inspector kunde inte ansluta. Kontrollera om det finns uppstartsfel i agentterminalen. Kontrollera interpretern, beroendena och HTTP-porten och återanslut sedan till porten som servern anger. När du öppnar Inspector startar inte processen.
En begäran lyckas men brytpunkterna aktiveras inte. Bekräfta att felsökningsprogrammet är kopplat till processen som hanterar begäran och använder rätt källkatalog. Mer information om Python finns i felsökning och problemlösning.
Diagrammet eller källnavigering saknas. Bekräfta att servern och arbetsflödet tillhandahåller utvecklingsdiagnostik och plats i källkoden. Inspektionen av Generic Responses ger inte dessa funktioner. LangGraph-arbetsflöden fungerar i playground utan arbetsflödesvisualisering.
Verktygsresultat saknas. Kontrollera Events för fel och väntande godkännanden. Bekräfta att begäran kräver ett verktyg och att verktyget är konfigurerat och kan nås.
Detaljer om token eller resonemang saknas. Kontrollera vad modellen och servern genererar. Inspektören kan bara visa den information som tillhandahålls.
Fjärrbilder blockeras. Välj Läs in fjärrbilder endast om du vill att Inspector ska hämta dem från fjärrvärdar. Den här visningsbehörigheten är inte ett verktygsgodkännande. URL:er eller innehåll som inte stöds kan fortfarande misslyckas att läsas in. En bild som saknas betyder inte nödvändigtvis att begäran från agenten misslyckades.
Svarsströmmen avbryts. Granska den partiella svars- och informationen om felet. Återanslut om det behövs och granska väntande godkännanden innan du försöker igen. Ett nytt försök kan upprepa pågående verktygsåtgärder.
Inspector har händelser men spårningsvisaren är tom. Protokollhändelser och OTLP-span skiljer sig. Konfigurera instrumentering och starta insamlare.

Relaterat innehåll

  • Uppdaterades senast