Microsoft Foundry Toolkit'te Agent Inspector ile aracılarda hata ayıklama

Visual Studio Code için Microsoft Foundry Araç Seti'ndeki Aracı Denetçisi, yerel bir aracıya istek göndermenize, model ve araç etkinliğini incelemenize ve kodunuzun hatalarını ayıklamanıza olanak tanır. Değişikliği dağıtmadan önce beklenmeyen yanıtları araştırmak için bunu kullanın.

Bu iş akışı, özel kodunuzu Foundry Agent Service içinde çalıştıran barındırılan aracılar için kullanışlıdır. Yerel denetim, bu kodda hata ayıklamanıza yardımcı olur. Üretim kullanımı öncesinde, dağıtılan ajanı çalışma zamanı kimliği, yapılandırması ve ağ erişimiyle de test edin.

Bu makalede, yerel bir aracıya bağlanır, bir isteği araştırır ve tanılama olaylarını kaydedersiniz. Ana yol Yanıtlar protokolünü kullanır. Kullanılabilir görünümler, ajan sunucunuzun sağladığı protokole ve tanılamaya bağlıdır.

Prerequisites

  • Visual Studio Code, geçerli genel Foundry Toolkit uzantısıyla. Bkz. Foundry Toolkit'i Yükleme.
  • Bağımlılıkları, model yapılandırması ve kimlik bilgileri ayarlanmış bir yerel aracı projesi. Bir örnekten başlamak için yerel test sürecinde hosted-agent hızlı başlangıç kılavuzunu izleyin.
  • Projeniz için gereken hata ayıklayıcısı. Python örneği Python uzantısını ve debugpy kullanır. Diğer diller ve örnekler farklı gereksinimlere sahiptir.

Mevcut bir proje için, Foundry Toolkit Copilot tools yapılandırmanın hazırlanmasına yardımcı olabilir. Oluşturulan dosyaları gözden geçirin ve projenin README.md yönergelerini izleyin. Onun başlatma dosyalarını genel bir yapılandırmayla değiştirmeyin.

Important

Yerel bir ajan bulut modellerini ve canlı araçları kullanabilir. Hassas olmayan test girişlerini kullanın, araç izinlerini denetleyin ve yapılandırılmış hizmetlerden kaynaklanan ücretleri hesaba katın. Denetçi araçları mock'larla değiştirmez.

Bağlan ve hata ayıkla

Inspector'a bağlanmadan önce aracı sunucusunu başlatın. Sunucu, çalışma dizini, yorumlayıcı ve hata ayıklayıcıyı uyumlu hale getirmek için projenizin oluşturulan başlatma yapılandırmasını kullanın.

  1. Aracıyı belgelenmiş hata ayıklama yapılandırmasıyla başlatın. Barındırılan aracı Python örneği için Yerel Aracı HTTP Sunucusunda Hata Ayıkla'yı seçin ve F5 tuşuna basın.
  2. Denetçi açık değilse Etkinlik Çubuğu'nda Foundry Toolkit'i ve ardından Geliştirici Araçları>Derleme>Agent Inspector'ı seçin.
  3. Inspector üst bilgisinde endpoint’i denetleyin. Geçerli Python scaffold'ı http://localhost:8088 kullanır. Farklı bir sunucu bağlantı noktası için uç noktanın yanındaki kalem düğmesini seçin, bağlantı noktasını girin ve Bağlan'ı seçin.
  4. Üst bilgide Bağlı ifadesinin gösterildiğini onaylayın. Inspector, uç nokta ulaşılabilir olduğunda Responses veya Invocations protokolünü otomatik olarak algılar.
  5. Ajan kodunuzda bir kesme noktası ayarlayın ve oyun alanında bir ileti gönderin. Yürütme duraklatıldığında değişkenleri inceleyin, ardından devam edin ve yanıtı gözden geçirin.

Yerel aracı hata ayıklama yapılandırmasının ve başarılı bir yanıtla 8088 numaralı bağlantı noktasında localhost'a bağlı Aracı Denetçisi'nin ekran görüntüsü.

