Fouten opsporen in agents met Agent Inspector in Microsoft Foundry Toolkit

Met Agent Inspector in Microsoft Foundry Toolkit voor Visual Studio Code kunt u aanvragen verzenden naar een lokale agent, model- en hulpprogrammaactiviteit controleren en fouten in uw code opsporen. Gebruik deze om onverwachte antwoorden te onderzoeken voordat u een wijziging implementeert.

Deze werkstroom is handig voor gehoste agents, die uw aangepaste code uitvoeren in Foundry Agent Service. Lokale inspectie helpt u die code te debuggen. Voordat u het in productie gebruikt, test u ook de geïmplementeerde agent met de runtime-identiteit, configuratie en netwerktoegang.

In dit artikel maakt u verbinding met een lokale agent, onderzoekt u een verzoek en slaat u diagnostische gebeurtenissen op. Het hoofdpad maakt gebruik van het Responses-protocol. De beschikbare weergaven zijn afhankelijk van het protocol en de diagnostische gegevens die uw agentserver biedt.

Prerequisites

  • Visual Studio Code met de huidige openbare Foundry Toolkit-extensie. Zie Foundry Toolkit installeren.
  • Een lokaal agentproject met de bijbehorende afhankelijkheden, modelconfiguratie en inloggegevens ingesteld. Als u wilt beginnen met een voorbeeld, volgt u de quickstart voor de gehoste agent via lokaal testen.
  • Het foutopsporingsprogramma dat is vereist voor uw project. Het Python voorbeeld maakt gebruik van de Python-extensie en debugpy. Andere talen en voorbeelden hebben verschillende vereisten.

Voor een bestaand project kunnen de Foundry Toolkit Copilot-hulpprogramma's helpen bij het voorbereiden van de configuratie. Controleer de gegenereerde bestanden en volg de van het project README.md. Vervang de startbestanden niet door een algemene configuratie.

Important

Een lokale agent kan cloudmodellen en livehulpprogramma's aanroepen. Gebruik niet-gevoelige testinvoer, controleer de machtigingen van hulpprogramma's en houd rekening met kosten van geconfigureerde services. Inspector vervangt geen hulpprogramma's door mocks.

Verbinding maken en debuggen

Start de agentserver voordat u verbinding maakt met Inspector. Gebruik de gegenereerde startconfiguratie van uw project om de server, werkmap, interpreter en foutopsporingsprogramma op elkaar af te stemmen.

  1. Start de agent met de gedocumenteerde foutopsporingsconfiguratie. Selecteer voor het Python-voorbeeld van de gehoste agent de Debug Local Agent HTTP Server en druk op F5.
  2. Als Inspector niet is geopend, selecteert u Foundry Toolkit in de activiteitenbalk en vervolgens Developer Tools>Build>Agent Inspector.
  3. Controleer het eindpunt in de Inspector-header. De huidige Python scaffold maakt gebruik van http://localhost:8088. Selecteer voor een andere serverpoort de potloodknop naast het eindpunt, voer de poort in en selecteer Connect.
  4. Controleer of de koptekst Verbonden weergeeft. Inspector detecteert automatisch het protocol Responses of Invocations wanneer het eindpunt bereikbaar is.
  5. Stel een breakpoint in uw agentcode in en verzend een bericht in de playground. Inspecteer variabelen wanneer de uitvoering wordt onderbroken, ga door en controleer het antwoord.

Schermopname van de configuratie voor foutopsporing van de lokale agent en Agent Inspector die is verbonden met localhost op poort 8088 met een geslaagd antwoord.

Als u Inspector alleen opent, wordt er geen server gestart of wordt er geen debugger gekoppeld. De gegenereerde Python-configuratie maakt gebruik van poort 5679 voor het foutopsporingsprogramma en poort 8088 voor HTTP-aanvragen voor agents. Deze poorten staan los van de OTLP-traceringspoorten.

Verbinding maken met een generiek Responses endpoint

Inspector kan verbinding maken met een lokaal generiek Responses-endpoint zonder de volledige interface voor ontwikkelingsdiagnose. U kunt de Responses-gebeurtenissen die door de server worden verzonden controleren, maar de werkstroomgrafiek en de invoer- en uitvoerweergave zijn niet beschikbaar.

Een geslaagde verbinding betekent niet dat de server bronlocaties, tokengebruik of redenering levert.

Een HTTP-aanroep verzenden

