Yetmiş Araçlı Ajan Neden Yanlış Çekmeceyi Açıyor?

Bir müşteri temsilcisi yapay zekâ ajanına şöyle yazıyor: “Müşterinin son görüşmesini bul ve hesaba kısa bir not ekle.” Ajanın önünde yetmiş araç var. Aradığı iki araç katalogda gerçekten mevcut. Buna rağmen benzer adlı search_contacts yerine search_companies aracını çağırıyor, notu doğru hesaba değil kişi kaydına ekliyor veya araç kullanmadan önceki konuşmalardan tahminde bulunuyor.

İlk tepki genellikle modeli suçlamak oluyor: “Daha güçlü bir model seçelim” ya da “Promptu biraz daha ayrıntılı yazalım.” Bunlar bazen işe yarar; fakat temel sorun çoğu zaman zekâ eksikliği değil, bilgi erişimidir. Yetmiş çekmeceli bir dolap düşünün. Etiketlerin yarısı birbirine benziyor, bazı çekmecelerin içinde ne olduğu yazmıyor ve tehlikeli araçlarla sık kullanılan araçlar yan yana duruyor. Böyle bir dolapta deneyimli bir insan da zaman kaybeder.

Bu yazıda araç kataloğunu bir özellik listesi olarak değil, bulunabilirlik sistemi olarak tasarlayacağız. Benzer CRM araçlarından oluşan doldurulmuş bir örnek üzerinden karışıklıkları ölçecek; görev ailelerini, adları, açıklamaları ve parametre şemalarını yeniden kuracağız. Sonra küçük bir araç çekirdeği ile talep üzerine keşfi ayıracak, silme ve gönderme gibi riskli eylemlere ek kapılar koyacak ve tasarımı on gerçek istekle yeniden sınayacağız.

Araç seçimi neden bir bilgi erişim problemidir?

Bir ajan, aracı yalnızca çalıştırmaz. Önce kullanıcının niyetini yorumlar, katalogda uygun adayları bulur, benzer adayları birbirinden ayırır, gerekli parametreleri çıkarır ve aracın sonucunu doğrular. Bu zincirin ilk halkaları bozuksa kusursuz çalışan bir API bile doğru sonuca götürmez.

Büyük kataloglarda dört ayrı hata türü görülür:

• Bulamama: Doğru araç vardır, fakat adı veya açıklaması kullanıcının diliyle eşleşmez.
• Karıştırma: Ajan, benzer adlara sahip iki araçtan yanlış olanı seçer.
• Şema yanılgısı: Doğru aracı seçer, fakat contact_id yerine account_id gönderir.
• Atlama: Araç kullanması gereken yerde belleğine ya da tahmine dayanarak cevap verir.

Araç tanımlarının tamamını her istekte modele göstermek de bedelsiz değildir. Tanımlar bağlam alanı tüketir; ilgisiz seçeneklerin sayısı arttıkça ayırt etme işi zorlaşır. Anthropic’in tool search yaklaşımı ile OpenAI Agents SDK’de belgelenen ertelenmiş araçlar ve ad alanları, bu nedenle bütün kataloğu baştan yüklemek yerine ilgili araçları ihtiyaç anında buldurmayı öne çıkarır.

Karar kuralı: Doğru araç katalogda bulunduğu hâlde sık sık seçilemiyorsa önce modeli değil, kataloğun erişim mimarisini inceleyin.

Önce karışıklığı görünür kılın

“Ajan bazen yanlış araç seçiyor” geliştirme için yeterli bir teşhis değildir. Hangi niyetin hangi araçla karıştığını kaydetmek gerekir. Örnek CRM kataloğumuzda şu altı araç bulunsun:

Şimdi on gerçek kullanıcı isteği seçip beklenen ve gerçekleşen çağrıları kaydedelim. İlk ölçümde örneğin altı istek doğru araçla tamamlanmış, ikisinde yanlış araç seçilmiş, birinde yanlış parametre kullanılmış, birinde ise araç çağrısı atlanmış olsun. Bu sayılar evrensel bir performans iddiası değil; yeniden tasarım kararını açıklayan örnek bir başlangıç ölçümüdür.

