Ladění agentů pomocí nástroje Agent Inspector v Microsoft Foundry Toolkit

Agent Inspector v Microsoft Foundry Toolkit pro Visual Studio Code umožňuje odesílat požadavky místnímu agentovi, zkoumat aktivitu modelu a nástrojů a ladit kód. Použijte ho k prošetření neočekávaných odpovědí před nasazením změny.

Tento pracovní postup je užitečný pro hostované agenty, kteří spouští vlastní kód ve službě Foundry Agent Service. Místní kontrola vám pomůže tento kód ladit. Před produkčním použitím také otestujte nasazeného agenta s jeho identitou runtime, konfigurací a síťovým přístupem.

V tomto článku se připojíte k místnímu agentovi, prošetříte požadavek a uložíte diagnostické události. Hlavní cesta používá protokol Responses. Dostupná zobrazení závisí na protokolu a diagnostice, které poskytuje váš agentní server.

Prerequisites

  • Visual Studio Code s aktuálním veřejným rozšířením Foundry Toolkit. Vizte Install Foundry Toolkit.
  • Místní projekt agenta nastavený se svými závislostmi, konfigurací modelu a přihlašovacími údaji. Pokud chcete začít z ukázky, postupujte podle rychlého startu hostovaného agenta až k místnímu testování.
  • Ladicí program vyžadovaný vaším projektem. Ukázka v Pythonu používá rozšíření Python a debugpy. Jiné jazyky a ukázky mají různé požadavky.

U existujícího projektu můžou nástroje Foundry Toolkit Copilot pomoct s přípravou konfigurace. Zkontrolujte vygenerované soubory a postupujte podle projektu README.md. Nenahrazujte jeho spouštěcí soubory obecnou konfigurací.

Important

Místní agent může využívat cloudové modely a nástroje v reálném čase. Používejte necitlivé testovací vstupy, zkontrolujte oprávnění nástroje a počítejte s poplatky za nakonfigurované služby. Inspektor nenahrazuje nástroje mocky.

Připojit a ladit

Před připojením Inspector spusťte server agenta. Pomocí vygenerované konfigurace spuštění projektu slaďte server, pracovní adresář, interpret a ladicí program.

  1. Spusťte agenta s dokumentovanou konfigurací ladění. V ukázce hostovaného agenta Python vyberte Debug Local Agent HTTP Server a stiskněte klávesu F5.
  2. Pokud inspektor není otevřený, na panelu aktivit vyberte Foundry Toolkit a poté Developer Tools>Build>Agent Inspector.
  3. Zkontrolujte endpoint v hlavičce Inspectoru. Aktuální šablona Pythonu používá http://localhost:8088. U jiného portu serveru vyberte tlačítko tužky vedle koncového bodu, zadejte port a vyberte Připojit.
  4. Potvrďte, že záhlaví zobrazuje Připojeno. Inspector automaticky zjistí protokol Responses nebo Invocations, když je koncový bod dostupný.
  5. Nastavte zarážku v kódu agenta a odešlete zprávu v Playgroundu. Zkontrolujte proměnné, když se provádění pozastaví, a pak pokračujte a zkontrolujte odpověď.

Snímek obrazovky s konfigurací ladění místního agenta a nástrojem Agent Inspector připojeným k localhostu na portu 8088 s úspěšnou odpovědí

Samotné otevření inspektoru nespustí server ani nepřipojí ladicí program. Vygenerovaná konfigurace Python používá port 5679 pro ladicí program a port 8088 pro požadavky HTTP agenta. Tyto porty jsou oddělené od trasovacích portů OTLP.

Připojení k obecnému koncovému bodu Responses

Inspektor se může připojit k místnímu obecnému koncovému bodu Responses bez úplného vývojového diagnostického rozhraní. Můžete zkontrolovat události Responses, které server odesílá, ale graf pracovního postupu a jeho vstupní a výstupní zobrazení nejsou k dispozici.

Úspěšné připojení neznamená, že server poskytuje zdrojová umístění, využití tokenu ani odůvodnění.

Odeslání volání HTTP