Gebruik HTTP-aanroepen wanneer uw agent een aangepaste requestbody accepteert in plaats van een gespreksbericht. De aanvraagindeling en het antwoordprotocol van de server bepalen hoe Inspector het resultaat verzendt en weergeeft.

  1. Maak verbinding met uw actieve HTTP invocations-server. Inspector detecteert het protocol automatisch.
  2. Voer de aanvraagbody in die is vereist door uw agent. Als de server een compatibele OpenAPI-specificatie beschikbaar maakt, kan Inspector een voorbeeld invullen. Controleer het voordat u deze verzendt of volg de aanvraagindeling van het voorbeeld als er geen voorbeeld beschikbaar is.
  3. Selecteer het tandwiel Aanvraaginstellingen naast de invoer om Inhoudstype en Accepteren in te stellen zoals vereist door de server. Gebruik bijvoorbeeld application/json voor een JSON-hoofdtekst en text/event-stream wanneer de server een streaming-antwoord ondersteunt.
  4. Selecteer Verzenden en inspecteer de antwoordstatus en hoofdtekst.
  5. Schakel tussen preview voor opgemaakte uitvoer en Raw voor het onderliggende antwoord. Het detailvenster bevat ook I/O - en LLM-aanroepen. Model-, hulpprogramma- en tokendetails zijn afhankelijk van herkende server gebeurtenissen, dus niet elk antwoord vult elk tabblad.

Inspector verwerkt een normaal HTTP-antwoord, een stroom van door de server verzonden gebeurtenissen of een asynchrone reactie. Voor een asynchroon 202 Accepted antwoord wordt de aanroep gecontroleerd totdat deze is voltooid of mislukt. Het selecteren van een antwoordindeling voegt geen streaming- of asynchrone ondersteuning toe aan uw server.

Voor een streaming-antwoord verbreekt Stop de verbinding met de clientstream. Voor een gepollte aanroep verzendt Cancel een annuleringsaanvraag naar de server. Geen van beide acties garandeert dat het agentproces of een externe toolbewerking is gestopt.

Deze weergave is geen WebSocket-client. Activity Protocol-voorbeelden gebruiken een andere testomgeving. Zie Kies een ander protocol of sample voor het juiste lokale testpad.

Inspector gebruiken

Begin met een aanvraag die het gedrag test dat u wilt begrijpen. Voor een weerhulpmiddel vraagt u bijvoorbeeld om informatie waarvoor dat hulpprogramma is vereist, in plaats van een algemeen antwoord dat het model zonder het kan produceren.

  1. Verzend de aanvraag in de playground en bekijk het streaming-antwoord.
  2. Gebruik de detailtabbladen om de trage of mislukte bewerking te vinden.
  3. Controleer de relevante gebeurtenis of de aanroep van het hulpprogramma, wijzig uw code of configuratie en herhaal de aanvraag.

Druk op Enter om te verzenden of Shift+Enter om een nieuwe regel toe te voegen. Als u een eerder verzoek wilt oproepen, plaatst u de caret aan het begin van de invoer en drukt u op Pijl-omhoog. Druk op pijl-omlaag aan het einde om naar nieuwere aanvragen te gaan en terug te keren naar uw niet-verzonden concept.

U kunt een teruggeroepen aanvraag bewerken voordat u deze verzendt. Invoergeschiedenis is handig in Inspector, niet een duurzaam archief met opgeslagen prompts.

View Gebruik het om
Overview Volg de latencywaterval en de geordende uitvoeringstijdlijnweergave. Selecteer alle runs of één run om model- en toolactiviteit te onderscheiden van tijd tussen runs.
Tokens Controleer het gerapporteerde gebruik van invoer- en uitvoertoken. Ontbrekende gebruiksgegevens zijn geen nul-tokenresultaat.
Events Geparseerde Responses-gebeurtenissen inspecteren, inclusief fouten, functie-aanroepen en resultaten. Zoek op gebeurtenistype of JSON-inhoud en filter op categorie.
Gereedschappen Inspecteer hulpprogramma-aanroepen gegroepeerd op responsrun, inclusief status, aanroep-id, argumenten en resultaten.

In de antwoordvoettekst worden model-, duur-, tokengebruik- en tijdstempelgegevens weergegeven wanneer deze worden opgegeven. Redeneertekst en redeneringssamenvattingen worden weergegeven in afzonderlijke samenvouwbare secties wanneer de agent deze verzendt. Inspector genereert geen ontbrekende redenering of geeft geen informatie weer die de modelprovider niet retourneert.

Hulpprogramma's en machtigingen controleren

Gebruik Hulpprogramma's om te controleren of de agent het verwachte hulpprogramma met de verwachte argumenten heeft aangeroepen en een resultaat heeft ontvangen. Een geslaagd modelantwoord bewijst niet dat een hulpprogramma is uitgevoerd. Als uw code gebruikmaakt van een mock, is het weergegeven resultaat nog steeds een mockresultaat.

