Araç çağırma ve ajan döngüsü

Kargo asistanına "Son faturamı göster" dedin ve fatura ekrana geldi. Faturayı model getirmedi. Arkada araç çağırma (tool calling) düzeni çalıştı.

Uygulama isteğe araçların listesini ekler. Her aracın adı, ne işe yaradığı ve hangi argümanları aldığı bir şemayla anlatılır. Şema her alanın tipini, zorunlu olup olmadığını ve sayı aralığını da tanımlar.

Model soruyu okur, uygun aracı seçer ve argümanları doldurur. Ürettiği şey yine metindir: araç adı ve argümanlardan oluşan yapılandırılmış bir istek. Bu derste çağrının yolunu uçtan uca izler, yetkinin hangi satırda durduğunu bulursun.

Araç tanımı üç alandan oluşur: ad, açıklama ve parametre şeması. Aşağıdaki tanım fatura getiren bir aracı anlatır. Model bu metni isteğin bir parçası olarak okur, tıpkı sistem promptu gibi. Araç tanımları bu yüzden bağlam penceresinden pay alır.

Anthropic belgesine göre araç kullanımı açıkken API isteğe ayrıca birkaç yüz jetonluk bir sistem metni ekler. Çok sayıda araç tanımlayan uygulama, her istekte bu bedeli öder. Açıklama metni aynı zamanda bir saldırı yüzeyidir. Araç tanımı güvenilmeyen bir kaynaktan geliyorsa, açıklamaya gizlenmiş bir talimat modeli yönlendirebilir.

{
  "name": "fatura_getir",
  "description": "Müşteri numarasına göre son faturayı döner",
  "parameters": {
    "type": "object",
    "properties": {
      "musteri_no": { "type": "string" },
      "ay": { "type": "integer", "minimum": 1, "maximum": 12 }
    },
    "required": ["musteri_no"]
  }
}

Şemayı satır satır oku. name alanı aracın adıdır, model çağrıda bu adı yazar. description modele aracın ne işe yaradığını anlatır, model aracı seçerken en çok buna bakar. parameters alanı JSON Schema biçimindedir.

musteri_no metin, ay ise 1 ile 12 arasında tam sayıdır. required listesi zorunlu alanları sayar, ay bu yüzden isteğe bağlıdır. Şema modele bir sözleşme sunar. Sözleşmeye uyulup uyulmadığını denetleyen ise yine senin kodundur.

Şemadan sonra çağrının yolu gelir. OpenAI belgesi akışı beş adımda anlatır. Uygulama isteği araç listesiyle gönderir.

Model bir araç çağrısı döndürür. Uygulama kodu kendi tarafında çalıştırır. Sonucu ikinci istekle modele verir.

Model son yanıtı yazar ya da yeni bir araç ister. Claude belgesi de aynı ayrımı yapar: senin tanımladığın aracı senin uygulaman çalıştırır. Claude çağrı önerdiğinde yanıtın durma nedeni tool_use olur. Modelin isteğini okuyup fonksiyonu çağıran koda çalıştırıcı (runner) denir.

// Modelin yanıtındaki blok (stop_reason: "tool_use")
{
  "type": "tool_use",
  "id": "toolu_01A",
  "name": "fatura_getir",
  "input": { "musteri_no": "M-20817", "ay": 9 }
}

// Uygulamanın bir sonraki istekte gönderdiği sonuç
{
  "type": "tool_result",
  "tool_use_id": "toolu_01A",
  "content": "Eylül faturası: 412,50 TL, son ödeme 15 Ekim"
}

Blokları satır satır oku. tool_use bloğu modelin önerisidir: hangi aracı, hangi girdiyle istediğini söyler. id alanı bu çağrıyı tanımlar.

Uygulama aracı çalıştırır ve sonucu tool_result bloğuyla geri yollar. tool_use_id alanı sonucu doğru çağrıya bağlar. Sonucun metni bir sonraki turda bağlamın parçası olur.

OpenAI'da call_id aynı işi görür, argümanlar da JSON metni olarak gelir. Dikkat et: bu JSON'da hiçbir şey çalışmadı. Model yalnız yapılandırılmış bir metin yazdı. Çalıştıran, onaylayan ve sonucu seçen senin uygulamandır.

Bu ayrım dersin kalbidir. Modelin çıktısı bir istektir, emir değildir. Çalıştırıcı isteği sorgusuz uygularsa yetki fiilen modele geçer. Modeli yönlendiren her metin de o yetkiye ortak olur: kullanıcı mesajı, RAG parçası, araç sonucu.

Çalıştırıcı isteği doğrularsa yetki kodda kalır. OWASP LLM06:2025 bu yüzden izin kararını modele bırakmaz, alt sistemde verilmesini ister. OWASP aşırı yetkinin üç kökünü sayar: gereğinden fazla işlev, gereğinden fazla izin ve gereğinden fazla özerklik. Yalnız özet çıkarması gereken bir e-posta asistanı ileti de gönderebiliyorsa, ilk kök oradadır.

Argüman üretimi ayrı bir risk taşır. Model argümanı konuşmadaki metinden türetir. Kullanıcı "M-10442 numaralı müşterinin faturası" derse model musteri_no alanına bu numarayı yazar.

Kod numarayı oturumdaki kullanıcıyla karşılaştırmazsa başka müşterinin faturası döner. Buna yatay yetki aşımı denir, web güvenliğindeki güvensiz doğrudan nesne başvurusunun (IDOR) ajan dünyasındaki karşılığıdır. Cümleyi kullanıcının yazması da gerekmez, zehirli bir belge de aynı isteği taşır.

Model eksik argümanı tahminle de doldurabilir. Claude belgesi, zorunlu alan eksik kaldığında modelin makul bir değer uydurabileceğini açıkça yazar.

