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

تحوّل واجهة Declarative API عناصر HTML <form> العادية إلى أدوات WebMCP من خلال السمات. يُنشئ المتصفّح مخطّط JSON من مدخلات النموذج ويتعامل مع تفاعلات الوكيل.

نماذج Angular Signal: لا تضيفوا toolname/tooldescription إلى النماذج التي تم إنشاؤها باستخدام form() من @angular/forms/signals. بدلاً من ذلك، أضِف provideExperimentalWebMcpForms() إلى موفّري التطبيقات ومرِّر الخيار experimentalWebMcpTool: { name, description } إلى form(). بعد ذلك، يسجّل Angular النموذج من خلال واجهة برمجة التطبيقات Imperative API، وينشئ المخطط من نموذج الإشارة ويربطه بعملية التحقّق والإرسال. يؤدي استخدام كلا النهجَين إلى تسجيل النموذج نفسه مرّتَين.

سمات النموذج

• ‫toolname: اسم فريد للأداة
• ‫tooldescription: وظيفة الأداة ومتى يجب أن يستخدمها الوكيل لا تدرِج حقول النموذج أو خياراته أو حدوده، لأنّ المتصفّح يتضمّنها في المخطّط الذي ينشئه من عناصر التحكّم في النموذج.
• ‫toolautosubmit: (اختياري) في حال توفّره، يمكن للوكيل إرسال النموذج بدون انتظار تفاعل المستخدم.
• ‫toolparamdescription: (اختياري) يوفّر طريقة لتحديد وصف السمة ضمن مخطّط JSON. استخدِم هذا النص لشرح معنى القيمة (على سبيل المثال، باستخدام قيم نموذجية)، وليس لتكرار خيارات عنصر التحكّم أو حدوده.
  • ترتيب الحلّ: يستخدم المتصفّح toolparamdescription إذا كان متوفّرًا. وفي حال عدم توفّرها، يتم استخدام textContent للعنصر <label> المرتبط (مع تخطّي العناصر التابعة التي يمكن تصنيفها). في حال عدم توفّر تصنيف، يتم الرجوع إلى aria-description.
  • التجميع (مجموعات الحقول): لإرفاق وصف بمجموعة من العناصر ذات الصلة (مثل أزرار <input type="radio">)، ضَع toolparamdescription على أقرب عنصر رئيسي <fieldset> ليتم تطبيقه على مجموعة المَعلمات ككل.

مثال

<form toolname="search-cars" 
      tooldescription="Perform a car make/model search" 
      toolautosubmit>
  <label for="make">Vehicle Make</label>
  <input type="text" id="make" name="make" required>
  
  <label for="model">Vehicle Model</label>
  <input type="text" id="model" name="model" toolparamdescription="e.g., 330i, F-150" required>
  
  <button type="submit">Search</button>
</form>

معالجة عمليات الإرسال في JavaScript

عندما يرسل الوكيل النموذج، يتضمّن SubmitEvent السمتَين agentInvoked (منطقية) وrespondWith(promise).

document.querySelector('form').addEventListener('submit', (event) => {
  event.preventDefault();

  // Validate the form
  const formValidationErrors = myFormIsValid();

  if (formValidationErrors.length > 0) {
    if (event.agentInvoked) {
      const errorString =
        'Validation failed: ' +
        formValidationErrors
          .map((err) => `${err.field} (${err.message})`)
          .join(', ');

      event.respondWith(Promise.resolve(errorString));
    }
    return;
  }

  const resultPromise = performAsyncSearch(new FormData(event.target));

  // Return the result directly to the agent without navigation
  if (event.agentInvoked) {
    event.respondWith(resultPromise);
  }
});

أحداث مراحل النشاط

يُصدر document.modelContext أحداثًا عندما يبدأ الوكلاء أو يتوقفون عن التفاعل مع أداة: يتم تنشيط toolactivated عند بدء تنفيذ الأداة، ويتم تنشيط toolcancel عند إلغائها.

