Declarative API

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

Published: May 18, 2026

Explainer الويب الإضافات حالة Chrome النيّة بالشراء
GitHub مرحلة التجربة والتقييم مرحلة التجربة والتقييم العرض النيّة بالتجربة

يمكنك استخدام واجهة برمجة التطبيقات الإعلانية لتحويل نماذج 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 Schema. بدون هذه السمة، يستخدم المتصفّح المحتوى ضمن <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". يتم تفعيل هذا الحدث في النافذة بعد ملء حقول النموذج مسبقًا. في المقابل، إذا ألغى المستخدم العملية المستندة إلى الوكيل أو تم استدعاء الطريقة reset()، يتم تفعيل الحدث "toolcancel". لا يمكن إلغاء كلا الحدثَين، ويوفّران سمة toolName لتحديد الهوية.

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

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

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

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

  • يتم تطبيق :tool-form-active على عنصر form في HTML الخاص بالأداة.
  • يتم تطبيق :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 حاليًا لمناقشة نشطة وقد يتغيّر في المستقبل. إذا جرّبت واجهة برمجة التطبيقات هذه وكانت لديك ملاحظات، يُرجى إعلامنا بها.