宣告式 API

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

發布日期：2026 年 5 月 18 日

說明 網頁 擴充功能 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 時，瀏覽器會將焦點帶到表單，並填入表單欄位。使用者仍可查看表單。

如果移除 toolname 或 tooldescription HTML 屬性，工具就會取消註冊。

(選用) 工具參數

如要提高準確率，請在個別表單元素中加入下列 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 布林屬性。每當 AI 代理觸發表單時，這項屬性就會設為 true，以便根據代理程式互動調整網頁應用程式的行為。

此外，SubmitEvent 也包含 respondWith(Promise<any>) 方法，因此您可以將 Promise 傳遞至瀏覽器，並使用表單結果解析該 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 虛擬類別，提供視覺回饋：

  • 會套用至工具的 HTML form 元素。:tool-form-active
  • :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 並提供意見。