HTTP volání použijte, když váš agent přijme vlastní tělo požadavku místo konverzační zprávy. Formát požadavku serveru a protokol odpovědi určují, jak Inspector odesílá a zobrazuje výsledek.

  1. Připojte se ke spuštěnému serveru HTTP invokací. Inspektor zjistí protokol automaticky.
  2. Zadejte tělo požadavku vyžadované vaším agentem. Pokud server zveřejňuje kompatibilní specifikaci OpenAPI, může inspektor vyplnit příklad. Před odesláním ho zkontrolujte nebo postupujte podle formátu požadavku z ukázky, pokud není k dispozici žádný příklad.
  3. Vyberte ozubené kolečko Nastavení požadavku vedle vstupu a nastavte Content-Type a Accept podle požadavků serveru. Můžete například použít application/json pro tělo požadavku JSON a text/event-stream použijte, když server podporuje streamovanou odpověď.
  4. Vyberte Odeslat a zkontrolujte stav a text odpovědi.
  5. Přepínejte mezi Náhledem pro formátovaný výstup a Raw pro původní odpověď. Podokno podrobností obsahuje také V/V a volání LLM. Podrobnosti o modelu, nástroji a tokenu závisí na rozpoznaných událostech serveru, takže ne každá odpověď vyplní každou záložku.

Inspektor zpracovává normální odpověď HTTP, stream událostí odesílaných serverem nebo asynchronní odpověď. Pro asynchronní 202 Accepted odpověď se dotazuje na stav volání, dokud neskončí úspěchem nebo selháním. Výběr formátu odpovědi nepřidá na váš server streamování ani asynchronní podporu.

V případě streamované odpovědi Stop odpojí klientský stream. U dotazovaného vyvolání Cancel odešle na server požadavek na zrušení. Ani jedna z akcí nezaručuje, že se proces agenta nebo externí operace nástroje zastavil.

Toto zobrazení není klientem WebSocket. Ukázky protokolu aktivit používají jiný playground. Viz Zvolte jiný protokol nebo ukázku, kde najdete vhodný postup místního testování.

Použijte nástroj Inspektor

Začněte požadavkem, který ověří chování, kterému chcete porozumět. Například v případě nástroje pro počasí požádejte o informace, jejichž získání vyžaduje tento nástroj, místo obecné odpovědi, kterou může model vytvořit bez něj.

  1. Odešlete žádost v Playgroundu a zkontrolujte streamovanou odpověď.
  2. Pomocí karet podrobností vyhledejte pomalou nebo neúspěšnou operaci.
  3. Zkontrolujte relevantní volání události nebo nástroje, změňte kód nebo konfiguraci a opakujte požadavek.

Stisknutím klávesy Enter odešlete nebo stisknutím kláves Shift+Enter přidáte nový řádek. Chcete-li vyvolat předchozí požadavek, umístěte kurzor na začátek vstupu a stiskněte šipku nahoru. Stisknutím klávesy Šipka dolů na konci se přesuňte k novějším požadavkům a vraťte se k vašemu neodeslanému konceptu.

Před odesláním můžete odvolanou žádost upravit. Historie vstupu slouží v Inspectoru jen pro pohodlí, nikoli jako trvalé úložiště uložených promptů.

Zobrazení Použijte ho k
Overview Sledujte vodopád latence a seřazenou časovou osu spuštění. Vyberte všechna spuštění nebo jedno spuštění, abyste odlišili aktivitu modelu a nástroje od času mezi spuštěními.
Odznaky Zkontrolujte hlášené využití vstupních a výstupních tokenů. Chybějící data o využití nejsou výsledkem s nulovým počtem tokenů.
Události Zkontrolujte analyzované události Responses, včetně chyb, volání funkcí a výsledků. Hledání podle typu události nebo obsahu JSON a filtrování podle kategorie
Nářadí Prohlédněte si volání nástrojů seskupená podle spuštění odpovědi, včetně stavu, ID volání, argumentů a výsledků.

Zápatí odpovědi zobrazuje model, dobu trvání, využití tokenu a informace o časovém razítku, pokud jsou k dispozici. Text a souhrny zdůvodnění se zobrazí v samostatných sbalitelných oddílech, když je agent vygeneruje. Inspektor nevygeneruje chybějící odůvodnění ani nezpřístupňuje informace, které poskytovatel modelu nevrací.

Zkontrolujte nástroje a oprávnění

Pomocí nástrojů zkontrolujte, jestli agent volal očekávaný nástroj s očekávanými argumenty a obdržel výsledek. Úspěšná odpověď modelu neprokazuje, že nástroj běžel. Pokud váš kód používá mock, zobrazený výsledek je stále výsledkem mocku.

