AI Agent'lar için Observability: Bir AI Agent'ı Nasıl Debug Edersiniz?

Bir REST endpoint'inde hata genelde tekrarlanabilir: aynı istek, aynı 500 hatası. Ajanlarda üç fark var. Birincisi non-determinizm: aynı prompt farklı araç sırası üretebilir. İkincisi hatanın biçimi: ajan çoğu zaman çökmez, yanlış bir araç seçer, eksik parametre gönderir ya da araçtan dönen hatayı görmezden gelip uydurma bir sonuçla devam eder. Üçüncüsü uzunluk: tek bir kullanıcı isteği 20-30 model ve araç çağrısına yayılabilir.

Tipik senaryo: kullanıcı 'geçen ayki faturamı gönder' diyor, ajan doğru müşteriyi bulamayınca en yakın isimli müşterinin faturasını gönderiyor. Log'larda hata yok, HTTP 200'ler var. Bu hatayı görmenin tek yolu, ajanın hangi aramayı yaptığını, aramanın ne döndürdüğünü ve modelin bu sonuçtan hangi kararı çıkardığını sıralı ve iç içe görebilmek. Aynı isteği yeniden göndermek farklı bir yol üretebileceği için ilk çalışmanın kaydı çoğu zaman tek kanıttır.

Son on iki ayda ajan gözlemlenebilirliği deneysel bir ekten temel bir gereksinime dönüştü. LangChain'in Haziran 2026'da yayımladığı State of Agent Engineering anketine (1.340 katılımcı) göre ekiplerin yüzde 57,3'ünün üretimde ajanı var; yüzde 89'u bir tür observability kullanıyor, yüzde 62'si tek tek adımları ve tool call'ları gösteren ayrıntılı tracing'e sahip. Eval tarafı geride: çevrimdışı eval yapanlar yüzde 52,4, çevrimiçi eval yapanlar yüzde 37,3. En büyük engel yüzde 32 ile kalite.

Standart tarafında OpenTelemetry, 12 Haziran 2026'daki v1.42.0 ile tüm `gen_ai.*` içeriğini çekirdek semantic conventions reposundan çıkarıp ayrı `semantic-conventions-genai` reposuna taşıdı. Yeni repoda henüz etiketli sürüm yok ve GenAI alanlarının hiçbiri Stable değil. Nisan 2026'daki v1.41.0 `invoke_agent` span'ini client ve internal olarak ikiye ayırdı. MCP'nin 28 Temmuz 2026 spesifikasyonu da trace bağlamını (`traceparent`, `tracestate`) istek meta verisinde taşıma kuralını belgeledi ve Logging özelliğini OpenTelemetry lehine deprecated ilan etti. Anthropic'in Ocak 2026 tarihli eval rehberi, gerçek hatalardan türetilmiş 20-50 görevle başlamayı öneriyor.

Ajan gözlemlenebilirliğinin temel birimi trace (iz) ve onun içindeki span'ler (zaman aralıkları). Tipik bir ajan trace'i şöyle iç içe geçer: en dışta ajan çağrısını temsil eden bir span, altında her model çağrısı için bir span, model bir araç çağırmaya karar verdiğinde de o aracın çalışmasını temsil eden ayrı bir span. Araç başka bir servise HTTP isteği atıyorsa, o istek de aynı trace'e bağlı alt span olur.

OpenTelemetry GenAI konvansiyonlarında bu yapı `gen_ai.operation.name` değerleriyle ifade ediliyor: ajan için `invoke_agent`, model çağrısı için `chat`, araç için `execute_tool`. Span adları da buna göre kuruluyor; ör. `execute_tool search_invoices`. Bu yapı kurulduğunda fatura örneğindeki hata görünür hale gelir: `search_customers` span'i iki sonuç döndürmüş, sonraki `chat` span'i ikinciyi seçmiş. Debug, 'model neden ikinciyi seçti?' sorusuna daralır.

OpenTelemetry'nin GenAI semantic conventions'ı (anlamsal konvansiyonlar), model ve ajan telemetrisini hangi attribute adlarıyla kaydedeceğimizi standartlaştırıyor. Öne çıkan alanlar: `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.usage.input_tokens` ve `gen_ai.usage.output_tokens`, `gen_ai.conversation.id`, ajan için `gen_ai.agent.name`, araç için `gen_ai.tool.name` ve `gen_ai.tool.call.id`. Metrik tarafında `gen_ai.client.token.usage` ve `gen_ai.client.operation.duration` gibi histogramlar tanımlı.

