Biểu mẫu tác nhân

Tính năng web: Các thuộc tính WebMCP liên kết với biểu mẫu

API khai báo chuyển đổi các phần tử HTML <form> chuẩn thành các công cụ WebMCP thông qua các thuộc tính. Trình duyệt tổng hợp Giản đồ JSON từ dữ liệu đầu vào của biểu mẫu và xử lý các hoạt động tương tác của tác nhân.

Biểu mẫu tín hiệu Angular: KHÔNG thêm toolname/tooldescription vào biểu mẫu được tạo bằng form() từ @angular/forms/signals. Thay vào đó, hãy thêm provideExperimentalWebMcpForms() vào nhà cung cấp ứng dụng và truyền tuỳ chọn experimentalWebMcpTool: { name, description } đến form(). Sau đó, Angular đăng ký biểu mẫu thông qua API mệnh lệnh, xây dựng giản đồ từ mô hình tín hiệu và kết nối giản đồ đó với quy trình xác thực và gửi. Việc sử dụng cả hai phương pháp sẽ đăng ký cùng một biểu mẫu hai lần.

Thuộc tính biểu mẫu

  • toolname: Tên riêng biệt của công cụ.
  • tooldescription: Chức năng của công cụ và thời điểm tác nhân nên sử dụng công cụ đó. Đừng liệt kê các trường, lựa chọn hoặc giới hạn của biểu mẫu: trình duyệt đã đưa các thông tin này vào giản đồ mà trình duyệt tạo từ các thành phần điều khiển biểu mẫu.
  • toolautosubmit: (Không bắt buộc) Nếu có, nhân viên hỗ trợ có thể gửi biểu mẫu mà không cần đợi người dùng tương tác.
  • toolparamdescription: (Không bắt buộc) Cung cấp cách xác định nội dung mô tả thuộc tính trong Giản đồ JSON. Hãy sử dụng văn bản này để giải thích ý nghĩa của giá trị (ví dụ: bằng các giá trị mẫu), chứ không phải để lặp lại các lựa chọn hoặc giới hạn của chế độ kiểm soát.
    • Thứ tự phân giải: Trình duyệt sử dụng toolparamdescription nếu có. Nếu không có, thì thuộc tính này sẽ sử dụng textContent của <label> được liên kết (bỏ qua các thành phần con có thể gắn nhãn). Nếu không có nhãn nào, nhãn sẽ quay lại aria-description.
    • Nhóm (Fieldset): Để đính kèm nội dung mô tả vào một nhóm các phần tử có liên quan (như nút <input type="radio">), hãy đặt toolparamdescription trên phần tử mẹ <fieldset> gần nhất để nội dung mô tả đó áp dụng cho toàn bộ nhóm tham số.

Ví dụ

<form toolname="search-cars" 
      tooldescription="Perform a car make/model search" 
      toolautosubmit>
  <label for="make">Vehicle Make</label>
  <input type="text" id="make" name="make" required>
  
  <label for="model">Vehicle Model</label>
  <input type="text" id="model" name="model" toolparamdescription="e.g., 330i, F-150" required>
  
  <button type="submit">Search</button>
</form>

Xử lý nội dung gửi trong JavaScript

Khi nhân viên hỗ trợ gửi biểu mẫu, SubmitEvent sẽ bao gồm agentInvoked (boolean) và respondWith(promise).

document.querySelector('form').addEventListener('submit', (event) => {
  event.preventDefault();

  // Validate the form
  const formValidationErrors = myFormIsValid();

  if (formValidationErrors.length > 0) {
    if (event.agentInvoked) {
      const errorString =
        'Validation failed: ' +
        formValidationErrors
          .map((err) => `${err.field} (${err.message})`)
          .join(', ');

      event.respondWith(Promise.resolve(errorString));
    }
    return;
  }

  const resultPromise = performAsyncSearch(new FormData(event.target));

  // Return the result directly to the agent without navigation
  if (event.agentInvoked) {
    event.respondWith(resultPromise);
  }
});

Sự kiện trong vòng đời

document.modelContext phát ra các sự kiện khi tác nhân bắt đầu hoặc dừng tương tác với một công cụ: toolactivated kích hoạt khi quá trình thực thi công cụ bắt đầu và toolcancel kích hoạt khi quá trình này bị huỷ.