// Starting in Chrome 156, these events are dispatched on `document.modelContext`.
// Older versions dispatch them on `window`. Feature-detect the event handler
// property to pick the right target for backward compatibility.
const targetFor = (type, listener, options) =>
  (`on${type}` in (document.modelContext ?? {}) ? document.modelContext : window)
    .addEventListener(type, listener, options);

targetFor('toolactivated', ({ toolName }) => {
  console.log(`Tool "${toolName}" started execution.`);
});

targetFor('toolcancel', ({ toolName }) => {
  console.log(`Tool "${toolName}" execution is cancelled.`);
});

الملاحظات المرئية (CSS)

استخدِم الفئات الزائفة لتمييز النماذج عندما يتفاعل معها الوكيل:

• ‫:tool-form-active: يتم تطبيقها على عنصر <form> الذي يستخدمه الوكيل بشكل نشط.
• ‫:tool-submit-active: يتم تطبيقها على زر الإرسال عندما يتوقف المتصفّح مؤقتًا لمراجعة المستخدم (في حال حذف toolautosubmit).

form:tool-form-active {
  outline: 2px dashed blue;
  background-color: rgba(0, 0, 255, 0.05);
}

button:tool-submit-active {
  outline: 2px dashed red;
  animation: pulse 2s infinite;
}

مدى ملاءمة النموذج (حالات تجنُّب استخدامه)

تُعدّ واجهة Declarative API الأفضل للنماذج العادية المستقلة. ويُعدّ خيارًا سيئًا في الحالات التالية:

• الحقول شديدة الاعتمادية: النماذج التي تتغيّر فيها الخيارات أو مستوى الظهور استنادًا إلى إدخالات أخرى لا يمكن للمخطط المركّب التعبير عن هذه التبعيات بشكل جيد.
• مكوّنات واجهة المستخدم المخصّصة: النماذج التي تعتمد على إدخالات غير عادية (مثل اللوحة ومحرّرات النصوص المنسّقة) والتي لا تُسلسل القيم تلقائيًا.
• معالِجات متعددة الخطوات: مهام سير العمل المعقّدة التي تتطلّب إرسال نماذج متعددة من الأفضل استخدام واجهة برمجة التطبيقات Imperative API أو تفاعل DOM العادي هنا.

حالات استخدام toolautosubmit

• العمليات وطلبات البحث للقراءة فقط: عمليات البحث أو الفلترة أو جلب التفاصيل أو التحقّق من الحالة (مثل البحث عن طراز سيارة أو البحث في دليل أو التحقّق من توفّر المخزون).
• الإجراءات المنخفضة المخاطر والقابلة للتراجع: هي إجراءات في النماذج يمكن للمستخدم التراجع عنها أو تحسينها يدويًا بسهولة (مثل إضافة سلع إلى سلة التسوّق أو تطبيق رمز قسيمة أو حفظ مسودة أو ضبط خيارات تنسيق مؤقتة).

حالات حذف toolautosubmit

• الإجراءات المدمّرة أو التي لا يمكن التراجع عنها: حذف السجلات أو إعادة ضبط إعدادات النظام أو محو قواعد البيانات
• الإجراءات المالية والمعاملات: إرسال نموذج دفع أو تحويل الأموال أو الموافقة على دفعات الاشتراك أو تقديم الطلبات النهائية
• التواصل مع المستخدمين بشكل كبير: إرسال طلب وظيفة نهائي أو رسائل إلكترونية/رسائل إلى مستخدمين حقيقيين آخرين أو نشر محتوى موجّه للجمهور
• إعدادات الحساب الحسّاسة: تغيير كلمات المرور أو تعديل أدوار المستخدمين أو أذوناتهم أو تعديل معلومات الفوترة أو الملف الشخصي

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

يمكن استخدام WebMCP Declarative API بأمان في جميع المتصفّحات. ستتجاهل المتصفّحات التي لا تتوافق مع WebMCP سمات tool*، وسيستمر <form> في العمل كنموذج HTML عادي. لا يلزم رصد الميزات.