Bu tablo bize “model kötü” demekten daha fazla şey söyler. Arama ailesinde varlık türleri, etkinlik ailesinde tekil kayıt ile listeleme, yazma ailesinde ise iç not ile dış iletişim ayrıştırılamıyor. Müdahaleyi tam bu sınırlara yöneltebiliriz.

Kataloğu görev ailelerine ayırın

Araçları ürün ekiplerine, API servislerine veya şirket organizasyonuna göre gruplamak geliştirici için doğal görünebilir. Kullanıcı niyeti ise çoğunlukla bu yapıyı izlemez. Kullanıcı “CRM v2 etkinlik servisini çağır” demez; “Son görüşmede ne konuşulmuş?” der. Katalog da bu görev diline yaklaşmalıdır.

Örnek sistemde beş görev ailesi oluşturabiliriz:

• crm_search: kişi ve hesap bulma,
• crm_read: profil ve etkinlik okuma,
• crm_internal_write: iç not ve sınıflandırma ekleme,
• communications: taslak hazırlama ve dış mesaj gönderme,
• crm_admin: birleştirme, arşivleme ve silme.

Bu ayrım yalnız düzen sağlamaz. “Müşteriye gönder” ifadesi geldiğinde aramayı communications ailesine, “hesaba iç not düş” geldiğinde crm_internal_write ailesine daraltır. Aynı zamanda yönetim araçlarını gündelik görevlerin uzağına taşır.

Ad, açıklama ve şema birlikte ayırt etmelidir

Kısa araç adları tek başına erdem değildir. get, update veya send gibi adlar küçük bir katalogda çalışabilir; büyüdükçe bağlamlarını kaybeder. İyi bir ad üç soruya mümkün olduğunca cevap verir: Hangi nesne? Hangi eylem? Sonuç iç sistemde mi kalır, dış dünyayı mı etkiler?

Örneğin add_note yerine crm_account_add_internal_note; send_message yerine communications_send_customer_email daha uzundur ama ayrım taşır. Asıl kazanç açıklama ve şema da aynı ayrımı desteklediğinde gelir:

Ad: crm_account_add_internal_note
Açıklama: Var olan bir CRM hesabına yalnızca ekip içinde görülen not ekler.
Müşteriye mesaj göndermez ve etkinlik kaydı oluşturmaz.

Gerekli parametreler:
account_id: Doğrulanmış CRM hesap kimliği
note_text: Kaydedilecek düz metin, en fazla 1000 karakter
source_activity_id: Notun dayandığı etkinlik kimliği

Kullanma:
- Müşteriye e-posta veya sohbet mesajı göndermek için
- Kişi kaydına not eklemek için
- Hesap kimliği yalnızca şirket adından tahmin edilmişse

Olumsuz kullanım koşulu özellikle değerlidir. Yalnız “ne yapar?” açıklaması, yakın araçların hepsini makul gösterebilir. “Ne zaman kullanılmaz?” bölümü karar sınırını çizer.

Parametre adları da iş anlamını taşımalıdır. Her araçta belirsiz bir id kullanmak yerine account_id, contact_id ve activity_id kullanın. Serbest metin yerine mümkün olduğunda enum, tarih biçimi, uzunluk sınırı ve zorunluluk belirtin. Ajanın şirket adını hesap kimliği sanmasını önlemek için arama sonucundan alınmış doğrulanmış kimlik şartı koyun.

Küçük bir çekirdek, talep üzerine açılan çekmeceler

Bütün araçları gizlemek de doğru değildir. Her görevde gereken küçük bir çekirdek doğrudan erişilebilir kalabilir. Örnek CRM ajanında çekirdek şu dört yetenekten oluşsun:

• araç veya görev ailesi arama,
• kimlik çözümleme,
• salt okunur kayıt getirme,
• işlem sonucunu ve kanıtını raporlama.