Schermopname van het tabblad Extra met aanroepen gegroepeerd per uitvoering en een uitgevouwen toolaanroep met de argumenten en het resultaat.

Wanneer een antwoord wordt onderbroken voor MCP-goedkeuring (Model Context Protocol) of OAuth-toestemming, worden aanvragen die in behandeling zijn, weergegeven boven de berichtinvoer. Verleen alleen de toegang die u wilt toestaan.

Voor een MCP-hulpprogrammaaanroep selecteert u Argumenten weergeven, controleert u de invoer en selecteert u Goedkeuren of Weigeren. Alles goedkeuren en Alles weigeren zijn van toepassing op de aanvragen die in behandeling zijn, niet op een permanent goedkeuringsbeleid voor hulpprogramma's.

Voor OAuth-toestemming voltooit u zowel de autorisatie van de browser als de bevestiging in Inspector:

  1. Selecteer Open toestemming voor de aanvraag in behandeling.
  2. Voltooi de autorisatie in de browser, ga terug naar Inspector en selecteer Consent done. Als u autorisatie wilt weigeren, selecteert u in plaats daarvan Annuleren.
  3. Los de resterende toestemmingsaanvragen op. Gebruik All done, indien beschikbaar, pas na het voltooien van de autorisatie voor alle geopende aanvragen.

Als u alleen een toestemmingspagina opent, wordt de aanvraag niet hervat. Inspector wacht op een beslissing over elke in behandeling zijnde toestemming voordat Inspector de server opnieuw controleert. Aanvragen kunnen opnieuw verschijnen als de server nog steeds autorisatie vereist.

Controleer het volgende resultaat van de tool, niet alleen de goedkeuring, om de voltooiing te bevestigen. Zie Tool Catalog voor het instellen van verbinding en verificatie. Wijzig de aanmeldingsgegevens of machtigingen van het hulpprogramma niet alleen om een diagnostische fout te laten verdwijnen.

Werkstromen en broncode controleren

Voor ondersteunde Microsoft Agent Framework-werkstromen kan de ontwikkelserver werkstroomdiagnose en bronlocaties bieden. Inspector gebruikt deze informatie om de uitvoeringsgrafiek weer te geven en u te helpen naar uw code te navigeren.

  1. Selecteer een werkstroomknooppunt om de beschikbare invoer en uitvoer te controleren.
  2. Dubbelklik op het knooppunt om de bronlocatie te openen.
  3. Stel een onderbrekingspunt in en herhaal het verzoek om de bewerking in het foutopsporingsprogramma te inspecteren.

U kunt LangGraph-werkstromen testen in de playground, maar werkstroomvisualisatie wordt hiervoor niet ondersteund. Een server zonder workflowmetadata kan nog steeds nuttige antwoordgebeurtenissen retourneren.

Storingen onderzoeken met Copilot

Gebruik de foutacties in Events om een gerichte aanvraag voor GitHub Copilot voor te bereiden in plaats van het hele gesprek te kopiëren.

  1. Zoek de gebeurtenis met fout en controleer de details op gevoelige inhoud voordat u ze deelt.
  2. Selecteer Fix naast de mislukte gebeurtenis om een prompt voor die mislukking op te stellen. Bij meerdere fouten beperkt u de lijst met zoek- en categoriefilters en selecteert u Oplossen met Copilot. Deze actie omvat de zichtbare mislukkingen.
  3. Controleer de voorbereide prompt in GitHub Copilot Chat voordat u deze verzendt. Controleer de voorgestelde wijzigingen en voer de oorspronkelijke agentaanvraag opnieuw uit om het resultaat te bevestigen.

Voor deze acties is geen OTLP-collector vereist. Het voorbereiden van een diagnostische prompt herstelt de agent niet en voert de mislukte bewerking niet opnieuw uit.

Schermopname van het tabblad Gebeurtenissen met mislukte reacties, zoek- en filterbesturingselementen, exportacties en diagnostische gegevens die zijn voorbereid in Copilot Chat.

Diagnostische gebeurtenissen opslaan

Sla een momentopname van een gebeurtenis op om een mislukking te vergelijken met een latere uitvoering of een gerichte reproductie te delen.

  1. In Gebeurtenissen beperkt u de lijst met het zoekveld en het categoriefilter.
  2. Selecteer Zichtbare gebeurtenissen kopiëren om de gefilterde gebeurtenissen als JSONL te kopiëren. U kunt ook zichtbare gebeurtenissen downloaden selecteren om de export te openen in VS Code.
  3. Voor het geopende exportbestand gebruikt u Bestand>Opslaan als om een kopie op te slaan op een locatie die u bepaalt voordat u het document sluit. De geopende export is een tijdelijk bestand, geen permanente download.

