Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Imperative API

Alexandra Klepper

François Beaufort

Ngày xuất bản: 18 tháng 5 năm 2026, Cập nhật lần gần đây nhất: 15 tháng 10 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ử theo nguyên gốc		Xem	Mục đích thử nghiệm

Bạn có thể sử dụng API bắt buộc WebMCP để xác định nhiều loại công cụ bằng JavaScript tiêu chuẩn. Các công cụ của bạn có thể thực thi nhiều hàm, chẳng hạn như nhập biểu mẫu, điều hướng trang web và quản lý trạng thái.

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

Cung cấp bối cảnh mô hình

Sử dụng giao diện modelContext để đăng ký công cụ. Việc đăng ký công cụ yêu cầu có tên, nội dung mô tả và giản đồ đầu vào với các thuộc tính có liên quan.

Sử dụng registerTool để thêm một công cụ vào bối cảnh mô hình.

Trình tạo WebMCPza

await document.modelContext.registerTool({
  name: 'toggle_layer',
  description: 'Control pizza layers (sauce, cheese). Use "add", "remove", or "toggle".',
  inputSchema: {
    type: 'object',
    properties: {
      layer: { type: 'string', enum: ['sauce-layer', 'cheese-layer'] },
      action: { type: 'string', enum: ['add', 'remove', 'toggle'] },
    },
    required: ['layer'],
  },
  execute: async ({ layer, action }) => {
    await toggleLayer(layer, action);
    return `Performed ${action || 'toggle'} on layer: ${layer}`;
  },
});

Xem trạng thái đơn đặt hàng

await document.modelContext.registerTool({
  name: 'get_order_status',
  description: 'Search orders in a given timeframe. Returns order number, shipping status and location',
  inputSchema: {
    "type": "object",
    "properties": {
      "timeframe": { "type": "string", "oneOf": [
        { "type": "string", "const": "today", "title": "Today" },
        { "type": "string", "const": "yesterday", "title": "Yesterday" },
        { "type": "string", "const": "last_7_days", "title": "Last 7 Days" },
        { "type": "string", "const": "last_30_days", "title": "Last 30 Days" },
        { "type": "string", "const": "last_6_months", "title": "Last 6 Months" }],
      "enum": [ "today", "yesterday", "last_7_days", "last_30_days", "last_6_months" ],
      "description": "Timeframe for the order lookup." }
    },
    "required": [ "timeframe" ]
  },
  execute: async ({ timeframe }) => {
    // Add your API or database logic here to fetch and return the order data as a string.
  },
});

Chú thích công cụ (không bắt buộc)

Khi đăng ký một công cụ, bạn có thể thêm siêu dữ liệu vào thuộc tính annotations. Các chú thích này giúp tác nhân và trình duyệt hiểu được các đặc điểm an toàn, tác dụng phụ dự kiến, độ tin cậy của đầu ra và đối tượng mục tiêu của công cụ:

readOnlyHint (boolean, mặc định là false): Khi true, cho biết rằng công cụ chỉ đọc thông tin và không sửa đổi trạng thái của ứng dụng hoặc hệ thống (ví dụ: tìm kiếm danh mục sản phẩm hoặc truy xuất trạng thái đơn đặt hàng). Điều này giúp các tác nhân xác định xem có thể gọi công cụ một cách an toàn mà không có tác dụng phụ hay không.
untrustedContentHint (boolean, mặc định là false): Khi true, cho biết rằng đầu ra của công cụ chứa dữ liệu không đáng tin cậy theo quan điểm của tác giả công cụ (ví dụ: nội dung do người dùng tạo, bài đánh giá hoặc dữ liệu web bên ngoài). Điều này báo hiệu cho tác nhân và máy khách rằng tải trọng được trả về yêu cầu xử lý bảo mật nâng cao, chẳng hạn như làm sạch hoặc phân tách, để giảm thiểu tiêm câu lệnh gián tiếp (prompt injection).
consequentialHint (boolean, mặc định là false): Khi true, cho biết rằng việc thực thi công cụ sẽ dẫn đến các hành động quan trọng, trong thế giới thực hoặc không thể đảo ngược (ví dụ: đặt vé máy bay, chuyển tiền hoặc xoá dữ liệu). Điều này cho phép các tác nhân và trình duyệt thực thi lời nhắc xác nhận bắt buộc của người dùng trước khi thực thi các công cụ có mức độ rủi ro cao, giảm thiểu nguy cơ vô tình hoặc cố ý xuyên tạc ý định của người dùng.
debugging (boolean, mặc định là false, có từ Chrome 156): Khi true, cho biết rằng công cụ được thiết kế riêng cho việc kiểm tra và công cụ cho nhà phát triển (ví dụ: khung kiểm thử hoặc tính năng hỗ trợ AI của Chrome DevTools) thay vì tương tác với người dùng cuối. Điều này cho phép các tác nhân người dùng đa năng và người dùng cuối lọc ra các công cụ tập trung vào nhà phát triển.