Geri kalan araçlar ad alanları ve tool search arkasında talep üzerine yüklenir. Akış şöyle işler: Ajan önce niyeti “hesap etkinliklerini okuma” olarak sınıflandırır; crm_read ailesini arar; yalnız ilgili iki veya üç tanımı bağlama alır; sonra uygun aracı çağırır.

Burada iki uçtan kaçınmak gerekir. Çok geniş bir arama sonucu, başlangıçtaki katalog sorununu yalnızca birkaç saniye erteleyebilir. Aşırı dar etiketleme ise doğru aracı görünmez yapabilir. Bu nedenle her aracın görev ailesi, eş anlamlı niyet ifadeleri ve ayırt edici olumsuz koşulları arama dizinine dahil edilmelidir.

Pratik karar kuralı şudur: Hemen her görevde kullanılan, salt okunur ve yanlış çağrıldığında etkisi sınırlı araçları çekirdekte tutun. Seyrek kullanılan, büyük şemalı veya belirli bir alana ait araçları talep üzerine yükleyin.

Bulunabilir olmak, kullanılabilir olmak değildir

En kritik tasarım ayrımı burada ortaya çıkar. Tool search bir keşif mekanizmasıdır; yetkilendirme mekanizması değildir. Bir aracın arama sonucunda bulunması, ajanın onu hemen çalıştırabilmesi gerektiği anlamına gelmez.

Müşteriye mesaj gönderme, kayıt silme, hesapları birleştirme veya finansal işlem başlatma gibi eylemler için ayrı bir yetki zinciri gerekir:

1. Keşif: Ajan uygun aracın varlığını öğrenir.
2. Hazırlık: Parametreleri doldurur ve beklenen etkiyi açıklar.
3. Ön kontrol: Kimlik, kapsam, yinelenen işlem ve politika koşulları makine tarafından sınanır.
4. Onay: Risk düzeyine göre kullanıcıdan ya da yetkili bir kural katmanından izin alınır.
5. Çalıştırma: Kısa ömürlü ve yalnız bu işleme özgü yetkiyle araç çağrılır.
6. Doğrulama: Sonuç kaydı okunur; hedeflenen değişiklik ile gerçekleşen değişiklik karşılaştırılır.

Örneğin “Ayşe Hanım’a yenileme hatırlatması gönder” isteğinde ajan önce doğru kişi ve hesabı salt okunur araçlarla bulur. Ardından mesaj taslağını üretir; alıcı adresini, konu satırını ve gönderim kanalını kullanıcıya gösterir. Kullanıcı onaylamadan communications_send_customer_email çağrısı erişilebilir hâle gelmez. Onay da genel bir “iletişim araçlarını kullanabilir” izni değil, belirli alıcı ve belirli içerik için tek işlem iznidir.

MCP’nin araç anotasyonları gibi risk ipuçları, okuma ve yıkıcı işlem ayrımını ortak bir sözlüğe dönüştürmeye yardımcı olabilir. Fakat bunlar güvenlik sınırı değildir; araç sağlayıcısının beyanına dayanır ve bağımsız politika, yetki ve doğrulama kontrollerinin yerini tutmaz.

On gerçek istekle yeniden ölçün

Yeni katalog masa başında temiz görünse bile gerçek kullanıcı diliyle sınanmadan başarılı sayılmaz. İlk ölçümde kullandığımız aynı on isteği tekrar çalıştıralım. Her denemede yalnız son cevabı değil, araç izini de kaydedelim:

• İlk aramada doğru görev ailesi bulundu mu?
• Doğru araç sonuçlar arasında yer aldı mı?
• Yanlış araç çağrıldı mı?
• Eksik parametre yüzünden ek tur gerekti mi?
• Riskli eylem onay kapısından geçti mi?
• Sonuç bağımsız bir okuma ile doğrulandı mı?

