Yapay Zeka Ajanı Araç Çağrısı İzleme: Her İstekte Neler Kaydedilmeli?

Bir kullanıcı, aracının dün öğleden sonra “garip bir şey yaptığını” bildiriyor. Logları açtığınızda şunları görüyorsunuz:

INFO  agent run started
INFO  calling tool: updateOrder
INFO  tool returned 200
INFO  agent run completed

Araç updateOrder çağırmış; ancak hangi argümanlarla, hangi sipariş için, neden bu aracı seçtiği veya ne döndüğü belli değil. Tüm ölçümlere göre çalıştırma başarılı ve alınan tek bir karar bile yeniden yapılandırılamıyor.

Apidog'u bugün deneyin

Araç sistemleri genellikle sonradan anlamlı görünen şekillerde başarısız olur. Bu nedenle log, yalnızca operasyonel bir çıktı değil, hata ayıklama için nihai üründür.

Bu kılavuzda:

• Her araç çağrısında nelerin kaydedileceğini
• Model kararının ürettiği HTTP isteğiyle nasıl ilişkilendirileceğini
• Hassas verilerin nasıl redakte edileceğini
• İzlerin test senaryolarına nasıl dönüştürüleceğini
• Hangi metriklerin izleneceğini

ele alacağız.

API gözlemlenebilirliği hizmet tarafını kapsar. Bu yazı ise onun üzerinde çalışan araç katmanına odaklanır.

Bir izleme verisine sahip olduğunuzda Apidog özellikle yararlıdır: başarısız bir çağrıyı aynı uç noktaya karşı yeniden oynatabilir ve sonucu doğrudan inceleyebilirsiniz.

Üç katman, tek bir iz

Bir araç üç seviyede olay üretir:

1. Mantık katmanı: Modelin bağlamı, mevcut araçları, seçtiği aracı ve ürettiği argümanları içerir.
2. Araç katmanı: Argümanları doğrular, politikayı uygular, HTTP çağrısını başlatır ve sonucu işler.
3. HTTP katmanı: Metot, URL, başlıklar, gövde, durum kodu ve gecikme gibi kablo üzerindeki ayrıntıları içerir.

Hata ayıklama çoğunlukla bu katmanları aşar. Örneğin:

• “Araç yanlış müşteri kimliği gönderdi” HTTP katmanında görünen bir mantık problemidir.
• “API boş gövdeyle 200 döndürdü” ise birkaç adım sonra mantık hatası olarak ortaya çıkan bir HTTP problemidir.

Katmanlar ortak bir kimlik ile bağlanmazsa zaman damgalarına göre ilişkilendirme yapmak zorunda kalırsınız. İki çalıştırma çakıştığında bu yaklaşım güvenilir değildir.

Bu nedenle temel kural şudur:

• Her çalıştırma için bir trace ID
• Her araç çağrısı için bir span ID
• Her iki kimliğin her katmandaki tüm kayıtlarda bulunması

OpenTelemetry izleri bu modeli zaten destekler. Alan adlarını taşınabilir tutmak için GenAI semantik konvansiyonlarından yararlanabilirsiniz.

Her araç çağrısında neleri kaydetmeli?

Kullanışlı bir kayıt, şu soruları yanıtlamalıdır:

{
  "trace_id": "run_01J8ZK3M2Q",
  "span_id": "call_004",
  "parent_span_id": "call_003",
  "timestamp": "2026-08-26T14:03:11.482Z",
  "agent": "billing",
  "step": 4,

  "tool_name": "refundOrder",
  "tool_args": {
    "orderId": "ord_92",
    "amount": 1200,
    "reason": "duplicate"
  },
  "tools_available": [
    "getOrder",
    "listOrders",
    "refundOrder",
    "voidInvoice"
  ],

  "http": {
    "method": "POST",
    "url": "/v1/orders/ord_92/refund",
    "request_body_hash": "sha256:1f4c...",
    "status": 200,
    "duration_ms": 412,
    "retry_count": 1,
    "idempotency_key": "9f2b7c14-6d3a-4b18"
  },

  "outcome": "success",
  "tokens": {
    "prompt": 8420,
    "completion": 96
  },
  "policy": {
    "approval_required": true,
    "approved_by": "user_31",
    "dry_run": false
  }
}

En kritik alanlar

• tool_args: En sık eksik bırakılan, ancak en çok ihtiyaç duyulan alandır. Modelin ürettiği argümanları yürütücünüz normalleştirmeden önce kaydedin. Yanlış kimlik çoğu zaman burada görünür.
• tools_available: Modelin neden belirli bir aracı seçtiğini anlamanızı sağlar. Garip bir seçimde ilk sorunuz, “Başka hangi seçenekler vardı?” olur.
• retry_count: Yavaş bir API ile iki kez başarısız olup üçüncü denemede başarılı olan API çağrısını ayırır.
• outcome: Durum kodundan türetilen belirsiz bir alan değil, açık bir enum olmalıdır:
  • success
  • failed
  • timed_out
  • blocked_by_policy
  • rejected_by_human