await document.modelContext.registerTool({
  name: 'book_flight',
  description: 'Book a flight for the user with confirmed flight details.',
  inputSchema: {
    type: 'object',
    properties: {
      flightId: { type: 'string', description: 'ID of the flight to book' },
      passengers: { type: 'number', description: 'Number of tickets to purchase' },
    },
    required: ['flightId', 'passengers'],
  },
  annotations: {
    readOnlyHint: false,
    consequentialHint: true,
    untrustedContentHint: false,
    debugging: false,
  },
  execute: async ({ flightId, passengers }) => {
    // Add your flight booking transaction logic here.
    return `Booked ${passengers} passenger(s) on flight ${flightId}.`;
  },
});

Để biết ví dụ về cách chú thích có thể ảnh hưởng đến hành vi của tác nhân, hãy xem phần Ví dụ về tiện ích WebMCP.

Huỷ đăng ký công cụ

Bạn có thể xoá một công cụ bằng AbortSignal khi được truyền dưới dạng tham số không bắt buộc.

const addTodoTool = {
  name: "addTodo",
  description: "Add a new item to the to-do list",
  inputSchema: {
    type: "object",
    properties: { text: { type: "string" } },
  },
  execute: async ({ text }) => {
    // You should handle the persistence logic here (omitted for demo)
    return `Added to-do: ${text}`;
  },
  annotations: {
    readOnlyHint: false,
    untrustedContentHint: true
  },
};
const controller = new AbortController();
await document.modelContext.registerTool(addTodoTool, { signal: controller.signal });

// Unregister the tool later...
controller.abort();

Kể từ Chrome 153, bạn có thể huỷ đăng ký một công cụ mà không cần huỷ và làm gián đoạn quá trình thực thi đang diễn ra. Điều này giúp ngăn chặn các tác dụng phụ không mong muốn khi quản lý vòng đời của công cụ trong các khung thành phần.

Xử lý việc huỷ công cụ

Hàm execute nhận một tham số AbortSignal có tên là signal làm đối số thứ hai để xử lý một cách suôn sẻ các yêu cầu huỷ thực thi do người dùng hoặc tác nhân khởi tạo. Việc truyền tín hiệu này đến các tác vụ không đồng bộ chạy trong thời gian dài hoặc các thao tác mạng (chẳng hạn như fetch()) giúp ngăn chặn công việc không cần thiết, cải thiện khả năng quản lý tài nguyên tổng thể và tránh rò rỉ tiềm ẩn.

await document.modelContext.registerTool({
  name: 'fetch_tool',
  description: 'Fetch the text content of a URL and stream the response.',
  inputSchema: {
    type: 'object',
    properties: {
      url: { type: 'string', description: 'The URL to fetch' },
      priority: { type: 'string', enum: ['high', 'low', 'auto'] },
    },
    required: ['url'],
  },
  execute: async ({ url, priority }, { signal }) => {
    // Abort the fetch request when tool execution is aborted.
    const response = await fetch(url, { priority, signal });
    const stream = response.body.pipeThrough(new TextDecoderStream());
    for await (const chunk of stream) {
      document.querySelector('pre').textContent += chunk;
    }
    return 'Success';
  },
});

Khám phá các công cụ

Sử dụng document.modelContext.getTools() để truy xuất các công cụ hiện có. Phương thức không đồng bộ này trả về danh sách các công cụ được sắp xếp theo bảng chữ cái mà tài liệu gọi được phép truy cập.

const [tool] = await document.modelContext.getTools();
console.log(tool);

// {
//   annotations: { consequentialHint: false, debugging: false, readOnlyHint: false, untrustedContentHint: true }, // Optional hints
//   description: "Add a new item to the to-do list",
//   inputSchema: {"type":"object","properties":{…}},
//   name: "addTodo",
//   origin: "https://example.com",
//   title: ""
//   window: Window {window: Window, self: Window, …},
// }

Theo mặc định, getTools() chỉ trả về các công cụ cùng nguồn gốc do tài liệu gọi hoặc các tài liệu cùng nguồn gốc khác trong cây khung đăng ký. Để truy xuất các công cụ nhiều nguồn gốc, bạn phải liệt kê rõ ràng các nguồn gốc của chúng trong tuỳ chọn fromOrigins. Mảng này chỉ hỗ trợ các nguồn gốc an toàn.

Các công cụ từ tài liệu khác nguồn gốc chỉ được đưa vào nếu:

Nguồn gốc lưu trữ được liệt kê trong tuỳ chọn fromOrigins.
Công cụ đã được hiển thị rõ ràng cho nguồn gốc của bạn.

// https://example.com