De momentopname bevat de gebeurtenissen die zichtbaar zijn wanneer u de actie selecteert, niet toekomstige gebeurtenissen van de actieve agent. Er wordt geen agentversie opgeslagen, code geïmplementeerd of cloudtraceringsgeschiedenis gemaakt.

Caution

Gebeurtenissen kunnen vragen, antwoorden, hulpprogrammaargumenten, resultaten en foutdetails bevatten. Gevoelige inhoud controleren en verwijderen voordat u een export opslaat of deelt.

Een nieuw gesprek starten

Selecteer Chat wissen om een nieuw gesprek te starten en de status van Chat, Gebeurtenissen en Details te wissen. Exporteer eerst diagnostische gebeurtenissen die u nodig hebt. Als u dezelfde verbonden agent vernieuwt, blijft de inspectiestatus behouden, terwijl het wisselen van agent de verouderde status wist.

Voor antwoorden is Clear Chat uitgeschakeld terwijl een antwoord actief wordt gestreamd. Deze blijft beschikbaar wanneer de sessie wordt onderbroken voor goedkeuring of toestemming. Het is geen algemene opdracht om uw agent te stoppen.

Vertrouw niet op de lokale Inspector-status als een duurzaam gespreksarchief. De server beheert de persistentie van gesprekken, die kan verschillen tussen lokale ontwikkeling en een geïmplementeerde gehoste agent. Clearing Inspector verwijdert geen traceringen die al lokaal zijn verzameld of zijn opgeslagen in Application Insights.

Hoe Inspector en tracering verschillen

Inspector communiceert met uw lokale server via HTTP en streamt response-events. Een compatibele ontwikkelingsserver levert ook een afzonderlijke diagnostische stroom voor werkstroomdetails en bronnavigatie. Het foutopsporingsprogramma maakt onafhankelijk verbinding met uw actieve proces.

Deze livediagnoses vereisen geen lokale OTLP-collector. Het tabblad Traceringen van Inspector opent de afzonderlijke traceringsviewer. Er worden geen protocolgebeurtenissen omgezet in opgeslagen OpenTelemetry-spans.

Als u spans wilt verzamelen voor latere analyse, configureert u local tracing. Gebruik gehoste agenttraceringen voor geïmplementeerde agents.

Implementeer de gehoste agent na lokale tests. Test het afzonderlijk omdat de identiteit, omgeving en netwerktoegang verschillen van uw lokale proces.

Troubleshooting

Issue Wat u moet controleren
Inspector kan geen verbinding maken. Controleer de agentterminal op opstartfouten. Controleer de interpreter, afhankelijkheden en HTTP-poort en maak vervolgens opnieuw verbinding met de poort die door de server wordt gemeld. Door Inspector te openen wordt het proces niet gestart.
Een verzoek slaagt, maar breakpoints worden niet bereikt. Controleer of het foutopsporingsprogramma is gekoppeld aan het proces dat het verzoek verwerkt en de juiste bronmap gebruikt. Voor Python, zie debugging en probleemoplossing.
De graaf- of bronnavigatie ontbreekt. Controleer of de server en workflow diagnostische gegevens en bronlocaties voor ontwikkeling bieden. Inspectie van Generic Responses biedt deze mogelijkheden niet. LangGraph workflows werken in de playground zonder workflowvisualisatie.
De resultaten van het hulpprogramma ontbreken. Controleer Events op fouten en goedkeuringen in behandeling. Controleer of voor de aanvraag een tool is vereist en of de tool is geconfigureerd en bereikbaar.
Token- of redeneringsgegevens ontbreken. Controleer wat het model en de server verzenden. Inspector kan alleen de door hen verstrekte informatie weergeven.
Externe afbeeldingen worden geblokkeerd. Selecteer Externe afbeeldingen laden alleen als u wilt dat Inspector ze ophaalt van externe hosts. Deze weergavemachtiging is geen goedkeuring van een tool. Niet-ondersteunde URL's of inhoud kunnen nog steeds niet worden geladen. Een ontbrekende afbeelding betekent niet noodzakelijkerwijs dat de agentaanvraag is mislukt.
De responsstroom wordt onderbroken. Controleer de details van het gedeeltelijke antwoord en de foutdetails. Maak zo nodig opnieuw verbinding en controleer de goedkeuringen die in behandeling zijn voordat u het opnieuw probeert. Een nieuwe poging kan live toolacties herhalen.
Inspector heeft gebeurtenissen, maar de traceringsviewer is leeg. Protocol-gebeurtenissen en OTLP-spans verschillen. Configureer instrumentation en start de collector.

Verwante onderwerpen

  • Laatst bijgewerkt om