Ügynökök hibakeresése Agent Inspectorral a Microsoft Foundry Toolkitben

Az Microsoft Foundry Toolkit for Visual Studio Code ügynökfelügyelője lehetővé teszi, hogy kéréseket küldjön egy helyi ügynöknek, vizsgálja meg a modell- és eszköztevékenységet, és hibakeresést végez a kódban. A módosítás üzembe helyezése előtt vizsgálja meg a váratlan válaszokat.

Ez a munkafolyamat olyan hosztolt ügynökök számára hasznos, amelyek az egyéni kódját a Foundry Agent Service-ben futtatják. A helyi ellenőrzés segít a kód hibakeresésében. Éles használat előtt tesztelje az üzembe helyezett ügynököt futásidejű identitásával, konfigurációjával és hálózati hozzáférésével.

Ebben a cikkben egy helyi ügynökprogramhoz csatlakozik, megvizsgál egy kérést, és menti a diagnosztikai eseményeket. A fő elérési út a Responses protokollt használja. Az elérhető nézetek az ügynökkiszolgáló által biztosított protokolltól és diagnosztikától függenek.

Prerequisites

  • Visual Studio Code a jelenlegi nyilvános Foundry Toolkit bővítménnyel. Lásd: Install Foundry Toolkit.
  • Egy helyi ügynökprojekt, amelynek függőségei, modellkonfigurációja és hitelesítő adatai be vannak állítva. Ha egy mintából szeretne kiindulni, kövesse a hostolt ügynök rövid útmutatóját egészen a helyi tesztelésig.
  • A projekt által igényelt hibakereső. A Python minta a Python bővítményt és debugpymintát használja. Más nyelvek és minták eltérő követelményekkel rendelkeznek.

Egy meglévő projekt esetében az Foundry Toolkit Copilot eszközei segíthetnek a konfiguráció előkészítésében. Tekintse át a létrehozott fájlokat, és kövesse a projekt README.md irányelveit. Ne cserélje le a saját indítási fájljait általános konfigurációval.

Important

Egy helyi agent hívhat felhőmodelleket és valós idejű eszközöket. Használjon nem bizalmas tesztbemeneteket, ellenőrizze az eszköz engedélyeit, és vegye figyelembe a konfigurált szolgáltatások díjait. Az Inspector nem cseréli le az eszközöket mockokra.

Csatlakozás és hibakeresés indítása

Indítsa el az ügynökkiszolgálót, mielőtt csatlakozna az Inspectorhoz. A projekt által létrehozott indítási konfigurációval összehangolhatja a kiszolgálót, a munkakönyvtárat, az értelmezőt és a hibakeresőt.

  1. Indítsa el az ügynököt a dokumentált hibakeresési konfigurációjával. A hosztolt ügynök Python-mintája esetében válassza a Helyi ügynök HTTP-kiszolgáló hibakeresése lehetőséget, és nyomja le az F5 billentyűt.
  2. Ha az Inspector nincs megnyitva, válassza az Foundry Toolkit elemet a tevékenységsávon, majd a Fejlesztői eszközök>Build>.
  3. Ellenőrizze a végpontot az Inspector fejlécében. Az aktuális Python-állványzat a(z) http://localhost:8088 elemet használja. Másik kiszolgálóport esetén válassza a végpont melletti ceruza gombot, írja be a portot, és válassza a Csatlakozás lehetőséget.
  4. Győződjön meg arról, hogy a fejlécen a Csatlakozva felirat látható. Az Inspector automatikusan észleli a Responses vagy Invocations protokollt, ha a végpont elérhető.
  5. Állítson be egy töréspontot az ügynökkódban, és küldjön üzenetet a Playgroundban. Vizsgálja meg a változókat, amikor a végrehajtás szünetel, majd folytassa és tekintse át a választ.

Képernyőkép a helyi ügynök hibakeresési konfigurációjáról és a localhosthoz csatlakoztatott Agent Inspectorról a 8088-os porton, sikeres válasszal.

