تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

Imperative API

Alexandra Klepper

François Beaufort

تاريخ النشر: 18 مايو 2026، تاريخ آخر تعديل: 15 أكتوبر 2026

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

يمكنك استخدام 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، يشير ذلك إلى أنّ تنفيذ الأداة يؤدي إلى إجراءات مهمة أو واقعية أو غير قابلة للإلغاء (على سبيل المثال، حجز رحلة جوية أو تحويل أموال أو حذف بيانات). يتيح ذلك للوكلاء والمتصفّحات فرض طلبات تأكيد إلزامية من المستخدم قبل تنفيذ الأدوات ذات المخاطر العالية، ما يقلّل من خطر إساءة تفسير نية المستخدم عن طريق الخطأ أو بشكل ضار.
‫debugging (قيمة منطقية، القيمة التلقائية هي false، متاحة من الإصدار 156 من Chrome): عند ضبطها على true، تشير إلى أنّ الأداة مصمّمة خصيصًا للفحص وأدوات المطوّرين (على سبيل المثال، أُطر عمل الاختبار أو المساعدة المستندة إلى الذكاء الاصطناعي في "أدوات مطوّري البرامج في Chrome") بدلاً من تفاعلات المستخدم النهائي. يتيح ذلك لوكلاء المستخدم المخصّصين للأغراض العامة والمستخدمين النهائيين فلترة الأدوات التي تركّز على المطوّرين.

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

اعتبارًا من الإصدار 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, 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. لا تتيح هذه المصفوفة سوى المصادر الآمنة.

لا يتم تضمين الأدوات من المستندات المتعدّدة المصادر إلا في الحالات التالية:

يتم إدراج مصدر الاستضافة في الخيار fromOrigins.
تم عرض الأداة بشكل صريح لمصدرك.

// 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 وتنفيذها ضمن واجهة محادثة مستندة إلى الويب. راجِع مثال إضافة WebMCP للاطّلاع على كيفية عثور وكيل في إضافة متصفّح على الأدوات وتشغيلها في إطارات iframe من المصدر نفسه ومتعدّدة المصادر.

تنفيذ الأداة

لتنفيذ أداة تم اكتشافها في getTools() يدويًا، يمكنك استدعاء document.modelContext.executeTool() باستخدام كائن JavaScript اختياري لوسيطات الإدخال التي يمكن تسلسلها إلى سلسلة 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();

الفعاليات

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

التوافق مع Angular

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

دعم Vue

توفّر Vue دعمًا تجريبيًا لـ WebMCP باستخدام حزمة @vueuse/core. إذا كان تطبيقك مكتوبًا باستخدام Vue، يمكنك تسجيل الأدوات باستخدام الدالة المركّبة useWebMCP المرتبطة بدورة حياة نطاق Vue الحالي. يتيح أيضًا تسجيل الأدوات التفاعلية والشرطية، كما يعمل على تسوية نتائج التنفيذ تلقائيًا.

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

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

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

البدء

Declarative API