LLM'ler kodunuza erişmez – size bir istek iletirler ve siz fonksiyonu çalıştırırsınız. Bu basit gerçek, "model sihirli bir şekilde Python rutinimi çağırıyor" mitini tersine çevirir ve geliştiricileri hata ayıklama (debugging) ve güvenlik konularını yeniden düşünmeye zorlar.

Adım adım dağıtım döngüsü (dispatch loop)

Bir büyük dil modeli (LLM) bir araca ihtiyaç duyduğunda deterministik bir dizi izler:

  1. Planlama – model bir eylemin gerekli olduğuna karar verir (örneğin, "bir ödemeyi iade et").
  2. İstek oluşturma – aracı isimlendiren ve argümanları sağlayan yapılandırılmış bir metin —genellikle JSON— çıktı olarak verir.
  3. Ayrıştırma (Parsing) – uygulamanız veya destekleyici bir framework bu metni okur.
  4. Eşleştirme – framework, ismi sizin dışarıya açtığınız gerçek fonksiyonlar sicilinde (registry) arar.
  5. Doğrulama – argümanların fonksiyon şemasıyla eşleşip eşleşmediğini ve çağırıcının yetkili olup olmadığını kontrol eder.
  6. Yürütme – eşleşen fonksiyon sizin ortamınızda çalışarak işi gerçekleştirir.
  7. Geri döndürme – sonuç paketlenir ve daha fazla muhakeme yapması için modele geri gönderilir.

LLM'yi bir planlayıcı, framework'ü bir dağıtıcı (dispatcher) ve fonksiyonu ise veriyi veya parayı fiilen hareket ettiren işçi olarak düşünün.

"Sihir" miti neden devam ediyor?

Çoğu geliştirici, model çıktısında bir fonksiyon çağrısına benzeyen tek bir satır görür ve işlemin kendisi tarafından gerçekleştirildiğini varsayar. Sağlayıcı dokümanlarındaki "tool calling" (araç çağırma) terimi, sanki model doğrudan kodu çağırıyormuş gibi bir izlenim verir.

Gerçekte model, yalnızca bir çağrıyı tanımlayan metin üretir. Ağır işi —arama, tip kontrolü, izin uygulama, hata yönetimi— sizin süreciniz yapar.

Tesisatı gizleyen framework'ler

PydanticAI ve LangChain gibi kütüphaneler, iş mantığına odaklanabilmeniz için döngüyü soyutlar. Bunlar otomatik olarak şunları yapar:

  • Argümanları bir şemaya (örneğin bir Pydantic modeli) göre doğrular.
  • İzinleri uygular, kullanıcının aracı tetikleyebileceğinden emin olur.
  • Hata durumunda tekrar dener, bir araç hata döndürdüğünde modele geri döner.
  • Kontrolsüz döngülere karşı korur, ardışık araç çağrılarını sınırlar.
  • Konuşma durumunu korur, araç sonuçlarını diyaloğa dahil eder.

Bu yardımcılarla bile desen aynı kalır: model asla kod yürütmez.

Sağlayıcılardan gelen yerel (native) araç çağırma desteği

Bazı sağlayıcılar, araç tanımlarını ve istek formatlarını standartlaştıran "yerel" bir araç çağırma arayüzü sunar. Bu, entegrasyonu kolaylaştırır ancak dağıtım (dispatch) adımını ortadan kaldırmaz. İstenen işlemi fiilen çalıştıran kodu hala siz yazarsınız (veya içe aktarırsınız).

Sorunu yeniden adlandırdığınızda hata ayıklama kolaylaşır

"Kafası karışmış bir ajan" suçlamak yerine, sorunun "model yanıtının hiçbir araç çağrısı içermediği" olduğunu söyleyin. Bu ayrım önemlidir:

  • Araç çağrısı yok – model doğrudan yanıt verdi veya doğru formatlanmış bir istek oluşturamadı.
  • Hatalı istek – JSON sözdizimsel olarak yanlış veya gerekli alanlar eksik, bu nedenle dağıtıcı (dispatcher) isteği reddeder.
  • Doğrulama hatası – argümanlar şema ile eşleşmiyor ve yürütme öncesinde bir hata tetikliyor.

Hataları kategorize etmek, döngünün her aşamasını günlüğe kaydetmenize ve işlerin nerede rayından çıktığını tam olarak belirlemenize olanak tanır.

Güvenilir bir boru hattı (pipeline) için pratik ipuçları

  • Model çıktısını güvenilmeyen girdi olarak kabul edin. Yan etkisi olan herhangi bir kodu çağırmadan önce her isteği deterministik bir doğrulamadan geçirin.
  • Ham isteği ve her doğrulama adımının sonucunu günlüğe kaydedin. Bu, bir şeyler ters gittiğinde yeniden oynatılabilir bir iz oluşturur.
  • Ardışık araç çağrıları için açık sınırlar belirleyin; kontrolsüz bir döngü kaynakları tüketebilir veya hız sınırlarına (rate limits) takılabilir.
  • Her fonksiyonu, modelin anlayabileceği yapılandırılmış bir hata nesnesi döndüren ve bir yeniden denemeyi veya zarif bir geri dönüşü (fallback) tetikleyen bir try/except bloğu içine alın.
  • İzin kontrollerini iş mantığından ayırın. Fonksiyon çalışmadan önce, özellikle "kullanıcıyı sil" gibi ayrıcalıklı işlemler için çağırıcının haklarını doğrulayın.
  • Şema güdümlü tanımlar (örneğin Pydantic modelleri) kullanın, böylece framework modelin uyması gereken JSON şemasını otomatik olarak oluşturabilir.

Sırada ne var?

Sağlayıcılar yerel araç çağırma API'lerini geliştirdikçe, istek formatları etrafında daha sıkı sözleşmeler ve daha zengin hata kodları bekleyin. Bu değişiklikler doğrulamayı kolaylaştıracak ve geliştiricilerin daha sıkı güvenlik bariyerleri oluşturmasına olanak tanıyacaktır. Kütüphane güncellemelerini takip edin; birçoğu en yeni sağlayıcı özelliklerine yerleşik destek ekliyor.

Özet

LLM gelişmiş bir metin oluşturucudur, bir yürütücü değildir. Eylemleri gerçekleştiren tek yetkili kodunuzdur; oluşturduğunuz (veya içe aktardığınız) dispatcher ise bu eylemleri doğrulayan, yetkilendiren ve çalıştıran bir denetleyicidir. İş akışını yeniden çerçevelemek, "sihir" mitini ortadan kaldırır, hata ayıklama sürecini keskinleştirir ve her üretim sisteminin ihtiyaç duyduğu güvenlik disiplinini sağlar.