Imperative API

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

Published: May 18, 2026, Last updated: September 1, 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();

اعتبارًا من 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, 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 Page Agent للحصول على مثال حول كيفية استرداد الأدوات من إطار 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 "سياسة الأذونات" `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 باستخدام حزمة usewebmcp. إذا كان تطبيقك مكتوبًا باستخدام React، يمكنك تسجيل الأدوات باستخدام الخطافات المستقلة المرتبطة بدورة حياة التحميل والإلغاء للمكوّن. يوفّر الخطاف useWebMCP أيضًا استنتاجًا للنوع يستند إلى المخطط ويعرض حالة التنفيذ المحلية.

دعم Angular

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

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

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

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