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) طراحی شده است، نه برای تعاملات کاربر نهایی. این کار به نمایندگان کاربر نهایی و چندمنظوره اجازه می‌دهد ابزارهای متمرکز بر توسعه‌دهنده را فیلتر کنند.
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 Page Agent را ببینید. به افزونه نمونه WebMCP مراجعه کنید تا ببینید چگونه عاملی در افزونه مرورگر ابزارها را در iframeهای هم‌مبدأ و میان‌مبدئی پیدا و اجرا می‌کند.

اجرا کردن ابزار

برای اجرای دستی ابزار کشف‌شده در getTools()، document.modelContext.executeTool() را با شیء جاوا اسکریپت اختیاری برای آرگومان‌های ورودی که به رشته JSON قابل‌سریال‌سازی است فراخوانی کنید. این روش ناهمگام نتیجه اجرای ابزار را برمی‌گرداند، یا اگر پیمایشی راه‌اندازی شود، مقدار null را برمی‌گرداند.

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();

رویدادها

قاب‌ها می‌توانند به رویداد toolchange در document.modelContext گوش دهند تا وقتی فهرست ابزارهای دردسترس تغییر کرد مطلع شوند.

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

‫iframeهای میان‌مبدئی

‫WebMCP از iframe میان‌مبدئی که هم از خط‌مشی‌های اجازه و هم از دروازه‌بندی مبدأ صریح استفاده می‌کند پشتیبانی می‌کند.

خط‌مشی اجازه‌ها

ثبت ابزار به‌طور پیش‌فرض در iframe میان‌مبدئی غیرفعال است. صفحه باید بااستفاده از tools خط‌مشی اجازه‌ها دسترسی را واگذار کند:

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

مواجهه مبدأ

ابزارها به‌طور پیش‌فرض برای اسناد میان‌مبدئی دردسترس نیستند. می‌توانید از آرایه exposedTo در registerTool برای فهرست کردن مبدأهای خاصی که مجاز به مشاهده و اجرای ابزار هستند استفاده کنید. این آرایه فقط از مبدأهای امن پشتیبانی می‌کند.

// 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: ابزارهای مرتبط با چرخه حیات تزریق وابستگی برنامه را ثبت کنید و Signal Forms خود را به ابزارهای WebMCP تبدیل کنید.
  • Vue: از ترکیب‌پذیر useWebMCP از بسته @vueuse/core استفاده کنید. ابزارهای ثبت‌شده مرتبط با چرخه حیات محدوده Vue فعلی. پیاده‌سازی Vue از ثبت ابزار واکنشی و شرطی پشتیبانی می‌کند و نتایج اجرا را به‌طور خودکار نرمال‌سازی می‌کند.

تعامل و هم‌رسانی بازخورد

WebMCP درحال‌حاضر درحال بحث و بررسی است و ممکن است در آینده تغییر کند. اگر این API را امتحان کردید و بازخوردی دارید، خوشحال می‌شویم آن را بشنویم.

قبلی
شروع به کار
بعدی
API اعلانی