Denetçi'nin tek başına açılması bir sunucu başlatmaz veya hata ayıklayıcı bağlamaz. Oluşturulan Python yapılandırması, hata ayıklayıcı için 5679 numaralı bağlantı noktasını ve aracı HTTP istekleri için 8088 numaralı bağlantı noktasını kullanır. Bu bağlantı noktaları OTLP izleme bağlantı noktalarından ayrıdır.

Genel bir Responses uç noktasına bağlanın

Denetçi, tam geliştirme tanılama arabirimi olmadan yerel genel Yanıtlar uç noktasına bağlanabilir. Sunucunun gönderdiği Yanıtlar olaylarını inceleyebilirsiniz, ancak iş akışı grafiği ve onun giriş/çıkış görünümü kullanılamaz.

Başarılı bir bağlantı, sunucunun kaynak konumları, belirteç kullanımını veya akıl yürütmeyi sağladığı anlamına gelmez.

HTTP çağrısı gönderme

Aracınız konuşma iletisi yerine özel bir istek gövdesi kabul ettiğinde HTTP çağrılarını kullanın. Sunucunun istek biçimi ve yanıt protokolü, Inspector'ın sonucu nasıl gönderip görüntülediğini belirler.

  1. Çalışan HTTP invocation sunucunuza bağlanın. Denetçi protokolü otomatik olarak algılar.
  2. Aracınızın gerektirdiği istek gövdesini girin. Sunucu uyumlu bir OpenAPI belirtimi sunuyorsa, Inspector bir örneği doldurabilir. Göndermeden önce gözden geçirin veya örnek yoksa örnek istek biçimini izleyin.
  3. Girişin yanındaki İstek ayarları dişlisini seçerek Content-Type ve Accept ayarlarını sunucunun gerektirdiği şekilde ayarlayın. Örneğin, bir JSON gövdesi için text/event-stream ve sunucu bir akış yanıtını desteklediğinde application/json kullanın.
  4. Gönder'i seçin ve yanıt durumunu ve gövdesini inceleyin.
  5. Biçimlendirilmiş çıkış için Önizleme ile temel alınan yanıt için Ham arasında geçiş yapın. Ayrıntılar bölmesi G/Ç ve LLM Çağrılarını da içerir. Model, araç ve belirteç ayrıntıları tanınan sunucu olaylarına bağlıdır, bu nedenle her yanıt her sekmeyi doldurmaz.

Denetçi normal bir HTTP yanıtını, sunucu tarafından gönderilen olayların akışını veya eşzamansız yanıtı işler. Eşzamansız 202 Accepted yanıt için, tamamlanma veya hataya kadar çağrıyı yoklar. Yanıt biçimi seçmek sunucunuza akış veya zaman uyumsuz destek eklemez.

Akış yanıtı için Durdur , istemci akışının bağlantısını keser. Yoklanan çağrı için İptal , sunucuya bir iptal isteği gönderir. Hiçbir eylem, ajan sürecinin veya harici bir araç işleminin durduğunu garanti etmez.

Bu görünüm bir WebSocket istemcisi değildir. Activity Protocol örnekleri farklı bir çalışma alanı kullanır. Uygun yerel test yolu için bkz. Başka bir protokol veya örnek seçin.

Denetçiyi kullanın

Anlamak istediğiniz davranışı sınayan bir istekle başlayın. Örneğin bir hava durumu aracı için modelin bu araç olmadan üretebileceği genel bir yanıt yerine bu aracı gerektiren bilgileri isteyin.

  1. İsteği Playground'da gönderin ve akış yanıtını gözden geçirin.
  2. Yavaş veya başarısız olan işlemi bulmak için Ayrıntılar sekmesini kullanın.
  3. İlgili olay veya araç çağrısını inceleyin, kodunuzu veya yapılandırmanızı değiştirin ve isteği yineleyin.

