# Bir yapay zeka ajanının kullanabileceği araçlar nasıl tasarlanır?

> Bu saha notunda veridive, bir yapay zeka ajanının kullanabileceği araçların nasıl tasarlanacağını anlatıyor. Ajan ancak araçları kadar güvenli olduğu için her araç dar kapsamlı, açıkça tanımlanmış, en az yetkiyle sınırlanmış, iki kez çağrıldığında zarar vermeyen ve başarısız olduğunda yol gösteren biçimde kurulmalıdır. Not, iyi ve kötü tanımları karşılaştırıyor ve araçların modelle birlikte nasıl test edileceğini ele alıyor.

Bir ajan, araçları kadar güvenli ve güvenilirdir. Her aracı dar kapsamlı ve açıkça tanımlanmış yapın, en az yetkiyle sınırlayın; iki kez çağrıldığında zarar vermesin, başarısız olduğunda da yol göstersin.

## Öne çıkanlar

- Model açısından bir araç bir ad, bir açıklama ve parametrelerden ibarettir; gerçek sınırlar aracın arkasındaki kodda durur.
- Sabit seçenekli, dar kapsamlı araçları tercih edin; her biri ajanın kendi servis hesabı altında en az yetkiyle çalışsın.
- İşlemleri tekrarda zararsız kılın: idempotency anahtarları, değeri artırmak yerine atayan işlemler ve bir insanın onayladığı taslaklar.
- Modele bir sonraki adımı söyleyen hatalar döndürün, her çağrıyı kaydedin ve araçları modelin de katıldığı testlerle sınayın.

Modelin gözünden bir araç üç şeyden ibarettir: bir ad, bir açıklama ve bir parametre listesi. Model bunları okur, bir çağrının işe yarayıp yaramayacağına karar verir ve argümanları yazar. Geri kalan her şeyi, yani aracın nelere erişebildiğini, girdilerini kontrol edip etmediğini ve iki kez çalışırsa ne olacağını, aracın arkasındaki kod belirler.

Bu yüzden bir ajan ancak araçları kadar güvenli ve güvenilirdir. Yapay zeka ajanı araç tasarımında her aracı dar kapsamlı ve açıkça tanımlanmış yapın, en az yetkiyle sınırlayın; iki kez çağrıldığında zarar vermesin, başarısız olduğunda da yol göstersin.

## Model açısından bir araç neye benzer?

Bir araç tanımının bir adı, sade bir dille yazılmış bir açıklaması ve bir parametre şeması vardır; şema türleri, zorunlu alanları ve izin verilen değerleri içerir. Model aracın ne yaptığını başka hiçbir yerden bilmez: araçları, yeni bir çalışanın şirket içi wiki sayfalarını okuması gibi, açıklamalarını okuyarak seçer. Çağrıyı kodunuz çalıştırır ve sonucu metin olarak döndürür; model bir sonraki adımına karar vermeden önce bu metni okur.