Az Inspector önmagában nem indít el kiszolgálót, és nem csatlakoztat hibakeresőt. A létrehozott Python konfiguráció az 5679-s portot használja a hibakeresőhöz, a 8088-at pedig ügynöki HTTP-kérésekhez. Ezek a portok elkülönülnek az OTLP nyomkövetési portoktól.

Csatlakozás egy általános Responses végponthoz

Az Inspector a teljes fejlesztési diagnosztikai felület nélkül tud csatlakozni egy helyi általános Responses-végponthoz. Megvizsgálhatja a kiszolgáló által küldött válaszeseményeket, de a munkafolyamat-gráf, valamint annak bemeneti és kimeneti nézete nem érhető el.

A sikeres kapcsolat nem jelenti azt, hogy a kiszolgáló forráshelyeket, tokenhasználatot vagy következtetési adatokat biztosít.

HTTP-hívás küldése

HTTP-hívásokat akkor használjon, ha az ügynök beszélgetési üzenet helyett egyéni kéréstörzset fogad el. A kiszolgáló kérésformátuma és válaszprotokollja határozza meg, hogy az Inspector hogyan küldi el és jeleníti meg az eredményt.

  1. Csatlakozzon a futó HTTP-invokációs kiszolgálóhoz. Az Ellenőrző automatikusan észleli a protokollt.
  2. Adja meg az ügynökprogram által igényelt kérés törzsét. Ha a kiszolgáló egy kompatibilis OpenAPI-specifikációt tesz elérhetővé, az Inspector kitölthet egy példát. Tekintse át a küldés előtt, vagy kövesse a mintában szereplő kérés formátumát, ha nincs elérhető példa.
  3. A bemenet mellett válassza a Kérés beállításai fogaskerék ikont a Content-Type és az Accept beállításához a kiszolgáló által megkövetelt módon. Használjon például application/json JSON-törzshöz, és text/event-stream pedig akkor, ha a kiszolgáló támogatja a streamelt választ.
  4. Válassza a Küldés lehetőséget, és vizsgálja meg a válasz állapotát és választörzsét.
  5. Váltson a formázott kimenet Előnézete és az alapul szolgáló válasz Nyers nézete között. A részletek panelen I/O - és LLM-hívások is találhatók. A modell, az eszköz és a token részletei a felismert kiszolgálói eseményektől függnek, így nem minden válasz tölti ki az összes lapfület.

Az Inspector normál HTTP-választ, kiszolgáló által küldött események streamét vagy aszinkron választ kezel. Aszinkron 202 Accepted válasz esetén a rendszer a befejezésig vagy hibáig lekérdezi a meghívást. A válaszformátum kiválasztása nem ad streamelést vagy aszinkron támogatást a kiszolgálón.

Streamelési válasz esetén a Stop leválasztja az ügyfélstreamet. Lekérdezéses hívás esetén a Mégse megszakítási kérelmet küld a kiszolgálóra. Egyik művelet sem garantálja, hogy az ügynökfolyamat vagy egy külső eszközművelet leállt-e.

Ez a nézet nem egy WebSocket-ügyfél. Az Activity Protocol-minták egy másik tesztkörnyezetet használnak. A megfelelő helyi tesztelési útvonalért lásd: Másik protokoll vagy minta kiválasztása.

Az Inspector használata

Kezdje egy kéréssel, amely a megérteni kívánt működést teszteli. Egy időjárási eszköz esetében például olyan információkat kell kérnie, amelyek az eszközt igénylik, és nem egy általános választ, amelyet a modell anélkül tud előállítani.

  1. Küldje el a kérést a Playgroundban, és tekintse át a streamelt választ.
  2. A részletek lapfülek segítségével megkeresheti a lassú vagy sikertelen műveletet.
  3. Vizsgálja meg a vonatkozó eseményt vagy eszközhívást, módosítsa a kódot vagy a konfigurációt, és ismételje meg a kérést.

A küldéshez nyomja le az Enter billentyűt, vagy új sor hozzáadásához a Shift+Enter billentyűkombinációt. Egy korábbi kérés visszahívásához helyezze a kurzort a bemenet elejére, és nyomja meg a Fel nyílbillentyűt. A le nyílbillentyűvel a végén lépjen az újabb kérések felé, és térjen vissza a nem küldött piszkozathoz.

