Declarative API

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

תאריך פרסום: 18 במאי 2026

סרטון הסבר פיתוח אתרים תוספים הסטטוס של Chrome הרציונל
GitHub תקופת ניסיון למפתחים ל-תקופת ניסיון למפתחים תקופת ניסיון למפתחים ל-תקופת ניסיון למפתחים תצוגה הבעת עניין בהשתתפות בניסוי

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

לפני שמשתמשים ב-API הזה, כדאי לקרוא על תרחישי שימוש לדוגמה.

רישום כלי

מוסיפים לטופס את מאפייני ה-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. אם לא מציינים את המאפיין הזה, הדפדפן משתמש בתוכן בתוך התג <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 בכל פעם שסוכן AI מפעיל טופס, כדי להתאים את ההתנהגות של אפליקציית האינטרנט במיוחד לאינטראקציות מבוססות-סוכן.

בנוסף, SubmitEvent כולל את השיטה respondWith(Promise<any>), כך שאפשר להעביר אובייקט promise לדפדפן שמוגדר עם התוצאות של הטופס. הערך שמתקבל עובר סריאליזציה ומוחזר למודל כפלט של הכלי. כדי להשתמש בשיטה הזו, צריך קודם להתקשר אל 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>

האותות מהדפדפן מציינים שסוכן AI הפעיל כלי באמצעות האירוע "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 מוחל על רכיב ה-HTML של הכלי form.
  • ‫: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 נמצאת כרגע בתהליכי דיון ויכול להיות שהיא תשתנה. אם תנסו את ה-API הזה ונשמח לקבל מכם משוב.