Göndermek için Enter tuşuna veya yeni satır eklemek için Shift+Enter tuşlarına basın. Önceki bir isteği geri çağırmak için giriş işaretini girişin başlangıcına yerleştirin ve Yukarı Ok tuşuna basın. Daha yeni isteklere doğru ilerlemek ve gönderilmemiş taslağınıza dönmek için sondaki Aşağı Ok tuşuna basın.

Geri çağrılmış bir isteği göndermeden önce düzenleyebilirsiniz. Giriş geçmişi, Denetçi içinde bir kolaylıktır; kaydedilmiş istemlerin kalıcı deposu değildir.

View Bunu kullanarak
Overview Gecikme süresi şelalesini ve sıralı çalıştırma zaman çizelgesini izleyin. Model ve araç etkinliğini çalıştırmalar arasındaki süreden ayırt etmek için tüm çalıştırmaları veya tek bir çalıştırmayı seçin.
Belirteçler Bildirilen giriş ve çıkış belirteci kullanımını gözden geçirin. Eksik kullanım verileri sıfır tokenlı bir sonuç değildir.
Events Hatalar, işlev çağrıları ve sonuçlar dahil olmak üzere ayrıştırılmış Yanıtlar olaylarını inceleyin. Olay türüne veya JSON içeriğine göre arama yapıp kategoriye göre filtreleyin.
Tools Durum, çağrı kimliği, bağımsız değişkenler ve sonuçlar dahil olmak üzere yanıt çalıştırmalarına göre gruplandırılmış araç çağrılarını inceleyin.

Yanıt alt bilgisi model, süre, belirteç kullanımı ve varsa zaman damgası bilgilerini gösterir. Aracı bunları ürettiğinde, mantık metni ve mantık özetleri ayrı daraltılabilir bölümlerde görünür. Denetçi eksik mantık oluşturmaz veya model sağlayıcısının döndürmediği bilgileri kullanıma sunmaz.

Araçları ve izinleri inceleyin

Araçlar'ı, aracının beklenen aracı beklenen bağımsız değişkenlerle çağırıp çağırmadığını ve bir sonuç alıp almadığını denetlemek için kullanın. Başarılı bir model yanıtı, bir aracın çalıştığını kanıtlamaz. Kodunuz bir mock kullanıyorsa, görüntülenen sonuç yine de bir mock sonuç olur.

Çalıştırmaya göre gruplandırılmış çağrıların ve bağımsız değişkenlerini ve sonucunu gösteren genişletilmiş araç çağrısının yer aldığı Araçlar sekmesinin ekran görüntüsü.

Model Bağlam Protokolü (MCP) onayı veya OAuth onayı için yanıt duraklatıldığında, ileti girişinin üzerinde bekleyen istekler görünür. Yalnızca izin vermek istediğiniz erişimi verin.

MCP araç çağrısı için Bağımsız değişkenleri göster'i seçin, girişleri gözden geçirin ve ardından Onayla veya Reddet'i seçin. Tümünü onayla ve Tümünü reddet , kalıcı bir araç onay ilkesine değil bekleyen isteklere uygulanır.

OAuth onayı için hem tarayıcı yetkilendirmesini hem de Denetçi onayını tamamlayın:

  1. Bekleyen istek için Onayı aç seçin.
  2. Tarayıcıda yetkilendirmeyi tamamlayın, Denetçi'ye dönün ve Consent done'u seçin. Yetkilendirmeyi reddetmek için bunun yerine İptal'i seçin.
  3. Kalan onay isteklerini yanıtlayın. Yalnızca tüm açık istekler için yetkilendirme tamamlandıktan sonra, kullanılabilir olduğunda Tümü tamamlandı'yı kullanın.

Bir onay sayfasını tek başına açmak isteği devam ettirmez. Denetçi, sunucuyu yeniden denetlemeden önce bekleyen her onayla ilgili bir karar bekler. Sunucunun hâlâ yetkilendirmeye ihtiyacı varsa istekler yeniden görünebilir.

Tamamlandığını doğrulamak için yalnızca onayı değil, sonraki araç sonucunu denetleyin. Bağlantı ve kimlik doğrulaması kurulumu için bkz. Araç Kataloğu. Araç kimlik bilgilerini veya izinlerini yalnızca tanılama hatasının kaybolması için değiştirmeyin.