A visszavont kérést a küldés előtt szerkesztheti. A bemeneti előzmények az Inspector kényelmi funkciói közé tartoznak, nem pedig a mentett kérések tartós tárolására szolgálnak.

View Használd erre:
Overview Kövesse a latencia-vízesésdiagramot és a rendezett futtatási ütemtervet. Az összes vagy egyetlen futtatás kiválasztásával megkülönböztetheti a modell- és eszköztevékenységet, valamint a futtatások közötti időt.
Jogkivonatok Tekintse át a jelentett bemeneti és kimeneti tokenek használatát. A hiányzó használati adat nem nulla tokenes eredmény.
Events Vizsgálja meg az elemzett Responses-eseményeket, beleértve a hibákat, a függvényhívásokat és az eredményeket. Keressen eseménytípus vagy JSON-tartalom alapján, és szűrjön kategória alapján.
Tools Vizsgálja meg az eszközhívásokat válaszfuttatások szerint csoportosítva, beleértve az állapotot, a hívásazonosítót, az argumentumokat és az eredményeket.

A válaszláb a modell, az időtartam, a tokenhasználat és az időbélyeg adatait jeleníti meg, ha meg van adva. Az érvelési szöveg és az érvelés összegzése külön összecsukható szakaszokban jelenik meg, amikor az ügynök kibocsátja őket. Az Inspector nem következtet ki hiányzó indoklást, és nem tesz közzé olyan információkat, amelyeket a modellszolgáltató nem ad vissza.

Eszközök és engedélyek vizsgálata

Az Eszközök eszközzel ellenőrizze, hogy az ügynök a várt argumentumokkal meghívta-e a várt eszközt, és kapott-e eredményt. A sikeres modellválasz nem bizonyítja, hogy egy eszköz futott. Ha a kód egy mockot használ, a megjelenített eredmény továbbra is egy mock eredménye.

Képernyőkép az Eszközök lapról, amelyen futtatás szerint csoportosított hívások és egy kibontott eszközhívás látható az argumentumaival és az eredményével.

Ha egy válasz a modellkörnyezeti protokoll (MCP) jóváhagyására vagy az OAuth-hozzájárulásra várakozás miatt szünetel, a függőben lévő kérések megjelennek az üzenet bemenete fölött. Csak az engedélyezni kívánt hozzáférést adja meg.

MCP-eszközhívás esetén válassza az Argumentumok megjelenítése lehetőséget, tekintse át a bemeneteket, majd válassza a Jóváhagyás vagy a Megtagadás lehetőséget. Összes jóváhagyása és Összes elutasítása a függőben lévő kérelmekre vonatkozik, nem pedig egy állandó eszközhasználati jóváhagyási szabályzatra.

OAuth-hozzájárulás esetén végezze el a böngészős hitelesítést és az Inspector megerősítését:

  1. Válassza a függőben lévő kérelemhez tartozó hozzájárulás megnyitása lehetőséget.
  2. Fejezze be az engedélyezést a böngészőben, térjen vissza az Inspectorhez, és válassza a Hozzájárulás megadva lehetőséget. Az engedélyezés elutasításához válassza a Mégse lehetőséget.
  3. Kezelje a fennmaradó hozzájárulási kérelmeket. Ha elérhető, használja a(z) Kész lehetőséget, csak az összes megnyitott kérelem engedélyezésének befejezése után.

A hozzájárulási oldal önmagában nem folytatja automatikusan a kérést. A felügyelő minden függőben lévő jóváhagyással kapcsolatos döntésre vár, mielőtt újra ellenőrizné a kiszolgálót. A kérelmek újra megjelenhetnek, ha a kiszolgálónak továbbra is hitelesítésre van szüksége.

A befejezés megerősítéséhez ellenőrizze a későbbi eszközeredményt, nem csak a jóváhagyást. A kapcsolat és a hitelesítés beállításához tekintse meg az eszközkatalógust. Ne módosítsa az eszköz hitelesítő adatait vagy engedélyeit kizárólag azért, hogy eltüntessen egy diagnosztikai hibát.

Munkafolyamatok és forráskód vizsgálata

