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

Imperative API

Alexandra Klepper

François Beaufort

تاريخ النشر: 18 مايو 2026، تاريخ آخر تعديل: 21 سبتمبر 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}.`;
  },
});

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

يمكنك إزالة أداة باستخدام 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" للحصول على مثال حول كيفية استرداد الأدوات من إطار 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

يتضمّن React دعمًا تجريبيًا لـ WebMCP باستخدام حزمة usewebmcp. إذا كان تطبيقك مكتوبًا باستخدام React، يمكنك تسجيل الأدوات باستخدام خطافات مستقلة مرتبطة بدورة حياة عملية تحميل المكوّن وإلغاء تحميله. توفّر أداة الربط useWebMCP أيضًا استنتاجًا للأنواع مستندًا إلى المخطط، كما تعرض حالة التنفيذ المحلية.

التوافق مع Angular

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

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

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

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

البدء

Declarative API