声明性 API

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

Published: May 18, 2026

说明类视频 Web 扩展程序 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，以便专门针对基于智能体的互动调整 Web 应用的行为。

此外，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>

浏览器会使用 "toolactivated" 事件发出 AI 智能体执行工具的信号。此事件会在表单字段预填充后在窗口中触发。相反，如果 用户取消了智能体操作或调用了 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 并有反馈，欢迎您与我们分享。