فرم‌های عامل‌گرا

Declarative API عناصر استاندارد HTML <form> را ازطریق مشخصه‌ها به ابزارهای WebMCP تبدیل می‌کند. مرورگر یک «طرح‌واره JSON» را از ورودی‌های فرم ترکیب می‌کند و تعاملات عامل را مدیریت می‌کند.

Angular Signal Forms: DO NOT add toolname/tooldescription to forms built with form() from @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>

مدیریت ارسال‌ها در جاوا اسکریپت

وقتی نماینده فرم را ارسال می‌کند، 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;
}

مناسب بودن فرم (چه زمانی باید اجتناب کرد)

«میانای برنامه‌سازی کاربردی اعلانی» برای فرم‌های استاندارد مستقل بهترین گزینه است. در این سناریوها انتخاب خوبی نیست:

• فیلدهای بسیار وابسته: فرم‌هایی که در آن‌ها ورودی‌ها گزینه‌ها یا رؤیت‌پذیری را براساس ورودی‌های دیگر تغییر می‌دهند. طرح ترکیبی نمی‌تواند این وابستگی‌ها را به‌خوبی بیان کند.
• مؤلفه‌های واسط کاربر سفارشی: فرم‌هایی که به ورودی‌های غیراستاندارد (مثلاً بوم، ویرایشگرهای نوشتار غنی‌شده) متکی هستند و مقادیر را به‌طور خودکار سریال‌سازی نمی‌کنند.
• جادوگرهای چندمرحله‌ای: گردش‌های کاری پیچیده که به ارسال چند فرم نیاز دارند. Imperative API یا تعامل DOM استاندارد برای اینجا مناسب‌تر است.

چه زمانی از toolautosubmit استفاده کنیم

• عملیات و پُرسمان‌های فقط خواندنی: جستجوها، فیلترها، واکشی جزئیات، یا بررسی وضعیت (برای مثال، جستجوی مدل خودرو، جستجوی دایرکتوری، بررسی موجودی کالا).
• کنش‌های برگشت‌پذیر کم‌خطر: کنش‌های فرم که کاربر می‌تواند به‌راحتی آن‌ها را به‌صورت دستی واگرد یا اصلاح کند (برای مثال، افزودن موارد به سبد خرید، اعمال کد تخفیف، ذخیره کردن پیش‌نویس، یا تنظیم گزینه‌های چیدمان موقت).

چه زمانی toolautosubmit را حذف کنیم

• کنش‌های مخرب یا برگشت‌ناپذیر: حذف سوابق، بازنشانی پیکربندی‌های سیستم، یا پاک کردن پایگاه‌های داده.
• کنش‌های مالی و تراکنشی: ارسال فرم تسویه‌حساب، انتقال وجه، صدور مجوز پرداخت اشتراک، یا ثبت نهایی سفارش.
• ارتباطات کاربر با تأثیر بالا: ارسال درخواست نهایی شغل، ارسال ایمیل/ پیام به کاربران واقعی دیگر، یا انتشار محتوای عمومی.
• تنظیمات حساس حساب: تغییر گذرواژه‌ها، اصلاح نقش‌ها/اجازه‌های کاربر، یا به‌روزرسانی اطلاعات صورت‌حساب/نمایه.

راهبردهای جایگزین

استفاده از WebMCP Declarative API در همه مرورگرها ایمن است. مرورگرهایی که از WebMCP پشتیبانی نمی‌کنند، مشخصه‌های tool* را نادیده می‌گیرند و <form> همچنان به‌عنوان یک فرم HTML معمولی عمل خواهد کرد. نیازی به تشخیص ویژگی نیست.