טפסים עם יכולות של AI אקטיבי

‫Declarative API הופך רכיבי HTML <form> רגילים לכלי WebMCP באמצעות מאפיינים. הדפדפן יוצר סכימת JSON מהקלט של הטופס ומטפל באינטראקציות של הסוכן.

טופסי Angular Signal: אל תוסיפו toolname/tooldescription לטפסים שנוצרו באמצעות form() מ-@angular/forms/signals. במקום זאת, צריך להוסיף את provideExperimentalWebMcpForms() לספקי האפליקציה ולהעביר את האפשרות experimentalWebMcpTool: { name, description } אל form(). לאחר מכן, Angular רושם את הטופס דרך ה-API ההכרחי, בונה את הסכימה ממודל האותות ומקשר אותה לאימות ולשליחה. אם משתמשים בשתי השיטות, אותו טופס נרשם פעמיים.

מאפייני הטופס

• ‫toolname: שם ייחודי לכלי.
• ‫tooldescription: מה הכלי עושה ומתי הסוכן צריך להשתמש בו. אל תפרטו את השדות, האפשרויות או המגבלות של הטופס: הדפדפן כבר כולל אותם בסכימה שהוא יוצר מהפקדים של הטופס.
• toolautosubmit: (אופציונלי) אם הוא קיים, הנציג יכול לשלוח את הטופס בלי לחכות לאינטראקציה של המשתמש.
• ‫toolparamdescription: (אופציונלי) מאפשר להגדיר תיאור של מאפיין בסכימת ה-JSON. השתמשו בו כדי להסביר מה המשמעות של הערך (לדוגמה, עם ערכים לדוגמה), ולא כדי לחזור על האפשרויות או המגבלות של הפקד.
  • סדר הרזולוציה: הדפדפן משתמש ב-toolparamdescription אם הוא קיים. אם אין תווית, המערכת משתמשת ב-textContent של ה-<label> המשויך (תוך דילוג על צאצאים שניתן להוסיף להם תוויות). אם אין תווית, המערכת חוזרת אל aria-description.
  • קיבוץ (Fieldsets): כדי לצרף תיאור לקבוצה של רכיבים קשורים (כמו לחצני <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;
}

מתי לא כדאי להשתמש בטפסים

ה-API ההצהרתי מתאים במיוחד לטפסים סטנדרטיים עצמאיים. הוא לא מתאים בתרחישים הבאים:

• שדות עם תלות גבוהה: טפסים שבהם קלט מסוים משנה את האפשרויות או את החשיפה של קלט אחר. הסכימה המסונתזת לא יכולה לבטא את יחסי התלות האלה בצורה טובה.
• רכיבים מותאמים אישית של ממשק המשתמש: טפסים שמסתמכים על קלט לא סטנדרטי (למשל, רכיבי canvas, עורכי טקסט עשיר) שלא מבצעים סריאליזציה אוטומטית של ערכים.
• אשפים עם כמה שלבים: תהליכי עבודה מורכבים שדורשים שליחה של כמה טפסים. במקרה כזה, עדיף להשתמש ב-Imperative API או באינטראקציה רגילה עם DOM.

מתי להשתמש ב-toolautosubmit

• פעולות ושאילתות לקריאה בלבד: חיפושים, סינונים, אחזור פרטים או בדיקת סטטוס (למשל, חיפוש דגם של רכב, חיפוש בספרייה, בדיקת זמינות במלאי).
• פעולות הפיכות בסיכון נמוך: פעולות בטפסים שהמשתמש יכול לבטל או לשנות בקלות באופן ידני (למשל, הוספת פריטים לעגלת הקניות, שימוש בקוד שובר, שמירת טיוטה או הגדרת אפשרויות פריסה זמניות).

מתי להשמיט את toolautosubmit

• פעולות הרסניות או בלתי הפיכות: מחיקת רשומות, איפוס הגדרות מערכת או ניקוי מסדי נתונים.
• פעולות פיננסיות ועסקאות: שליחת טופס תשלום, העברת כספים, אישור תשלומים על מינויים או ביצוע הזמנות סופיות.
• תקשורת עם משתמשים בעלת השפעה רבה: שליחת בקשה סופית למשרה, שליחת אימיילים או הודעות למשתמשים אמיתיים אחרים או פרסום תוכן שגלוי לכולם.
• הגדרות חשבון רגישות: שינוי סיסמאות, שינוי תפקידים או הרשאות של משתמשים, או עדכון פרטי הפרופיל או החיוב.

אסטרטגיות חלופיות

אפשר להשתמש ב-WebMCP Declarative API בבטחה בכל הדפדפנים. דפדפנים שלא תומכים ב-WebMCP יתעלמו מהמאפיינים של tool*, וה-<form> ימשיך לפעול כטופס HTML רגיל. לא נדרש זיהוי תכונות.