Imperative API

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

تاریخ انتشار: ۱۸ مه ۲۰۲۶، آخرین به‌روزرسانی: ۱۶ اکتبر ۲۰۲۶

راهنمای توضیحی وب برنامه‌های افزودنی Chrome Status هدف
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

React پشتیبانی آزمایشی از WebMCP دارد که از بسته use-webmcp-tool استفاده می‌کند. اگر برنامه‌تان ازقبل با React نوشته شده است، می‌توانید بااستفاده از قلاب useWebMCP که به چرخه حیات سوار کردن و پیاده کردن مؤلفه‌تان گره خورده است، ابزارها را ثبت کنید. همچنین از ثبت ابزار شرطی پشتیبانی می‌کند و نتایج اجرا را به‌طور خودکار عادی‌سازی می‌کند.

پشتیبانی Angular

Angular پشتیبانی آزمایشی از WebMCP دارد. اگر برنامه‌تان قبلاً با Angular نوشته شده است، می‌توانید ابزارهای مرتبط با چرخه حیات تزریق وابستگی برنامه را ثبت کنید و Signal Forms خود را به ابزارهای WebMCP تبدیل کنید.

پشتیبانی Vue

Vue پشتیبانی آزمایشی از WebMCP بااستفاده از بسته @vueuse/core دارد. اگر برنامه‌تان ازقبل با Vue نوشته شده است، می‌توانید ابزارها را بااستفاده از useWebMCP composable که به چرخه حیات دامنه Vue فعلی گره خورده است ثبت کنید. این مدل همچنین از ثبت ابزار واکنشی و شرطی پشتیبانی می‌کند و نتایج اجرا را به‌طور خودکار نرمال‌سازی می‌کند.

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

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

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