أدوات JavaScript المستندة إلى الذكاء الاصطناعي الوكيل

تستخدم واجهة Imperative API السمة document.modelContext.registerTool() لتحديد أدوات JavaScript آليًا. وهذا الإجراء مثالي للتطبيقات من صفحة واحدة (SPA) التي تحتاج إلى إضافة أدوات أو إزالتها استنادًا إلى المسار الحالي أو حالة المستخدم.

يعمل WebMCP على بنية المنتج/المستهلك:

• صفحات الويب هي منتِجة للأدوات: يمكنك تحديد الأدوات وتسجيلها باستخدام document.modelContext.registerTool(). هذا كل ما تحتاج صفحة الويب إلى تنفيذه. ليس عليك استدعاء getTools() أو executeTool() في الصفحة لإتاحة الأدوات للوكلاء.
• وكلاء المتصفّح والإضافات هم المستهلكون الأساسيون: يكتشف الوكلاء الذين يوفّرهم المتصفّح أو من خلاله، بما في ذلك الوكيل المضمّن في المتصفّح وإضافات المتصفّح وأدوات مطوري البرامج والمساعدون على مستوى النظام، الأدوات المسجّلة ويستدعونها خارج النطاق من خلال آليات المنصة الداخلية.
• الوكلاء في الصفحة ومفعِّلات الاختبار: تم تصميم getTools() وexecuteTool() خصيصًا لمساعدي JavaScript في الصفحة (مثل تطبيق مصغّر مضمّن للمحادثة أو <iframe>) والحزم الاختبارية المبرمَجة التي تحتاج إلى اكتشاف الأدوات واستدعائها مباشرةً ضمن سياق الصفحة.

التسجيل ومراحل النشاط

يتم تسجيل الأدوات من خلال تمرير عنصر تعريف الأداة وعنصر خيارات اختياري (ModelContextRegisterToolOptions)، والذي يتيح استخدام عضوَين اختياريَين:

• ‫signal: AbortSignal يُستخدَم لإلغاء تسجيل الأداة عندما لا تعود هناك حاجة إليها.
• ‫exposedTo: مصفوفة من سلاسل المصادر التي تتحكّم في المستندات المسموح لها في شجرة المستندات باكتشاف الأداة وتنفيذها عبر حدود الإطارات.

التعامل مع مراحل النشاط باستخدام AbortController

لا يوفّر WebMCP طريقة unregisterTool(). لإلغاء تسجيل أداة، يجب تمرير AbortSignal أثناء التسجيل وإلغاء هذه الإشارة عندما لا تعود الأداة مطلوبة.

const controller = new AbortController();

await document.modelContext.registerTool({
  name: "get_user_preferences",
  description: "Retrieves the user's saved preferences.",
  inputSchema: { type: "object", properties: {} },
  execute() {
    const prefs = localStorage.getItem("user_prefs");
    return prefs ? JSON.parse(prefs) : { theme: "light" };
  },
  annotations: { readOnlyHint: true }
}, { signal: controller.signal });

// To unregister the tool (e.g., on component unmount):
controller.abort();

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

التحكّم في عرض الأدوات المتعدّدة المصادر باستخدام exposedTo

تكون الأداة المسجّلة تلقائيًا خاصة بوثيقة التسجيل والإطارات من المصدر نفسه. عندما يكون تطبيقك مضمّنًا في <iframe> (أو يتضمّن تطبيقات مصغّرة تابعة لجهات خارجية) وتحتاج إلى إطارات سابقة أو تابعة لاكتشاف الأداة واستدعائها، حدِّد المصادر المسموح بها باستخدام exposedTo.

const controller = new AbortController();

await document.modelContext.registerTool({
  name: "get_cart_items",
  description: "Retrieves items currently in the user's shopping cart.",
  inputSchema: { type: "object", properties: {} },
  async execute(input, { signal }) {
    return await cartService.getItems({ signal });
  },
  annotations: { readOnlyHint: true },
}, {
  signal: controller.signal,
  exposedTo: ["https://checkout.example.com"],
});

• الموافقة المتبادلة: يتطلّب استكشاف الأدوات المتعدّدة المصادر موافقة متبادلة. يسمح إطار عمل موفّر الأداة لمصدر المستهلك عبر exposedTo، ويجب أن يطلب إطار عمل المستهلك صراحةً مصدر الموفّر عبر getTools({ fromOrigins: [...] }). بدون fromOrigins، يرسل getTools() طلبات بحث إلى المستندات من المصدر نفسه فقط.
• مطابقة المصدر: يمكن دائمًا الوصول إلى مصدر وثيقة التسجيل. يتم منح المصادر المحدّدة في exposedTo الإذن باكتشاف الأداة من خلال document.modelContext.getTools({ fromOrigins: [...] }) وتنفيذها من خلال document.modelContext.executeTool().
• متطلبات الأمان: يجب أن يكون كل مصدر في exposedTo جديرًا بالثقة (HTTPS أو المضيف المحلي). يؤدي تمرير مصدر غير صالح أو غير آمن إلى رفض registerTool() باستخدام SecurityError.
• النطاق: يتحكّم exposedTo في إمكانية العثور على المستندات في الصفحة نفسها عبر الإطارات في شجرة المستندات.

تحديد المَعلمات

يتم تحديد المَعلمات (params) باستخدام السمة inputSchema. يجب أن يكون هذا عنصر مخطط JSON يصف البيانات المنظَّمة التي تتوقّعها الأداة.

await document.modelContext.registerTool({
  name: "calculate_area",
  description: "Calculates the area of a rectangle.",
  inputSchema: {
    type: "object",
    properties: {
      width: { type: "number", description: "The width of the rectangle." },
      height: { type: "number", description: "The height of the rectangle." }
    },
    required: ["width", "height"]
  },
  execute(input) {
    // input is { width: 10, height: 20 }
    return input.width * input.height;
  },
  annotations: { readOnlyHint: true }
});

أداة الكتابة وأوصاف المَعلمات

يتلقّى الوكيل مسبقًا inputSchema الكامل، لذا يحتاج description فقط إلى توضيح وظيفة الأداة ومتى يجب استخدامها. لا تكرِّر أسماء المَعلمات أو أنواعها أو قيم enum أو القيم التلقائية أو الحدود فيها، بل حدِّدها في المخطط (enum أو default أو minimum/maximum) بدلاً من ذلك. تتبع أوصاف المعلمات نفس القاعدة: قل ما تعنيه القيمة، وليس نوعها أو القيم المسموح بها.

لا يتحقّق المتصفّح من صحة الوسيطات في inputSchema أو يطبّق قيم default، لذا عليك تنفيذ كليهما في execute.

const SORT_ORDERS = ["newest", "price_low_to_high"];

await document.modelContext.registerTool({
  name: "search_products",
  // Don't list the sort orders here, even via SORT_ORDERS: `enum` already does.
  description: "Searches the product catalog by keyword. Use when the user wants to find or compare products.",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string", description: "Words to search for." },
      sort: { type: "string", enum: SORT_ORDERS, default: "newest", description: "Order of the results." },
    },
    required: ["query"],
  },
  async execute({ query, sort = "newest" }, { signal }) {
    if (typeof query !== "string" || !SORT_ORDERS.includes(sort)) {
      return { error: "Pass a search query and a supported sort order.", sortOrders: SORT_ORDERS };
    }
    return await productService.search({ query, sort }, { signal });
  },
  annotations: { readOnlyHint: true },
});

أنماط التنفيذ

تتلقّى دالة ردّ الاتصال execute دائمًا وسيطتَين: عنصر الإدخال وعنصر الخيارات الذي يحمل AbortSignal — execute(inputObject, { signal }).

حالات استخدام async execute

استخدِم async عندما تتضمّن الأداة عمليات تعرض Promise أو تستغرق وقتًا لإكمالها:

• طلبات الشبكة: جلب البيانات من واجهة برمجة التطبيقات
• مساحة التخزين غير المتزامنة: الوصول إلى IndexedDB
• الأحداث الخارجية: الانتظار حتى يتغيّر وضع معيّن أو تنتهي حركة معيّنة

async execute(input, { signal }) {
  const response = await fetch(`/api/data/${input.id}`, { signal });
  return await response.json();
}

حالات استخدام execute (متزامن)

استخدِم دالة متزامنة عادية للعمليات الفورية. يتم تشغيل أداة متزامنة حتى تكتمل قبل أن يتم رصد الإلغاء، لذا يمكنها تجاهل الإشارة:

• المنطق الخالص: العمليات الحسابية أو الفلترة أو ترتيب البيانات الموجودة في الذاكرة
• الحالة المتزامنة: القراءة من localStorage أو من مدير الحالة المتزامنة

execute(input) {
  return input.items.filter(item => item.active);
}

معالجة الأخطاء في execute

عندما يعرض execute خطأ (أو يعرض وعدًا مرفوضًا)، يتلقّى الوكيل رسالة خطأ عامة في التنفيذ فقط. لا تتم إعادة توجيه رسالة الخطأ إلى موظّف الدعم. إذا واجهت أداتك خطأً يمكن اتخاذ إجراء بشأنه أو يمكن إصلاحه (مثل إدخال غير صالح أو عناصر مفقودة أو حالة HTTP تعذّر تنفيذها)، لا throw new Error(...). بدلاً من ذلك، يجب عرض حمولة خطأ منظَّمة من خلال القيمة المرجَعة العادية للأداة لكي يتلقّى وكيل الذكاء الاصطناعي تفاصيل التشخيص ويتمكّن من التصحيح الذاتي أو إعادة المحاولة:

execute({ itemName }) {
  const item = menuItems.find((entry) => entry.name.toLowerCase() === itemName.toLowerCase());
  if (!item) {
    // Return the error as a value instead of throwing, so the agent receives the message:
    return {
      error: `Menu item "${itemName}" not found.`,
      availableItems: menuItems.map((entry) => entry.name),
    };
  }
  return item;
}

يجب إعادة طرح الاستثناء فقط عند إلغاء التنفيذ (signal.aborted هو true).

جارٍ إلغاء عمليات التنفيذ قيد التقدّم

يبدأ المستخدم أو موظف الدعم عملية الإلغاء. إلزامي: أي أداة تنفّذ طلبات شبكة أو مهام غير متزامنة أخرى طويلة الأمد يجب أن تلتزم بـ signal، وإلا ستستمر عمليات التنفيذ التي تم إلغاؤها في استهلاك الموارد ويمكن أن تكتب بيانات قديمة في واجهة المستخدم بعد انتقال الوكيل إلى مهمة أخرى.

• واجهات برمجة التطبيقات التي تقبل إشارة (برامج قراءة fetch() وaddEventListener() وReadableStream): يتم تمرير signal مباشرةً.
• واجهات برمجة التطبيقات التي لا (setTimeout وsetInterval وحلقات الاستطلاع ومسارات المعالجة التي تستخدم await بكثافة): يمكنك استدعاء signal.throwIfAborted() بين الخطوات و/أو رفض signal.addEventListener('abort', ...). لا تقبل الموقّتات أي إشارة، لذا عليك محوها بنفسك في أداة الاستماع إلى الإلغاء.

await document.modelContext.registerTool({
  name: "fetch_tool",
  description: "Fetch the text content of a URL and show it on the page.",
  inputSchema: {
    type: "object",
    properties: {
      url: { type: "string", description: "The URL to fetch" },
      priority: {
        type: "string",
        enum: ["high", "low", "auto"],
        description: "Relative network priority for the request",
      },
    },
    required: ["url"],
  },
  execute: async ({ url, priority }, { signal }) => {
    const output = document.querySelector("pre");
    output.textContent = "Loading…";
    try {
      // Passing `signal` aborts the network request the moment execution is cancelled.
      const response = await fetch(url, { priority, signal });
      if (!response.ok) {
        output.textContent = "";
        return { error: `Request failed with status ${response.status}` };
      }
      const text = await response.text();
      output.textContent = text;
      return text;
    } catch (err) {
      // Roll back the UI state this execution set, so a cancelled run leaves no trace.
      output.textContent = "";
      if (signal.aborted) {
        // The execution was cancelled: re-throw instead of returning an error value.
        throw err;
      }
      // Return other errors as a value instead of throwing, so the agent receives the message.
      return { error: err instanceof Error ? err.message : String(err) };
    }
  },
  annotations: { readOnlyHint: true }
});

أدوات الإبلاغ عن المحتوى الذي يؤدي إلى عواقب وخيمة

اعتبارًا من الإصدار 154 من Chrome، يتيح annotations استخدام consequentialHint. اضبطه على 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'],
  },
  execute: async ({ flightId, passengers }, { signal }) => {
    // Forward `signal` to the transaction API to honor cancellation:
    return await bookFlightReservation({ flightId, passengers }, { signal });
  },
  annotations: {
    readOnlyHint: false,      // This tool mutates state (it makes a booking).
    consequentialHint: true,  // Spends money and is not trivially reversible.
    untrustedContentHint: false, // Output is first-party data, not third-party content.
  }
});

إلزامي: يجب التعامل مع consequentialHint كتلميح وليس كآلية تنفيذ. ولا يحظر التنفيذ من تلقاء نفسه، ولن تطلب المتصفّحات التي تسبق التلميح أي شيء على الإطلاق. احتفِظ بأي تأكيد داخل التطبيق يضمنه الإجراء حاليًا.

أدوات تصحيح الأخطاء في الإبلاغ عن المحتوى

اعتبارًا من الإصدار 156 من Chrome، أصبح "annotations" متوافقًا مع "debugging". اضبط annotations.debugging على true للأدوات المصمّمة لتصحيح الأخطاء وأدوات المطوّرين بدلاً من مهام المستخدم النهائي. على سبيل المثال، تفريغ حالة التطبيق الداخلية أو تبديل علامات الميزات أو إنشاء بيانات الاختبار. يتيح ذلك للوكلاء التمييز بين الأدوات المخصّصة للمطوّرين فقط والأدوات المخصّصة للعمل نيابةً عن المستخدم. القيمة التلقائية هي false. ويمكن للوكلاء في الصفحة ومفعِّلات الاختبار قراءته من RegisteredTool.annotations.debugging عبر getTools().

await document.modelContext.registerTool({
  name: "dump_app_state",
  description: "Returns a snapshot of the internal application store for debugging.",
  execute() {
    return appStore.getState();
  },
  annotations: {
    readOnlyHint: true, // Only reads state.
    debugging: true,    // Developer tooling, not an end-user action.
  }
});

الوكلاء في الصفحة والاختبار (getTools وexecuteTool)

لا تحتاج صفحات الويب إلى getTools() أو executeTool() لإتاحة الأدوات لوكلاء الذكاء الاصطناعي. يكفي استدعاء document.modelContext.registerTool() لكي تتمكّن وكلاء المتصفّح والإضافات و"أدوات مطوّري البرامج" والمساعدين على مستوى النظام من اكتشاف أدواتك وتنفيذها خارج النطاق.

تتوفّر الطريقتان getTools() وexecuteTool() خصيصًا للمستهلكين الذين يستخدمون بيئة JavaScript:

1. وكلاء JavaScript في الصفحة: مساعد مستنِد إلى الذكاء الاصطناعي أو تطبيق مصغّر مساعد أو واجهة محادثة مضمّنة مباشرةً في الصفحة (أو تعمل داخل <iframe>) يحتاج إلى اكتشاف الأدوات التي توفّرها الصفحة المحيطة أو الإطارات التي يمكن الوصول إليها في شجرة المستندات، واستدعاؤها نيابةً عن المستخدم.
2. الاختبار وتصحيح الأخطاء بشكل آلي: حِزم اختبارية (مثل Playwright أو Vitest أو اختبارات الوحدات داخل المتصفّح) تفحص البيانات الوصفية للأدوات المسجّلة وتحاكي عمليات استدعاء أدوات الوكيل بدون الحاجة إلى حزمة اختبارية خارجية مباشرة للنموذج اللغوي الكبير

استكشاف الأدوات المتاحة من خلال "getTools()"

تستدعي الوكلاء في الصفحة document.modelContext.getTools() لاسترداد مصفوفة من عناصر RegisteredTool من المستند الحالي وأي إطارات يمكن الوصول إليها في شجرة المستند.

اعتبارًا من الإصدار 155 من Chrome، يتم عرض RegisteredTool.inputSchema مباشرةً ككائن JavaScript (نسخة كاملة من المخطط المقدَّم عند التسجيل). لا يؤدي تغيير هذا العنصر إلى تغيير المخطط الفعلي للأداة المسجّلة.

// Example: An in-page AI assistant discovering tools available on the page:
const tools = await document.modelContext.getTools();

// In-page agents can listen for tools being registered or unregistered dynamically:
document.modelContext.addEventListener("toolchange", async () => {
  const updatedTools = await document.modelContext.getTools();
  console.log(`Active tools updated: ${updatedTools.map((t) => t.name).join(", ")}`);
});

للعثور على الأدوات المسجَّلة داخل إطارات iframe فرعية متعدّدة المصادر (والتي يجب أن تمنح الإذن بالوصول صراحةً من خلال exposedTo أثناء التسجيل)، مرِّر fromOrigins في قاموس الخيارات:

// Query tools registered in the embedded cart frame that exposed them to this checkout origin:
const cartTools = await document.modelContext.getTools({
  fromOrigins: ["https://cart.example.com"],
});

استدعاء الأدوات باستخدام executeTool()

تستدعي الوكلاء في الصفحة والنصوص البرمجية للاختبار document.modelContext.executeTool(tool, inputObject, options) لتنفيذ أداة مسجَّلة. تعمل الأداة على المستند الذي تم تسجيلها فيه، ويتم حلّ الوعد إلى النتيجة النصية التي تعرضها دالة الاستدعاء execute للأداة.

منذ الإصدار 155 من Chrome، يقبل executeTool() كائن JavaScript عاديًا مباشرةً لـ inputObject، ما يتطابق مع تنسيق الإدخال الذي تتلقّاه دالة الاستدعاء execute في أداتك.

// 1. Discover the tool (typically done during agent initialization or test setup):
const tools = await document.modelContext.getTools();
const areaTool = tools.find((t) => t.name === "calculate_area");

if (areaTool) {
  const controller = new AbortController();
  // Example input payload matching the tool's inputSchema:
  const inputObject = { width: 10, height: 20 };
  const options = { signal: controller.signal };

  // 2. Pass input arguments as a JavaScript object, with a JSON string fallback for Chrome <155:
  let resultString;
  try {
    resultString = await document.modelContext.executeTool(areaTool, inputObject, options);
  } catch (err) {
    if (err?.message?.startsWith("Failed to parse input")) {
      resultString = await document.modelContext.executeTool(
        areaTool,
        JSON.stringify(inputObject),
        options
      );
    } else {
      // Re-throw real tool execution or cancellation errors:
      throw err;
    }
  }

  console.log("Execution output string:", resultString);
}

يتم رفض الوعد الذي تم إرجاعه في الحالات التالية:

• ‫inputObject ليس عنصرًا أو لا يمكن تحويله إلى سلسلة JSON (على سبيل المثال، مراجع دائرية أو قيم BigInt). يُرجى العِلم أنّ القيم التي تم حذفها من خلال تسلسل JSON (مثل الدوال وundefined) سيتم حذفها من العنصر الذي تتلقّاه الأداة بدلاً من رفضها.
• تم إلغاء التنفيذ من خلال options.signal.
• لم يتم تسجيل الأداة قبل التنفيذ أو حدث خطأ غير معالَج أثناء التشغيل.

نمط مصنع الأدوات

لتمرير السياق (مثل المتاجر أو نُسخ التطبيقات) إلى أدواتك، استخدِم دوال المصنع.

export function createInventoryTool(inventoryManager) {
  return {
    name: "get_inventory",
    description: "Lists items in the inventory.",
    inputSchema: { type: "object", properties: {} },
    execute() {
      return inventoryManager.getItems();
    },
    annotations: { readOnlyHint: true }
  };
}

أنواع TypeScript

في مشاريع TypeScript، لا تكتب يدويًا تعريفات document.modelContext. ثبِّت حزمة webmcp-types الرسمية (npm install --save-dev webmcp-types) وأضِفها إلى tsconfig.json، لأنّه لا يتم رصدها تلقائيًا:

{
  "compilerOptions": {
    "types": ["webmcp-types"]
  }
}

• تمت كتابة document.modelContext كاختياري، لذا يجب حمايته باستخدام if (document.modelContext) قبل الاستخدام.
• باستخدام inputSchema مضمّن، يتم استنتاج نوع الإدخال execute من المخطط.
• الأنواع المُسمّاة، مثل WebMCP.ModelContextTool، هي أنواع عامة (لا حاجة إلى استيرادها)، وهي مفيدة لكتابة مصانع الأدوات.

دعم إطار العمل

إلزامي: إذا كان التطبيق يستخدم React أو Angular أو Vue، يجب تسجيل الأدوات من خلال دمج WebMCP الرسمي لإطار العمل هذا، والمدرج أدناه. لا تستدعِ document.modelContext.registerTool() من المكوّنات أو تكتب برنامج تضمين مراحل النشاط الخاص بك. يتولّى كل دمج معالجة رصد الميزات وعمليات تنظيف AbortSignal وتحديد نطاق الأدوات لمراحل نشاط المكوّن أو أداة الحقن. واجهات برمجة التطبيقات هذه تجريبية، لذا قبل كتابة الرمز، ابحث عن التوقيع الحالي في أنواع الحزمة أو مستنداتها.

تنطبق جميع القواعد الواردة في هذا الدليل عند استخدام عمليات الدمج هذه:

• يجب الحفاظ على شكل تعريف الأداة نفسه: name وdescription وinputSchema وexecute(input, { signal }) وannotations.
• اتّبِع قواعد الأوصاف والتعليقات التوضيحية.
• التحقّق من صحة الإدخال وتطبيق الإعدادات التلقائية داخل execute
• مرِّر signal إلى العمل الطويل المدى.
• لإتاحة أداة في بعض الأحيان فقط، مرِّر enabled (React, Vue). لا تضع الخطاف أو الدالة المركّبة في شرط.
• قد تدمج عمليات الدمج النتائج والأخطاء (على سبيل المثال، كـ { content, isError }). يُرجى مراجعة مستندات عملية الدمج قبل الاعتماد على كيفية وصول الأخطاء إلى الوكيل.

ملاحظات حول واجهة برمجة التطبيقات

• ‫annotations: (اختياري) قاموس للبيانات الوصفية للأداة.
  • ‫readOnlyHint: (اختياري) يتم ضبطه على true إذا كانت الأداة لا تعدّل أي حالة وتقرأ البيانات فقط. يساعد ذلك الوكلاء في تحديد الحالات التي يكون فيها من الآمن استدعاء الأداة.
  • ‫consequentialHint: (اختياري، الإصدار 154 من Chrome والإصدارات الأحدث) يتم ضبطه على true للإجراءات المهمة أو غير القابلة للتراجع أو الواقعية، لكي يطلب الوكلاء تأكيد المستخدم أولاً.
  • ‫untrustedContentHint: (اختياري) يتم ضبطه على true عندما تعرض الأداة محتوًى لا يتحكّم فيه موقعك الإلكتروني، مثل النصوص من إنشاء المستخدمين أو الردود من واجهات برمجة التطبيقات التابعة لجهات خارجية.
  • ‫debugging: (اختياري، الإصدار 156 من Chrome والإصدارات الأحدث) يتم ضبطه على true عندما تكون الأداة مخصّصة لتصحيح الأخطاء وأدوات المطوّرين، وليس لمهام المستخدم النهائي. القيمة التلقائية هي false.
• خيارات التسجيل:
  • ‫signal: (اختياري) AbortSignal يُستخدَم لإلغاء تسجيل الأداة عندما لا تعود هناك حاجة إليها.
  • ‫exposedTo: (اختياري) مصفوفة من سلاسل المصادر الآمنة التي تتحكّم في المستندات المسموح لها في شجرة المستندات باكتشاف الأداة وتنفيذها عبر حدود الإطارات.
• خيارات استكشاف الأدوات (ModelContextGetToolOptions):
  • ‫fromOrigins: (اختياري) مصفوفة من سلاسل المصادر الآمنة لطلب البحث في الإطارات التي يمكن الوصول إليها. يؤدي استدعاء getTools() بدون fromOrigins إلى البحث في المستندات من المصدر نفسه فقط.
• تنسيق الإرجاع: يمكن أن تعرض الدالة execute أي قيمة قابلة للتسلسل بتنسيق JSON (كائن أو مصفوفة أو سلسلة أو رقم أو قيمة منطقية). لا تتم إعادة توجيه رسالة الاستثناء التي تم طرحها من execute إلى الوكيل، لذا يجب عرض الأخطاء القابلة للتنفيذ كحمولة أخطاء منظَّمة (مثل { error: "..." }) من خلال القيمة المعروضة للأداة ليتمكّن الوكيل من قراءتها واتّخاذ إجراء بشأنها.
• سياق آمن: يتطلّب WebMCP استخدام بروتوكول HTTPS. يجب أيضًا أن تكون جميع المصادر في exposedTo وfromOrigins موثوقة.
• الميزات المتوقّفة نهائيًا أو التي تمت إزالتها: لم تعُد الميزات navigator.modelContext (متوقّفة نهائيًا في الإصدار 150 من Chromium) وunregisterTool() وprovideContext() وclearContext() متاحة.

استراتيجيات احتياطية

يجب استخدام WebMCP Imperative API مع ميزة "رصد الميزات" لضمان التوافق مع المتصفّحات التي لا تتيح استخدام WebMCP بعد.

if ('modelContext' in document) {
  // Register tools
}