DEV Community

Cover image for Yapay Zeka Ajanları İçin Doğru Uç Nokta Seçimi: Araç Şeması Tasarımı
Tobias Hoffmann
Tobias Hoffmann

Posted on Originally published at apidog.com

Yapay Zeka Ajanları İçin Doğru Uç Nokta Seçimi: Araç Şeması Tasarımı

Yapay Zeka Ajanlarında Araç Seçimini Güvenilir Hale Getirme

Ajanınıza updateUser ve deactivateUser araçlarını verdiniz. Bir destek talebinde “bu hesabı kapatın” yazıyor; ajan deactivateUser çağrısını yapıyor. Ancak geçen hafta neredeyse aynı talepte updateUser aracını status: "closed" ile çağırdı. API bunu kabul etti, fakat akışın devamında farklı bir anlama geldi. Model bozuk değildi: açıklamaları iki makul seçenek arasında yeterince ayrım yapmıyordu. Araçlarınız bir spesifikasyondan oluşturuluyorsa, örneğin OpenAPI belirtimini ajan araçlarına dönüştürme yaklaşımında olduğu gibi, düzeltmeniz gereken yer doğrudan spesifikasyondur. Araç açıklamalarını Apidog içinde iyileştirmek, dokümantasyonu ve ajan araçlarını birlikte iyileştirir.

Apidog'u bugün deneyin

Ajan araçları ve araç seçimi diyagramı

Model ne görüyor?

Araç seçimi sırasında model yalnızca şunları görür:

  • Konuşma geçmişi
  • Sistem istemi
  • Araç adı
  • Araç açıklaması
  • Parametre şeması

API dokümantasyonunuz, kod yorumlarınız veya ekipteki geleneksel bilgiler modele görünmez. Bu nedenle belirsizliği araç tanımına yazmalısınız.

Hem OpenAI işlev çağırma rehberi hem de Anthropic araç kullanımı dokümantasyonu, açıklamanın araç tanımındaki en kritik metin olduğunu vurgular.

Dört yaygın hata tür araç çağırmak yerine hafızasından yanıt verir | Kullanıcıların kullandığı ifadeleri ekleyin |
| Belirsiz parametreler | Doğru araç, yanlış argümanlarla çağrılır | Tür, enum, birim ve örnek kullanın |
| Eksik sıra bilgisi | Model araçları yanlış sırada zincirler | Önkoşulları açıklamaya yazın |

Araçları yaptıkları işe göre adlandırın

Araç adları modelin ilk okuduğu sinyaldir. Tüm sette aynı fiilİsim biçimini kullanın:

createOrder
refundOrder
getOrderStatus
Enter fullscreen mode Exit fullscreen mode

Belirsiz isimlerden kaçının:

search
list
query
Enter fullscreen mode Exit fullscreen mode

Bunun yerine nesneyi ve arama yöntemini belirtin:

searchCustomersByEmail
getOrderById
listActiveSubscriptions
Enter fullscreen mode Exit fullscreen mode

Aşağıdaki ilkeler önemlidir:

  • Araç listesinin tamamında aynı adlandırma stilini kullanın.
  • Dahili jargonu değil, görev dilini kullanın.
  • Bir adı farklı bağlamlarda yeniden kullanmayın.
  • Aynı araç listesinde iki farklı list aracı bulundurmayın.

Örneğin API’niz “varlık” dese bile kullanıcı “müşteri” diyorsa, araç adı getCustomer olmalıdır.

Ayırt edici açıklamalar yazın

İyi bir açıklama dört soruyu cevaplar:

  1. Ne yapar?
  2. Neyi değiştirir?
  3. Ne zaman kullanılır?
  4. Ne zaman kullanılmaz?

Zayıf açıklamalar:

{
  "name": "updateUser",
  "description": "Bir kullanıcıyı günceller."
}
Enter fullscreen mode Exit fullscreen mode 
{
  "name": "deactivateUser",
  "description": "Bir kullanıcıyı devre dışı bırakır."
}
Enter fullscreen mode Exit fullscreen mode

Ayırt edici açıklamalar:

{
  "name": "updateUser",
  "description": "Ad, e-posta veya saat dilimi gibi aktif bir kullanıcının profil alanlarını günceller. Kullanıcı tarafından talep edilen düzeltmeler ve profil düzenlemeleri için kullanın. Hesap durumunu DEĞİŞTİRMEZ. Bir hesabı devre dışı bırakmak için bunun yerine deactivateUser kullanın. Bir hesabı kapatmak veya iptal etmek için kullanmayın."
}
Enter fullscreen mode Exit fullscreen mode 
{
  "name": "deactivateUser",
  "description": "Bir kullanıcı hesabını devre dışı bırakır, tüm oturumları iptal eder ve oturum açmayı engeller. reactivateUser ile geri alınabilir. Bir müşteri hesabını kapatmak, iptal etmek, duraklatmak veya askıya almak istediğinde kullanın. Verileri SİLMEZ. Kalıcı silme için deleteUser kullanın, bu geri alınamaz."
}
Enter fullscreen mode Exit fullscreen mode

Bu açıklamalar dört önemli teknik uygular:

  • Kardeş aracı adlandırır: “Bunun yerine deactivateUser kullanın” ifadesi doğrudan çakışmayı giderir.
  • Kullanıcının kelimelerini içerir: “Kapat”, “iptal et”, “duraklat” ve “askıya al” gibi ifadeler kullanıcı talepleriyle eşleşir.
  • Yapmadığı şeyi belirtir: Negatif ifadeler, benzer araçları ayırmak için özellikle değerlidir.
  • Geri alınabilirliği açıklar: Riskli işlemleri görünür hale getirir.

Yıkıcı bir uç noktaya yanlış çağrıyı önleyen yüz kelimelik açıklama pahalı değildir. Gerçek koruma ise yapay zeka ajan korumaları gibi uygulama katmanındaki önlemlerle sağlanmalıdır.

Yanlış argümanları zorlaştıracak parametreler tasarlayın

Doğru araç seçildikten sonra sıradaki hata kaynağı argümanlardır. JSON Schema, gerekli kısıtların çoğunu sağlar. Desteklenen anahtar sözcükler için JSON Schema doğrulama sözlüğünü inceleyin.

Kapalı değer kümelerinde enum kullanın

Serbest metin status değerleri modelin değer uydurmasına yol açar:

"status": {
  "type": "string",
  "enum": ["pending", "paid", "refunded", "cancelled"],
  "description": "Sipariş durumu. 'cancelled' asla yerine getirilmedi anlamına gelir; 'refunded' yerine getirildi ve sonra tersine çevrildi anlamına gelir."
}
Enter fullscreen mode Exit fullscreen mode

Birimleri parametre adına ekleyin

Şu isim belirsizdir:

amount
Enter fullscreen mode Exit fullscreen mode

Bunun yerine:

amount_cents
timeout_seconds
distance_meters
duration_ms
Enter fullscreen mode Exit fullscreen mode

kullanın.

Tarih formatını örnekle belirtin 

{
  "description": "ISO 8601 formatında başlangıç tarihi, örneğin 2026-08-26"
}
Enter fullscreen mode Exit fullscreen mode

Bu yaklaşım, yalnızca “başlangıç tarihi” açıklamasından daha güvenilir biçimlendirilmiş tarihler üretir.

required listesini dürüst tutun

  • Gerçekte gerekli olan alanları isteğe bağlı yapmak, hatayı çalışma zamanına iter.
  • API’nin varsayılanla doldurabildiği alanları zorunlu yapmak, modelin değer uydurmasına neden olur.

Bu doğrulama hataları, ajanlar için API hata tasarımı yaklaşımında ele alınmalıdır.

Düz şemaları tercih edin

İç içe yapı:

{
  "customer": {
    "address": {
      "postal_code": "..."
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Ajanlar için daha fazla yapısal hata üretir. Araç sınırında mümkünse düzleştirin:

{
  "customer_postal_code": "..."
}
Enter fullscreen mode Exit fullscreen mode

Ardından yürütücü katmanında tekrar birleştirin.

Aşırı yüklenmiş araçları bölün

Diğer parametrelerin anlamını değiştiren bir mode alanı varsa, büyük olasılıkla tek araç değil iki araç tasarlıyorsunuzdur. Bölmek hem araç seçimini hem de şemaları iyileştirir.

Önkoşulları ve sırayı açıklayın

Çok adımlı işlerde model sırayı bilmezse adımları atlayabilir. Önkoşulu bağımlı aracın açıklamasına yazın:

{
  "name": "captureCharge",
  "description": "Daha önce yetkilendirilmiş bir ödemeyi yakalar. authorizeCharge'dan bir authorization_id gerektirir. Halihazırda yoksa önce authorizeCharge'ı çağırın. Yetkilendirilmiş miktardan daha fazlasını yakalayamaz."
}
Enter fullscreen mode Exit fullscreen mode

Bu kalıp her yerde uygulanabilir:

  • Güncellemeden önce oluşturun.
  • İşlemden önce yükleyin.
  • Yakalamadan önce yetkilendirin.
  • Bağımlı adımın açıklamasında önceki adımı açıkça adlandırın.

Sıra birden fazla ajanı kapsıyorsa, alt ajanlar arasında bağlam geçirme için devir kurallarını uygulayın.

Araç seçimini test edin

Açıklamalar da kod gibi gerileyebilir. Birisi açıklamayı kısalttığında, ajan sonraki sürümde yanlış uç noktayı seçmeye başlayabilir.

Küçük bir araç seçimi paketi oluşturun:

  1. 20–50 kullanıcı istemi hazırlayın.
  2. Her istem için beklenen araç adını kaydedin.
  3. Testleri sahte veriler üzerinde çalıştırın.
  4. Yalnızca seçilen araç adını doğrulayın.
  5. Her istemi birkaç kez çalıştırın.

Argümanlar çalıştırmalar arasında değişebilir; araç seçimi değişmemelidir.

Araç seçimini sahte verilerle test etme görseli

Test paketinize özellikle şunları ekleyin:

  • Birbirine en çok benzeyen iki aracı ayırması gereken istemler
  • API dili yerine müşteri dili kullanan istemler
  • Hiçbir araçla eşleşmemesi gereken istemler
  • Yanlış çağrının maliyetli olduğu yıkıcı işlemler

Beş denemeden dördünde doğru aracı seçen bir açıklama, üretimde güvenilir değildir. Seçim testlerini canlı veriden uzak tutmak için ajanları üretim yerine sahte verilere karşı çalıştırın. Apidog, araçların üretildiği aynı tanımdan sahte veriler sunarak şema ve davranışın uyumlu kalmasına yardımcı olur.

Sık yanlış giden üç araç seti

CRUD seti

Bir API şu araçları açığa çıkarıyorsa:

getUser
listUsers
searchUsers
queryUsers
Enter fullscreen mode Exit fullscreen mode

model bunları aynı fikrin dört farklı adı olarak görebilir. Çözüm dört açıklamayı uzatmak değildir; ajana yalnızca gerekli aracı sunmaktır. Küratörlü bir araç seti, eksiksiz bir araç setinden daha güvenilirdir.

Yönetici seti

Şu araçlar aynı tonda tanımlanırsa:

getInvoice
voidInvoice
deleteInvoice
Enter fullscreen mode Exit fullscreen mode

yıkıcı işlemlerin riski görünmez olur. Açıklamaya sonucu ekleyin, onay gereksinimini işaretleyin ve gerçek korumayı yürütücüde uygulayın. Katmanlı yaklaşım için ajanların API'nizi yok etmesini önleme rehberini izleyin.

Eski araç seti

İki uç nokta aynı işi yapıyor ve biri kullanımdan kaldırılmışsa, eski aracı listeden kaldırın. Bu mümkün değilse açıklamayı şu ifadeyle başlatın:

Kullanımdan kaldırıldı. Bunun yerine createOrderV2 kullanın.
Enter fullscreen mode Exit fullscreen mode

Modeller bu uyarıyı açıklamanın başında olduğunda daha güvenilir biçimde dikkate alır.

Açıklamaları paylaşılan yapılandırma olarak yönetin

Araç açıklamalarını bir kişinin yerel dosyasındaki ayar olarak değil, gözden geçirilebilir ortak bir yapılandırma olarak ele alın.

Örneğin bir Sharkly Ajansı; talimatları, Çalışma Zamanını, Becerileri ve depolama alanlarını içeren kaydedilmiş bir yapılandırmadır. Bir Alan içinde paylaşılması, bir kişinin çalışma düzenini ekibin yeniden kullanabileceği hale getirir.

Asıl değer depolama değildir. Bir açıklama değişikliğinin, yalnızca tek bir geliştiricinin ajan davranışını değiştiren gizli yerel ayar yerine, herkesi etkileyen incelenebilir bir değişiklik olmasıdır.

Kullanıcıların gerçek dilini izleyin

Araç seçimindeki en yaygın eksik, kelime dağarcığıdır.

API dili Kullanıcı dili
abonelik plan, üyelik, faturalama
devre dışı bırak iptal et, kapat, askıya al

Destek taleplerinden, arama günlüklerinden ve başarısız ajan çalıştırmalarından en sık kullanılan ifadeleri toplayın. Ardından bu ifadeleri eşleşmesi gereken araç açıklamalarına ekleyin.

Bir ajan hiçbir araç seçmeden kendi bilgisinden cevap veriyorsa, bu genellikle muhakeme hatası değil kelime dağarcığı eksikliğidir: görev dili, araç metniyle eşleşmiyordur.

Kontrol listesi

  • [ ] İsimler tek bir fiilİsim kuralına uyuyor ve belirli nesneleri adlandırıyor.
  • [ ] Her açıklama neyin değiştiğini, ne zaman kullanılacağını ve ne zaman kullanılmayacağını belirtiyor.
  • [ ] Çakışan araçlar birbirini açıkça adlandırıyor.
  • [ ] Açıklamalar, yalnızca dahili terimleri değil kullanıcıların gerçek kelimelerini de içeriyor.
  • [ ] Yıkıcı ve geri döndürülemez eylemler açıkça belirtiliyor.
  • [ ] Tüm kapalı değer kümeleri enum ile tanımlanıyor.
  • [ ] Birimler ve biçimler adlarda veya açıklamalarda örnekleriyle yer alıyor.
  • [ ] required listeleri API’nin gerçek davranışıyla eşleşiyor.
  • [ ] Bağımlı araçlar önkoşullarını açıkça adlandırıyor.
  • [ ] CI içinde sahte verilere karşı çalışan bir seçim paketi bulunuyor.

Model, yazdığınız metne göre desen eşleştirmesi yapar. Yanlış aracı seçtiğinde ilk bakmanız gereken yer açıklamadır. Açıklamaları, sahte verileri ve testleri aynı projede yönetmek için Apidog'u indirin.

Sıkça Sorulan Sorular

Bir araç açıklaması ne kadar uzun olmalı?

Belirsizliği giderecek kadar uzun olmalıdır; bu çoğu zaman iki ila beş cümledir. Belirsiz olmayan araçlarda kısa kalın, birbirine yakın araçlarda daha fazla bağlam kullanın.

Açıklamaya örnek koymalı mıyım?

Evet. Özellikle tarih biçimleri ve birimler için tek örnek, tüm bir hata sınıfını ortadan kaldırabilir. Ancak uzun kullanım senaryolarından kaçının; bağlam maliyetini artırırlar ve araç seçimini nadiren iyileştirirler.

Çok sayıda dar araç mı, az sayıda esnek araç mı daha iyidir?

Bir noktaya kadar dar araçlar daha iyidir; her biri tek bir işi yaptığı için daha güvenilir seçilir. Ancak birkaç düzineden sonra listenin kendisi sorun olur. Bu durumda OpenAPI'den ajan araçları oluşturma yaklaşımındaki gibi filtreleme veya araç alma uygulayın.

Araç seçimini sistem isteminde düzeltebilir miyim?

Kısmen. Bir veya iki bilinen çakışma için geçici çözüm olabilir. Ancak sistem istemi tüm araçlar arasında paylaşılır; açıklama ise ihtiyacı olan araçla birlikte yaşar ve daha iyi ölçeklenir.

Model parametre değerleri uydurmaya devam ederse ne yapmalıyım?

Türü kısıtlayın, enum ekleyin ve değerin oluşturulmak yerine önceki bir çağrıdan gelmesi gerektiğini belirtin. Sorun sürerse sarmalayıcıda doğrulama yapın ve izin verilen değerleri içeren bir hata döndürün.

Bu kurallar MCP sunucuları için de geçerli mi?

Evet. MCP sunucuları da isimleri, açıklamaları ve şemaları açığa çıkarır; bu nedenle aynı ifade kuralları geçerlidir. Protokolün kendisi için MCP'nin ne olduğu açıklamasına bakın.

Top comments (0)