Declarative API

Alexandra Klepper

François Beaufort

تاريخ النشر: 18 مايو 2026، تاريخ آخر تعديل: 25 سبتمبر 2026

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

استخدِم Declarative API لتحويل نماذج HTML العادية إلى أدوات WebMCP من خلال إضافة تعليقات توضيحية. تحدّد التعليقات التوضيحية اسم الأداة والغرض منها في العنصر <form>، بينما تعمل الحقول كمعلَمات للأداة. ويحوّل المتصفّح هذه العناصر إلى تمثيل منظَّم يمكن للوكلاء استخدامه بطريقة مشابهة للأدوات الإجرائية.

قبل استخدام واجهة برمجة التطبيقات هذه، اطّلِع على أمثلة على حالات الاستخدام.

تسجيل الأداة

أضِف سمات HTML التالية إلى النموذج:

• toolname: يجب تسمية الأداة بوضوح استنادًا إلى الغرض منها.
• tooldescription: صِف الإجراء الذي تتخذه الأداة والغرض منها.

على سبيل المثال، يتوفّر النموذج التالي على example.com/get-customer-support:

<form toolname="createSupportRequest" tooldescription="Submits a request for customer support.">
</form>

عندما يستدعي الوكيل toolname، يركّز المتصفّح على النموذج ويملأ الحقل. يبقى النموذج مرئيًا للمستخدم.

إذا أزلت سمة HTML‏ toolname أو tooldescription، سيتم إلغاء تسجيل الأداة.

(اختياري) مَعلمات الأداة

لتحسين الدقة، أضِف سمات HTML التالية إلى عناصر النموذج الفردية:

• toolparamdescription: لربط العناصر بوصف خاصية ضمن مخطّط JSON بدون هذه السمة، يستخدم المتصفّح المحتوى ضِمن العنصر <label> المرتبط ويتخطّى العناصر الفرعية التي يمكن تصنيفها. إذا لم يكن هناك تصنيف، يشير المتصفّح إلى aria-description.

يستخدم النموذج التالي المَعلمات الاختيارية للعنصر <select>.

<form toolname="supportRequestTool"
  tooldescription="Submit a request for support."
  action="/submit">

  <label for="firstName">First Name</label>
  <input type=text name=firstName>

  <label for="lastName">Last Name</label>
  <input type=text name=lastName>

  <select name="select" required
    toolparamdescription="Determines what team this request is routed to.">
    <option value="Customer happiness team">Return my purchase.</option>
    <option value="Distribution team">Check where my package is.</option>
    <option value="Website support team">Get help on the website.</option>
  </select>

  <button type=submit>Submit</button>
</form>

يفسّر المتصفّح هذا النموذج كأداة، ويتم تمثيله باستخدام JSON التالي:

[
  {
    "name": "supportRequestTool",
    "description": "Submit a request for support.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "firstName": {
          "type": "string"
        },
        "lastName": {
          "type": "string"
        },
        "select": {
          "type": "string",
          "anyOf": [
            {
              "type": "string",
              "const": "Customer happiness team",
              "title": "Return my purchase."
            },
            {
              "type": "string",
              "const": "Distribution team",
              "title": "Check where my package is."
            },
            {
              "type": "string",
              "const": "Website support team",
              "title": "Get help on the website."
            }
          ],
          "enum": [
            "Customer happiness team",
            "Distribution team",
            "Website support team"
          ],
          "description": "Determines what team this request is routed to."
        }
      },
      "required": [
        "select"
      ]
    }
  }
]

إرسال النموذج

لديك خياران لإرسال النموذج:

• على المستخدم النقر يدويًا على إرسال لإكمال المهمة.
• أضِف toolautosubmit لتفعيل عملية الإرسال وعنصر تنقّل عندما يستدعي النموذج هذه الأداة.

تقدّم واجهة SubmitEvent السمة المنطقية agentInvoked. يتم ضبط هذه السمة على "صحيح" كلّما تم تشغيل نموذج من خلال وكيل الذكاء الاصطناعي، وذلك لتكييف سلوك تطبيق الويب الخاص بك مع التفاعلات المستندة إلى الوكيل على وجه التحديد.

بالإضافة إلى ذلك، يتضمّن SubmitEvent الطريقة respondWith(Promise<any>)، وبالتالي يمكنك تمرير وعد إلى المتصفّح يتم تنفيذه باستخدام نتائج النموذج. بعد ذلك، يتم تحويل القيمة الناتجة إلى سلسلة وإرجاعها إلى النموذج كمخرجات الأداة. لاستخدام هذه الطريقة، يجب أولاً استدعاء preventDefault() لإيقاف عملية إرسال النموذج العادية في المتصفّح.

<form toolautosubmit toolname="search_tool"
  tooldescription="Search the web" action="/search">
  <input type=text name=query>
</form>
<script>
  document.querySelector("form").addEventListener("submit", (e) => {
    e.preventDefault();
    if (!myFormIsValid()) {
      if (e.agentInvoked) { e.respondWith(myFormValidationErrorPromise) };
      return;
    }
    if (e.agentInvoked) { e.respondWith(Promise.resolve("Search is done!")); }
  });
</script>

يشير المتصفّح إلى أنّ وكيل الذكاء الاصطناعي نفّذ أداةً باستخدام الحدث "toolactivated" event. يتم تشغيل هذا الحدث عند document.modelContext بعد ملء حقول النموذج مسبقًا. في المقابل، إذا ألغى المستخدم العملية التي ينفّذها الوكيل أو تم استدعاء الطريقة reset()، سيتم تشغيل الحدث "toolcancel". لا يمكن إلغاء أي من هذين الحدثين، كما أنّهما يوفّران السمة toolName لتحديد الهوية.

document.modelContext.addEventListener('toolactivated', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was activated.`);
  // TODO: Update UI or validate form if needed.
});

document.modelContext.addEventListener('toolcancel', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was cancelled.`);
  // TODO: Let the user know. Update UI.
});

تعديل مؤشر التركيز

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

• يتم تطبيق :tool-form-active على عنصر HTML‏ form الخاص بالأداة.
• يتم تطبيق :tool-submit-active على زر الإرسال في النموذج، إذا كان متوفّرًا.

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

/* Chrome default declarative form styles. */
form:tool-form-active {
  outline: light-dark(blue, cyan) dashed 1px;
  outline-offset: -1px;
}

input:tool-submit-active {
  outline: light-dark(red, pink) dashed 1px;
  outline-offset: -1px;
}

مزيد من المعلومات حول أفضل الممارسات والأسلوب المتعلّقين بالتركيز

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

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

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