Daha Fazla Log Değil, Yürütme Ağaçları: Yapay Zeka Ajanları İçin Daha İyi Bir Hata Ayıklama Modeli

Zihinsel Zaman Çizelgesi İnşasının Ölçeklenememesi#

Geleneksel düz loglar (flat logs), sistemde art arda birkaç olayın gerçekleştiğini gösterebilir. Ancak çoğu zaman hangi işlemin bir sonrakine yol açtığını, hangi hatanın bir fallback mekanizmasını tetiklediğini ya da paralel araç çağrılarının tek bir planlama adımının alt parçası mı yoksa ilgisiz işler mi olduğunu açıklayamaz. Yapay zeka ajanlarında izlenen yol (path), ajanın sergilediği davranışın doğrudan bir parçasıdır.

Bu gereksinim doğrultusunda geliştirilen açık kaynaklı TypeScript aracı AgentInspect ([email protected]), ajan yürütmelerini yerel ortamda analiz etmek için yürütme ağaçlarını (execution trees) temel bir hata ayıklama modeli olarak sunar.

Ajan Akışını Zaman Çizgisi Olarak Okumanın Yarattığı Sorun#

Bir destek ajanının operasyonlarını ele aldığımızda tipik bir akış şöyle görünür:

09:00:00.000 planlama başladı
09:00:00.020 envanter isteği başladı
09:00:00.060 envanter isteği başarısız oldu: 503
09:00:00.061 envanter isteği yeniden başladı
09:00:00.120 envanter isteği başarılı
09:00:00.150 yanıt tamamlandı

Basit bir senaryoda bu akış zihinde canlandırılabilir; ancak bu yeniden inşa süreci tamamen geliştiricinin zihninde gerçekleşir. Sürece iç içe geçmiş ajanlar (nested agents), paralel çalışan araçlar, yinelenen işlem adları ve araya giren uygulama logları eklendiğinde zaman damgaları nedensellik ilişkisini (causality) kurmakta yetersiz kalır.

Yürütme ağacı (execution tree) ise bu hiyerarşik bağı açık hale getirir:

support-agent
- ├── plan
- ├── fetch-inventory (başarısız: 503)
- ├── fetch-inventory (başarılı)
- └── draft-answer

Bu ağaç yapısı ham log verisinin yerini almaz; geliştiricilerin bir hata anında sorduğu "Bu çalışma tam olarak hangi yolu izledi?" sorusuna hedeflenmiş bir izdüşüm sunar.

TypeScript ile Anlamlı Sınırları Yakalamak#

AgentInspect, tüm çerçeve içi operasyonları otomatik keşfetmek yerine geliştiricinin belirlediği anlamlı sınırları kayıt altına alır. inspectRun ve step fonksiyonlarıyla planlama, paralel araç çağrıları (Promise.all ile search-flights ve search-hotels) ve model katmanı açıkça gruplanır. Elde edilen izleme verisi yerel ortamda npx agent-inspect view travel-planner --dir .agent-inspect --summary komutuyla doğrudan görselleştirilebilir.

Farklı Hata Sınıflarını Açığa Çıkaran Yapılar#

1. İç içe geçmiş işler sahiplik hiyerarşisini gösterir: Üç seviyeli bir hiyerarşide (outer -> middle -> inner) girintiler yalnızca görsel bir detay değildir; inner işleminin middle'a, onun da outer'a ait olduğunu belgeler. Eğer inner çökerse, doğrudan hangi üst operasyonun sorumlu olduğu belirlenir. Düz loglarda bunu tespit etmek korelasyon ID'leri ve zaman damgası eşleştirmeleri gerektirir. Bu yaklaşım; bir ajanın diğerine görev devrettiği, bir aracın alt operasyonlar yürüttüğü ya da bir getirme (retrieval) adımının hem sorgu yeniden yazımı hem de vektör aramasını yönettiği senaryolarda kritik öneme sahiptir.

Pratik Geliştirici Çıkarımları#

Nedensellik Odaklı Hata Ayıklama: Çok adımlı ajan mimarilerinde sadece kronolojik olayları listelemek yetersizdir; hiyerarşik sahiplik ilişkileri netleştirilmelidir.
Yerel Gözlemlenebilirlik: Karmaşık bulut izleme araçlarına bağımlı kalmadan, yerel CLI tabanlı ağaç projeksiyonları ile geliştirme döngüsü hızlandırılabilir.

Bu konuyu derinlemesine öğrenmek isterseniz: Agent Monitoring ve Debugging modülüne göz atın.