WebMCP cho website cho phép bạn mô tả một hành động web như tìm kiếm, lọc sản phẩm hoặc gửi yêu cầu hỗ trợ dưới dạng công cụ có tên, mô tả và tham số có cấu trúc. Với Declarative API, bạn bắt đầu từ một thẻ HTML <form>, thêm các thuộc tính WebMCP rồi để trình duyệt cung cấp form đó cho agent tương thích.
Kết quả mục tiêu của bài này là một form tìm kiếm vẫn hoạt động với người dùng thông thường, đồng thời agent WebMCP-aware có thể nhận diện tool, điền trường query và gửi theo chính sách bạn chọn. WebMCP hiện vẫn là đề xuất thử nghiệm, chưa phải W3C Standard; tài liệu dự thảo được công bố ngày 10 tháng 9 năm 2026 (theo webmachinelearning.github.io).
WebMCP khác gì việc agent tự bấm giao diện?
WebMCP là API web đề xuất để ứng dụng công khai một số chức năng dưới dạng tool cho AI agent. Nếu không có lớp mô tả này, agent thường phải quan sát giao diện, tìm nút, điền trường và mô phỏng thao tác của người dùng. Với WebMCP, website khai báo trước tên hành động, mục đích và dữ liệu đầu vào; agent có thể gửi tham số theo cấu trúc rõ ràng hơn (theo developer.chrome.com).
WebMCP không tự biến website thành API công khai cho mọi máy chủ bên ngoài và cũng không thay thế backend. Công cụ được đăng ký trong ngữ cảnh trình duyệt; khả năng nhìn thấy và thực thi phụ thuộc vào trình duyệt, agent, phiên đăng nhập và chính sách của website.
| Cách tương tác | Agent phải làm gì? | Website cung cấp gì? |
|---|---|---|
| Mô phỏng giao diện | Nhìn trang, đoán nút, điền trường và bấm gửi | HTML, CSS và trạng thái hiển thị |
| WebMCP Declarative API | Gọi tool với tham số có cấu trúc | Tên tool, mô tả và schema suy ra từ form |
| API hoặc MCP backend | Gọi dịch vụ phía máy chủ | Endpoint, xác thực và logic backend |
Vì vậy, WebMCP phù hợp khi hành động đã tồn tại trong website và bạn muốn agent đi qua luồng đó. Xác thực, phân quyền, kiểm tra dữ liệu, giới hạn tần suất và xác nhận giao dịch vẫn phải được xử lý độc lập.
Chọn và chuẩn hóa form trước khi công khai cho agent
Hãy bắt đầu với hành động có phạm vi hẹp, kết quả dễ kiểm tra và rủi ro thấp. Form tìm kiếm, lọc sản phẩm hoặc gửi yêu cầu hỗ trợ thường phù hợp hơn thanh toán, xóa dữ liệu hay thay đổi quyền tài khoản.
- Form có một mục tiêu rõ ràng, chẳng hạn “tìm sản phẩm theo từ khóa”.
- Mỗi trường có
nameổn định để trở thành tên tham số. - Trường quan trọng có
label, kiểu nhập phù hợp vàrequiredkhi cần. - Máy chủ vẫn kiểm tra dữ liệu, quyền truy cập, trạng thái đăng nhập và giới hạn tần suất.
- Luồng gửi form truyền thống vẫn hoạt động khi trình duyệt hoặc agent không hỗ trợ WebMCP.
Đây là bước bắt buộc chứ không chỉ là cải thiện khả năng tiếp cận. Nhãn, kiểu input và giá trị option giúp người dùng, công nghệ hỗ trợ và agent cùng hiểu đúng ý nghĩa dữ liệu.
Thêm Declarative API vào HTML form
1. Khai báo tên, mô tả và tham số
Mở mã nguồn giao diện hoặc template chứa form trên môi trường phát triển hoặc staging, rồi thêm toolname và tooldescription. Theo tài liệu Declarative API, thiếu một trong hai thuộc tính này thì form không được đăng ký theo cơ chế này (theo developer.chrome.com).
<form
method="get"
action="/search"
toolname="searchProducts"
tooldescription="Tìm sản phẩm theo từ khóa và mở trang kết quả tìm kiếm."
>
<label for="query">Từ khóa sản phẩm</label>
<input
id="query"
name="query"
type="search"
required
toolparamdescription="Tên hoặc đặc điểm của sản phẩm cần tìm."
>
<button type="submit">Tìm kiếm</button>
</form>Đoạn mã trên được chèn vào HTML/template của trang, không chạy trong bảng điều khiển máy chủ. Nếu đường dẫn thật không phải /search, thay bằng endpoint xử lý form của bạn. Kết quả mong đợi là form vẫn có thể gửi bằng nút Tìm kiếm, còn agent tương thích nhìn thấy tool có tên searchProducts và tham số query.
toolnamelà tên định danh; dùng tên ổn định, dễ phân biệt và không chứa khoảng trắng.tooldescriptionmô tả hành động và kết quả, không phải câu quảng cáo.name="query"trở thành tên trường trong dữ liệu đầu vào.toolparamdescriptiongiải thích ý nghĩa nghiệp vụ của tham số.action="/search"giữ lại fallback HTML truyền thống.
Nếu không có toolparamdescription, trình duyệt có thể dùng nội dung của label để mô tả trường. Với tham số có ý nghĩa đặc thù, nên viết mô tả riêng để giảm khả năng agent suy đoán sai (theo developer.chrome.com).
2. Giới hạn lựa chọn bằng select
Nếu tham số chỉ nhận một tập giá trị cố định, dùng <select> thay vì để agent tự tạo chuỗi. Các giá trị value là dữ liệu gửi lên máy chủ; nội dung hiển thị giữa hai thẻ <option> có thể khác.
<label for="category">Danh mục</label>
<select
id="category"
name="category"
required
toolparamdescription="Danh mục sản phẩm cần tìm."
>
<option value="laptop">Laptop</option>
<option value="monitor">Màn hình</option>
<option value="keyboard">Bàn phím</option>
</select>Backend phải kiểm tra lại rằng category là laptop, monitor hoặc keyboard. HTML validation và schema do trình duyệt tạo ra không phải ranh giới bảo mật.
3. Chỉ bật tự động gửi cho hành động rủi ro thấp
Không thêm toolautosubmit ở giai đoạn đầu nếu bạn muốn người dùng xem lại dữ liệu trước khi gửi. Khi thuộc tính boolean này được bật, việc gọi tool có thể kích hoạt gửi form và tiếp tục theo luồng của form (theo developer.chrome.com).
<form
method="get"
action="/search"
toolname="searchProducts"
tooldescription="Tìm sản phẩm theo từ khóa."
toolautosubmit
>
<label for="query">Từ khóa</label>
<input id="query" name="query" type="search" required>
<button type="submit">Tìm kiếm</button>
</form>Mẫu trên chỉ phù hợp khi việc tìm kiếm không tạo, sửa hoặc xóa dữ liệu. Không nên bật tự động gửi cho thanh toán, đặt hàng, gửi email, xóa dữ liệu, đổi quyền truy cập hoặc hành động tạo nghĩa vụ tài chính. Với các luồng đó, giữ bước người dùng xem lại và xác nhận rõ ràng.
Nếu cần trả kết quả có cấu trúc cho agent
Form GET thông thường có thể điều hướng đến trang kết quả và không cần JavaScript riêng. Nếu muốn xử lý bằng API rồi trả một kết quả ngắn cho agent, hãy đăng ký lời hứa xử lý ngay khi nhận sự kiện; không đợi đến sau await fetch() mới gọi respondWith().
Đặt đoạn mã sau trong JavaScript của chính trang chứa form, sau khi DOM đã có form. Thay /api/search bằng endpoint thật và bảo đảm endpoint xác minh phiên đăng nhập, quyền truy cập, dữ liệu đầu vào và cơ chế chống gửi lặp.
const form = document.querySelector('form[toolname="searchProducts"]');
if (form) {
form.addEventListener('submit', (event) => {
if (!event.agentInvoked) {
return;
}
event.preventDefault();
event.respondWith(handleAgentSearch(form));
});
}
async function handleAgentSearch(form) {
const data = new FormData(form);
const query = String(data.get('query') || '').trim();
if (query.length < 2) {
return {
ok: false,
error: 'Từ khóa phải có ít nhất 2 ký tự.'
};
}
try {
const response = await fetch('/api/search', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({ query })
});
if (!response.ok) {
return {
ok: false,
error: 'Không thể hoàn tất tìm kiếm lúc này.'
};
}
const result = await response.json();
return {
ok: true,
resultUrl: result.resultUrl,
count: result.count
};
} catch (error) {
return {
ok: false,
error: 'Không thể kết nối đến dịch vụ tìm kiếm.'
};
}
}Đây là mẫu minh họa, không phải mã triển khai nguyên trạng cho mọi backend. Kiểm tra cấu trúc phản hồi trước khi đọc resultUrl và count; không đưa token, thông tin lỗi nội bộ, dữ liệu cá nhân hoặc dữ liệu nhạy cảm vào kết quả trả cho agent. Nếu website dùng CSRF token, cookie phiên hoặc yêu cầu header riêng, hãy giữ các cơ chế đó trong luồng backend hiện có.
Hiển thị trạng thái và cho phép hủy
Agent không nên khiến hành động trở nên vô hình. Tài liệu Declarative API mô tả các sự kiện toolactivated, toolcancel và các pseudo-class như :tool-form-active, :tool-submit-active để giao diện biểu thị trạng thái tương ứng (theo developer.chrome.com).
form:tool-form-active {
outline: 2px dashed #2563eb;
outline-offset: 4px;
}
form:tool-form-active::before {
content: "AI agent đang chuẩn bị biểu mẫu — hãy kiểm tra trước khi gửi";
display: block;
margin-bottom: 0.75rem;
color: #1d4ed8;
font-size: 0.9rem;
}Đoạn CSS này chỉ là chỉ báo trực quan. Hãy kiểm tra độ tương phản, không che trường nhập và không dùng màu sắc làm tín hiệu duy nhất. Với hành động có hậu quả, cần có văn bản, nút xác nhận và cách hủy rõ ràng.
Kiểm thử trong môi trường tương thích
Hãy kiểm thử trên staging trước khi đưa lên sản xuất. Vì WebMCP đang phát triển, agent hoặc trình duyệt này hoạt động không có nghĩa là mọi môi trường đều hỗ trợ (theo webmachinelearning.github.io).
- Fallback: không dùng agent, gửi form bằng người dùng thông thường và xác nhận trang hoặc phản hồi vẫn đúng.
- Nhận diện: xác nhận agent nhìn thấy đúng
searchProductsvà không có tool trùng tên. - Schema: thử trường bắt buộc, chuỗi quá ngắn, kiểu dữ liệu không hợp lệ và từng giá trị của
select. - Xác nhận: với hành động ghi dữ liệu, kiểm tra người dùng có thể xem lại, sửa và hủy trước khi gửi.
- Lỗi: mô phỏng hết phiên đăng nhập, lỗi mạng, phản hồi 4xx và 5xx; thông báo trả cho agent phải ngắn và không chứa bí mật.
- Gọi lặp: gọi cùng tool nhiều lần để kiểm tra không tạo bản ghi hoặc giao dịch trùng.
- Nhật ký: ghi nhận tên tool, thời điểm, phiên hoặc người dùng và kết quả ở mức cần thiết; không ghi toàn bộ dữ liệu nhạy cảm.
Cách bật và mức hỗ trợ có thể thay đổi theo môi trường. OpenAI mô tả việc kiểm tra WebMCP trong trình duyệt tích hợp của ChatGPT và Chrome với tính năng thử nghiệm hoặc origin trial; hãy đọc hướng dẫn của môi trường bạn định hỗ trợ thay vì ghi cứng một cờ trình duyệt vào tài liệu sản phẩm (theo openai.com).
Các rủi ro phải xử lý ở backend
Mô tả tool không phải cơ chế bảo mật
tooldescription chỉ giúp agent hiểu mục đích. Máy chủ vẫn phải xác thực phiên, phân quyền theo người dùng và bản ghi, kiểm tra kiểu và phạm vi dữ liệu, đồng thời áp dụng giới hạn tần suất.
Không tin dữ liệu do agent gửi
Giới hạn độ dài chuỗi, số lượng mục và kích thước yêu cầu. Từ chối giá trị ngoài danh sách cho phép, chuẩn hóa dữ liệu ở server và kiểm tra lại trạng thái nghiệp vụ ngay trước khi thực thi.
Kiểm soát prompt injection và dữ liệu không đáng tin
Nội dung sản phẩm, bình luận hoặc phản hồi API có thể chứa chỉ dẫn nhằm đánh lừa agent. Bản dự thảo WebMCP nêu prompt injection, thực thi hành động ngoài ý định và rò rỉ riêng tư do tham số quá rộng là những nhóm rủi ro cần xem xét (theo webmachinelearning.github.io).
Phân biệt hành động đọc và hành động ghi
Tìm kiếm hoặc lọc thường dễ kiểm soát hơn đặt hàng, gửi biểu mẫu pháp lý hoặc xóa tài khoản. Hãy yêu cầu xác nhận ở bước cuối, dùng khóa chống lặp khi cần và thiết kế khả năng hủy hoặc hoàn tác nếu nghiệp vụ cho phép.
Khi nào nên dùng WebMCP và khi nào nên dùng API backend?
| Nhu cầu | Lựa chọn phù hợp hơn | Lý do |
|---|---|---|
| Cho agent dùng một form hoặc luồng có sẵn trong trình duyệt | WebMCP Declarative API | Ít thay đổi giao diện và vẫn giữ được fallback HTML. |
| Cung cấp chức năng cho nhiều ứng dụng bên ngoài | API backend hoặc MCP server | Kiểm soát xác thực, phiên bản, giới hạn và giám sát tập trung hơn. |
| Thực hiện giao dịch có giá trị hoặc quyền hạn cao | Backend với bước xác nhận rõ ràng | Không nên giao toàn bộ kiểm soát cho mô tả hoặc tự động gửi của form. |
| Chỉ muốn agent đọc nội dung công khai | HTML có cấu trúc, dữ liệu có ngữ nghĩa hoặc API đọc | Không phải bài toán đọc nào cũng cần đăng ký một tool có khả năng thực thi. |
Lộ trình triển khai tối thiểu
- Chọn một hành động rủi ro thấp như tìm kiếm hoặc lọc.
- Ổn định
name,label, kiểu trường và các giá trị hợp lệ. - Thêm
toolname,tooldescriptionvà mô tả tham số cần thiết. - Giữ bước xác nhận thủ công; chưa bật
toolautosubmit. - Kiểm thử fallback, schema, quyền truy cập, lỗi, log và gọi lặp trên staging.
- Chỉ mở rộng sang hành động ghi dữ liệu khi đã có xác nhận, chống lặp và phương án khôi phục.
Tóm lại, cách an toàn để bắt đầu với WebMCP cho website là chọn một HTML form có mục tiêu rõ ràng, mô tả nó bằng Declarative API và giữ toàn bộ kiểm tra quan trọng ở backend. Hãy coi WebMCP là lớp giao tiếp dành cho agent, không phải lớp bảo mật hay sự thay thế cho API. Nếu form có fallback, tham số rõ ràng, bước xác nhận phù hợp và kiểm thử thực tế, website sẽ dễ được agent sử dụng hơn mà không bỏ qua người dùng thông thường.
Nguồn tham khảo
- WebMCP — Web Machine Learning Community Group, Draft Community Group Report, 10 September 2026.
- WebMCP and AI agents — Chrome for Developers.
- Declarative API — Chrome for Developers.
- WebMCP — webmachinelearning/webmcp GitHub repository.
- The WebMCP Challenge — OpenAI.