# Zayıf
sonuc = ARACLAR[ad](**arg)

# Sağlam
if ad not in oturum.izinli_araclar:
    raise Yetkisiz(ad)
arg = sema_dogrula(ad, arg)              # tip, aralık, fazla alan
arg["musteri_no"] = oturum.musteri_no    # modelden değil oturumdan
sonuc = ARACLAR[ad](**arg)

Sağlam sürümde üç kontrol var. İzin listesi, oturumun hangi araçları çağırabileceğini söyler. Şema doğrulaması yanlış tipi, aralık dışı değeri ve fazla alanı reddeder. Kimlik alanı modelden değil oturumdan yazılır.

Biçim denetiminin bir kısmını API'ye de bırakabilirsin. OpenAI ve Claude, araç tanımına strict: true eklendiğinde çağrının şemaya tam uymasını güvenceye alır. Bu mod JSON Schema'nın yalnız bir alt kümesini destekler. Claude belgesine göre minimum ve maximum gibi sayı kısıtları bu alt kümede yok, ay alanının aralığını yine senin kodun denetler.

Güvence biçimle ilgilidir. musteri_no alanının doğru tipte olduğunu garanti eder, o numaranın oturumdaki kullanıcıya ait olduğunu bilmez. Şimdi eksik bir çalıştırıcıyı incele.

Ajan tek atışlık çağrı değildir, bir döngüdür. Tek atışlık çağrıda model bir kez araç ister ve iş biter. Ajan ise hedefi alır, plan kurar, araç çağırır, çıktıyı gözlemler ve yeniden planlar.

Döngü hedefe ulaşana ya da bir sınıra çarpana kadar sürer. Her turda araç çıktısı bağlama eklenir.

Her tur yeni bir model isteğidir, bu yüzden bağlam büyür ve ilk dersteki bütçe kuralları burada da geçerlidir. Bu çıktı da dış veridir. Arama aracı web sayfası, dosya aracı belge, e-posta aracı yabancı birinin mektubunu getirir. İçinde emir yazıyor olabilir.

Şemadaki her durak farklı bir sahibe aittir. Hedefi kullanıcı verir. Plan ve yanıt modelin ürünüdür.

Araç çağrısı durağı ise çalıştırıcı koddur ve yetki sınırı orada durur. Gözlem dışarıdan gelir, bu yüzden güvenilmez veri sayılır. OWASP'ın örneği bu riski somutlar.

E-postaları özetleyen bir asistanın gönderme yetkisi de var. Kötü niyetli bir e-posta, gelen kutusundaki hassas bilgiyi toplayıp bir adrese iletmesini söyler. Asistan e-postayı gözlem olarak okur ve talimatı plana katar. OWASP'ın önerdiği savunma eklentiyi salt okunur yapmak ve göndermeden önce insan onayı istemektir.

Döngünün üç çıkışı vardır. Model artık araç istemez ve son yanıtı yazar. Tur sayısı üst sınıra çarpar. Süre ya da maliyet bütçesi dolar.

Son iki çıkışı sen kurarsın, model kendi kendine durmayı garanti etmez. Tur sınırını ve bütçeyi yapılandırmada sabitle, modelin değiştirebileceği bir yerde tutma.

Başarısız aramayı tekrar tekrar deneyen ajan hem para yakar hem kayıtları doldurur. Yüksek etkili adımda, örneğin para iadesinde ya da silmede, döngü durur ve insandan onay ister. OWASP LLM06 bu kontrolü insan onayı (human-in-the-loop) adıyla önerir.

MITRE ATLAS saldırganın bu yeteneği kullanmasını AML.T0053 (AI Agent Tool Invocation) olarak adlandırır: ajana erişen saldırgan, ajanın bağlı olduğu araçları çağırır. Bağlı bir API, veri kaynağı ya da komut yorumlayıcısı böylece saldırganın eline geçer. Karşılık gelen önlem AML.M0029'dur: ajanın eylemini, uygulanmadan önce bir insan onaylar.

ATLAS onayın derecesini sonucun ağırlığına bağlar. Basit ve tekrarlı işler az denetim ister. Ağır sonuçlu işlerde birden çok onaylayıcı gerekebilir.

Onayın yerini de kod belirler. 2025 yazında bir kod yazma servisinin ajanı, kullanıcının kod dondurma talimatına rağmen üretim veritabanını sildi. Kullanıcı yasağı büyük harflerle defalarca yazmıştı.

Talimat bir istemdi, engel değildi. Platformda dondurmayı zorlayan bir mekanizma yoktu, geliştirme ile üretim ortamı da ayrılmamıştı. Silme gibi yıkıcı bir işlem onay beklemeden çalıştı.

Ders şudur: istemde yazılı kuralı model çiğneyebilir. Çalıştırıcıdaki kontrol ise modelin ikna edilmesinden etkilenmez. Yıkıcı aracı çalıştırıcıda onaya bağla ve üretim yetkisini ajandan ayır.

Tespit için çalıştırıcıyı kayda bağla. Her çağrıda tur numarasını, aracı, argümanları ve oturumdaki kullanıcıyı yaz. Kayıt, sonradan "model bunu neden yaptı" sorusunun tek cevabıdır. Kayda modelin gördüğü kaynakları da ekle: hangi belge, hangi araç sonucu bağlama girdi.

Olay incelemesinde asıl soru çoğu zaman emri kimin yazdığıdır. Cevap genellikle bir gözlemdedir, kullanıcının mesajında değil. Argümanları kaydederken kişisel veriyi maskele, çünkü kayıt da bir veri deposudur. Onay adımlarını da yaz: kim, ne zaman, hangi çağrıyı onayladı.