Declarative API

Alexandra Klepper

تم النشر في: 18 مايو 2026

مستند توضيحي	الويب	الإضافات	حالة Chrome	النيّة بالشراء
GitHub	إصدار تجريبي للمطوّرين	إصدار تجريبي للمطوّرين	العرض	النيّة بالتجربة

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

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

تسجيل الأداة

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

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

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

<form toolname="supportRequestTool" tooldescription="Submit a request for 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 toolparamtitle="Support type" 
    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": {
        "text": {
          "type": "string",
          "title": "firstName",
          "description": "First name"
        },
        "text": {
          "type": "string",
          "title": "lastName",
          "description": "Last name"
        },
        "select": {
          "type": "string",
          "anyOf": [
            {
              "const": "Customer happiness team",
              "title": "Return my purchase."
            },
            {
              "const": "Distribution team",
              "title": "Check where my package is."
            },
            {
              "const": "Website support team",
              "title": "Get help on the website."
            }
          ],
          "enum": [
            "Customer happiness team",
            "Distribution team",
            "Website support team"
          ],
          "title": "Support type",
          "description": "Determines what team this request is routed to."
        }
      },
      "required": [
        "select"
      ]
    }
  }
]

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

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

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

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

بالإضافة إلى ذلك، تتضمّن 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 قيد المناقشة النشطة وهو خاضع للتغيير في المستقبل. إذا جرّبت واجهة برمجة التطبيقات هذه وكانت لديك ملاحظات، يُرجى إعلامنا بها.

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