Declarative API

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky
François Beaufort
François Beaufort
GitHub

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

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

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

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

רישום כלי

מוסיפים לטופס את מאפייני ה-HTML הבאים:

  • ‫toolname: צריך לתת לכלי שם ברור, על סמך המטרה שלו.
  • ‫tooldescription: מתארים את הפעולה שהכלי מבצע ואת המטרה שלו.

לדוגמה, הטופס הבא נמצא בכתובת example.com/get-customer-support:

<form toolname="createSupportRequest" tooldescription="Submits a request for customer 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 
    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": {
        "firstName": {
          "type": "string"
        },
        "lastName": {
          "type": "string"
        },
        "select": {
          "type": "string",
          "anyOf": [
            {
              "type": "string",
              "const": "Customer happiness team",
              "title": "Return my purchase."
            },
            {
              "type": "string",
              "const": "Distribution team",
              "title": "Check where my package is."
            },
            {
              "type": "string",
              "const": "Website support team",
              "title": "Get help on the website."
            }
          ],
          "enum": [
            "Customer happiness team",
            "Distribution team",
            "Website support team"
          ],
          "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 הזה ונשמח לקבל מכם משוב.