Olgunluk konusunda dürüst olmak gerekiyor: konvansiyonlar hâlâ 'Development' statüsünde, yani attribute adları sürümler arasında değişebilir. Haziran 2026'da (v1.42.0) GenAI ve MCP konvansiyonları ayrı bir `semantic-conventions-genai` reposuna taşındı; yeni repoda henüz etiketli sürüm ve kesinleşmiş bir schema URL yok. Nisan 2026'daki v1.41.0'da `invoke_agent` span'i client ve internal olarak ikiye ayrıldı; bu da adların hâlâ oynadığını gösteriyor. Pratik sonuç: enstrümantasyon kütüphanesini sabitleyin, dashboard sorgularını attribute adlarına doğrudan gömmek yerine bir görünüm katmanından geçirin ve yükseltmeleri changelog okuyarak yapın.

Bir başka güncel bağlantı noktası MCP (Model Context Protocol). MCP spesifikasyonunun 28 Temmuz 2026'da yayımlanan revizyonu, trace bağlamının (`traceparent`, `tracestate`) istek meta verisinde nasıl taşınacağını belgeliyor. Bu sayede ajanınızın çağırdığı bir MCP sunucusundaki işlem de aynı trace'in parçası olarak görünebilir; ajan ile araç sunucusu arasındaki kör nokta kapanır.

Bir ajanı debug ederken en çok işe yarayan veri, modele giden mesajlar ve modelden dönen yanıt. Ama bu veri kişisel bilgi, müşteri verisi ve gizli iş bilgisi içerir. GenAI konvansiyonları bu yüzden içeriği varsayılan olarak span attribute'u yapmıyor; `gen_ai.input.messages` ve `gen_ai.output.messages` gibi alanlar ayrı bir event üzerinden ve açıkça etkinleştirilerek (opt-in) yakalanıyor. Kütüphanelerin çoğu bunu bir ortam değişkeniyle açıp kapatıyor; değer adları kütüphaneye göre değişiyor.

Makul bir politika: geliştirme ve staging'de içerik tam açık; üretimde içerik kapalı, yalnızca token sayıları, araç adları, hata tipleri ve süreler açık; şikâyet veya incelemeye düşen konuşmalarda örnekleme ile içerik kaydı, maskeleme filtresinden geçerek. Anti-pattern: tüm prompt'ları 90 gün boyunca maskesiz bir gözlem aracına göndermek ve KVKK incelemesinde bunu ilk kez fark etmek.

Ajan gözlemlenebilirliği yalnızca hata ayıklama değil, aynı zamanda finans. Her `chat` span'inde input ve output token sayısı varsa, trace bazında maliyet hesaplanabilir; trace'leri kullanıcıya, müşteriye veya özelliğe göre gruplayınca 'hangi özellik bize ayda ne kadara mal oluyor' sorusu cevaplanır.

İzlenmesi gereken birkaç gösterge: istek başına model çağrısı sayısı (p50 ve p95), istek başına araç çağrısı sayısı, ilk token'a kadar geçen süre ve toplam süre. Eşik örneği: p50'de 4 araç çağrısı yapan bir ajan bir sürümden sonra p95'te 18'e çıkıyorsa, büyük ihtimalle bir döngüye giriyor ya da bir aracın hata mesajını anlamıyor. Bu tür bir sapmayı alarma bağlamak, faturada sürpriz görmekten iyidir. Ayrıca araç başına maksimum çağrı sayısı ve istek başına token bütçesi gibi sert limitleri kodda tutun; gözlem limiti uygulamaz, yalnızca ihlali gösterir.

Trace size ajanın ne yaptığını gösterir; iyi yapıp yapmadığını eval (değerlendirme) söyler. İki katman var. Çevrimdışı eval: sabit bir veri setinde (Anthropic'in Ocak 2026 rehberi gerçek hatalardan türetilmiş 20-50 görevle başlamayı öneriyor) her prompt veya model değişikliğinden önce ajanı çalıştırıp skorlamak. Çevrimiçi eval: üretim trace'lerinden örneklem alıp otomatik değerlendiricilerle (kural tabanlı kontroller veya LLM-as-judge) puanlamak.

Ajanlar için yalnızca son cevabı puanlamak yetmez; yol da puanlanmalı. Doğru aracı seçti mi, gereksiz çağrı yaptı mı, araç hatasını fark etti mi? Fatura örneğinde iyi bir eval vakası şöyledir: 'iki benzer isimli müşteri varsa ajan kullanıcıya hangisi olduğunu sormalı'. Pratik döngü: üretimde kötü giden trace'i bul, onu eval setine vaka olarak ekle, düzeltmeyi yap, setin tamamında regresyon olmadığını gör. Langfuse, Arize Phoenix gibi araçlar bu döngüyü trace verisiyle birleştiriyor. Konvansiyonlardaki `gen_ai.evaluation.result` event'i (v1.38.0, Ekim 2025) eval skorunu ilgili span'e bağlamayı da standartlaştırıyor.