Salı öğleden sonra. On iki dönüş bir hata ayıklama oturumuna dönüştü ve ajan kendinden emin bir şekilde `/users` uç noktamızın kırk yedi saniyede yanıt verdiğini söylüyordu. Gerçek sayı kırk yedi milisaniyeydi.
Bu hatayı iki gündür kovalıyordum. MCP sunucusuna her print ifadesi eklediğimde, ajanın cevabı, bir yere vardığımı düşünmemi sağlayacak kadar değişiyordu. Sistem istemini her yeniden yazdığımda, yanıt daha makul geliyordu. Hiçbiri doğru değildi.
O öğleden sonraya kadar yapmadığım şey, gerçek yürütme izini açıp model ile araç arasında neyin geçtiğine bakmaktı. Apidog'un Yapay Zeka Aracısı Hata Ayıklayıcısı işte tam da bunun için var. Üç hafta önce kurmuştum ve unutmuştum. Hatayı bulmak on iki dakikamı aldı.
Beni şaşırtan buydu.
Kovaladığım hata
Kurulum basitti. GPT-5.5 üzerine kurulu bir aracı. Bir hafta sonunda yazdığım, metrik boru hattımızı sorgulayan bir `get_response_time(endpoint)` aracı sunan bir MCP sunucusu. Belki kırk kelimelik bir sistem istemi. Kullanıcı istemi: "/users uç noktası ne kadar hızlı?"
Aracı hızlı yanıt verdi. Kendinden emin yanıt verdi. Her zaman, farklı şekillerde yanlış yanıt verdi. Bazen "uç nokta 47 saniyede yanıt veriyor." Bazen "yaklaşık 0.05 saniye." Bir keresinde, akılda kalıcı bir şekilde, "performans kabul edilebilir."
Yapmanız gereken şeyleri yapıyordum. MCP sunucusuna günlük kaydı ekliyordum. Modelin yanıtını token-token okuyordum. Sistem istemlerini karşılaştırıyordum. Küfür ediyordum. Salı sabahına kadar üç açık terminal pencerem ve başarısız hipotezlerden oluşan bir Notion sayfam vardı.
Aracıların hatalarını ayıklamanın zor yanı, hatanın nadiren ilk baktığınız yerde olmasıdır. Sistem isteminde, model seçiminde, araç tanımında, modelin araca ilettiği parametrelerde, aracın döndürdüğü verilerde veya modelin bu verileri nasıl yorumladığında yaşayabilir. Altı yer. Bir konsol günlüğü size birini gösterir.
İzler paneli aslında ne gösterir
Apidog hata ayıklayıcı üç sütuna açılır. Solda oturumlar. Ortada dönüşler. Sağda izler. Herhangi bir oturuma tıkladığınızda orta sütun size diyaloğu gösterir: kullanıcı mesajı, model yanıtı, araç çağrısı, araç dönüşü, bir sonraki model yanıtı. Herhangi bir dönüşe tıkladığınızda sağ sütun, altındaki tüm yürütme ağacını genişletir.
Yürütme ağacı, kaçırdığım kısımdı. Her adım, sırayla:
- Modelin aldığı sistem istemi
- Modelin aldığı kullanıcı istemi
- Modelin yaydığı şekilde, JSON olarak araç çağrısı adı ve parametreleri
- Aracın döndürdüğü şekilde, JSON olarak araç sonuç yükü
- Model yanıtı, dönüş için zamanlama ve tokenlar ile
Başarısız oturumu açtım. Araç çağrısı iyi görünüyordu: `get_response_time(endpoint="/users")`. Model doğru argümanla doğru aracı seçmişti.
Ardından araç sonucunu genişlettim.
{"value": 47, "p95": 89, "samples": 1240}
İşte oradaydı. Metrik boru hattı değeri milisaniye cinsinden döndürüyordu. Model ise saniye varsayıyordu. 47, birimi sorgulamaya zahmet etmeyen kendinden emin bir halüsinasyon yoluyla "47 saniye" haline geldi. Araç doğruydu. Model yanlıştı. Sistem istemimde birimler hakkında bir talimat yoktu ve araç yanıtında birim açıklaması yoktu.
Hata ayıklayıcıyı açtıktan on iki dakika sonra. İki gün boyunca sistem istemini suçlamıştım.
Düzeltme altı satır sürdü
İki şeyi değiştirdim. MCP sunucusunda yanıt şeklini güncelledim:
{
"value": { "amount": 47, "unit": "ms" },
"p95": { "amount": 89, "unit": "ms" },
"samples": 1240
}
Ardından sistem istemine bir cümle ekledim: "Araç sonuçları birimleri açıkça döndürür. Bunları dikkatlice okuyun."
Aynı `/users` istemini üç kez daha çalıştırdım. Sol panelde üç farklı oturum. Üçü de doğru bir şekilde "uç nokta yaklaşık 47 ms'de yanıt veriyor" yanıtını verdi ve modelin akıl yürütmesinde milisaniyeden yüzdeye kadar bir döküm vardı. Token maliyeti, başarısız denemelerimden yüzde on sekiz daha düşüktü, muhtemelen model kendi kötü varsayımları etrafında kurtarma metni üretmiyordu.
Aynı istemi Claude Opus 4.7 üzerinde ikinci bir oturumda, yan yana çalıştırdım. Aynı sonuç, iki katı maliyet, biraz daha ayrıntılı. Hangi modelin üretime gideceğini biliyordum.
Bu, aracın saygımı kazanan kısmıydı. Herhangi iyi bir hata ayıklayıcının yapması gereken hata bulma değil. Sol panelde özet metriklerle (dönüş sayısı, adım sayısı, zaman, token, dolar) aynı konfigürasyonlarda çalışan model karşılaştırması. Bu karşılaştırmayı altı aydır bir Google E-Tablosunda yapıyordum. Şimdi üç tıkla yapılıyordu.
Neleri yanlış yapıyordum
Ucuz yorum, Yapay Zeka Aracısı Hata Ayıklayıcısının bir günlük kaydı aracı olduğudur. Değildir. Günlük kaydı araçları size ne olduğunu gösterir. Hata ayıklayıcı ise model ve aracın gerçekte ne alışveriş yaptığını gösterir, bu farklı bir katmandır.
Eğer aracı yazıyorsanız ve benim yaptığım şeyi yapıyorsanız, yani model çıktısını okuyup başarısızlıkların nedenini tahmin ediyorsanız, işte size karşı çıkacağım şey. Siz aracıda hata ayıklamıyorsunuz. Aracınınız hakkındaki hipotezinizde hata ayıklıyorsunuz. Bunlar farklı şeylerdir ve sadece biri sizi bir düzeltmeye götürür.
Altı ay boyunca içselleştirmeyi reddettiğim şey, aracının model, istem, araçlar ve araç yanıtları arasında kapalı bir sistem olduğuydu. Hata her zaman bu dördünden birinde yaşar. Dördünü de aynı anda görebiliyorsanız, hatayı on iki dakikada bulabilirsiniz. Göremezseniz, bir hafta peşinden koşabilirsiniz.
Hata ayıklayıcının ortaya çıkardığı, beklemediğim diğer bir şey de kendi aracımda determinist olmayan davranışlardı. Düzeltmeden sonra aynı istemi beş kez çalıştırdım, sadece onaylamak için. Üç çalışma `get_response_time`'ı bir kez çağırdı. İki çalışma ise iki kez çağırdı, ikinci seferde uç nokta yolu farklı bir büyük/küçük harf durumundaydı. Araç şemam büyük/küçük harf duyarlıydı. Başarısız test durumlarımın hepsi küçük harf kullandığı için fark etmemiştim. Bu, görmeden yayına alacağım ikinci bir hataydı.
Çoklu çalıştırma analizi, ileride en çok kullanacağım özelliktir. Çalıştır'a beş kez tıklayın. Oturumlar paneline bakın. Çalıştırmalar arasında değişen her şey, aracınızın kırılgan olduğu bir yerdir.
Kendiniz deneyin: tam kurulum rehberi
Hata avı sırasında kullandığım aynı kurulumu istiyorsanız, işte yeni bir kurulumdan çalışan bir hata ayıklama oturumuna giden yol. Sırasıyla beş ekran.
Adım 1: Yeni bir aracı hata ayıklama oturumu oluşturun
Apidog'u açın ve üst sekme çubuğundaki AI Agent Debugger'a tıklayın. Sayfanın üst bölümü modeli ve çalıştırma durumunu yapılandırır.
- Solda model sağlayıcısını seçin (OpenAI, Anthropic ve diğerleri)
- Ortada belirli modeli seçin, örneğin `gpt-5.5`
- Sağlayıcı seçildikten sonra Temel URL otomatik olarak dolar, manuel giriş gerekmez
- Bir oturum başlatmak için Çalıştır'a tıklayın
Adım 2: İstemleri yapılandırın
İstemler sekmesinde iki giriş alanı bulunur.
- Sistem İstemisi: aracının rolünü, hedeflerini, kısıtlamalarını ve araç kullanım kurallarını tanımlar
- Kullanıcı İstemisi: bu oturum için test girişi, örneğin "Apidog nedir?"
İkisi de ayarlandığında sağ üstteki Çalıştır'a tıklayın. Her çalıştırmadan sonra giriş kutusunun otomatik olarak temizlenmesini istiyorsanız, Gönderdikten sonra temizle'yi işaretleyin.
Adım 3: Araçları yapılandırın
Araçlar sekmesi, aracının çalışma zamanında çağırabileceği her şeyi listeler. Sekmedeki sayı, mevcut veya yapılandırılmış araçların güncel sayısını gösterir.
Yerleşik araçlar hata ayıklayıcıyla birlikte gelir. İhtiyaç duyulduğunda açıp kapatın.
| Araç | Ne işe yarar |
|---|---|
bash |
Kalıcı bir kabuk oturumunda komutları yürütün |
web_fetch |
Web içeriğini getirir ve Markdown, metin veya HTML'ye dönüştürür |
read |
Metin, resim veya PDF dosyalarını okur |
edit |
Dosyalara hassas dize değiştirmeler uygular |
write |
Dosyalar oluşturur veya üzerine yazar |
grep |
Düzenli ifadelerle dosya içeriğini arar |
glob |
Glob desenlerini kullanarak dosyaları bulur |
kill_shell |
Geçerli kabuk oturumunu sıfırlar |
MCP araçları, MCP Sunucuları aracılığıyla harici sistemler veya özel yetenekler ekler. Üç bağlantı yöntemi:
- STDIO: yerel bir MCP Sunucusu sürecini başlatır
- HTTP: Akış Yapabilen HTTP'yi destekleyen bir MCP Sunucusuna bağlanır
- SSE: Sunucu Tarafından Gönderilen Olaylara (Server-Sent Events) dayalı bir MCP Sunucusuna bağlanır
Kimlik doğrulama gerektiren MCP Sunucuları, istek başlıklarını veya OAuth 2.0 akışlarını kabul eder. Bağlantı başarılı olduğunda, sunucunun araca hangi araçları sunduğunu seçin.
Adım 4: Becerileri, kimlik doğrulamayı ve model parametrelerini yapılandırın
Üç küçük sekme kurulumu tamamlar.
- Beceriler: aracı için yeniden kullanılabilir iş akışları. Sabit proje iş akışları, ortak görev işlem özellikleri ve sistem istemlerinde tekrarlayan uzun metinleri azaltmak için kullanışlıdır. Beceriler çalışma zamanında gerektiği gibi yüklenir.
- Kimlik Doğrulama: model hizmetleri veya MCP hizmetleri tarafından istenen kimlik bilgileri.
- Ayarlar: Sıcaklık, Maks Tokenlar ve Üst P gibi model çalışma zamanı parametreleri. Desteklenen parametreler sağlayıcıya göre değişir, bu nedenle modelinizin gerçekte neleri kabul ettiğini kontrol edin.
Adım 5: Üç paneli okuyun
Çalıştır'a tıkladıktan sonra, az önce oluşturduğunuz oturum sol panelde görünür. Her oturum tek satırlık bir özet gösterir:
Oturum 3
1 dönüş · 1 adım · 10sn · 3.1k token · 0.02$
gpt-5.5
- Oturumlar paneli (sol): özet metriklerle her çalıştırmanın geçmişi
- Dönüşler paneli (orta): kullanıcı/model diyalogunun her turu. Sağda yürütme detayını yüklemek için bir tura tıklayın.
- İzler paneli (sağ): sistem ve kullanıcı istemleri, her model çağrısı, modelin düşünme süreci (eğer model bunu ifşa ediyorsa), MCP araç çağrıları ve özel Yetenek yürütmeleri, araç giriş parametreleri, sonuçlar, harcanan zaman, hata mesajları ve nihai çıktı dahil olmak üzere aracının tam yürütme zinciri sırasıyla.
Bir araç çağrısı başarısız olduğunda veya model bir istisna döndürdüğünde, başarısız adım, girişleri ve çıktıları görünür şekilde İzler panelinde hemen oradadır. Günlüklerde dalmaya gerek yok.
Adım 6: Model performansını karşılaştırın
Aynı istem, aynı araç yapılandırması, farklı model. Her çalıştırma yeni bir oturum oluşturur ve sol panel, bunları yan yana karşılaştırmanıza olanak tanır.
Karşılaştırmak için faydalı metrikler:
- Aynı görev için yürütme adımı sayısı
- Hangi model araçları daha doğru seçer
- Hangi modelin yanıt süresi daha düşüktür
- Hangi model token tüketimini ve maliyeti daha öngörülebilir tutar
Önemli Çıkarım
İki günlük hata ayıklama bir öğleden sonraya sıkıştı ve hatayla ilgili dersi öğrenmedim. Araçlarla ilgili dersi öğrendim. Yanlış düzeltmenin peşinden koşmamın nedeni, kullandığım araçların bana görmem gerekeni göstermemesiydi. Bir model çıktım ve bir araç çıktım vardı, ve bunları birlikte bakabileceğim ortak bir çerçeve yoktu. Ortak çerçeve tüm olayın anahtarıydı.
Birden fazla aracı yazdıysanız ve henüz Apidog'un Yapay Zeka Aracısı Hata Ayıklayıcısını açmadıysanız, göndereceğiniz bir sonraki aracı, model ile araç arasında yaşayan bir hataya sahip olacaktır. Bunun üzerinde bir hafta harcayacaksınız. Başarısız hipotezlerden oluşan bir Notion sayfası yazacaksınız. Hata, hata ayıklayıcının size ilk gün göstereceği yerde olacaktır.
Apidog'u indirin ve size kendinden emin bir sesle yanlış bir yanıt veren bir sonraki aracıda açın. On iki dakika. Kırk yedi milisaniye, kırk yedi saniye değil.
MCP taşıma kurulumu ve plan kullanılabilirliği dahil olmak üzere tüm özellik referansı, Apidog AI Agent Debugger: kullanılabilirlik, kapsam ve kurulum adresinde bulunmaktadır.