Bundan üç sonuç çıkar. Açıklama bir prompttur ve aynı özeni hak eder. Şema bir sözleşmedir ve her çağrıda kodla uygulanır. Sonuç da bir sonraki kararın girdisidir; bu yüzden müşteri metnini ya da bir web sayfasını aktaran bir sonuç, ajanın okuduğu her şey gibi güvenilmezdir. Bir görevin ajana gerçekten ihtiyaç duyup duymadığı ise daha önce sorulması gereken bir sorudur ve [ajan mı, iş akışı mı sorusunu ele alan notun](https://veridive.com/tr/saha-notlari/yapay-zeka-ajani-veya-is-akisi/) konusudur.

## Araçlar neden dar kapsamlı olmalı?

Bir destek ajanı için iki temsili araç tanımına bakalım:

| Temsili araç | `update_ticket_status` | `run_database_query` |
|---|---|---|
| Parametreler | Talep kimliği; sabit bir listeden durum: açık, müşteri bekleniyor, çözüldü | Herhangi bir sorgu metni |
| Modelin doğru yapması gereken | Hangi talep olduğu ve üç durumdan biri | Tablolar, birleştirmeler (join), filtreler ve söz dizimi |
| Yanlış kullanılırsa en kötü durum | Kolayca geri alınabilen, yanlış durumdaki tek bir talep | Herhangi bir kaydın okunması, değiştirilmesi ya da silinmesi |
| Test | Her durum için bir avuç vaka | Hiçbir sonlu test seti onu kapsamaz |

Dar kapsamlı araç, modele yanılmak için daha az yol bırakır ve gerçek sınırlar koymayı mümkün kılar. Her çağrı ajanın kendi servis hesabı altında, araç başına tanımlanmış yetkilerle çalışır: durum aracı tek bir alana yazabilir, bir sorgu aracı yalnızca okuyabilir ve hiçbir şey yönetici yetkisiyle çalışmaz. Ajan bir kullanıcı adına okuma yaptığında yalnızca o kullanıcının görmeye yetkili olduğu şeyleri görür. Dar kapsamlı bir araca ulaşan enjekte edilmiş bir talimat, ancak aracın izin verdiği kadarını yapabilir.

Yine de dar kapsamlı olmak, sonsuz sayıda araç demek değildir. Birbiriyle örtüşen onlarca araç, doğru aracı seçmeyi zorlaştırır. Her ajana yalnızca işinin gerektirdiği araçları verin; yalnızca tek bir parametrede ayrışan araçları birleştirin.

## Bir aracın açıklaması nasıl yazılmalı?

Dikkatli ve yeni bir çalışana yazılan talimatlar gibi:

- **Ne yaptığı ve ne zaman kullanılacağı.** “Müşterinin sorunu çözüldüğünde bir destek talebinin durumunu değiştirir.”
- **Ne zaman kullanılmayacağı.** “Mükerrer talepleri kapatmak için kullanmayın; bunun için `merge_tickets` aracını kullanın.”
- **Her parametre, biçimiyle birlikte.** Kimlik kalıpları, yıl-ay-gün biçiminde tarihler, birimler ve sabit bir liste halinde izin verilen değerler.
- **Açıkça belirtilmiş yan etkiler.** “Yalnızca taslak oluşturur” ya da “müşteriye e-posta gönderir” ifadesi, modelin aracı ne kadar dikkatli kullanması gerektiğini değiştirir.

Adları birbirinden ayırt edilebilir, açıklamaları örtüşmeyen biçimde yazın. Birbirine benzeyen iki araç karıştırılır; kayıtlar da bunu gösterir.

## Tekrarlanan işlemler nasıl zararsız hale getirilir?

Ajanlar kendilerini tekrarlar. Bir çağrı zaman aşımına uğrar ve yeniden denenir, bir ağ hatası başarılı bir işlemi gizler ya da model emin olmak için aynı çağrıyı yeniden yapar. Bir durum güncellemesinde bu zararsızdır; bir para iadesinde değildir. Üç alışkanlık tekrarları güvenli kılar:

- **Idempotency anahtarları.** Her yazma işlemi, vakadan ve işlemden türetilmiş bir anahtar taşır. Aynı anahtarla gelen ikinci çağrı, işlemi yeniden yapmak yerine ilk sonucu döndürür.
- **Artırmak yerine atamak.** “Durumu çözüldü olarak ayarlamak” iki kez çalışabilir; “miktarı bir artırmak” çalışamaz.
- **Önce taslak.** Mümkün olan her yerde araç bir yanıt, para iadesi ya da ERP kaydı için taslak oluşturur; nihai bir şey olmadan önce bu taslağı bir insan onaylar. Bir taslağın üzerine güvenle yeniden yazılabilir; gönderilmiş bir e-posta ise geri alınamaz.

> Bir ajan, ona verdiğiniz araçlar kadar güvenlidir.

## Bir şey ters gittiğinde araç ne döndürmeli?

Hata mesajı modele verilen bir talimattır; onu bir talimat gibi yazın. “Error 500” modeli tahmin yürütmeye ya da körlemesine tekrar denemeye bırakır. “Talep bulunamadı; `find_ticket` ile müşteri e-postasına göre arayın ya da kullanıcıdan talep numarasını isteyin” ise ona bir sonraki adımı verir.

- **Yeniden denenip denenmeyeceğini söyleyin.** Bir zaman aşımı bir kez yeniden denenebilir; bir yetki hatası asla yeniden denenmemeli ve vaka bir insana gitmelidir.
- **Alanı adıyla belirtin.** Bir doğrulama hatası hangi parametrenin geçemediğini ve neye izin verildiğini söyler.
- **Hiçbir şey sızdırmayın.** Hata metninde yığın izi (stack trace), kimlik bilgisi ya da başka müşterilerin verisi yer almaz.

Her çağrıyı kaydedin: araç, girdileri ve çıktıları, hatalar, süre, ait olduğu vaka ve çalıştırma, prompt ve model sürümleri. Tuhaf bir çalıştırmada hatayı ayıklamak, bir denetçiye yanıt vermek ve bir sonraki değerlendirme vakalarını bulmak için bu kayda başvurursunuz.

## Araçlar modelle birlikte nasıl test edilir?

Önce modelsiz. Her aracın doğrulamasını, yetkilerini, tekrara dayanıklılığını (iki kez çağırarak) ve hata mesajlarını, her API’de olduğu gibi birim testleriyle sınayın.

Ardından modelle birlikte, test sistemlerine bağlı bir test ortamında (sandbox). Gerçekçi görevlerden oluşan bir listeyi birkaç kez çalıştırın, çünkü yollar çalıştırmadan çalıştırmaya değişir. Şunları kontrol edin:

- **Seçim.** Ajan doğru aracı seçti mi, yanlış araçlara dokunmadı mı?
- **Argümanlar.** Geçerli ve doğru muydu?
- **Toparlanma.** Zaman aşımları, eksik kayıtlar ve yetki hataları yaratın. Ajan toparlanabiliyor ya da işi düzgünce bir insana aktarabiliyor mu?
- **Kötüye kullanım.** Talep metnine, görevin ihtiyaç duymadığı bir aracı isteyen talimatlar yerleştirin; [prompt enjeksiyonuna karşı hangi savunmaların işe yaradığını anlatan nottaki](https://veridive.com/tr/saha-notlari/prompt-enjeksiyonu-savunmalari/) gibi.

Yanlış araç ve geçersiz argüman oranlarını, görev başına adım sayısını ve insana yapılan aktarımları izleyin; başarısız çalıştırmaları değerlendirme vakası olarak saklayın.

## Mevcut araçlar nasıl denetlenir?

Ajanınızın çağırabileceği her aracı listeleyin. Her biri için en kötü durumu yazın: yanlış argümanlarla çağrılırsa, iki kez çağrılırsa ya da enjekte edilmiş bir talimat yüzünden çağrılırsa ne olur? En kötü durumunu kabul edemeyeceğiniz her aracı daraltın. Araç tasarımı, [koruma önlemi sorularının](https://veridive.com/tr/nasil-calisiyoruz/#guardrails) koda dönüştüğü yerdir ve [özel yapay zeka yazılımı](https://veridive.com/tr/hizmetler/ozel-yapay-zeka-yazilimi/) olarak geliştirdiğimiz, sınırları belli ajanların merkezinde durur.

## Sık sorulan sorular

### Bir yapay zeka ajanı için iyi bir araç nasıl olmalı?

İyi bir araç tek ve dar bir iş yapar; ne zaman kullanılacağını ve ne zaman kullanılmayacağını açıkça anlatan bir açıklaması vardır. Parametreleri mümkün olduğunca sabit seçeneklerden oluşur ve ajanın kendi hesabı altında en az yetkiyle çalışır. İki kez çağrıldığında zarar vermez; başarısız olduğunda da modele bir sonraki adımda ne yapacağını söyleyen bir mesaj döndürür.

### LLM’lerde function calling nedir?

Function calling ya da diğer adıyla tool calling (araç çağırma) sayesinde bir dil modeli, yazılımınızdan bir işlem talep edebilir. Model her aracın adını, açıklamasını ve parametre şemasını okur, bir çağrının işe yarayıp yaramayacağına karar verir ve argümanları yazar; aracı kodunuz çalıştırır ve sonucu geri verir. Model hiçbir şeyi kendisi çalıştırmaz; bu yüzden sınırlar her aracın arkasındaki kodda olmalıdır.

### Bir yapay zeka ajanının bir işlemi tekrarlaması nasıl önlenir?

Her yazma işlemini tekrarlandığında zarar vermeyecek biçimde tasarlayın. Her çağrıya vakadan ve işlemden türetilen bir idempotency anahtarı verin; aynı anahtarla gelen ikinci çağrı, işlemi yeniden yapmak yerine ilk sonucu döndürsün. Bir değeri artıran işlemler yerine değeri atayan işlemleri tercih edin ve nihai işlemler yerine bir insanın onaylayacağı taslaklar oluşturun.

## Kaynaklar

1. LLM06:2025 Excessive Agency. OWASP Gen AI Security Project. https://genai.owasp.org/llmrisk/llm062025-excessive-agency/
2. LLM01:2025 Prompt Injection. OWASP Gen AI Security Project. https://genai.owasp.org/llmrisk/llm01-prompt-injection/