声明性 API

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

发布时间：2026 年 5 月 18 日

说明类视频 Web 扩展程序 Chrome 状态 目的
GitHub 开发者试用 开发者试用 开发者试用 开发者试用 查看 实验意向

通过添加注释，使用声明性 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 并有反馈意见，欢迎随时告诉我们。