Ajan Mimarisinde Araç Tanımlama: İyi Tool Şeması Nasıl Yazılır

Ajan mimarisinde tool tanımlama, bir yapay zeka ajanının kullanabileceği araçları (fonksiyonları) modele hangi isim, açıklama ve parametrelerle sunduğunuzu belirleyen tasarım işidir. Ajan bir aracı çağırıp çağırmamaya yalnızca bu şemaya bakarak karar verdiği için, iyi bir tool tanımlama ajanın doğru davranmasının en belirleyici etkenidir.

Bir ajanın "zekâsı" çoğu zaman modelden değil, ona sunulan araç şemasının kalitesinden gelir. Model güçlü olsa bile, aracın ne işe yaradığını belirsiz anlatan bir şema yanlış araç seçimine ve hatalı argümanlara yol açar. Bu yazıda ajan neden yanlış araç seçer, isimlendirme ve parametre açıklaması nasıl yazılır, kaç araç fazladır, hata mesajları nasıl tasarlanır ve bir tool tanımlama nasıl test edilir sorularını bir danışman titizliğiyle ele alıyoruz; araçları modele bağlayan protokolü işleyen kapsamlı rehbere de değineceğiz.

Tanım

Tool Tanımlama (Araç Şeması Yazımı)

Bir yapay zeka ajanının kullanabileceği her aracı (fonksiyonu) modele hangi isim, hangi açıklama ve hangi parametrelerle sunacağınızı belirleyen tasarım işi. Ajan bir aracı çağırıp çağırmayacağına yalnızca bu araç şemasına bakarak karar verdiği için, tool tanımlama kalitesi ajan araç seçimi doğruluğunu doğrudan belirler.

Ayrıca: araç tanımlama, tool schema, araç şeması, fonksiyon şeması

Bir ajan, eline verilen görevi tek başına metin üreterek değil, dış araçları çağırarak yürütür; bu araç çağırma mekanizmasının adı fonksiyon çağırmadır. Modelin gördüğü tek şey, her aracın adı, açıklaması ve parametre listesinden oluşan araç şemasıdır — aracın kodunu, ne yaptığını veya yan etkilerini görmez. Dolayısıyla ajan araç seçimi, tamamen bu şemadaki metnin ne kadar net olduğuna bağlıdır. Ajanın nasıl karar verdiğini AI agent nedir ve agentic AI nedir yazılarında ele alıyoruz.

Yanlış araç seçiminin üç tipik nedeni vardır. Birincisi, iki aracın açıklamasının birbirine benzemesidir: "kullanıcı bilgisi getir" ve "kullanıcı hesabı getir" araçları arasında model kararsız kalır. İkincisi, açıklamanın aracın ne zaman kullanılacağını değil yalnızca ne yaptığını söylemesidir; model ne yaptığını bilse de hangi durumda çağıracağını bilemez. Üçüncüsü, belirsiz bir parametre açıklaması yüzünden modelin doğru aracı seçip yanlış argümanla çağırmasıdır. Fonksiyon çağırma mekanizmasının ayrıntısını function calling nedir ve modelin metni nasıl işlediğini LLM nedir yazısında bulabilirsiniz.

İyi bir tool tanımlama isimden başlar. Araç adı, işlevini tek bakışta anlatan, fiil içeren ve tutarlı bir kalıpta olmalıdır: get_user_orders, send_invoice_email gibi. Kısaltmalar, kod içi jargon ve belirsiz adlar (do_it, process2) modeli yanıltır ve benzer araçlar arasında kararı zorlaştırır.

Açıklama ise aracın en kritik alanıdır. İyi bir açıklama üç soruyu yanıtlar: bu araç ne yapar, ne zaman kullanılmalı ve ne zaman kullanılmamalı. "Sipariş getirir" yerine "Bir müşterinin geçmiş siparişlerini getirir; yalnızca sipariş numarası veya müşteri kimliği bilindiğinde kullan, ürün araması için kullanma" demek, ajan araç seçimini belirgin biçimde iyileştirir. Aşağıdaki tablo, iyi ve kötü bir araç şeması arasındaki farkı özetler:

İyi ve kötü bir tool tanımının (araç şeması) karşılaştırması

Boyut	Kötü tanım	İyi tanım
İsim	do_it, handle, process2	get_user_orders (fiil + nesne)
Açıklama	Sipariş işler	Müşterinin siparişlerini getirir; ne zaman kullanılacağını söyler
Ne zaman kullanılır	Belirtilmez	Açıkça yazılır; ne zaman kullanılmayacağı da
Parametre açıklaması	id: string	order_id: sipariş numarası, örn. ORD-1024
Hata mesajı	Error 400	order_id bulunamadı; geçerli bir numara girin

Dikkat edilmesi gereken nokta şudur: bu alanlar kullanıcıya değil, modele yazılır. Bu yüzden aracın rolünü ve sınırlarını sistem promptu düzeyinde sabitlemek de kaliteyi artırır; ayrımı sistem promptu nedir yazısında ele alıyoruz.

Doğru aracı seçen bir ajan bile parametreleri yanlış doldurursa başarısız olur; bu yüzden her alanın net tanımlanması, doğru araç seçmek kadar önemlidir. Her parametrenin bir türü (type), bir parametre açıklaması ve mümkünse bir örnek değeri olmalıdır. Parametre açıklaması alanın ne beklediğini, biçimini ve sınırlarını söyler: "tarih" yerine "ISO 8601 biçiminde tarih, örn. 2026-08-17".

Zorunlu ve opsiyonel alanlar net ayrılmalı; serbest metin yerine sabit bir seçenek kümesi (enum) kullanılabiliyorsa mutlaka kullanılmalıdır, çünkü model kapalı bir listeden seçim yaparken çok daha az hata yapar. Numaralandırılmış değerler, varsayılanlar ve birimler de parametre açıklamasında belirtilmelidir; "miktar" alanının adet mi yoksa kilogram mı beklediğini model tahmin etmemeli, şemadan okumalıdır. İyi yazılmış bir alan, modelin hem doğru argümanı üretmesini hem de eksik bilgi olduğunda kullanıcıdan bunu istemesini sağlar.

Bir başka sık atlanan ayrıntı, alanlar arasındaki bağımlılıklardır. Bir parametre yalnızca bir diğeri belirli bir değerdeyken anlamlıysa, bu ilişki parametre açıklamasında açıkça yazılmalıdır; aksi halde model iki alanı çelişkili doldurabilir. Kısacası şema, modelin aklından geçebilecek her belirsizliği önceden yanıtlayan bir sözleşme gibi düşünülmelidir: ne kadar az yorum bırakırsa, ajan araç seçimi ve argüman üretimi o kadar tutarlı olur.

Sezgiye aykırı biçimde, bir ajana ne kadar çok araç verirseniz o kadar iyi çalışmaz — çoğu zaman tersi olur. Her ek araç, modelin her kararda taraması gereken seçenek sayısını artırır ve birbirine benzeyen araçlar seçim hatasını büyütür. Ayrıca tüm araç şemaları modelin bağlamına (context window) yüklendiği için, çok sayıda araç hem maliyeti artırır hem de dikkati dağıtır. Bağlamın ve maliyetin sınırındaki rolü token nedir yazısında ele alıyoruz.

Pratik bir eşik yoktur ama deneyim şunu gösterir: bir ajana aynı anda onlarca araç vermek yerine, göreve göre daraltılmış küçük araç kümeleri sunmak daha güvenilirdir. Araç sayısı arttıkça çoklu ajan mimarisi düşünülmelidir: her biri dar bir araç kümesine sahip uzman ajanlar, tek bir dev ajandan daha isabetli çalışır. Bu deseni çoklu ajan sistemi nedir yazısında ayrıntılandırıyoruz.

Bir aracın döndürdüğü hata mesajı, kullanıcıya değil, modele yazılmış bir talimattır. Ajan bir aracı yanlış argümanla çağırdığında, dönen hata mesajı modelin kendini düzeltebileceği kadar açıklayıcı olmalıdır. "Error 400" modeli çıkmaza sokar; "order_id 'ABC' geçersiz; sipariş numarası ORD- ile başlamalıdır" mesajı ise modele bir sonraki denemede ne yapacağını söyler. İyi tasarlanmış hata mesajları, ajanın kendini toparlamasını (self-correction) mümkün kılar ve gereksiz başarısızlıkları önler.

Hata mesajı ayrıca eylem önermeli: hangi parametrenin hatalı olduğunu, beklenen biçimi ve varsa geçerli bir örneği içermelidir. Güvenlik açısından ise hata mesajları iç sistem ayrıntılarını sızdırmamalı ve kötü niyetli girdilere karşı korunmalıdır; koruyucu katmanların rolünü guardrail nedir yazısında ele alıyoruz.

Bir tool tanımlama, yazıldığı anda değil, test edildikten sonra bitmiş sayılır. Bir araç şemasını test etmenin en pratik yolu, gerçek kullanıcı sorularından oluşan küçük bir senaryo kümesi hazırlayıp ajanın hangi aracı, hangi argümanlarla çağırdığını gözlemlemektir. Amaç yalnızca "çalışıyor mu" değil, "belirsiz durumlarda doğru aracı mı seçiyor" sorusunu yanıtlamaktır.

Nasıl Yapılır

Bir tool şemasını test etme adımları

Bir araç şemasının ajan araç seçimi doğruluğunu ve dayanıklılığını gerçek senaryolarla ölçmenin temel adımları.

1. 1

   Senaryo kümesi hazırla

   Aracın kullanılması ve kullanılmaması gereken gerçekçi kullanıcı isteklerini bir liste halinde toplayın.