İş akışlarını ve kaynak kodunu inceleyin

Desteklenen Microsoft Agent Framework iş akışları için geliştirme sunucusu iş akışı tanılamaları ve kaynak konumları sağlayabilir. Denetçi, yürütme grafiğini göstermek ve kodunuza gitmenize yardımcı olmak için bu bilgileri kullanır.

  1. Kullanılabilir girişleri ve çıkışları incelemek için bir iş akışı düğümü seçin.
  2. Kaynak konumunu açmak için düğüme çift tıklayın.
  3. Hata ayıklayıcıda işlemi incelemek için bir kesme noktası ayarlayın ve isteği yineleyin.

Oyun alanında LangGraph iş akışlarını test edebilirsiniz, ancak iş akışı görselleştirmesi bunlar için desteklenmez. İş akışı meta verileri olmayan bir sunucu yine de yararlı yanıt olayları döndürebilir.

Copilot ile başarısızlıkları araştırma

Konuşmanın tamamını kopyalamak yerine, GitHub Copilot için odaklanmış bir istek hazırlamak üzere Olaylar bölümündeki hata eylemlerini kullanın.

  1. Başarısız olayı bulun ve paylaşmadan önce ayrıntılarını hassas içerik açısından gözden geçirin.
  2. Bu hata için bir istem hazırlamak için başarısız olayın yanındaki Düzelt'i seçin. Birkaç başarısızlık için listeyi arama ve kategori filtreleri ile daraltın ve ardından Copilot ile çözümle seçin. Bu eylem görünür hataları içerir.
  3. Göndermeden önce GitHub Copilot Chat'te hazırlanan istemi gözden geçirin. Önerilen değişiklikleri gözden geçirin, ardından sonucu onaylamak için özgün ajan isteğini yeniden çalıştırın.

Bu eylemler OTLP toplayıcısı gerektirmez. Tanılama isteminin hazırlanması aracıyı düzeltmez veya başarısız işlemi yeniden çalıştırmaz.

başarısız yanıtlar, arama ve filtre denetimleri, dışa aktarma eylemleri ve Copilot Chat'de hazırlanan tanılama ayrıntılarını içeren Olaylar sekmesinin ekran görüntüsü.

Tanılama olaylarını kaydet

Bir hatayı daha sonraki bir çalıştırmayla karşılaştırmak veya odaklı bir yeniden oluşturmayı paylaşmak için olay anlık görüntüsünü kaydedin.

  1. Olaylar'da, arama alanı ve kategori filtresiyle listeyi daraltın.
  2. Filtrelenen olayları JSONL olarak kopyalamak için Görünür olayları kopyala'yı seçin. Alternatif olarak, dışarı aktarmayı VS Code'da açmak için Görünür olayları indir'i seçin.
  3. Açık dışa aktarma için, belgeyi kapatmadan önce bir kopyasını denetiminizde olan bir konuma kaydetmek için Dosya>Farklı Kaydet'i kullanın. Açılan dışarı aktarma, kalıcı bir indirme değil geçici bir dosyadır.

Anlık görüntü, eylemi seçtiğinizde görünen olayları içerir, çalışan ajandan gelecek olayları içermez. Ajan sürümünü kaydetmez, kod dağıtmaz veya Cloud Trace geçmişi oluşturmaz.

Caution

Olaylar istemleri, yanıtları, araç argümanlarını, sonuçları ve hata ayrıntılarını içerebilir. Dışarı aktarmayı kaydetmeden veya paylaşmadan önce hassas içeriği gözden geçirin ve gizleyin.

Yeni bir konuşma başlat

Yeni bir konuşma başlatmak ve sohbet, Olaylar ve Ayrıntılar durumunu temizlemek için Sohbeti Temizle'yi seçin. önce ihtiyacınız olan tanılama olaylarını dışarı aktarın. Aynı bağlı ajanı yenilemek denetim durumunu korurken farklı bir ajana geçilmesi eski durumu temizler.

