Imperative API

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

প্রকাশিত: ১৮ মে, ২০২৬, শেষবার আপডেট করা হয়েছে: ১৬ অক্টোবর, ২০২৬

ব্যাখ্যামূলক ওয়েব এক্সটেনশন Chrome স্ট্যাটাস ইনটেন্ট
GitHub অরিজিন ট্রায়াল অরিজিন ট্রায়াল ভিউ পরীক্ষা করার ইচ্ছা

আপনি স্ট্যান্ডার্ড জাভাস্ক্রিপ্ট সহ বিভিন্ন ধরনের টুল সংজ্ঞায়িত করতে WebMCP Imperative API ব্যবহার করতে পারেন। আপনার টুল বিভিন্ন ফাংশন এক্সিকিউট করতে পারে, যেমন ফর্ম ইনপুট, সাইট নেভিগেশন এবং স্টেট ম্যানেজমেন্ট।

এই API ব্যবহার করার আগে, ব্যবহারের উদাহরণ সম্পর্কে পড়ুন।

মডেল কন্টেক্সট প্রদান করুন

টুল রেজিস্টার করতে 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 হলে, এটি ইঙ্গিত করে যে টুলটি এক্সিকিউট করলে উল্লেখযোগ্য, বাস্তব-জগতের বা অপরিবর্তনীয় অ্যাকশন (যেমন, ফ্লাইট বুক করা, টাকা ট্রান্সফার করা বা ডেটা মুছে ফেলা) হবে। এটি এজেন্ট এবং ব্রাউজারগুলিকে হাই-স্টেক টুল চালানোর আগে বাধ্যতামূলক ব্যবহারকারীর নিশ্চিতকরণ প্রম্পট প্রয়োগ করতে দেয়, ব্যবহারকারীর অভিপ্রায়ের দুর্ঘটনাজনিত বা ক্ষতিকারক ভুল উপস্থাপনের ঝুঁকি হ্রাস করে।
  • debugging (বুলিয়ান, ডিফল্ট হিসেবে false, Chrome 156 থেকে উপলভ্য): true হলে, এটি দেখায় যে টুলটি বিশেষভাবে পরীক্ষা এবং ডেভেলপার টুলিংয়ের (যেমন, টেস্টিং ফ্রেমওয়ার্ক বা Chrome DevTools AI অ্যাসিস্ট্যান্স) জন্য ডিজাইন করা হয়েছে, এন্ড-ইউজার ইন্টার‍্যাকশনের জন্য নয়। এটি সাধারণ-উদ্দেশ্য এবং এন্ড-ইউজার এজেন্টদের ডেভেলপার-কেন্দ্রিক টুল ফিল্টার করার অনুমতি দেয়।
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 ফাংশনটি তার দ্বিতীয় আর্গুমেন্ট হিসেবে signal নামের একটি AbortSignal প্যারামিটার গ্রহণ করে। দীর্ঘ সময় ধরে চলা অ্যাসিঙ্ক্রোনাস টাস্ক বা নেটওয়ার্ক অপারেশনে (যেমন 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 Page Agent ডেমো দেখুন। ব্রাউজার এক্সটেনশনে কোনও এজেন্ট কীভাবে একই-অরিজিন এবং ক্রস-অরিজিন iframe জুড়ে টুল খুঁজে পায় এবং চালায় তা দেখতে উদাহরণ WebMCP এক্সটেনশন দেখুন।

টুল এক্সিকিউট করুন

getTools()-এ খুঁজে পাওয়া টুল ম্যানুয়ালি এক্সিকিউট করতে, ইনপুট আর্গুমেন্টের জন্য ঐচ্ছিক JavaScript অবজেক্ট সহ 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-কে সাপোর্ট করে যা অনুমতি সংক্রান্ত নীতি এবং এক্সপ্লিসিট অরিজিন গেটিং, দুটিই ব্যবহার করে।

অনুমতি সংক্রান্ত নীতি

ক্রস-অরিজিন আইফ্রেমে টুল রেজিস্ট্রেশন ডিফল্ট হিসেবে বন্ধ করা থাকে। কোনও পৃষ্ঠাকে অবশ্যই 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 সংক্রান্ত সহায়তা

use-webmcp-tool প্যাকেজ ব্যবহার করে React-এ WebMCP-এর জন্য পরীক্ষামূলক সহায়তা আছে। আপনার অ্যাপ্লিকেশনটি যদি আগে থেকেই React-এ লেখা থাকে, তাহলে আপনি আপনার কম্পোনেন্টের মাউন্ট এবং আনমাউন্ট লাইফসাইকেলের সাথে যুক্ত useWebMCP হুক ব্যবহার করে টুল রেজিস্টার করতে পারেন। এছাড়াও, এটি শর্তসাপেক্ষ টুল রেজিস্ট্রেশন সমর্থন করে এবং এক্সিকিউশন ফলাফল অটোমেটিক স্বাভাবিক করে।

Angular সংক্রান্ত সহায়তা

Angular-এ WebMCP-এর জন্য পরীক্ষামূলক সহায়তা আছে। আপনার অ্যাপ্লিকেশনটি আগে থেকেই Angular-এ লেখা থাকলে, আপনি অ্যাপ্লিকেশনের ডিপেন্ডেন্সি ইনজেকশন লাইফসাইকেলের সাথে যুক্ত টুল রেজিস্টার করতে পারেন এবং আপনার সিগন্যাল ফর্মগুলিকে WebMCP টুলে পরিণত করতে পারেন।

Vue সহায়তা

@vueuse/core প্যাকেজ ব্যবহার করে Vue-তে WebMCP-এর জন্য পরীক্ষামূলক সহায়তা আছে। আপনার অ্যাপ্লিকেশনটি আগে থেকেই Vue-এর মাধ্যমে লেখা থাকলে, বর্তমান Vue স্কোপ লাইফসাইকেলের সাথে যুক্ত useWebMCP কম্পোজেবল ব্যবহার করে আপনি টুল রেজিস্টার করতে পারবেন। এটি রিঅ্যাক্টিভ ও কন্ডিশনাল টুল রেজিস্ট্রেশনও সাপোর্ট করে এবং এক্সিকিউশন ফলাফল অটোমেটিক নরমালাইজ করে।

যোগাযোগ করুন এবং মতামত শেয়ার করুন

WebMCP নিয়ে সক্রিয় আলোচনা চলছে এবং ভবিষ্যতে এটিতে পরিবর্তন হতে পারে। আপনি যদি এই API ব্যবহার করে থাকেন এবং আপনার কোনও মতামত থাকে, তাহলে আমরা তা জানতে চাই।

পূর্ববর্তী
শুরু করুন
পরবর্তী
ঘোষণামূলক এপিআই