Doldurulmuş örneğimizde yeniden tasarım sonrasında on isteğin dokuzunda doğru araç ilk uygun adaylar arasında bulunsun ve dokuzu doğru tamamlansın. Bir istek, “Geçen konuştuğumuz şirkete not ekle” ifadesindeki belirsizlik nedeniyle ek kimlik sorusu gerektirsin. Bu ek tur başarısızlık değildir; yanlış hesaba yazmaktan daha ucuz ve güvenli bir davranıştır.

Bu sonuçlar örnek senaryonun ölçümleridir; başka bir katalogda aynı oranların çıkacağı iddia edilemez. Önemli olan, karşılaştırmanın aynı istek seti ve aynı başarı tanımıyla yapılmasıdır. Maliyet hesabına yalnız model tokenlarını değil; araç arama turlarını, API çağrılarını, insan onay süresini ve hatalı işlemi düzeltme yükünü de katın.

Bir haftalık uygulanabilir katalog denetimi

Kendi sisteminizde başlamak için büyük bir yeniden yazım gerekmiyor. Şu doldurulmuş çalışma sırası küçük bir pilot olarak kullanılabilir:

1. Pazartesi — İz toplayın: CRM ajanının son 30 araçlı görevinden yanlış seçim, eksik parametre ve atlama örneklerini çıkarın.
2. Salı — Karışıklık çiftlerini bulun: add_note/send_message, contact/account ve get/list_activity çiftlerini önceliklendirin.
3. Çarşamba — Tanımları düzeltin: Her araç için nesne, eylem, etki alanı ve en az iki “kullanma” koşulu yazın.
4. Perşembe — Erişimi katmanlayın: Dört salt okunur çekirdek yeteneği açık bırakın; diğerlerini görev ailesi arkasına taşıyın; gönderme ve silmeye onay kapısı ekleyin.
5. Cuma — Aynı on isteği çalıştırın: Doğru bulma, yanlış çağrı, ek tur, toplam maliyet ve doğrulanmış sonuç ölçülerini önceki sürümle karşılaştırın.

Pilotun kabul ölçütü “ajan daha akıllı hissettiriyor” olmamalıdır. Örneğimiz için somut sözleşme şöyledir: On isteğin en az dokuzu doğru tamamlanacak; hiçbir dış mesaj onaysız gönderilmeyecek; hiçbir hesap kimliği addan tahmin edilmeyecek; her yazma işleminden sonra kayıt yeniden okunacak; belirsiz kalan istekte ajan eyleme geçmek yerine açıklayıcı soru soracak.

Sonuç: Daha büyük kutu değil, daha iyi düzenlenmiş bir çalışma alanı

Bir ajana yeni araç eklemek kolaydır; o aracın doğru niyette bulunmasını, benzerlerinden ayrılmasını ve güvenli sınırlar içinde kullanılmasını sağlamak daha zor bir tasarım işidir. Araç sayısı büyüdükçe katalog, basit bir liste olmaktan çıkar. Arama dizini, görev taksonomisi, parametre sözleşmesi, yetki sistemi ve değerlendirme yüzeyi hâline gelir.

İlk adım olarak bütün yetmiş aracı yeniden adlandırmaya çalışmayın. Son izlerden en sık karışan iki araç çiftini seçin. Görev ailelerini ayırın, açıklamalara olumsuz kullanım koşulları ekleyin, parametreleri iş anlamıyla adlandırın ve aynı on istekle tekrar ölçün. Sonra riskli araçları keşif katmanından ayırıp açık bir onay ve doğrulama zincirine bağlayın.

Ajanın başarısı, kutusunda kaç araç bulunduğuyla değil; doğru anda doğru çekmeceyi açması, neyi neden yaptığını gösterebilmesi ve tehlikeli çekmecelerde anahtar istemesiyle ölçülür.

Kaynaklar

• Anthropic — Scale to many tools with tool search
• OpenAI Agents SDK — Tools
• OpenAI — A practical guide to building agents
• Model Context Protocol Blog — Tool Annotations as Risk Vocabulary