Temsilci Tabanlı Formlar

Declarative API, standart HTML <form> öğelerini özellikler aracılığıyla WebMCP araçlarına dönüştürür. Tarayıcı, form girişlerinden bir JSON şeması oluşturur ve temsilci etkileşimlerini yönetir.

Angular Signal Forms: @angular/forms/signals'ten form() ile oluşturulan formlara toolname/tooldescription EKLEMEYİN. Bunun yerine, uygulama sağlayıcılarına provideExperimentalWebMcpForms() ekleyin ve experimentalWebMcpTool: { name, description } seçeneğini form() öğesine iletin. Ardından Angular, formu Imperative API aracılığıyla kaydeder, şemayı sinyal modelinden oluşturur ve doğrulama ile gönderme işlemlerine bağlar. Her iki yaklaşımı da kullanmak aynı formu iki kez kaydeder.

Form Özellikleri

• toolname: Aracın benzersiz adı.
• tooldescription: Aracın ne işe yaradığı ve bir temsilcinin bu aracı ne zaman kullanması gerektiği. Formun alanlarını, seçeneklerini veya sınırlarını listelemeyin: Tarayıcı, form kontrollerinden oluşturduğu şemaya bunları zaten dahil eder.
• toolautosubmit: (İsteğe bağlı) Varsa temsilci, kullanıcı etkileşimini beklemeden formu gönderebilir.
• toolparamdescription: (İsteğe bağlı) JSON şemasında bir özellik açıklaması tanımlamanın bir yolunu sunar. Bu alanı, denetimin seçeneklerini veya sınırlarını tekrarlamak için değil, değerin ne anlama geldiğini açıklamak (ör. örnek değerlerle) için kullanın.
  • Çözümleme Sırası: Tarayıcı, varsa toolparamdescription kullanır. Bu yoksa ilişkili <label> öğesinin textContent değerini kullanır (etiketlenebilir alt öğeleri atlar). Etiket yoksa aria-description kullanılır.
  • Gruplandırma (Alan kümeleri): Bir grup ilgili öğeye (ör. <input type="radio"> düğmeleri) açıklama eklemek için toolparamdescription öğesini en yakın üst <fieldset> öğesine yerleştirerek parametre grubuna bir bütün olarak uygulanmasını sağlayın.

Örnek

<form toolname="search-cars" 
      tooldescription="Perform a car make/model search" 
      toolautosubmit>
  <label for="make">Vehicle Make</label>
  <input type="text" id="make" name="make" required>
  
  <label for="model">Vehicle Model</label>
  <input type="text" id="model" name="model" toolparamdescription="e.g., 330i, F-150" required>
  
  <button type="submit">Search</button>
</form>

JavaScript'te Gönderimleri İşleme

Temsilci formu gönderdiğinde SubmitEvent, agentInvoked (boole) ve respondWith(promise) değerlerini içerir.

document.querySelector('form').addEventListener('submit', (event) => {
  event.preventDefault();

  // Validate the form
  const formValidationErrors = myFormIsValid();

  if (formValidationErrors.length > 0) {
    if (event.agentInvoked) {
      const errorString =
        'Validation failed: ' +
        formValidationErrors
          .map((err) => `${err.field} (${err.message})`)
          .join(', ');

      event.respondWith(Promise.resolve(errorString));
    }
    return;
  }

  const resultPromise = performAsyncSearch(new FormData(event.target));

  // Return the result directly to the agent without navigation
  if (event.agentInvoked) {
    event.respondWith(resultPromise);
  }
});

Yaşam Döngüsü Olayları

document.modelContext, temsilciler bir araçla etkileşime girmeye başladığında veya etkileşimi durdurduğunda etkinlikler yayınlar: Araç yürütme işlemi başladığında toolactivated, iptal edildiğinde ise toolcancel tetiklenir.

// Starting in Chrome 156, these events are dispatched on `document.modelContext`.
// Older versions dispatch them on `window`. Feature-detect the event handler
// property to pick the right target for backward compatibility.
const targetFor = (type, listener, options) =>
  (`on${type}` in (document.modelContext ?? {}) ? document.modelContext : window)
    .addEventListener(type, listener, options);

targetFor('toolactivated', ({ toolName }) => {
  console.log(`Tool "${toolName}" started execution.`);
});

targetFor('toolcancel', ({ toolName }) => {
  console.log(`Tool "${toolName}" execution is cancelled.`);
});

Görsel Geri Bildirim (CSS)

Bir temsilci formlarla etkileşimde bulunduğunda formları vurgulamak için sözde sınıfları kullanın:

• :tool-form-active: Temsilci tarafından etkin olarak kullanılan <form> öğesine uygulanır.
• :tool-submit-active: Tarayıcı, kullanıcı incelemesi için duraklatıldığında gönder düğmesine uygulanır (toolautosubmit atlanırsa).

form:tool-form-active {
  outline: 2px dashed blue;
  background-color: rgba(0, 0, 255, 0.05);
}

button:tool-submit-active {
  outline: 2px dashed red;
  animation: pulse 2s infinite;
}

Form Uygunluğu (Ne Zaman Kaçınılmalı?)

Bildirim API'si, bağımsız ve standart formlar için en uygun seçenektir. Aşağıdaki senaryolarda ise iyi bir seçenek değildir:

• Yüksek Oranda Bağımlı Alanlar: Girişlerin, diğer girişlere göre seçenekleri veya görünürlüğü değiştirdiği formlar. Sentezlenen şema bu bağımlılıkları iyi ifade edemez.
• Özel kullanıcı arayüzü bileşenleri: Değerleri otomatik olarak serileştirmeyen standart dışı girişlere (ör. tuval, zengin metin düzenleyiciler) dayalı formlar.
• Çok adımlı sihirbazlar: Birden fazla form gönderimi gerektiren karmaşık iş akışları. Bu durumda, zorunlu API veya standart DOM etkileşimi daha uygundur.

toolautosubmit ne zaman kullanılır?

• Salt Okunur İşlemler ve Sorgular: Aramalar, filtreler, ayrıntıları getirme veya durum kontrolü (ör. araba modeli arama, dizinde arama yapma, stok durumunu kontrol etme).
• Düşük Riskli, Geri Alınabilir İşlemler: Kullanıcı tarafından kolayca geri alınabilen veya manuel olarak hassaslaştırılabilen form işlemleri (ör. sepete ürün ekleme, kupon kodu uygulama, taslak kaydetme veya geçici düzen seçenekleri ayarlama).

toolautosubmit ne zaman atlanmalıdır?

• Zarar Verici veya Geri Alınamaz İşlemler: Kayıtları silme, sistem yapılandırmalarını sıfırlama veya veritabanlarını temizleme.
• Finansal ve İşlemle İlgili İşlemler: Ödeme formu gönderme, para transferi, abonelik ödemelerini yetkilendirme veya nihai sipariş verme.
• Yüksek etkili kullanıcı iletişimi: Nihai iş başvurusu gönderme, diğer gerçek kullanıcılara e-posta/mesaj gönderme veya herkese açık içerik yayınlama.
• Hassas hesap ayarları: Şifreleri değiştirme, kullanıcı rollerini/izinlerini değiştirme veya faturalandırma/profil bilgilerini güncelleme.

Yedek stratejiler

WebMCP Declarative API, tüm tarayıcılarda güvenle kullanılabilir. WebMCP'yi desteklemeyen tarayıcılar tool* özelliklerini yoksayar ve <form> normal bir HTML formu olarak çalışmaya devam eder. Özellik algılama gerekmez.