Son iki değer özellikle önemlidir. Politika tarafından engellenen veya insan tarafından reddedilen çağrı, sistem hatası değil, çalışan bir koruyucudur. Bunları başarısızlıklarla karıştırmak hata oranlarını bozar.

• policy: Denetim kaydınızdır. Yıkıcı bir eylemin onaylanıp onaylanmadığı sorulduğunda yanıt burada bulunur. Uygulama ayrıntıları için yapay zeka aracı koruyucuları hakkındaki kılavuza bakabilirsiniz.

Sadece eylemi değil, kararı da kaydedin

En zor araç hataları çağrının kendisinden değil, seçimden kaynaklanır. Bu yüzden modeli yeniden yapılandırmaya yetecek bilgiyi saklayın.

Araç tanımlarını ve özetini saklayın

Çalıştırmada kullanılan araç tanımlarını veya bunların hash değerini kaydedin. Seçim doğruluğu değiştiğinde ilk şüphelilerden biri düzenlenmiş bir açıklamadır.

Hash, iyi ve kötü çalıştırmalar arasında araç setinin değişip değişmediğini hızlıca gösterir. Araç açıklamalarının davranışı neden etkilediği, aracılar için API araç şemaları tasarlama yazısında ele alınıyor.

Model yapılandırmasını kaydedin

Çalıştırma kaydında en az şunlar bulunmalıdır:

• Model kimliği
• Sıcaklık
• İstem sürümü
• Araç seti özeti

Model sürümleri arasındaki davranış değişikliklerini bu alanlar olmadan ayırmak oldukça zordur.

Bağlam boyutunu kaydedin

Tam istem dökümü pahalı olabilir ve hassas bilgiler içerebilir. Bunun yerine çoğu teşhis için şunlar yeterlidir:

• İstem token sayısı
• İstem hash’i
• Yanıt token sayısı
• İstem ve yanıt boyutları

Normalden iki kat büyük bir istem, bağlama beklenmedik bir şey eklendiğine işaret edebilir.

Ham araç sonucunu kırpmadan saklayın

Yürütücünüz yanıtı modele vermeden önce küçültüyorsa, ham yanıtı izleme verisinde koruyun. Araç yanıtlarını bağlam penceresinden uzak tutma yaklaşımını kullanırken bu ayrım kritiktir.

Aksi halde verinin API tarafından mı eksik döndüğünü, yoksa sizin mi kırptığınızı anlayamazsınız.

Depolamadan önce redakte edin

Araç izleri hem isteği hem de karar bağlamını içerir. İstemler kişisel veri barındırabildiği için bu kayıtlar olağan loglardan daha hassastır.

Dört temel kural

1. Kimlik bilgilerini saklamayın.
   
   Authorization başlıklarını, API anahtarlarını, çerezleri ve imzalı URL’leri çıkarın. Değer yerine anahtar kimliği gibi güvenli bir tanımlayıcı saklayın. Aracılar için en az ayrıcalıklı API anahtarları bu yaklaşımın nedenlerini açıklar.

2. Redaksiyonu sınırda yapın.
   
   Okuma sırasında filtrelemek, sırrın önce diske yazılması, çoğaltılması ve yedeklenmesi anlamına gelebilir. Redaksiyonu loglama ara katmanında, kayıt sistemiyle buluşmadan önce uygulayın.

3. Saklayamadığınız gövdeleri hash’leyin.
   
   İstek gövdesi hash’i, yükü saklamadan iki çağrının aynı olduğunu kanıtlamanızı sağlar. Bu, çift kayıt araştırmaları için çoğu zaman yeterlidir.

4. Saklama süresini hassasiyete göre katmanlandırın.
   
   Örneğin:

   • Tam izler: birkaç gün veya bir hafta
   • Redakte edilmiş özetler: birkaç ay veya bir yıl

Çoğu hata birkaç gün içinde incelenir; denetim soruları ise daha sonra ortaya çıkabilir.

İzleri testlere dönüştürün

İyi izleme yalnızca hata ayıklamayı hızlandırmaz; gerçekçi test senaryoları da üretir.

Her başarısız çalıştırma bir test adayıdır:

1. Başarısız izden araç çağrılarını çıkarın.
2. Çağrıları API’nize karşı yeniden oynatın.
3. Sorunu yeniden üretin.
4. Düzeltmeden sonra aynı akışı regresyon testi olarak saklayın.

Apidog, başarısız isteği kaydedilmiş bir durum olarak yeniden oluşturmanıza, düzeltilmiş davranışı doğrulamanıza ve testi CI sürecine eklemenize yardımcı olur.