A támogatott Microsoft Agent Framework-munkafolyamatok esetében a fejlesztőkiszolgáló képes munkafolyamat-diagnosztikát és forráshelyeket biztosítani. Az Inspector ezeket az információkat használja a végrehajtási gráf megjelenítéséhez, és segít a kódhoz való navigálásban.

  1. Válasszon ki egy munkafolyamat-csomópontot az elérhető bemenetek és kimenetek vizsgálatához.
  2. Kattintson duplán a csomópontra a forráshely megnyitásához.
  3. Állítson be egy töréspontot, és ismételje meg a kérést a művelet hibakeresőben való vizsgálatához.

A LangGraph-munkafolyamatokat tesztelheti a Playgroundban, de a munkafolyamat-vizualizáció nem támogatott ezekhez. A munkafolyamat metaadataival nem rendelkező kiszolgáló továbbra is hasznos válaszeseményeket adhat vissza.

Hibák kivizsgálása a Copilottal

Az Események hibakezelési műveleteivel a teljes beszélgetés másolása helyett a GitHub Copilot számára készíthet elő egy célzott kérést.

  1. A megosztás előtt keresse meg a sikertelen eseményt, és tekintse át annak részleteit az érzékeny tartalom szempontjából.
  2. A sikertelen esemény melletti Javítás elemet választva előkészítheti a hibára vonatkozó promptot. Több hiba esetén szűkítse a listát keresési és kategóriaszűrőkkel, majd válassza a Megoldás a Copilottal lehetőséget. Ez a művelet tartalmazza a látható hibákat.
  3. Mielőtt elküldené, tekintse át az előkészített promptot a GitHub Copilot Chatben. Tekintse át a javasolt módosításokat, majd futtassa újra az eredeti ügynökkérést az eredmény megerősítéséhez.

Ezekhez a műveletekhez nincs szükség az OTLP-gyűjtőre. A diagnosztikai prompt előkészítése nem javítja ki az ügynököt, és nem futtatja újra a sikertelen műveletet.

Képernyőkép az Események lapról, sikertelen válaszokkal, keresési és szűrővezérlőkkel, exportálási műveletekkel, valamint a Copilot Chatben előkészített diagnosztikai részletekkel.

Diagnosztikai események mentése

Mentsen egy esemény-pillanatképet, hogy összehasonlítsa a hibát egy későbbi futtatással, vagy megosszon egy célzott reprodukciót.

  1. Az Események területen szűkítse a listát a keresőmezővel és a kategóriaszűrővel.
  2. A szűrt események JSONL-ként való másolásához válassza a Látható események másolása lehetőséget. Másik lehetőségként válassza a Látható események letöltése lehetőséget az exportált fájl VS Code-ban való megnyitásához.
  3. A megnyitott exportfájlhoz a Fájl>mentése másként parancsot használva mentsen egy másolatot egy ön által meghatározott helyre, mielőtt bezárja a dokumentumot. A megnyitott export egy ideiglenes fájl, nem pedig végleges letöltés.

A pillanatkép a művelet kiválasztásakor látható eseményeket tartalmazza, nem a futó ügynök jövőbeli eseményeit. Nem menti az ügynökprogram verzióját, nem telepít kódot, és nem hoz létre Cloud Trace-előzményeket.

Caution

Az események tartalmazhatnak utasításokat, válaszokat, eszközargumentumokat, eredményeket és hibaadatokat. Az exportálás mentése vagy megosztása előtt tekintse át a bizalmas tartalmakat, és szerkessze ki azokat.

Új beszélgetés indítása

Új beszélgetés indításához és a csevegés, az Események és a Részletek állapot törléséhez válassza a Csevegés törlése lehetőséget. Exportálja a szükséges diagnosztikai eseményeket. Ugyanannak a csatlakoztatott ügynöknek a frissítése megőrzi a vizsgálati állapotát, míg a másik ügynökre váltás törli az elavult állapotot.

Válaszok esetén a Clear Chat le van tiltva, miközben egy válasz aktívan streamelődik. Akkor is elérhető marad, ha a folyamat jóváhagyásra vagy hozzájárulásra szünetel. Ez nem általános parancs az ügynököd leállításához.

