Declarative API

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

פורסם: 18 במאי 2026, עדכון אחרון: 25 בספטמבר 2026

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

אפשר להשתמש ב-Declarative API כדי להפוך טפסים רגילים של HTML לכלים של WebMCP על ידי הוספת הערות. ההערות מגדירות את השם והמטרה של הכלי ברכיב <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". התג הזה מופעל בדף document.modelContext אחרי שממלאים מראש את השדות בטופס. לעומת זאת, אם משתמש מבטל את הפעולה של הסוכן או אם מופעלת השיטה reset(), מופעל אירוע "toolcancel". אי אפשר לבטל את שני האירועים האלה, ויש להם מאפיין toolName לזיהוי.

document.modelContext.addEventListener('toolactivated', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was activated.`);
  // TODO: Update UI or validate form if needed.
});

document.modelContext.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 הזה ויהיה לכם משוב, נשמח לשמוע אותו.

הקודם
Imperative API
הבא
WebMCP לעומת MCP