Kazanimlar:
- Bir ajanı 'model + araçlar + döngü' olarak tanımlamak ve ne zaman gerektiğine karar vermek
- Tool tanımını name, description ve input_schema ile yazmak
- tool_use ve tool_result döngüsünün akışını ve hata yönetimini izlemek
Şimdiye kadar model hep tek işi yaptı: metin girdi al, metin cevap üret. Ama gerçek işler çoğu zaman metinden fazlasını gerektirir; bir hesaplama yapmak, bir veritabanını sorgulamak, bir API çağırmak, güncel bir kur öğrenmek. Model bunları kendi başına yapamaz — ama ne zaman yapılması gerektiğine karar verip birinden isteyebilir. İşte araç kullanımı (tool use) modele bu yeteneği kazandırır ve bu, AI ajanlarının temelidir. Bu ünitede ajanın ne olduğunu, aracın nasıl tanımlandığını ve tool_use döngüsünün nasıl işlediğini öğreneceğiz.
Ajan Nedir? Model + Araçlar + Döngü
Bir AI ajanı üç parçadan oluşur: model (kararı veren beyin), araçlar (modelin çağırabileceği fonksiyonlar: hava durumu, veritabanı sorgusu, e-posta gönder), ve döngü (loop; model araç çağırır, sonucu alır, ne yapacağına yeniden karar verir, bu böyle devam eder).
Kritik ayrım: Tek bir model çağrısı bir ajan değildir. Ajan, modelin adım adım ilerlediği, her adımda araç sonucuna göre bir sonraki hamleyi seçtiği bir süreçtir. "İnsan gibi düşün, elini kullan, sonuca bak, tekrar düşün."
Önemli bir gerçek: Aracı modelin kendisi çalıştırmaz. Model sadece "şu aracı şu girdilerle çağırmak istiyorum" der. Aracı sizin uygulamanız (buna harness denir) çalıştırır ve sonucu modele geri verir. Bu, güvenlik açısından hayatidir: model doğrudan sisteminize dokunmaz; her eylem sizin kontrolünüzden geçer.
İpucu: Her sorunu ajanla çözmeye çalışmayın. Ajan; gecikme, maliyet ve hata riskini artırır. Önce sorun: "Bu iş tek bir çağrıyla veya sabit bir iş akışıyla çözülür mü?" Cevap evetse ajana gerek yok. Ajan, adımların önceden bilinemediği, açık uçlu görevler içindir.
Tool Tanımı: name, description, input_schema
Modele bir aracı tanıtmak için üç şey verirsiniz:
- name (isim): Aracın kimliği, ör. hava_durumu_getir.
- description (açıklama): Aracın ne yaptığı ve ne zaman çağrılacağı. Bu, modelin doğru zamanda doğru aracı seçmesini sağlayan en önemli alandır. Sadece "ne yapar" değil, "ne zaman çağır" da yazın.
- input_schema (girdi şeması): Aracın hangi parametreleri, hangi tipte beklediğini tanımlayan JSON şema.
# Araç tanımı (kavramsal — JSON şema){ "name": "siparis_durumu_getir", "description": "Bir siparişin güncel kargo durumunu getirir. Kullanıcı bir sipariş numarasının nerede olduğunu veya ne zaman geleceğini sorduğunda çağır.", "input_schema": { "type": "object", "properties": { "siparis_no": {"type": "string", "description": "Sipariş numarası, ör. SP-1024"} }, "required": ["siparis_no"] }}
İyi bir araç tanımının kuralları: açık ve öz bir isim, "ne zaman kullan" içeren bir açıklama, her parametre için açıklama, gerçekten zorunlu olanları required'a koymak. Araç sayısını odaklı tutun; onlarca benzer araç modeli şaşırtır.
Alan
Ne işe yarar
İyi örnek
Kötü örnek
name
Aracın kimliği
siparis_durumu_getir
getir
description
Ne yaptığı + ne zaman çağrılacağı
"Kargo durumunu getirir; kullanıcı sipariş nerede diye sorunca çağır"
"veri getirir"
input_schema
Parametre tipi ve zorunluluğu
{siparis_no: string, açıklamalı}
şema yok / açıklama yok
tool_use → tool_result Döngüsü
Döngü şöyle işler, adım adım:
- Kullanıcı sorusunu + araç tanımlarını modele gönderirsiniz.
- Model ya doğrudan yanıt verir ya da bir tool_use bloğu üretir: "siparis_durumu_getir'i siparis_no=SP-1024 ile çağır."
- Uygulamanız (harness) aracı gerçekten çalıştırır (veritabanını sorgular).
- Sonucu tool_result olarak modele geri gönderirsiniz.
- Model bu sonuçla ya nihai cevabı üretir ya da başka bir araç çağırır. Döngü, model "işim bitti" diyene kadar sürer.
# Ajan döngüsü (kavramsal)mesajlar = [kullanici_sorusu]while True: yanit = model.uret(mesajlar, araclar=arac_tanimlari) if yanit.tur == "tool_use": sonuc = harness.calistir(yanit.arac_adi, yanit.girdiler) # UYGULAMA çalıştırır mesajlar += [yanit, tool_result(sonuc)] # sonucu geri ver else: break # nihai cevap; döngü biter
Modern SDK'ler bu döngüyü sizin için yürüten yardımcılar (tool runner) sunar; siz sadece araç fonksiyonlarını yazarsınız. Ama arkada olan tam olarak budur.
Hata Yönetimi
Araçlar başarısız olabilir: sipariş bulunamaz, API zaman aşımına uğrar, girdi geçersizdir. Aracı çalıştıramazsanız, hatayı modele açıklayıcı bir tool_result olarak ("hata: SP-9999 numaralı sipariş bulunamadı") ve hata işareti ile geri verin. Model bunu görüp kullanıcıya nazikçe açıklayabilir veya farklı bir yol dener. Hatayı yutup boş sonuç dönmeyin; model neyin yanlış gittiğini bilmeli.
Zayıf / Güçlü Araç Tanımı
Zayıf (belirsiz isim, "ne zaman" yok):
name: "veri", description: "veri getirir"# Model ne zaman ve nasıl çağıracağını bilemez; ya hiç çağırmaz ya yanlış çağırır.
Güçlü (net isim + ne zaman + parametre açıklaması):
name: "musteri_bakiyesi_getir"description: "Bir müşterinin güncel hesap bakiyesini getirir. Kullanıcı borç, alacak veya bakiye sorduğunda çağır. Ödeme YAPMAZ."input_schema: {musteri_id: string ("Müşteri kimliği")}# Model doğru zamanda, doğru parametreyle, sınırını bilerek çağırır.
Üç Mini Vaka
Vaka 1 — Gereksiz ajan. Bir ekip "metni özetle" işini çok araçlı bir ajanla kurmuş; her özet 4 model çağrısı ve 9 saniye sürüyormuş. İş aslında tek çağrılıkmış. Ajanı kaldırıp tek çağrıya inince süre 1,5 saniyeye, maliyet dörtte bire düşmüş. Ders: ajanı gerçekten gerektiğinde kullan.
Vaka 2 — Zayıf açıklama, yanlış çağrı. Bir destek ajanında getir adlı belirsiz bir araç, model tarafından bakiye sorusunda da kargo sorusunda da rastgele çağrılıyordu. Araçlar bakiye_getir ve kargo_durumu_getir olarak ayrılıp "ne zaman çağır" açıklamaları eklenince yanlış araç seçimi 50 örnekte 18'den 1'e indi.
Vaka 3 — Hata yutuldu. Bir ajan, sipariş bulunamadığında boş sonuç dönüyordu; model bunu "sipariş teslim edildi" diye yorumlayıp müşteriyi yanılttı. Hata mesajı açıkça tool_result'a ("sipariş bulunamadı") yazılınca model doğru şekilde "bu numarayı bulamadım, kontrol eder misiniz?" demeye başladı.
Sık yapılan hatalar
- Her şeyi ajana çevirmek: Tek çağrı yeterken ajan maliyet ve gecikme ekler.
- Belirsiz araç açıklaması: Model ne zaman çağıracağını bilemez; yanlış seçer.
- Aracı modelin çalıştırdığını sanmak: Aracı harness çalıştırır; model sadece ister.
- Hatayı yutmak: Model neyin yanlış gittiğini bilmeli; hatayı açık tool_result olarak verin.
- Çok fazla benzer araç: Model şaşırır; araç setini odaklı ve az tutun.
Dikkat: Modelin "şu aracı çağır" demesi, o eylemin yapılması gerektiği anlamına gelmez. Yıkıcı araçlarda (silme, ödeme, e-posta) uygulamanız çağrıyı körü körüne uygulamamalı — bu, bir sonraki ünitedeki güvenlik konusunun çekirdeğidir.
Özetle
- Ajan = model (karar) + araçlar (fonksiyonlar) + döngü (araç çağır, sonuç al, tekrar karar ver).
- Tek bir model çağrısı ajan değildir; ajan adım adım ilerleyen bir süreçtir.
- Aracı model çalıştırmaz; uygulamanız (harness) çalıştırıp sonucu tool_result olarak geri verir.
- Araç name, description (özellikle "ne zaman çağır") ve input_schema ile tanımlanır.
- Döngü tool_use → harness çalıştırır → tool_result → model devam eder şeklinde model "bitti" diyene kadar sürer; hatalar açıkça modele bildirilir.
Uygulama görevi
Kendi işinizden ajana verilebilecek 3 araç tasarlayın. (1) Her biri için name, "ne zaman çağır" içeren description ve input_schema yazın; en az biri yıkıcı olmayan bir okuma aracı, biri hesaplama olsun. (2) Gerçekçi bir kullanıcı sorusu seçip, modelin bu araçlardan hangisini hangi girdilerle çağıracağını ve tool_result geldikten sonra ne yapacağını adım adım (döngü olarak) elle yazın. (3) Araçlardan birinin başarısız olduğu bir senaryo kurgulayın ve hata mesajının modele nasıl döneceğini gösterin.
Kontrol listesi
- [ ] Ajanı "model + araçlar + döngü" olarak tanımlayabiliyorum ve ne zaman gerektiğine karar verebiliyorum.
- [ ] Aracı harness'ın çalıştırdığını, modelin sadece istediğini biliyorum.
- [ ] name, description ("ne zaman çağır") ve input_schema ile sağlam bir araç tanımı yazabiliyorum.
- [ ] tool_use → tool_result döngüsünü adım adım izleyebiliyorum.
- [ ] Araç hatalarını açık tool_result olarak modele bildiriyorum.