Yanıtlar için, yanıt hâlen iletilirken Clear Chat devre dışı bırakılır. Adım onay veya rıza için duraklatıldığında kullanılabilir durumda kalır. Bu, ajanınızı durdurmak için genel bir komut değildir.

Kalıcı konuşma arşivi olarak yerel Denetçi durumuna güvenmeyin. Konuşma kalıcılığından sunucu sorumludur; bu, yerel geliştirme ile dağıtılmış barındırılan bir ajan arasında farklılık gösterebilir. Denetçi temizlendiğinde, yerel olarak toplanan veya Application Insights'ta depolanan izlemeler silinmez.

Inspector ve izleme arasındaki fark

Denetçi HTTP üzerinden yerel sunucunuzla iletişim kurar ve yanıt olaylarını akış olarak iletir. Uyumlu bir geliştirme sunucusu, iş akışı ayrıntıları ve kaynak gezintisi için ayrı bir tanılama akışı da sağlar. Hata ayıklayıcı, çalışan işleminize bağımsız olarak eklenir.

Bu canlı tanılamalar için yerel OTLP toplayıcısı gerekmez. Denetçinin İzlemeler sekmesi ayrı izleme görüntüleyicisini açar. Protokol olaylarını depolanan OpenTelemetry spans'a dönüştürmez.

Daha sonra analiz için span’leri toplamak amacıyla yerel izlemeyi yapılandırın. Dağıtılan ajanlar için hosted-agent izlerini kullanın.

Yerel test sonrasında barındırılan aracıyı dağıtın. Kimliği, ortamı ve ağ erişimi yerel işleminizden farklı olduğundan ayrı olarak test edin.

Troubleshooting

Sorunu Denetlenecek şeyler
Denetçi bağlanamıyor. Başlatma hataları için ajan terminalini denetleyin. Yorumlayıcıyı doğrulayın, bağımlılıkları ve HTTP bağlantı noktasını onaylayın, ardından sunucunun bildirdiği bağlantı noktasına yeniden bağlanın. Inspector'ı açmak işlemi başlatmaz.
İstek başarılı olur ancak kesme noktalarına ulaşılmaz. Hata ayıklayıcının isteğe hizmet veren işleme eklendiğini ve doğru kaynak dizini kullandığını onaylayın. Python için hata ayıklama ve sorun giderme bölümüne bakın.
Grafik veya kaynak gezintisi eksik. Sunucunun ve iş akışının geliştirme tanılamaları ve kaynak konumları sağladığını onaylayın. Genel Yanıtlar denetimi bu özellikleri sağlamaz. LangGraph iş akışları, iş akışı görselleştirmesi olmadan oyun alanında çalışır.
Araç sonuçları eksik. Hatalar ve bekleyen onaylar için Events'i denetleyin. İsteğin bir araç gerektirdiğini ve aracın yapılandırıldığını ve ulaşılabilir olduğunu onaylayın.
Token veya akıl yürütme ayrıntıları eksik. Modelin ve sunucunun ne yaydığını kontrol edin. Denetçi yalnızca sağladığı bilgileri görüntüleyebilir.
Uzaktaki resimler engellendi. Uzak Görüntüleri Yükle'yi yalnızca Inspector'ın onları uzak konaklardan getirmesini istiyorsanız seçin. Bu görüntüleme izni bir araç onayı değildir. Desteklenmeyen URL'ler veya içerik yine de yüklenemeyebilir. Eksik görüntü, ajan isteğinin başarısız olduğu anlamına gelmez.
Yanıt akışı kesintiye uğrar. Kısmi yanıt ve hata ayrıntılarını gözden geçirin. Gerekirse yeniden bağlanıp yeniden denemeden önce bekleyen onayları gözden geçirin. Yeniden deneme, canlı araç eylemlerini yineleyebilir.
Denetçide olaylar var, ancak izleme görüntüleyicisi boş. Protokol olayları ve OTLP span'ları farklıdır. İzlemeyi yapılandırın ve toplayıcıyı başlatın.

İlgili içerik

  • Son güncelleştirme: