Declarative API

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

Ngày xuất bản: 18 tháng 5 năm 2026

Thông tin giải thích Web Phần mở rộng Trạng thái của Chrome Mục đích
GitHub Bản dùng thử theo nguyên gốc Bản dùng thử theo nguyên gốc Xem Mục đích thử nghiệm

Sử dụng API khai báo để chuyển đổi biểu mẫu HTML tiêu chuẩn thành công cụ WebMCP bằng cách thêm chú thích. Chú thích xác định tên và mục đích của công cụ trong phần tử <form>, trong khi các trường đóng vai trò là tham số của công cụ. Trình duyệt sẽ chuyển các phần tử này thành một biểu diễn có cấu trúc mà các tác nhân có thể sử dụng tương tự như các công cụ bắt buộc.

Trước khi sử dụng API này, hãy đọc về các trường hợp sử dụng mẫu.

Đăng ký công cụ

Thêm các thuộc tính HTML sau vào biểu mẫu:

  • toolname: Đặt tên rõ ràng cho công cụ dựa trên mục đích của công cụ đó.
  • tooldescription: Mô tả hành động mà công cụ thực hiện và mục đích của công cụ đó.

Ví dụ: biểu mẫu sau đây nằm tại example.com/get-customer-support:

<form toolname="createSupportRequest" tooldescription="Submits a request for customer support.">
</form>

Khi một tác nhân gọi toolname, trình duyệt sẽ tập trung vào biểu mẫu và điền vào trường của biểu mẫu đó. Biểu mẫu vẫn hiển thị cho người dùng.

Nếu bạn xoá thuộc tính HTML toolname hoặc tooldescription, công cụ sẽ bị huỷ đăng ký.

(Không bắt buộc) Tham số của công cụ

Để cải thiện độ chính xác, hãy thêm các thuộc tính HTML sau vào từng phần tử biểu mẫu:

  • toolparamdescription: Liên kết các phần tử với nội dung mô tả thuộc tính trong Lược đồ JSON. Nếu không có thuộc tính này, trình duyệt sẽ sử dụng nội dung trong <label> được liên kết và bỏ qua các phần tử con có thể gắn nhãn. Nếu không có nhãn, trình duyệt sẽ tham chiếu đến aria-description.

Biểu mẫu sau đây sử dụng các tham số không bắt buộc cho phần tử <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>

Trình duyệt diễn giải biểu mẫu này dưới dạng một công cụ, được biểu thị bằng JSON sau:

[
  {
    "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"
      ]
    }
  }
]

Gửi biểu mẫu

Bạn có 2 lựa chọn để gửi biểu mẫu:

  • Người dùng phải nhấp vào Gửi theo cách thủ công để hoàn tất tác vụ.
  • Thêm toolautosubmit để kích hoạt quá trình gửi và điều hướng khi mô hình gọi công cụ này.

Giao diện SubmitEvent giới thiệu thuộc tính boolean agentInvoked. Thuộc tính này được đặt thành true bất cứ khi nào một biểu mẫu được kích hoạt bởi tác nhân AI, để điều chỉnh hành vi của ứng dụng web dành riêng cho các tương tác dựa trên tác nhân.

Ngoài ra, SubmitEvent bao gồm phương thức respondWith(Promise<any>), vì vậy, bạn có thể truyền một lời hứa đến trình duyệt mà bạn giải quyết bằng kết quả của biểu mẫu. Sau đó, giá trị kết quả sẽ được tuần tự hoá và trả về mô hình dưới dạng đầu ra của công cụ. Để sử dụng phương thức này, trước tiên, bạn phải gọi preventDefault() để dừng quá trình gửi biểu mẫu tiêu chuẩn của trình duyệt.

<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>

Trình duyệt báo hiệu rằng một tác nhân AI đã thực thi một công cụ bằng sự kiện "toolactivated". Sự kiện này sẽ kích hoạt trên cửa sổ sau khi các trường biểu mẫu được điền sẵn. Ngược lại, nếu người dùng huỷ thao tác dựa trên tác nhân hoặc phương thức reset() được gọi, thì sự kiện "toolcancel" sẽ được kích hoạt. Cả hai sự kiện này đều không thể huỷ và cung cấp thuộc tính toolName để nhận dạng.

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.
});

Sửa đổi chỉ báo lấy tiêu điểm

Chỉ báo lấy tiêu điểm có thể nhìn thấy là rất quan trọng để thông báo cho người dùng và tác nhân biết vị trí của họ trên một trang. Khi một tác nhân gọi thành công một công cụ, tập trung vào biểu mẫu được liên kết và tự động điền các trường của biểu mẫu đó, trình duyệt sẽ kích hoạt các giả lớp CSS cụ thể để phản hồi bằng hình ảnh:

  • :tool-form-active được áp dụng cho phần tử form HTML của công cụ.
  • :tool-submit-active được áp dụng cho nút gửi của biểu mẫu (nếu có).

Các lớp này sẽ bị vô hiệu hoá sau khi biểu mẫu gửi, tác nhân huỷ thao tác hoặc người dùng đặt lại biểu mẫu. Bạn có thể tuỳ chỉnh CSS cho các trạng thái này hoặc dựa vào kiểu trình duyệt mặc định.

/* 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;
}

Tìm hiểu thêm về các phương pháp hay nhất và kiểu lấy tiêu điểm.

Tương tác và chia sẻ ý kiến phản hồi

WebMCP đang được thảo luận tích cực và có thể thay đổi trong tương lai. Nếu bạn dùng thử API này và có ý kiến phản hồi, chúng tôi rất mong nhận được ý kiến của bạn.