İzler ayrıca hangi uç noktalar için taklit API oluşturmanız gerektiğini gösterir. Aracınızın en sık çağırdığı uç noktaları ve gerçek hayatta karşılaştığı hata durumlarını doğrudan üretim verilerinden çıkarabilirsiniz. Ardından üretim yerine taklit API’lere karşı aracı çalıştırma yaklaşımını uygulayın.

Üretim davranışındaki yavaş kaymayı görmek için şu metrikleri haftalık izleyin:

• Araç seçim dağılımı
• Uç nokta başına yeniden deneme oranı
• Tamamlanan görev başına araç çağrısı
• Politika tarafından engellenen çalıştırmaların oranı

Bu değerlerdeki değişimler olay gerçekleşmeden önce sinyal verir. API sözleşme testi, bu değişimlere neden olan üst seviye API değişikliklerini yakalayabilir.

İzlemenin yanıtlaması gereken üç soru

“Araç yanlış müşteriyi ücretlendirdi.”

Şunlara ihtiyacınız vardır:

• Modelin ürettiği argümanlar
• Çözülen URL
• Önceki araç sonucu
• Önceki adım
• Belirsizlik ve seçim bilgisi

Çoğu vakada yanlış kimlik, birden fazla eşleşme döndüren önceki araç sonucundan gelir ve model ilk sonucu seçer. tool_args kaydedilmemişse elinizde yalnızca bir 200 ve mutsuz bir müşteri kalır.

“Salı günü çalışmayı durdurdu.”

İyi ve kötü çalıştırmaları alan bazında karşılaştırın:

• Model kimliği
• Araç seti hash’i
• İstem sürümü
• Ortalama yanıt boyutu

Genellikle değişikliklerden biri bu dört alandan birinde görünür. Çalıştırma kaydı yalnızca olayları değil, yapılandırmayı da taşımalıdır; diff ancak iki taraf aynı alanlara sahipse mümkündür.

“Bunu kim onayladı?”

Politika bloğu bu sorunun doğrudan yanıtıdır. Karar anında yazılmalıdır:

• approval_required
• approved_by
• Onay zaman damgası
• dry_run

Böylece gerilimli bir araştırma, tek bir log sorgusuna dönüşür.

Örnekleme: Neleri asla atmayın?

Her çalıştırmayı tam doğrulukla saklamak pahalı olabilir. Ancak araç trafiği tekdüze değildir; bu nedenle örneklemeyi sinyale göre yapın.

Her zaman saklayın:

• Başarısız çalıştırmaları
• Politika tarafından engellenen çalıştırmaları
• Yazma işlemi içeren çalıştırmaları

Başarılı, salt okunur çalıştırmaları örnekleyebilirsiniz. Bunlar hacmin çoğunu oluşturur ve tek tek daha az ilgi çekicidir; yine de temel çizgileri hesaplamak için yeterli sayıda örnek tutun.

Bu yaklaşım, Google SRE kitabının izleme bölümündeki “hacim yerine sinyal için örnekleme” mantığıyla uyumludur.

Yükleri attığınızda bile şu iskelet kaydı koruyun:

• Araç adı
• Sonuç
• Süre
• Durum
• Yeniden deneme sayısı
• Politika sonucu

Pahalı kısımlar genellikle gövdeler ve istem dökümleridir; ilk önce bunları özetleyin veya atın.

Kuyruk örneklemesine dikkat edin. Saklama kararını çalıştırma tamamlandıktan sonra verin. Üçüncü adımda başarılı görünen, ancak dokuzuncu adımda başarısız olan çalıştırma tamamen saklanmalıdır. Bu da veriyi ilerlerken atmak yerine arabelleğe almayı gerektirir.

İzler nerede yaşamalı?

Aracınız kendi API’lerinizi çağıran bir hizmetse merkezi depolama mantıklıdır. Ancak araçlar geliştirici makinelerinde veya yerel çalışma ortamlarında çalışıyorsa izler terminalde kalabilir.

Sharkly farklı bir yaklaşım benimser: çalıştırma izi, aracının atandığı Göreve eklenir. Çalıştırma geçmişi, loglar ve sonuç; hedef, durum ve insan inceleme yorumlarıyla aynı yerde bulunur.

Pratik faydası basittir: “Araç bunu neden yaptı?” sorusunu yanıtlamak için makineyi, oturumu ve geri kaydırma geçmişini aramak yerine Görevi açarsınız.

Bu yaklaşım çalışma zamanını değiştirmez; Claude Code ve Codex yine işi yürütür. Yalnızca araç bağımsız bir hizmet olarak çalışmadığında kaydın nereye gittiğini değiştirir.

Kontrol panelinde dört metrik

İzler yalnızca biri onlara baktığında değerlidir. Aşağıdaki dört metriği kontrol paneline ekleyin.