// Starting in Chrome 156, these events are dispatched on `document.modelContext`.
// Older versions dispatch them on `window`. Feature-detect the event handler
// property to pick the right target for backward compatibility.
const targetFor = (type, listener, options) =>
  (`on${type}` in (document.modelContext ?? {}) ? document.modelContext : window)
    .addEventListener(type, listener, options);

targetFor('toolactivated', ({ toolName }) => {
  console.log(`Tool "${toolName}" started execution.`);
});

targetFor('toolcancel', ({ toolName }) => {
  console.log(`Tool "${toolName}" execution is cancelled.`);
});

Phản hồi trực quan (CSS)

Sử dụng lớp giả để làm nổi bật biểu mẫu khi nhân viên hỗ trợ tương tác với biểu mẫu:

  • :tool-form-active: Áp dụng cho phần tử <form> mà tác nhân đang sử dụng.
  • :tool-submit-active: Áp dụng cho nút gửi khi trình duyệt tạm dừng để người dùng xem xét (nếu bỏ qua toolautosubmit).
form:tool-form-active {
  outline: 2px dashed blue;
  background-color: rgba(0, 0, 255, 0.05);
}

button:tool-submit-active {
  outline: 2px dashed red;
  animation: pulse 2s infinite;
}

Mức độ phù hợp của biểu mẫu (Trường hợp nên tránh)

API khai báo phù hợp nhất với các biểu mẫu chuẩn, độc lập. Bạn không nên chọn phương pháp này trong các trường hợp sau:

  • Trường có mức độ phụ thuộc cao: Biểu mẫu trong đó dữ liệu đầu vào thay đổi các lựa chọn hoặc chế độ hiển thị dựa trên dữ liệu đầu vào khác. Giản đồ tổng hợp không thể thể hiện rõ các phần phụ thuộc này.
  • Thành phần giao diện người dùng tuỳ chỉnh: Biểu mẫu dựa trên dữ liệu đầu vào không chuẩn (ví dụ: canvas, trình chỉnh sửa văn bản đa dạng thức) không tự động chuyển đổi tuần tự các giá trị.
  • Trình hướng dẫn nhiều bước: Quy trình công việc phức tạp yêu cầu gửi nhiều biểu mẫu. API mệnh lệnh hoặc tương tác DOM chuẩn sẽ phù hợp hơn trong trường hợp này.

Trường hợp sử dụng toolautosubmit

  • Thao tác và truy vấn chỉ có thể đọc: Tìm kiếm, lọc, tìm nạp thông tin chi tiết hoặc kiểm tra trạng thái (ví dụ: tìm kiếm mẫu xe, tìm kiếm danh bạ, kiểm tra tình trạng còn hàng).
  • Hành động có rủi ro thấp, có thể huỷ bỏ: Các hành động trên biểu mẫu mà người dùng có thể dễ dàng huỷ bỏ hoặc tinh chỉnh theo cách thủ công (ví dụ: thêm mặt hàng vào giỏ hàng, áp dụng mã giảm giá, lưu bản nháp hoặc đặt các lựa chọn bố cục tạm thời).

Trường hợp bỏ qua toolautosubmit

  • Hành động phá hoại hoặc không thể huỷ bỏ: Xoá bản ghi, đặt lại cấu hình hệ thống hoặc xoá cơ sở dữ liệu.
  • Hành động tài chính và giao dịch: Gửi biểu mẫu thanh toán, chuyển tiền, uỷ quyền thanh toán gói thuê bao hoặc đặt hàng lần cuối.
  • Giao tiếp có tác động lớn đến người dùng: Gửi đơn xin việc cuối cùng, gửi email/tin nhắn cho người dùng thực khác hoặc xuất bản nội dung công khai.
  • Cài đặt tài khoản nhạy cảm: Thay đổi mật khẩu, sửa đổi vai trò/quyền của người dùng hoặc cập nhật thông tin thanh toán/hồ sơ.

Chiến lược dự phòng

Bạn có thể sử dụng WebMCP Declarative API một cách an toàn trong mọi trình duyệt. Các trình duyệt không hỗ trợ WebMCP sẽ bỏ qua các thuộc tính tool* và <form> sẽ tiếp tục hoạt động như một biểu mẫu HTML thông thường. Không cần phát hiện tính năng.