WebMCP ile ilgili en iyi uygulamalar

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Yayınlanma tarihi: 18 Mayıs 2026

WebMCP aracı beyanı net olmalı, geliştiricilerin veya temsilcilerin çıktıları inceleyip yeniden denemesi gerekmemelidir. İster Imperative API'yi ister Declarative API'yi kullanın, aşağıdaki en iyi uygulamalardan yararlanın:

  • Geliştirmeden önce bir araç stratejisi oluşturun.
  • Açık bir dil ve semantik HTML kullanın.
  • Şemalarınızı tasarlayın ve girişi işleyin.
  • Güvenilir araçlar oluşturun.
  • Test edin ve hata ayıklayın.

Araç stratejisi oluşturma

Herhangi bir yazılım uygulamasında olduğu gibi, ilk adımınız araç stratejinizi planlamak olmalıdır:

  • Her araç tek bir işlevden oluşmalıdır. Örneğin, bir araç kullanıcıyı belirli bir form türüne yönlendirebilirken başka bir araç, giriş alanlarını kullanıcı bilgileriyle eşleştirmelidir. Ajanın hangi aracı kullanacağı konusunda kafası karışabileceği için çakışan araçlar oluşturmamaya dikkat edin. Kendinize şu soruyu sorun: Aynı işlevle birden fazla görevi kapsayabilir miyim?
  • Araç kaydını yönetme. Araçları belirli bir sayfa durumunda yararlı olduklarında kaydedin, artık kullanılamadıklarında ise kaydını silin.
    • Imperative API: Kaydı registerTool ile dinamik olarak yönetebilirsiniz.
    • Bildirim Temelli API: toolname ve tooldescription ile bir forma araç özellikleri ekleyerek veya kaldırarak kaydı dinamik olarak yönetebilirsiniz.
  • Karmaşıklığı azaltın: Çoğu uygulama için varsayılan yaklaşım statik kayıt olmalıdır.
  • Görevi tamamlaması için ajana güvenin. Katı veya olumsuz talimatlar yazmak yerine, aracının görevi tamamlamak için ne gerektiğini anlayabileceğini varsayın. Aracının adımların tam akışını yönetmesini beklemeyin.

İzin verilen maksimum araç sayısı olmasa da her araç, bağlam penceresinin bir kısmını kaplar ve tamamlanma süresini uzatır. Ne kadar çok araç sağlarsanız ve araçlar ne kadar çok örtüşürse temsilcinin doğru seçimi yapması o kadar zor olur. Uygulamanız için doğru olanı belirlemek üzere denemeler yapın.

Bu sayede, amacı çakışmayan bireysel araçlar oluşturabilir ve bu araçların ne zaman kullanılabileceğini yönetebilirsiniz.

Net bir dil ve semantik kod kullanın

Araçları adlandırırken ve kullanımlarını açıklarken açık ve doğrudan bir dil kullanın. Bu sayede, temsilciler ihtiyaç duydukları bilgileri bulabilir, bulduklarını anlayabilir ve bu bilgileri geliştiricinin beklediği şekilde kullanabilir.

Araç adlarını yazarken yürütme ile başlatma arasındaki farkı belirtin ve tam olarak ne olduğunu açıklayan fiiller kullanın. Örneğin, create-event anında etkinlik oluşturmaya yarayan bir araçtır ancak start-event-creation-process, kullanıcıyı etkinliği oluşturmak için bir forma yönlendiren bir araçtır.

Net bir açıklama, aracın ne işe yaradığını ve ne zaman kullanılması gerektiğini açıklamalıdır. Sınırlamalar gibi olumsuz ifadeler yerine olumlu ifadeler ve tercihler kullanın.

Yapılmaması gerekenler:

"Bu aracı hava durumu için kullanmayın."

Sınırlamalar, iyi yazılmış bir açıklamada belirtilmelidir.
Yapılması gerekenler

"Bu araç, belirli bir tarih ve saat için planlanmış bir takvim etkinliği oluşturabilir."

Bilişsel bilişimi en aza indirme

