Imperative API

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

पब्लिश होने की तारीख: 18 मई, 2026, पिछली बार अपडेट किए जाने की तारीख: 1 सितंबर, 2026

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

WebMCP Imperative API का इस्तेमाल करके, स्टैंडर्ड JavaScript की मदद से कई तरह के टूल तय किए जा सकते हैं. आपके टूल अलग-अलग फ़ंक्शन लागू कर सकते हैं. जैसे, फ़ॉर्म में जानकारी डालना, साइट पर नेविगेट करना, और स्टेट मैनेजमेंट.

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

मॉडल के लिए कॉन्टेक्स्ट देना

टूल रजिस्टर करने के लिए, modelContext इंटरफ़ेस का इस्तेमाल करें. टूल रजिस्टर करने के लिए, नाम, जानकारी, और इनपुट स्कीमा के साथ-साथ काम की प्रॉपर्टी की ज़रूरत होती है.

मॉडल कॉन्टेक्स्ट में कोई टूल जोड़ने के लिए, registerTool का इस्तेमाल करें.

WebMCPza Maker

await document.modelContext.registerTool({
  name: 'toggle_layer',
  description: 'Control pizza layers (sauce, cheese). Use "add", "remove", or "toggle".',
  inputSchema: {
    type: 'object',
    properties: {
      layer: { type: 'string', enum: ['sauce-layer', 'cheese-layer'] },
      action: { type: 'string', enum: ['add', 'remove', 'toggle'] },
    },
    required: ['layer'],
  },
  execute: async ({ layer, action }) => {
    await toggleLayer(layer, action);
    return `Performed ${action || 'toggle'} on layer: ${layer}`;
  },
});

ऑर्डर का स्टेटस पाना

await document.modelContext.registerTool({
  name: 'get_order_status',
  description: 'Search orders in a given timeframe. Returns order number, shipping status and location',
  inputSchema: {
    "type": "object",
    "properties": {
      "timeframe": { "type": "string", "oneOf": [
        { "type": "string", "const": "today", "title": "Today" },
        { "type": "string", "const": "yesterday", "title": "Yesterday" },
        { "type": "string", "const": "last_7_days", "title": "Last 7 Days" },
        { "type": "string", "const": "last_30_days", "title": "Last 30 Days" },
        { "type": "string", "const": "last_6_months", "title": "Last 6 Months" }],
      "enum": [ "today", "yesterday", "last_7_days", "last_30_days", "last_6_months" ],
      "description": "Timeframe for the order lookup." }
    },
    "required": [ "timeframe" ]
  },
  execute: async ({ timeframe }) => {
    // Add your API or database logic here to fetch and return the order data as a string.
  },
});

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

किसी टूल को रजिस्टर करते समय, annotations प्रॉपर्टी में मेटाडेटा के बारे में जानकारी जोड़ी जा सकती है. इन संकेतों से एजेंट और ब्राउज़र को, टूल की सुरक्षा से जुड़ी विशेषताओं, संभावित साइड इफ़ेक्ट, और आउटपुट की विश्वसनीयता को समझने में मदद मिलती है:

  • readOnlyHint (बूलियन, डिफ़ॉल्ट रूप से false): जब true होता है, तो इसका मतलब है कि टूल सिर्फ़ जानकारी पढ़ता है और ऐप्लिकेशन या सिस्टम की स्थिति में बदलाव नहीं करता. उदाहरण के लिए, किसी प्रॉडक्ट कैटलॉग को खोजना या ऑर्डर का स्टेटस वापस पाना. इससे एजेंट को यह तय करने में मदद मिलती है कि टूल को बिना किसी साइड इफ़ेक्ट के सुरक्षित तरीके से कॉल किया जा सकता है या नहीं.
  • untrustedContentHint (बूलियन, डिफ़ॉल्ट रूप से false पर सेट होता है): जब true होता है, तो इसका मतलब है कि टूल के आउटपुट में, टूल के लेखक के हिसाब से ऐसा डेटा शामिल है जिस पर भरोसा नहीं किया जा सकता. उदाहरण के लिए, यूज़र जनरेटेड कॉन्टेंट : यूजीसी, समीक्षाएं या बाहरी वेब डेटा. इससे एजेंट और क्लाइंट को यह पता चलता है कि लौटाए गए पेलोड को ज़्यादा सुरक्षा के साथ हैंडल करने की ज़रूरत है. जैसे, अप्रत्यक्ष प्रॉम्प्ट इंजेक्शन को कम करने के लिए, उसे सैनिटाइज़ करना या सीमा तय करना.
  • consequentialHint (बूलियन, डिफ़ॉल्ट रूप से false पर सेट होता है): true होने पर, यह बताता है कि टूल को चलाने से, असल दुनिया में होने वाली ज़रूरी या ऐसी कार्रवाइयां होती हैं जिन्हें बदला नहीं जा सकता. उदाहरण के लिए, फ़्लाइट बुक करना, पैसे ट्रांसफ़र करना या डेटा मिटाना. इससे एजेंट और ब्राउज़र, ज़्यादा जोखिम वाले टूल को लागू करने से पहले, उपयोगकर्ता से पुष्टि करने के लिए ज़रूरी प्रॉम्प्ट दिखा सकते हैं. इससे उपयोगकर्ता के मकसद को गलती से या गलत तरीके से पेश करने के जोखिम को कम किया जा सकता है.
await document.modelContext.registerTool({
  name: 'book_flight',
  description: 'Book a flight for the user with confirmed flight details.',
  inputSchema: {
    type: 'object',
    properties: {
      flightId: { type: 'string', description: 'ID of the flight to book' },
      passengers: { type: 'number', description: 'Number of tickets to purchase' },
    },
    required: ['flightId', 'passengers'],
  },
  annotations: {
    readOnlyHint: false,
    consequentialHint: true,
    untrustedContentHint: false,
  },
  execute: async ({ flightId, passengers }) => {
    // Add your flight booking transaction logic here.
    return `Booked ${passengers} passenger(s) on flight ${flightId}.`;
  },
});

टूल का रजिस्ट्रेशन रद्द करना

AbortSignal का इस्तेमाल करके, किसी टूल को हटाया जा सकता है. इसके लिए, टूल को वैकल्पिक पैरामीटर के तौर पर पास करना होगा.

const addTodoTool = {
  name: "addTodo",
  description: "Add a new item to the to-do list",
  inputSchema: {
    type: "object",
    properties: { text: { type: "string" } },
  },
  execute: async ({ text }) => {
    // You should handle the persistence logic here (omitted for demo)
    return `Added to-do: ${text}`;
  },
  annotations: {
    readOnlyHint: false,
    untrustedContentHint: true
  },
};
const controller = new AbortController();
await document.modelContext.registerTool(addTodoTool, { signal: controller.signal });

// Unregister the tool later...
controller.abort();

Chrome 153 से, किसी टूल को बिना रद्द किए और बिना किसी रुकावट के अनरजिस्टर किया जा सकता है. इससे कॉम्पोनेंट फ़्रेमवर्क में टूल के लाइफ़साइकल को मैनेज करते समय, अनचाहे साइड इफ़ेक्ट नहीं होते.

टूल रद्द करने की सुविधा को मैनेज करना

execute फ़ंक्शन को AbortSignal पैरामीटर मिलता है. इसे signal नाम दिया गया है. यह दूसरा आर्ग्युमेंट होता है. इसका इस्तेमाल, उपयोगकर्ता या एजेंट की ओर से शुरू किए गए अनुरोधों को रद्द करने की प्रोसेस को आसानी से मैनेज करने के लिए किया जाता है. इस सिग्नल को लंबे समय तक चलने वाले एसिंक्रोनस टास्क या नेटवर्क ऑपरेशन (जैसे कि fetch()) को पास करने से, गैर-ज़रूरी काम को रोकने में मदद मिलती है. साथ ही, इससे संसाधन के बेहतर मैनेजमेंट और संभावित लीक से बचने में मदद मिलती है.

await document.modelContext.registerTool({
  name: 'fetch_tool',
  description: 'Fetch the text content of a URL and stream the response.',
  inputSchema: {
    type: 'object',
    properties: {
      url: { type: 'string', description: 'The URL to fetch' },
      priority: { type: 'string', enum: ['high', 'low', 'auto'] },
    },
    required: ['url'],
  },
  execute: async ({ url, priority }, { signal }) => {
    // Abort the fetch request when tool execution is aborted.
    const response = await fetch(url, { priority, signal });
    const stream = response.body.pipeThrough(new TextDecoderStream());
    for await (const chunk of stream) {
      document.querySelector('pre').textContent += chunk;
    }
    return 'Success';
  },
});

टूल के बारे में जानें

उपलब्ध टूल वापस पाने के लिए, document.modelContext.getTools() का इस्तेमाल करें. यह एसिंक्रोनस तरीका, उन टूल की सूची दिखाता है जिन्हें कॉल करने वाले दस्तावेज़ को ऐक्सेस करने की अनुमति है. इस सूची में टूल के नाम, वर्णमाला के क्रम में होते हैं.

const [tool] = await document.modelContext.getTools();
console.log(tool);

// {
//   annotations: { consequentialHint: false, readOnlyHint: false, untrustedContentHint: true }, // Optional hints
//   description: "Add a new item to the to-do list",
//   inputSchema: {"type":"object","properties":{…}},
//   name: "addTodo",
//   origin: "https://example.com",
//   title: ""
//   window: Window {window: Window, self: Window, …},
// }

डिफ़ॉल्ट रूप से, getTools() सिर्फ़ एक ही ऑरिजिन के उन टूल को दिखाता है जिन्हें कॉल करने वाले दस्तावेज़ या फ़्रेम ट्री में मौजूद एक ही ऑरिजिन के अन्य दस्तावेज़ों ने रजिस्टर किया है. क्रॉस-ऑरिजिन टूल को वापस पाने के लिए, आपको fromOrigins विकल्प में उनके ऑरिजिन की सूची साफ़ तौर पर देनी होगी. यह कलेक्शन सिर्फ़ सुरक्षित ऑरिजिन के साथ काम करता है.

क्रॉस-ऑरिजिन दस्तावेज़ों के टूल सिर्फ़ तब शामिल किए जाते हैं, जब:

  1. होस्टिंग का ओरिजन, fromOrigins विकल्प में दिखता है.
  2. टूल को साफ़ तौर पर आपके ऑरिजिन के लिए उपलब्ध कराया गया हो.
// https://example.com

// Get same-origin tools only
const sameOriginTools = await document.modelContext.getTools();

// Get same-origin tools plus tools from specific cross-origin documents
const allTools = await document.modelContext.getTools({
  fromOrigins: ['https://partner.org']
});

किसी iframe से टूल वापस पाने और उन्हें वेब पर आधारित चैट इंटरफ़ेस में चलाने का उदाहरण देखने के लिए, WebMCP पेज एजेंट का डेमो देखें.

टूल का इस्तेमाल करना

getTools() में खोजे गए टूल को मैन्युअल तरीके से चलाने के लिए, document.modelContext.executeTool() को इनपुट आर्ग्युमेंट के साथ मान्य JSON स्ट्रिंग के तौर पर कॉल करें. यह एसिंक्रोनस तरीका, टूल के एक्ज़ीक्यूशन का नतीजा दिखाता है. अगर नेविगेशन ट्रिगर होता है, तो यह शून्य दिखाता है.

const result = await document.modelContext.executeTool(tool, '{"text": "Buy milk"}');
console.log(result);

// 'Added to-do: Buy milk'

AbortSignal का इस्तेमाल करके, टूल के ऐसे अनुरोध को रद्द किया जा सकता है जिसे पूरा होने में समय लग रहा है. हालांकि, ऐसा तब ही किया जा सकता है, जब इसे वैकल्पिक पैरामीटर के तौर पर पास किया गया हो.

const controller = new AbortController();
document.modelContext.executeTool(tool, '{"text": "Buy milk"}', {
  signal: controller.signal,
});

// Cancel tool execution later...
controller.abort();

इवेंट

फ़्रेम, document.modelContext पर toolchange इवेंट को सुन सकते हैं, ताकि उपलब्ध टूल की सूची में बदलाव होने पर उन्हें सूचना मिल सके.

document.modelContext.addEventListener("toolchange", (event) => {
  // Tools have changed.
});

क्रॉस-ऑरिजिन iframe

WebMCP, क्रॉस-ऑरिजिन iframe के साथ काम करता है. ये iframe, अनुमति से जुड़ी नीतियों और ऑरिजिन गेटिंग, दोनों का इस्तेमाल करते हैं.

अनुमतियों की नीति

क्रॉस-ओरिजिन iframe में, टूल रजिस्टर करने की सुविधा डिफ़ॉल्ट रूप से बंद होती है. किसी पेज को tools अनुमतियों की नीति का इस्तेमाल करके, ऐक्सेस डेलिगेट करना होगा:

<iframe src="https://example.com" allow="tools"></iframe>

ऑरिजिन एक्सपोज़र

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

// https://partner.org

await document.modelContext.registerTool({
  name: 'my_shared_tool',
  description: 'Shared across origins',
  // ...
}, {
  exposedTo: ['https://example.com']
});

React के लिए सहायता

React में usewebmcp पैकेज का इस्तेमाल करके, WebMCP के लिए एक्सपेरिमेंटल सपोर्ट उपलब्ध है. अगर आपका ऐप्लिकेशन पहले से ही React का इस्तेमाल करके लिखा गया है, तो टूल रजिस्टर किए जा सकते हैं. इसके लिए, अपने कॉम्पोनेंट के माउंट और अनमाउंट लाइफ़साइकल से जुड़े स्टैंडअलोन हुक का इस्तेमाल करें. useWebMCP हुक, स्कीमा के हिसाब से टाइप इन्फ़रेंस की सुविधा भी देता है. साथ ही, लोकल एक्ज़ीक्यूशन की स्थिति दिखाता है.

ऐंगुलर के साथ काम करता है

Angular में WebMCP के लिए एक्सपेरिमेंट के तौर पर उपलब्ध सुविधा है. अगर आपका ऐप्लिकेशन पहले से ही Angular में लिखा गया है, तो ऐप्लिकेशन के डिपेंडेंसी इंजेक्शन लाइफ़साइकल से जुड़े टूल रजिस्टर किए जा सकते हैं. साथ ही, अपने सिग्नल फ़ॉर्म को WebMCP टूल में बदला जा सकता है.

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

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

पीछे जाएं
शुरू करना
आगे बढ़ें
डिक्लेरेटिव एपीआई