// Get same-origin tools only
const sameOriginTools = await document.modelContext.getTools();

// Get same-origin tools plus tools from specific cross-origin documents
const allTools = await document.modelContext.getTools({
  fromOrigins: ['https://partner.org']
});

Hãy xem bản minh hoạ Tác nhân trang WebMCP để biết ví dụ về cách truy xuất các công cụ từ iframe và thực thi các công cụ đó trong giao diện trò chuyện dựa trên nền tảng web. Hãy tham khảo phần Ví dụ về tiện ích WebMCP để xem cách một tác nhân trong tiện ích trình duyệt tìm và chạy các công cụ trên các iframe cùng nguồn gốc và khác nguồn gốc.

Thực thi công cụ

Để thực thi thủ công một công cụ được phát hiện trong getTools(), hãy gọi document.modelContext.executeTool() bằng một đối tượng JavaScript không bắt buộc cho các đối số đầu vào có thể chuyển đổi tuần tự thành chuỗi JSON. Phương thức không đồng bộ này trả về kết quả thực thi công cụ hoặc giá trị rỗng khi một thao tác điều hướng được kích hoạt.

const result = await document.modelContext.executeTool(tool, { text: "Buy milk" });
console.log(result);

// 'Added to-do: Buy milk'

Bạn có thể huỷ thực thi công cụ đang chờ xử lý bằng AbortSignal khi được truyền dưới dạng tham số không bắt buộc.

const controller = new AbortController();
document.modelContext.executeTool(tool, { text: "Buy milk" }, { signal: controller.signal });

// Cancel tool execution later...
controller.abort();

Sự kiện

Khung có thể theo dõi sự kiện toolchange trên document.modelContext để được thông báo khi danh sách các công cụ hiện có đã thay đổi.

document.modelContext.addEventListener("toolchange", (event) => {
  // Tools have changed.
});

Iframe khác nguồn gốc

WebMCP hỗ trợ các iframe khác nguồn gốc sử dụng cả chính sách về quyền và cơ chế kiểm soát nguồn gốc rõ ràng.

Chính sách về quyền

Theo mặc định, tính năng đăng ký công cụ bị tắt trong các iframe khác nguồn gốc. Một trang phải uỷ quyền truy cập bằng tools Chính sách về quyền:

<iframe src="https://example.com" allow="tools"></iframe>

Hiển thị nguồn gốc

Theo mặc định, các công cụ không có sẵn cho tài liệu khác nguồn gốc. Bạn có thể sử dụng mảng exposedTo trong registerTool để liệt kê các nguồn gốc cụ thể được phép xem và thực thi một công cụ. Mảng này chỉ hỗ trợ các nguồn gốc an toàn.

// https://partner.org

await document.modelContext.registerTool({
  name: 'my_shared_tool',
  description: 'Shared across origins',
  // ...
}, {
  exposedTo: ['https://example.com']
});

Hỗ trợ React

React hỗ trợ thử nghiệm cho WebMCP bằng gói usewebmcp. Nếu ứng dụng của bạn đã được viết bằng React, bạn có thể đăng ký các công cụ bằng cách sử dụng các hook độc lập được liên kết với vòng đời gắn kết và huỷ gắn kết của thành phần. Hook useWebMCP cũng cung cấp tính năng suy luận kiểu dựa trên giản đồ và hiển thị trạng thái thực thi cục bộ.

Hỗ trợ Angular

Angular hỗ trợ thử nghiệm cho WebMCP. Nếu ứng dụng của bạn đã được viết bằng Angular, bạn có thể đăng ký các công cụ được liên kết với vòng đời chèn phần phụ thuộc của ứng dụng và chuyển các Biểu mẫu tín hiệu thành công cụ WebMCP.

Hỗ trợ Vue

Vue hỗ trợ thử nghiệm cho WebMCP bằng gói @vueuse/core. Nếu ứng dụng của bạn đã được viết bằng Vue, bạn có thể đăng ký các công cụ bằng cách sử dụng composable useWebMCP được liên kết với vòng đời phạm vi Vue hiện tại. Thư viện này cũng hỗ trợ đăng ký công cụ có điều kiện và phản ứng, đồng thời tự động chuẩn hoá kết quả thực thi.

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 biết ý kiến của bạn.

Đọc video giải thích về WebMCP, đặt câu hỏi và tham gia thảo luận.
Đọc cách xây dựng các công cụ WebMCP hiệu quả và các phương pháp hay nhất về WebMCP.
Xem lại cách triển khai cho Chrome trên trang Trạng thái của Chrome.
Tham gia chương trình xem trước sớm để xem trước các API mới và truy cập vào danh sách gửi thư của chúng tôi.
Nếu bạn có ý kiến phản hồi về cách triển khai của Chrome, hãy báo cáo lỗi Chromium.

Bắt đầu

Tiếp

Declarative API