एजेंटिक फ़ॉर्म

Declarative API, एट्रिब्यूट की मदद से स्टैंडर्ड एचटीएमएल <form> एलिमेंट को WebMCP टूल में बदल देता है. ब्राउज़र, फ़ॉर्म के इनपुट से JSON स्कीमा बनाता है और एजेंट के इंटरैक्शन को मैनेज करता है.

Angular Signal Forms: @angular/forms/signals के form() से बनाए गए फ़ॉर्म में toolname/tooldescription न जोड़ें. इसके बजाय, ऐप्लिकेशन प्रोवाइडर में provideExperimentalWebMcpForms() जोड़ें और form() को experimentalWebMcpTool: { name, description } विकल्प पास करें. इसके बाद, Angular इंपेरेटिव एपीआई के ज़रिए फ़ॉर्म को रजिस्टर करता है. साथ ही, सिग्नल मॉडल से स्कीमा बनाता है और उसे पुष्टि और सबमिशन के लिए वायर करता है. दोनों तरीकों का इस्तेमाल करने पर, एक ही फ़ॉर्म दो बार रजिस्टर हो जाता है.

फ़ॉर्म के एट्रिब्यूट

• toolname: टूल का यूनीक नाम.
• tooldescription: टूल क्या काम करता है और एजेंट को इसका इस्तेमाल कब करना चाहिए. फ़ॉर्म के फ़ील्ड, विकल्प या सीमाएं न डालें: ब्राउज़र, फ़ॉर्म कंट्रोल से बनाए गए स्कीमा में उन्हें पहले से शामिल करता है.
• toolautosubmit: (ज़रूरी नहीं) अगर यह मौजूद है, तो एजेंट उपयोगकर्ता के इंटरैक्शन का इंतज़ार किए बिना फ़ॉर्म सबमिट कर सकता है.
• toolparamdescription: (ज़रूरी नहीं) JSON स्कीमा में प्रॉपर्टी का ब्यौरा देने का तरीका उपलब्ध कराता है. इसका इस्तेमाल करके, वैल्यू का मतलब बताएं. उदाहरण के लिए, सैंपल वैल्यू का इस्तेमाल करें. कंट्रोल के विकल्पों या सीमाओं को दोहराने के लिए इसका इस्तेमाल न करें.
  • रिज़ॉल्यूशन ऑर्डर: अगर toolparamdescription मौजूद है, तो ब्राउज़र इसका इस्तेमाल करता है. अगर यह मौजूद नहीं है, तो यह उससे जुड़े <label> के textContent का इस्तेमाल करता है. हालांकि, यह लेबल किए जा सकने वाले डिसेंडेंट को छोड़ देता है. अगर कोई लेबल मौजूद नहीं है, तो यह aria-description पर वापस चला जाता है.
  • ग्रुप बनाना (फ़ील्डसेट): मिलते-जुलते एलिमेंट (जैसे, <input type="radio"> बटन) के ग्रुप में ब्यौरा जोड़ने के लिए, toolparamdescription को सबसे नज़दीकी पैरंट <fieldset> एलिमेंट पर रखें, ताकि यह पूरे पैरामीटर ग्रुप पर लागू हो.

उदाहरण

<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 में सबमिशन मैनेज करना

जब कोई एजेंट फ़ॉर्म सबमिट करता है, तो SubmitEvent में agentInvoked (बूलियन) और respondWith(promise) शामिल होते हैं.

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);
  }
});

लाइफ़साइकल इवेंट

document.modelContext, एजेंट के किसी टूल के साथ इंटरैक्ट करना शुरू करने या बंद करने पर इवेंट ट्रिगर करता है: टूल का इस्तेमाल शुरू होने पर toolactivated ट्रिगर होता है और टूल का इस्तेमाल रद्द होने पर toolcancel ट्रिगर होता है.

// 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.`);
});

विज़ुअल फ़ीडबैक (सीएसएस)

जब कोई एजेंट फ़ॉर्म के साथ इंटरैक्ट करता है, तो फ़ॉर्म को हाइलाइट करने के लिए सूडो-क्लास का इस्तेमाल करें:

• :tool-form-active: एजेंट के इस्तेमाल किए जा रहे <form> एलिमेंट पर लागू किया गया.
• :tool-submit-active: जब ब्राउज़र, उपयोगकर्ता की समीक्षा के लिए रुकता है, तब 'सबमिट करें' बटन पर लागू होता है (अगर toolautosubmit को शामिल नहीं किया गया है).

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;
}

फ़ॉर्म का इस्तेमाल कब करना चाहिए और कब नहीं

डिक्लेरेटिव एपीआई, स्टैंडर्ड फ़ॉर्म के लिए सबसे सही है. इन स्थितियों में यह विकल्प सही नहीं है:

• एक-दूसरे पर निर्भर फ़ील्ड: ऐसे फ़ॉर्म जिनमें एक फ़ील्ड में डाले गए इनपुट के आधार पर, दूसरे फ़ील्ड के विकल्प या उनकी विज़िबिलिटी बदल जाती है. सिंथसाइज़्ड स्कीमा, इन डिपेंडेंसी को अच्छी तरह से नहीं दिखा सकता.
• कस्टम यूज़र इंटरफ़ेस (यूआई) कॉम्पोनेंट: ऐसे फ़ॉर्म जो स्टैंडर्ड इनपुट पर निर्भर नहीं होते (जैसे, कैनवस, रिच टेक्स्ट एडिटर) और वैल्यू को अपने-आप क्रम में नहीं लगाते.
• कई चरणों वाले विज़र्ड: ऐसे जटिल वर्कफ़्लो जिनमें कई फ़ॉर्म सबमिट करने की ज़रूरत होती है. यहां इंपेरेटिव एपीआई या स्टैंडर्ड डीओएम इंटरैक्शन का इस्तेमाल करना बेहतर रहेगा.

टूलऑटोसबमिट का इस्तेमाल कब करना चाहिए

• सिर्फ़ पढ़ने के लिए उपलब्ध कार्रवाइयां और क्वेरी: खोजना, फ़िल्टर करना, जानकारी फ़ेच करना या स्थिति देखना. जैसे, कार का कोई मॉडल खोजना, डायरेक्ट्री खोजना, स्टॉक की उपलब्धता देखना.
• कम जोखिम वाली और पहले जैसी की जा सकने वाली कार्रवाइयां: फ़ॉर्म से जुड़ी ऐसी कार्रवाइयां जिन्हें उपयोगकर्ता आसानी से पहले जैसा कर सकता है या मैन्युअल तरीके से बेहतर बना सकता है. जैसे, कार्ट में आइटम जोड़ना, कूपन कोड लागू करना, ड्राफ़्ट सेव करना या लेआउट के कुछ समय के लिए उपलब्ध विकल्पों को सेट करना.

toolautosubmit को कब शामिल नहीं करना चाहिए

• नुकसान पहुंचाने वाली या पहले जैसी न की जा सकने वाली कार्रवाइयां: रिकॉर्ड मिटाना, सिस्टम कॉन्फ़िगरेशन रीसेट करना या डेटाबेस मिटाना.
• वित्तीय और लेन-देन से जुड़ी कार्रवाइयां: चेकआउट फ़ॉर्म सबमिट करना, फ़ंड ट्रांसफ़र करना, सदस्यता के पेमेंट की अनुमति देना या ऑर्डर पूरा करना.
• उपयोगकर्ता के साथ असरदार तरीके से बातचीत करना: नौकरी के लिए फ़ाइनल आवेदन सबमिट करना, अन्य असली उपयोगकर्ताओं को ईमेल/मैसेज भेजना या सार्वजनिक तौर पर उपलब्ध कॉन्टेंट पब्लिश करना.
• खाते की संवेदनशील सेटिंग: पासवर्ड बदलना, उपयोगकर्ता की भूमिकाओं/अनुमतियों में बदलाव करना या बिलिंग/प्रोफ़ाइल की जानकारी अपडेट करना.

फ़ॉलबैक रणनीतियां

WebMCP Declarative API का इस्तेमाल सभी ब्राउज़र में सुरक्षित है. WebMCP के साथ काम न करने वाले ब्राउज़र, tool* एट्रिब्यूट को अनदेखा कर देंगे. साथ ही, <form> सामान्य एचटीएमएल फ़ॉर्म की तरह काम करता रहेगा. सुविधा की पहचान करने की ज़रूरत नहीं है.