Karmaşık görevleri tamamlayan insanlar için bilişsel yükü en aza indirmeniz gerektiği gibi, model için de bilişsel hesaplamayı en aza indirmeniz gerekir:

  • Ham kullanıcı girişini kabul etme. Aracıdan matematik işlemi yapmasını veya giriş dizelerini dönüştürmesini istemeyin. Örneğin, bir kullanıcı "11:00-15:00" derse araç bunu dize olarak kabul etmelidir. Modelden bu saatler arasındaki dakikaları hesaplamasını istemeyin.
  • Dize, sayı veya enum gibi parametreler için belirli türler bildirin.
  • Belirli seçimleri neden yaptığınızı açıklayın. Yaptığınız seçim kendi kendini açıklayacak nitelikte olmalıdır. Neden sorusu, temsilcilerin daha iyi seçimler yapmasına yardımcı olur. Örneğin, bir e-ticaret mağazası işletiyorsanız kargo türünü belirsiz bir kimlik kullanmak yerine doğal dilde belirtin: shipping_id=1 yerine shipping="Express".

Güvenilirliğe öncelik verin

Aşağıdaki gibi beklentilere uygun şekilde çalışan araçlar hem temsilcilere hem de kullanıcılara fayda sağlar:

  • Hız sınırları için sorunsuz hata ayarlayın. Araçlar, fiyat karşılaştırması gibi durumlarda makul tekrarlara izin vermelidir. Bir araç hız sınırlamasına tabi tutuluyorsa anlamlı bir hata döndürün veya kullanıcıya görevi manuel olarak üstlenmesini tavsiye edin.
  • İşlevler tamamlandıktan sonra arayüz durumunu güncelleyin. Müşteri temsilcileri, sonraki adımları planlamak için arayüze güvenebilir. Ancak işlevlerin tamamlanması, arayüzün yüklenmesinden daha uzun sürebilir. Arayüz güncellendikten sonra temsilci, işlevin tamamlandığını onaylamalı veya tekrar güncelleme isteğinde bulunmalıdır.
  • Kodda katı, şemada gevşek doğrulama. İkili mantığa sahip işlevler ve kodlar için kısıtlamalar ve testler kullanılmalıdır. Şema kısıtlamaları faydalı olsa da garanti edilmez. Modelin kendini düzeltmesine ve yeni, geçerli parametrelerle yeniden denemesine olanak tanımak için fonksiyon kodunuza açıklayıcı hatalar ekleyin.

Değerlendirme testi ve hata ayıklama

Değerlendirme testleri oluşturun ve araçlarınızı hata ayıklama için kullanılabilir hale getirin. Deterministik birim testlerinin aksine, çıkışlar beklenmedik biçimlerde olabileceğinden değerlendirmeler sabit kodlanamaz.

  • Sorunu tanımlayın. Giriş türü, çıkış biçimi ve ek kısıtlamalar da dahil olmak üzere sorununuzu bir API sözleşmesi gibi çerçeveleyebilirsiniz.
  • Bir temel performans ve ideal sonuç tanımlayın. Özellikle metin girişiyle ilgili olarak, beklediğiniz çıktıyı hangi sonuç türlerinin verebileceğini anlamanız önemlidir.
  • Çıktının nasıl değerlendirileceğini belirleyin. Giriş kalitesi, fayda ve sonraki görevi tamamlama becerisine dayalı olarak öznel ve niteliksel sonuçları belirleyip ölçüyor olabilirsiniz. Çıkışı değerlendirmek için kullanabileceğiniz çeşitli teknikler vardır. Bunlar arasında kural tabanlı çıkışlar (karakter sınırları) için kod tabanlı kontroller ve LLM-as-a-judge yer alır.

Belirli bir modeldeki sorunları düzeltmek için dar kurallar eklemekten kaçının. Örneğin, hitap şekilleri için bir seçim alanı eklerseniz model yanlış seçim yapabilir. Bu sorunu düzeltmek için dar kurallar eklemek yerine aracınızı soyutlayın ve ayarlayın. Bu alanı isteğe bağlı olarak ayarlamanız en iyi seçenek olabilir. Ardından, kullanıcının sonuçtan memnun kalmasını sağlamak için temsilciden kullanıcıya hangi seçeneğin mantıklı olduğunu sormasını isteyin.

Etkileşim kurma ve geri bildirim paylaşma

WebMCP aktif olarak tartışılmaktadır ve gelecekte değişebilir. Bu API'leri denerseniz geri bildiriminizi bizimle paylaşmanızı rica ederiz.