Tamamlanan görev başına çağrı sayısı

En net verimlilik ölçüsüdür. Artış genellikle aracın daha fazla keşif yaptığına, açıklamaların kötüleştiğine veya bir uç noktanın başarısız olmaya başladığına işaret eder.

Uç noktaya göre yeniden deneme oranı

En güvenilmez bağımlılıkları sıralar ve bir uç noktanın ne zaman kötüleştiğini gösterir. Aracı hata kurtarma kılavuzu, listenin başındaki sorunlarla nasıl çalışılacağını açıklar.

Politika tarafından engellenen oran

Bu oran düşük ve istikrarlı olmalıdır. Artış iki anlama gelebilir:

• Araç yapmaması gereken eylemleri deniyor.
• Politika fazla katı ve darboğaz oluşturuyor.

İlk araç çağrısına kadar geçen süre

Yavaş başlangıç çoğu zaman büyümüş bir isteme işaret eder. İstem boyutu, kimse bilinçli olarak artırmadan büyüyebilen bir maliyettir.

Uygulama kontrol listesi

• [ ] Her çalıştırma için trace ID, her araç çağrısı için span ID var.
• [ ] Kimlikler mantık, araç ve HTTP katmanlarında damgalanıyor.
• [ ] Model argümanları normalleştirilmeden önce kaydediliyor.
• [ ] Mevcut araç listesi her çağrıda tutuluyor.
• [ ] Sonuç, politika blokları dahil açık bir enum olarak kaydediliyor.
• [ ] Yeniden deneme sayısı çağrı sayısından ayrı tutuluyor.
• [ ] Model, sıcaklık, istem sürümü ve araç seti hash’i çalıştırma kaydında bulunuyor.
• [ ] Ham araç sonucu, modele verilen kırpılmış sürümden ayrı saklanıyor.
• [ ] Kimlik bilgileri ara katmanda çıkarılıyor.
• [ ] Saklanamayan gövdeler hash’leniyor.
• [ ] Saklama süresi hassasiyete göre katmanlandırılıyor.
• [ ] Başarısız izler yeniden oynatılabilir test durumlarına dönüştürülebiliyor.

Hedef basit: biri aracınızın neden böyle davrandığını sorduğunda tahminle değil, kayıtlarla yanıt verebilmek.

Apidog'u indirin, izlerdeki çağrıları yeniden oynatın ve başarılı çoğaltmaları test olarak saklayın.

Sıkça sorulan sorular

OpenTelemetry mi, amaca özel bir araç gözlemlenebilirlik platformu mu?

İlişkilendirmeyi ve izleme modelini taşınabilir tuttuğu için OpenTelemetry ile başlayın. Araca özel platformlar faydalı görünümler ekleyebilir; ancak alttaki veriler OpenTelemetry ile uyumlu kalmalıdır.

Tam izlemenin depolama maliyeti ne kadar?

Katmanlandırıldığında beklenenden düşüktür. Birkaç gün boyunca tam yükleri, daha uzun süreler boyunca ise gövdesiz yapılandırılmış kayıtları saklayabilirsiniz.

İstem dökümleri genellikle en pahalı kısımdır. Varsayılan olarak tam metin yerine boyut ve hash saklayın.

Modelin muhakeme metnini kaydetmeli miyim?

Genellikle hayır. Seçilen araç, üretilen argümanlar ve mevcut seçenekler çoğu kararı açıklamak için yeterlidir.

Bir sağlayıcı muhakeme içeriğini sunuyorsa bunu yalnızca başarısız çalıştırmalar için saklamayı değerlendirin ve hassas veri olarak ele alın.

Birden fazla araç arasında nasıl izleme yaparım?

Tüm görev için tek bir trace ID kullanın. Her araca kendi span’ını verin ve araçlar arasındaki geçişi ayrı bir olay olarak kaydedin.

Bu olayda hangi aracın devrettiğini, hangisinin devraldığını, hangi bağlamın aktarıldığını ve neden geçiş yapıldığını tutun. Ayrıntılar için çoklu aracı el değiştirmesi kılavuzuna bakabilirsiniz.

Araç bir müşterinin makinesinde çalışıyorsa ne olur?

Yerel olarak loglayın, hassas verileri agresif biçimde redakte edin ve kullanıcı onay verene kadar yalnızca toplu metrikleri gönderin.

Araç adları, sonuçlar ve süreler; cihazdan herhangi bir yük çıkarmadan filo düzeyinde izleme için çoğu zaman yeterlidir.

İstek gövdesi hash’i gerçekten faydalı mı?

Evet. İki çağrının aynı olduğunu kanıtlar ve çoğu çift yazma araştırmasını yükü saklamadan çözmenizi sağlar.

Hash’i, çifti önlemesi gereken idempotency anahtarları ile birlikte kullanın.