Imperative API

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

تاريخ النشر: 18 مايو 2026، تاريخ آخر تعديل: 16 أكتوبر 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. لا تتيح هذه المصفوفة سوى المصادر الآمنة.

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

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

التوافق مع Angular

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

دعم Vue

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

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

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

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