Ne támaszkodjon a helyi Inspector-állapotra tartós beszélgetési archívumként. A kiszolgáló kezeli a beszélgetések perzisztenciáját, ami eltérhet a helyi fejlesztés és a telepített hosztolt ügynök között. A Clearing Inspector nem törli a helyileg gyűjtött vagy az Application Insightsban tárolt nyomkövetéseket.

Miben különbözik az Inspector és a nyomkövetés?

Az Inspector HTTP-en keresztül kommunikál a helyi kiszolgálóval, és streameli a válaszeseményeket. A kompatibilis fejlesztői kiszolgáló külön diagnosztikai streamet is biztosít a munkafolyamat részleteihez és a forrásnavigációhoz. A hibakereső függetlenül csatlakozik a futó folyamathoz.

Ezekhez az élő diagnosztikához nincs szükség a helyi OTLP-gyűjtőre. Az Inspector nyomkövetések lapfül megnyitja a különálló nyomkövetési megjelenítőt. Nem konvertálja a protokolleseményeket tárolt OpenTelemetry-spaneekké.

A későbbi elemzéshez szükséges spanok gyűjtéséhez konfigurálja a helyi nyomkövetést. Az üzembe helyezett ügynökökhöz használja a hosztolt ügynök nyomkövetéseit.

A helyi tesztelés után telepítse a hostolt ügynököt. Tesztelje külön, mert identitása, környezete és hálózati hozzáférése eltér a helyi folyamattól.

Troubleshooting

Issue Mit kell ellenőrizni?
Az Inspector nem tud csatlakozni. Ellenőrizze az ügynök terminálját indítási hibák szempontjából. Erősítse meg az interpretert, a függőségeket és a HTTP-portot, majd csatlakozzon újra ahhoz a porthoz, amelyet a kiszolgáló jelez. Az Opening Inspector nem indítja el a folyamatot.
A kérés sikeres, de a töréspontok nem aktiválódnak. Győződjön meg arról, hogy a hibakereső a kérést kiszolgáló folyamathoz van csatolva, és a megfelelő forráskönyvtárat használja. A Pythonhoz lásd a hibakeresés és hibaelhárítás részt.
Hiányzik a gráf- vagy forrásnavigáció. Győződjön meg arról, hogy a kiszolgáló és a munkafolyam fejlesztési diagnosztikát és a forráskód helyeit biztosítja. Az általános válaszok ellenőrzése nem biztosítja ezeket a képességeket. A LangGraph-munkafolyamatok munkafolyamat-vizualizáció nélkül működnek a Playgroundban.
Az eszköz eredményei hiányoznak. Ellenőrizze az Események között a hibákat és a függőben lévő jóváhagyásokat. Győződjön meg arról, hogy a kéréshez eszközre van szükség, és hogy az eszköz konfigurálva van és elérhető.
A token vagy az érvelés részletei hiányoznak. Ellenőrizze, hogy a modell és a kiszolgáló mit ad ki. Az ellenőr csak az általuk megadott információkat tudja megjeleníteni.
A távoli képek le vannak tiltva. Csak akkor válassza a Távoli képek betöltése lehetőséget, ha azt szeretné, hogy az Inspector lekérje őket távoli gazdagépekről. Ez a megjelenítési engedély nem eszközjóváhagyás. A nem támogatott URL-címek vagy tartalmak betöltése továbbra is sikertelen lehet. A hiányzó kép nem feltétlenül jelenti azt, hogy az ügynök kérése meghiúsult.
A válaszfolyam megszakadt. Tekintse át a részleges választ és a hiba részleteit. Szükség esetén csatlakozzon újra, és újrapróbálkozás előtt tekintse át a függőben lévő jóváhagyásokat. Az újrapróbálkozás megismételheti az élő eszközműveleteket.
Az Inspector eseményeket tartalmaz, de a nyomkövetési megjelenítő üres. A protokollesemények és az OTLP-spanek eltérőek. Konfigurálja az instrumentálást, és indítsa el a gyűjtőt.

Kapcsolódó tartalom

  • Utolsó frissítés időpontja: