Imperative API

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

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

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

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

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

मॉडल को कॉन्टेक्स्ट दें

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

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

WebMCP

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 पर सेट होने का मतलब है कि टूल को चलाने से, असल दुनिया में अहम या ऐसे असरदार नतीजे मिलते हैं जिन्हें पहले जैसा नहीं किया जा सकता. उदाहरण के लिए, फ़्लाइट बुक करना, पैसे ट्रांसफ़र करना या डेटा मिटाना. इससे एजेंट और ब्राउज़र, ज़्यादा जोखिम वाले टूल इस्तेमाल करने से पहले, उपयोगकर्ता से पुष्टि करने के लिए कह सकते हैं. इससे, उपयोगकर्ता के मकसद को गलती से या गलत तरीके से पेश करने का जोखिम कम हो जाता है.
  • debugging (बूलियन, डिफ़ॉल्ट रूप से false पर सेट होता है, Chrome 156 से उपलब्ध है): true पर सेट होने का मतलब है कि टूल को खास तौर पर, जांच और डेवलपर टूलिंग के लिए डिज़ाइन किया गया है. जैसे, टेस्टिंग फ़्रेमवर्क या Chrome DevTools में एआई असिस्टेंट. इसे असली उपयोगकर्ता के इंटरैक्शन के लिए डिज़ाइन नहीं किया गया है. इससे, अलग-अलग कामों के लिए इस्तेमाल किए जाने वाले और असली उपयोगकर्ता एजेंट को, डेवलपर के लिए बनाए गए टूल फ़िल्टर करने में मदद मिलती है.
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,
    debugging: false,
  },
  execute: async ({ flightId, passengers }) => {
    // Add your flight booking transaction logic here.
    return `Booked ${passengers} passenger(s) on flight ${flightId}.`;
  },
});

एनोटेशन, एजेंट के व्यवहार पर कैसे असर डाल सकते हैं, इसके उदाहरण देखने के लिए, WebMCP एक्सटेंशन का उदाहरण देखें.

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

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, debugging: 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 पेज एजेंट का डेमो देखें. WebMCP एक्सटेंशन का उदाहरण देखें. इससे आपको पता चलेगा कि ब्राउज़र एक्सटेंशन में मौजूद एजेंट, सेम-ऑरिजिन और क्रॉस-ऑरिजिन iframe में टूल कैसे ढूंढता है और उन्हें कैसे चलाता है.

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

getTools() में मिले किसी टूल को मैन्युअल तरीके से चलाने के लिए, document.modelContext.executeTool() को कॉल करें. इसके लिए, इनपुट आर्ग्युमेंट के लिए वैकल्पिक JavaScript ऑब्जेक्ट का इस्तेमाल करें. इसे 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 में WebMCP के लिए एक्सपेरिमेंट के तौर पर सहायता उपलब्ध है. इसके लिए, use-webmcp-tool पैकेज का इस्तेमाल किया जाता है. अगर आपका ऐप्लिकेशन पहले से ही React में लिखा गया है, तो अपने कॉम्पोनेंट के माउंट और अनमाउंट लाइफ़साइकल से जुड़े useWebMCP हुक का इस्तेमाल करके टूल रजिस्टर किए जा सकते हैं. यह टूल को शर्त के साथ रजिस्टर करने की सुविधा भी देता है. साथ ही, एक्ज़ीक्यूशन के नतीजों को अपने-आप सामान्य बनाता है.

Angular के साथ काम करने की सुविधा

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

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

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

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

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

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