Declarative API

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

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

Video 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ử dành cho nhà phát triển Dùng thử dành cho nhà phát triển Bản dùng thử dành cho nhà phát triển Dùng thử dành cho nhà phát triển Xem Ý định thử nghiệm

Sử dụng Declarative API để chuyển đổi các 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ẽ dịch 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 ví dụ.

Đă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="supportRequestTool" tooldescription="Submit a request for support.">
</form>

Khi một tác nhân gọi toolname, trình duyệt sẽ đưa biểu mẫu vào tiêu điểm và điền sẵn trường của biểu mẫu. Người dùng vẫn nhìn thấy biểu mẫu.

Nếu bạn xoá thuộc tính HTML toolname hoặc tooldescription, thì 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: Ánh xạ các phần tử đến nội dung mô tả thuộc tính trong Giản đồ 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 những thành phần 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 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>

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

Gửi biểu mẫu

Bạn có hai 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 nhiệm vụ.
  • Thêm toolautosubmit để kích hoạt quá trình gửi và thay đổi điều hướng.

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 một tác nhân AI, để điều chỉnh hành vi của ứng dụng web của bạn cho các tương tác dựa trên tác nhân.

Ngoài ra, SubmitEvent còn có 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ị thu được sẽ được chuyển đổi tuần tự và trả về cho 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 việc 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 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 có sự hỗ trợ của 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 một 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 tiêu điểm có thể nhìn thấy là yếu tố quan trọng để thông báo cho người dùng và tác nhân biết họ đang ở đâu trên một trang. Khi một tác nhân phần mềm gọi thành công một công cụ, lấy tiêu điểm biểu mẫu được liên kết và điền sẵ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ể để đưa ra phản hồi trực quan:

  • :tool-form-active được áp dụng cho phần tử HTML form 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ị huỷ kích hoạt sau khi biểu mẫu gửi, tác nhân huỷ hành động 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à phong cách lấy nét.

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 được lắng nghe.