डिक्लेरेटिव एपीआई

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky
François Beaufort
François Beaufort
GitHub

पब्लिश होने की तारीख: 18 मई, 2026

ज़्यादा जानकारी देने वाला वीडियो वेब एक्सटेंशन Chrome स्टेटस मकसद
GitHub ऑरिजिन ट्रायल ऑरिजिन ट्रायल देखें एक्सपेरिमेंट करने का इरादा

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

इस एपीआई का इस्तेमाल करने से पहले, इस्तेमाल के उदाहरणों के बारे में पढ़ें.

टूल रजिस्टर करना

अपने फ़ॉर्म में ये एचटीएमएल एट्रिब्यूट जोड़ें:

  • toolname: टूल के नाम को उसके मकसद के हिसाब से साफ़ तौर पर बताएं.
  • tooldescription: बताएं कि टूल कौनसी कार्रवाई करता है और इसका मकसद क्या है.

उदाहरण के लिए, यह फ़ॉर्म example.com/get-customer-support पर मौजूद है:

<form toolname="createSupportRequest" tooldescription="Submits a request for customer support.">
</form>

जब कोई एजेंट toolname को कॉल करता है, तो ब्राउज़र फ़ॉर्म को फ़ोकस में लाता है और उसके फ़ील्ड में जानकारी भरता है. यह फ़ॉर्म, उपयोगकर्ता को दिखता रहता है.

toolname या tooldescription एचटीएमएल एट्रिब्यूट को हटाने पर, टूल का रजिस्ट्रेशन रद्द हो जाता है.

(ज़रूरी नहीं) टूल के पैरामीटर

सटीकता को बेहतर बनाने के लिए, फ़ॉर्म के अलग-अलग एलिमेंट में यहां दिए गए एचटीएमएल एट्रिब्यूट जोड़ें:

  • toolparamdescription: JSON स्कीमा में मौजूद प्रॉपर्टी के ब्यौरे में मैप एलिमेंट. इस एट्रिब्यूट के बिना, ब्राउज़र, उससे जुड़े <label> में मौजूद कॉन्टेंट का इस्तेमाल करता है. साथ ही, लेबल किए जा सकने वाले डिसेंडेंट को छोड़ देता है. अगर कोई लेबल नहीं है, तो ब्राउज़र aria-description को रेफ़र करता है.

इस फ़ॉर्म में, <select> एलिमेंट के लिए वैकल्पिक पैरामीटर का इस्तेमाल किया गया है.

<form toolname="supportRequestTool"
  tooldescription="Submit a request for support."
  action="/submit">

  <label for="firstName">First Name</label>
  <input type=text name=firstName>

  <label for="lastName">Last Name</label>
  <input type=text name=lastName>

  <select name="select" required 
    toolparamdescription="Determines what team this request is routed to.">
    <option value="Customer happiness team">Return my purchase.</option>
    <option value="Distribution team">Check where my package is.</option>
    <option value="Website support team">Get help on the website.</option>
  </select>

  <button type=submit>Submit</button>
</form>

ब्राउज़र इस फ़ॉर्म को एक टूल के तौर पर समझता है. इसे यहां दिए गए JSON से दिखाया गया है:

[
  {
    "name": "supportRequestTool",
    "description": "Submit a request for support.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "firstName": {
          "type": "string"
        },
        "lastName": {
          "type": "string"
        },
        "select": {
          "type": "string",
          "anyOf": [
            {
              "type": "string",
              "const": "Customer happiness team",
              "title": "Return my purchase."
            },
            {
              "type": "string",
              "const": "Distribution team",
              "title": "Check where my package is."
            },
            {
              "type": "string",
              "const": "Website support team",
              "title": "Get help on the website."
            }
          ],
          "enum": [
            "Customer happiness team",
            "Distribution team",
            "Website support team"
          ],
          "description": "Determines what team this request is routed to."
        }
      },
      "required": [
        "select"
      ]
    }
  }
]

फ़ॉर्म सबमिट करना

फ़ॉर्म सबमिट करने के लिए, आपके पास दो विकल्प हैं:

  • टास्क पूरा करने के लिए, उपयोगकर्ता को मैन्युअल तरीके से सबमिट करें पर क्लिक करना होगा.
  • toolautosubmit को जोड़ें, ताकि मॉडल इस टूल को चालू करने पर सबमिट करने और नेविगेशन को ट्रिगर कर सके.

SubmitEvent इंटरफ़ेस में, agentInvoked बूलियन एट्रिब्यूट शामिल किया गया है. जब भी कोई फ़ॉर्म, एआई एजेंट से ट्रिगर होता है, तब इस एट्रिब्यूट को 'सही' पर सेट किया जाता है. इससे, एजेंट के साथ होने वाले इंटरैक्शन के लिए, आपके वेब ऐप्लिकेशन के व्यवहार को अडैप्ट किया जा सकता है.

इसके अलावा, SubmitEvent में respondWith(Promise<any>) तरीका शामिल होता है. इसलिए, ब्राउज़र को ऐसा प्रॉमिस पास किया जा सकता है जिसे फ़ॉर्म के नतीजों के साथ हल किया जा सकता है. इसके बाद, नतीजे के तौर पर मिली वैल्यू को क्रम से लगाया जाता है और मॉडल को टूल के आउटपुट के तौर पर वापस भेज दिया जाता है. इस तरीके का इस्तेमाल करने के लिए, आपको पहले preventDefault() को कॉल करना होगा, ताकि ब्राउज़र के स्टैंडर्ड फ़ॉर्म सबमिट करने की प्रोसेस को रोका जा सके.

<form toolautosubmit toolname="search_tool"
  tooldescription="Search the web" action="/search">
  <input type=text name=query>
</form>
<script>
  document.querySelector("form").addEventListener("submit", (e) => {
    e.preventDefault();
    if (!myFormIsValid()) {
      if (e.agentInvoked) { e.respondWith(myFormValidationErrorPromise) };
      return;
    }
    if (e.agentInvoked) { e.respondWith(Promise.resolve("Search is done!")); }
  });
</script>

ब्राउज़र यह सूचना देता है कि एआई एजेंट ने "toolactivated" इवेंट के साथ टूल को एक्ज़ीक्यूट किया है. फ़ॉर्म फ़ील्ड पहले से भरे होने पर, यह इवेंट विंडो पर ट्रिगर होता है. इसके उलट, अगर कोई उपयोगकर्ता एजेंट की कार्रवाई रद्द करता है या reset() तरीके को लागू किया जाता है, तो "toolcancel" इवेंट ट्रिगर होता है. इन दोनों इवेंट को रद्द नहीं किया जा सकता. साथ ही, ये पहचान के लिए toolName एट्रिब्यूट उपलब्ध कराते हैं.

window.addEventListener('toolactivated', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was activated.`);
  // TODO: Update UI or validate form if needed.
});

window.addEventListener('toolcancel', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was cancelled.`);
  // TODO: Let the user know. Update UI.
});

फ़ोकस इंडिकेटर में बदलाव करना

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

  • :tool-form-active को टूल के एचटीएमएल form एलिमेंट पर लागू किया जाता है.
  • :tool-submit-active को फ़ॉर्म के सबमिट बटन पर लागू किया जाता है. हालांकि, ऐसा तब ही होता है, जब सबमिट बटन मौजूद हो.

फ़ॉर्म सबमिट होने, एजेंट के कार्रवाई रद्द करने या उपयोगकर्ता के फ़ॉर्म रीसेट करने पर, ये क्लास बंद हो जाती हैं. इन स्थितियों के लिए सीएसएस को अपनी पसंद के मुताबिक बनाया जा सकता है. इसके अलावा, ब्राउज़र की डिफ़ॉल्ट स्टाइल का इस्तेमाल भी किया जा सकता है.

/* Chrome default declarative form styles. */
form:tool-form-active {
  outline: light-dark(blue, cyan) dashed 1px;
  outline-offset: -1px;
}

input:tool-submit-active {
  outline: light-dark(red, pink) dashed 1px;
  outline-offset: -1px;
}

फ़ोकस करने के सबसे सही तरीकों और स्टाइल के बारे में ज़्यादा जानें.

सुझाव/राय देना या शिकायत करना

WebMCP पर अभी काम चल रहा है. आने वाले समय में, इसमें बदलाव हो सकता है. अगर आपने इस एपीआई को आज़माया है और आपको कोई सुझाव, शिकायत या राय देनी है, तो हमें ज़रूर बताएं.