Imperative API

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

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

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

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

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

মডেলের প্রসঙ্গ দিন

টুল রেজিস্টার করতে 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 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-কে সাপোর্ট করে যা অনুমতি সংক্রান্ত নীতি এবং এক্সপ্লিসিট অরিজিন গেটিং, দুটিই ব্যবহার করে।

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

ক্রস-অরিজিন 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, Angular এবং Vue-তে WebMCP-এর জন্য এক্সপেরিমেন্টাল সহায়তা আছে।

  • React: use-webmcp-tool প্যাকেজ ব্যবহার করুন। আপনার কম্পোনেন্টের মাউন্ট ও আনমাউন্ট লাইফসাইকেলের সাথে যুক্ত useWebMCP হুক ব্যবহার করে টুল রেজিস্টার করুন। এই হুক কন্ডিশনাল টুল রেজিস্ট্রেশন সাপোর্ট করে এবং এক্সিকিউশন ফলাফল অটোমেটিক নরমালাইজ করে।
  • Angular: অ্যাপ্লিকেশনের ডিপেন্ডেন্সি ইনজেকশন লাইফসাইকেলের সাথে যুক্ত টুল রেজিস্টার করুন এবং আপনার সিগন্যাল ফর্মকে WebMCP টুলে পরিণত করুন।
  • Vue: @vueuse/core প্যাকেজ থেকে useWebMCP কম্পোজেবল ব্যবহার করুন। বর্তমান Vue স্কোপ লাইফসাইকেলের সাথে যুক্ত টুল রেজিস্টার করুন। Vue-এর ইমপ্লিমেন্টেশন রিঅ্যাক্টিভ ও কন্ডিশনাল টুল রেজিস্ট্রেশনকে সাপোর্ট করে এবং এক্সিকিউশন ফলাফল অটোমেটিক নরমালাইজ করে।

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

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

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