Snímek obrazovky s kartou Nástroje a voláními seskupenými spuštěním a rozbaleným voláním nástroje zobrazující jeho argumenty a výsledek

Když se odpověď pozastaví pro schválení protokolu MCP (Model Context Protocol) nebo souhlas OAuth, čekající žádosti se zobrazí nad vstupem zprávy. Udělte jenom přístup, který chcete povolit.

U volání nástroje MCP vyberte Zobrazit argumenty, zkontrolujte vstupy a pak vyberte Schválit nebo Odepřít. Schválit všechny a zamítnout všechny se vztahují na čekající žádosti, ne na trvalé zásady schválení nástroje.

V případě souhlasu OAuth dokončete autorizaci prohlížeče i potvrzení inspektoru:

  1. Pro čekající žádost vyberte Open consent.
  2. Dokončete autorizaci v prohlížeči, vraťte se do inspektoru a vyberte Consent done. Pokud chcete odmítnout autorizaci, vyberte místo toho Zrušit.
  3. Vyřešte zbývající žádosti o souhlas. Použijte Vše hotovo, pokud je k dispozici, až po dokončení autorizace pro všechny otevřené žádosti.

Otevření samotné stránky pro vyjádření souhlasu nepokračuje v požadavku. Inspektor čeká na rozhodnutí u každého čekajícího souhlasu předtím, než znovu zkontroluje server. Požadavky se můžou znovu zobrazit, pokud server stále potřebuje autorizaci.

Zkontrolujte následující výsledek nástroje, nejen schválení, abyste potvrdili dokončení. Informace o nastavení připojení a ověřování najdete v katalogu nástrojů. Neměňte přihlašovací údaje nebo oprávnění nástroje jen proto, aby diagnostická chyba zmizela.

Zkontrolujte pracovní postupy a zdrojový kód

Pro podporované workflowy Microsoft Agent Framework může vývojový server poskytovat diagnostiku workflowů a zdrojová umístění. Inspektor tyto informace používá k zobrazení grafu provádění a pomáhá vám přejít na váš kód.

  1. Vyberte uzel pracovního postupu a zkontrolujte dostupné vstupy a výstupy.
  2. Poklikáním na uzel otevřete jeho zdrojové umístění.
  3. Nastavte zarážku a zopakujte požadavek na kontrolu operace v ladicím programu.

Pracovní postupy LangGraph můžete testovat v Playgroundu, ale vizualizace pracovního postupu pro ně není podporovaná. Server bez metadat workflow může stále vracet užitečné události odpovědi.

Prozkoumat selhání pomocí Copilotu

Akce chyb v událostech slouží k přípravě zaměřeného požadavku na GitHub Copilot místo kopírování celé konverzace.

  1. Vyhledejte událost, která selhala, a před sdílením těchto podrobností zkontrolujte, zda neobsahují citlivý obsah.
  2. Výběrem možnosti Opravit vedle neúspěšné události připravte prompt pro toto selhání. V případě několika selhání seznam zužte pomocí filtrů hledání a kategorií a pak vyberte Vyřešit s Copilot. Tato akce zahrnuje zjevná selhání.
  3. Před odesláním zkontrolujte připravený prompt v GitHub Copilot Chat. Zkontrolujte všechny navrhované změny a pak znovu spusťte původní požadavek agenta, abyste potvrdili výsledek.

Tyto akce nevyžadují kolektor OTLP. Příprava diagnostického promptu neopraví agenta ani znovu nespustí neúspěšnou operaci.

Snímek obrazovky s kartou Události s neúspěšnými odpověďmi, ovládacími prvky vyhledávání a filtrování, akcemi exportu a podrobnostmi diagnostiky připravenými v Copilot Chat

Uložit diagnostické události

Uložte snímek události k porovnání selhání s pozdějším spuštěním nebo ke sdílení cílené reprodukce problému.

  1. V událostech seznam zúžíte pomocí vyhledávacího pole a filtru kategorií.
  2. Vyberte Kopírovat viditelné události a zkopírujte filtrované události jako JSONL. Případně vyberte možnost Stáhnout viditelné události a export se otevře v editoru VS Code.
  3. V případě otevřeného exportu před zavřením dokumentu uložte kopii do umístění, které řídíte, pomocí příkazu Soubor>Uložit jako. Otevřený export je dočasný soubor, nikoli trvale uložený stažený soubor.

