Imperative API

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

تاريخ النشر: 18 مايو 2026، تاريخ آخر تعديل: 11 سبتمبر 2026

فيديو توضيحي الويب الإضافات حالة Chrome النيّة بالشراء
Github مرحلة التجربة والتقييم مرحلة التجربة والتقييم العرض النية في إجراء تجربة

يمكنك استخدام WebMCP Imperative API لتحديد أنواع عديدة من الأدوات باستخدام JavaScript العادي. يمكن لأدواتك تنفيذ وظائف مختلفة، مثل إدخال البيانات في النماذج والتنقّل في الموقع الإلكتروني وإدارة الحالة.

قبل استخدام واجهة برمجة التطبيقات هذه، اطّلِع على أمثلة على حالات الاستخدام.

توفير سياق النموذج

استخدِم واجهة 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، يشير ذلك إلى أنّ تنفيذ الأداة يؤدي إلى اتّخاذ إجراءات مهمة أو واقعية أو غير قابلة للإلغاء (مثل حجز رحلة جوية أو تحويل أموال أو حذف بيانات). يتيح ذلك للوكلاء والمتصفحات فرض طلبات تأكيد إلزامية من المستخدمين قبل تنفيذ أدوات عالية المخاطر، ما يقلّل من خطر التحريف العرضي أو الخبيث لنية المستخدم.
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,
  },
  execute: async ({ flightId, passengers }) => {
    // Add your flight booking transaction logic here.
    return `Booked ${passengers} passenger(s) on flight ${flightId}.`;
  },
});

أدوات إلغاء التسجيل

يمكنك إزالة أداة باستخدام 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();

اعتبارًا من الإصدار 153 من Chrome، يمكنك إلغاء تسجيل أداة بدون إلغاء عمليات التنفيذ الجارية. يمنع ذلك حدوث آثار جانبية غير متوقّعة عند إدارة دورات حياة الأدوات في أُطر المكوّنات.

التعامل مع إلغاء الأداة

تتلقّى الدالة 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, 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']
});

يمكنك الاطّلاع على العرض التوضيحي لـ "وكيل صفحة WebMCP" للحصول على مثال حول كيفية استرداد الأدوات من إطار iframe وتنفيذها ضمن واجهة محادثة مستندة إلى الويب.

تنفيذ الأداة

لتنفيذ أداة تم العثور عليها في getTools() يدويًا، استدعِ الدالة document.modelContext.executeTool() مع كائن JavaScript اختياري لوسيطات الإدخال التي يمكن تسلسلها إلى سلسلة 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 دعمًا تجريبيًا لـ WebMCP باستخدام حزمة usewebmcp. إذا كان تطبيقك مكتوبًا باستخدام React، يمكنك تسجيل الأدوات باستخدام خطافات مستقلة مرتبطة بدورة حياة عملية تحميل المكوّن وإلغاء تحميله. توفّر أداة الربط useWebMCP أيضًا استنتاجًا للأنواع مستندًا إلى المخطط، كما تعرض حالة التنفيذ المحلية.

التوافق مع Angular

يتوافق Angular تجريبيًا مع WebMCP. إذا كان تطبيقك مكتوبًا باستخدام Angular، يمكنك تسجيل أدوات مرتبطة بدورة مراحل النشاط لإدخال الاعتمادية في التطبيق وتحويل "نماذج Signal" إلى أدوات WebMCP.

التفاعل مع الملاحظات ومشاركتها

لا يزال WebMCP قيد المناقشة النشطة، وقد يخضع للتغيير في المستقبل. إذا جرّبت هذه الواجهة وأردت مشاركة ملاحظاتك، يسعدنا تلقّيها.

السابق
البدء
التالي
Declarative API