2. 2

   Araç seçimini ölç

   Ajan her senaryoda doğru aracı mı seçiyor, yoksa benzer bir araca mı kayıyor gözlemleyin.

3. 3

   Argümanları denetle

   Seçilen aracın parametrelerinin doğru ve tam doldurulup doldurulmadığını kontrol edin.

4. 4

   Hata yollarını dene

   Eksik veya hatalı girdilerle aracı çağırıp modelin hata mesajından toparlanıp toparlanmadığını test edin.

5. 5

   Şemayı iyileştir

   Karışan araçların isim ve açıklamalarını netleştirin, parametre açıklamalarını keskinleştirin ve tekrar ölçün.

Bu döngü — senaryo hazırla, seçimi ölç, argümanı denetle, hatayı dene, iyileştir — bir tool tanımlama için düzenli tekrarlanmalıdır; çünkü yeni araçlar eklendikçe eski araçların açıklamaları da yeniden çakışabilir.

Tool şeması nasıl yazılır?

Bir tool şeması üç parçadan oluşur: isim, açıklama ve parametreler. İsim, işlevi tek bakışta anlatan ve fiil içeren tutarlı bir ad olmalı. Açıklama, aracın ne yaptığını, ne zaman kullanılacağını ve ne zaman kullanılmayacağını söylemeli. Her parametre için türü, biçimi ve bir örnek değeri içeren net bir parametre açıklaması yazılmalı; mümkünse serbest metin yerine kapalı bir seçenek kümesi kullanılmalı. Son olarak şema gerçek senaryolarla test edilmelidir.

Ajan neden yanlış araç seçiyor?

Ajan aracın kodunu değil yalnızca araç şemasını gördüğü için, yanlış seçim neredeyse her zaman şemadaki belirsizlikten kaynaklanır. Üç tipik neden vardır: iki aracın açıklaması birbirine benzer; açıklama aracın ne zaman kullanılacağını söylemez; ya da belirsiz bir parametre açıklaması yüzünden model doğru aracı seçip yanlış argümanla çağırır. Çözüm, benzer araçları netçe ayırmak, her açıklamaya kullanım koşulunu eklemek ve parametreleri örneklerle keskinleştirmektir.

Kaç araç fazla?

Kesin bir sayı yoktur ama ilke nettir: bir ajana ne kadar çok araç verirseniz seçim o kadar zorlaşır. Her araç şeması modelin bağlamına yüklenir, maliyeti artırır ve dikkati dağıtır; benzer araçlar seçim hatasını büyütür. Tek bir ajana onlarca araç yığmak yerine göreve göre daraltılmış küçük araç kümeleri sunmak daha güvenilirdir; araç sayısı büyüdükçe çoklu ajan mimarisi düşünülmelidir.

Fonksiyon çağırma ile tool tanımlama arasındaki ilişki nedir?

Fonksiyon çağırma, bir dil modelinin metin üretmek yerine yapılandırılmış bir çağrı üreterek dış bir aracı tetikleme mekanizmasıdır. Tool tanımlama ise modelin bu çağrıyı üretmek için okuduğu şemayı — ismi, açıklamayı ve parametreleri — yazma işidir. Yani fonksiyon çağırma mekanizma, tool tanımlama ise o mekanizmayı besleyen arayüz tasarımıdır; model doğru fonksiyon çağırma kararını ancak iyi yazılmış bir tool tanımlama sayesinde verebilir.

Parametre açıklaması neden bu kadar önemli?

Çünkü doğru aracı seçen bir ajan bile parametreyi yanlış doldurursa görev başarısız olur. Parametre açıklaması alanın türünü, biçimini, birimini ve sınırlarını söyler: "tarih" yerine "ISO 8601 biçiminde tarih, örn. 2026-08-17". İyi bir parametre açıklaması modelin hem doğru argümanı üretmesini hem de bilgi eksikse kullanıcıdan istemesini sağlar. Serbest metin yerine kapalı bir seçenek kümesi verildiğinde model çok daha az hata yapar.

Özetle, ajan mimarisinde tool tanımlama; aracı modele net bir isim, ne zaman kullanılacağını söyleyen bir açıklama, biçimini belirten bir parametre açıklaması ve kendini düzeltmeyi mümkün kılan hata mesajlarıyla sunmaktır. Ajan araç seçimi doğruluğu en pahalı modelden değil, bu şema disiplininden gelir; birbirine benzeyen araçları ayırmak, gereksiz araçları budamak ve her tool tanımlama işini senaryolarla test etmek, güvenilir bir ajanın temelidir.

Bu tür pratik ajan mühendisliği içeriklerini ve yeni rehberleri kaçırmamak için bültene abone olabilir, tüm konuları uçtan uca derinleştirmek için öğrenme merkezini inceleyebilirsiniz. İyi kurulmuş bir araç şeması, aynı modelden kat kat daha güvenilir bir ajan çıkarmanın en pratik yoludur.