Snímek obsahuje události viditelné při výběru akce, nikoli budoucích událostí ze spuštěného agenta. Neukládá verzi agenta, nasazuje kód ani nevytvoří historii trasování cloudu.

Caution

Události můžou zahrnovat výzvy, odpovědi, argumenty nástroje, výsledky a podrobnosti o chybě. Před uložením nebo sdílením exportu zkontrolujte a odstraňte citlivý obsah.

Začít novou konverzaci

Výběrem možnosti Vymazat chat zahájíte novou konverzaci a vymažete stav chatu, událostí a podrobností. Nejprve vyexportujte všechny diagnostické události, které potřebujete. Obnovení stejného připojeného agenta zachová svůj stav kontroly a při změně agentů se vymaže zastaralý stav.

U odpovědí je Vymazat chat zakázáno, když se odpověď aktivně streamuje. Zůstane k dispozici, když se tah pozastaví kvůli schválení nebo souhlasu. Nejedná se o obecný příkaz k tomu, aby se váš agent zastavil.

Nespoléhejte na stav místního inspektoru jako trvalý archiv konverzací. Server zajišťuje perzistenci konverzací, která se může lišit mezi místním vývojem a nasazeným hostovaným agentem. Vymazání Inspectoru neodstraní trasování, která jsou už shromážděná místně nebo uložená ve službě Application Insights.

Jak se Inspector a trasování liší

Inspektor komunikuje s vaším místním serverem přes HTTP a streamuje události odezvy. Kompatibilní vývojový server také poskytuje samostatný diagnostický stream pro podrobnosti pracovního postupu a navigaci ve zdroji. Ladicí program se připojí k běžícímu procesu samostatně.

Tyto živé diagnostické údaje nevyžadují místní kolektor OTLP. Karta Trasování v Inspektoru otevře samostatný prohlížeč trasování. Nepřevádí události protokolu na uložené spany OpenTelemetry.

Pokud chcete shromažďovat spany pro pozdější analýzu, nakonfigurujte lokální trasování. Pro nasazené agenty použijte trasování hostovaného agenta.

Po místním testování nasaďte hostovaného agenta. Testujte ho samostatně, protože jeho identita, prostředí a přístup k síti se liší od vašeho místního procesu.

Troubleshooting

Problém Co zkontrolovat
Inspektor se nemůže připojit. Zkontrolujte v terminálu agenta chyby při spuštění. Potvrďte interpreta, závislosti a port HTTP a pak se znovu připojte k portu, který server oznámí. Otevření Inspectoru nespustí proces.
Požadavek je úspěšný, ale breakpointy nejsou zasaženy. Ověřte, že je ladicí program připojený k procesu obsluhující požadavek, a používá správný zdrojový adresář. Pro Python viz řešení potíží s laděním.
Chybí graf nebo zdrojová navigace. Ověřte, že server a pracovní postup poskytují diagnostiku vývoje a umístění ve zdrojovém kódu. Inspekce Generic Responses neposkytuje tyto možnosti. Pracovní postupy LangGraph fungují v playgroundu bez vizualizace pracovního postupu.
Chybí výsledky nástrojů. Zkontrolujte v Událostech selhání a čekající schválení. Ověřte, že žádost vyžaduje nástroj a že je nástroj nakonfigurovaný a dosažitelný.
Chybí podrobnosti o tokenu nebo o uvažování. Zkontrolujte, co model a server vygenerují. Inspektor může zobrazit jenom informace, které jsou jim poskytnuty.
Vzdálené obrázky jsou blokované. Vyberte Načíst vzdálené obrázky jenom v případě, že chcete, aby je Inspector načetl ze vzdálených hostitelů. Toto oprávnění k zobrazení není schválením nástroje. Nepodporované adresy URL nebo obsah se přesto nemusí načíst. Chybějící obrázek nemusí nutně znamenat, že se žádost agenta nezdařila.
Proud odpovědi je přerušen. Projděte si částečnou odpověď a podrobnosti o selhání. Před opakováním se znovu připojte v případě potřeby a zkontrolujte čekající schválení. Opakování pokusu může zopakovat živé akce nástrojů.
Inspektor má události, ale prohlížeč trasování je prázdný. Události protokolu a OTLP spany se liší. Nakonfigurujte instrumentaci a spusťte kolektor.

Související obsah

  • Poslední aktualizace v