Imperative 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, Cập nhật gần đây nhất: 1 tháng 6 năm 2026

Người 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 Bản dùng thử cho nhà phát triển 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 các ví dụ về trường hợp sử dụng.

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 tên, nội dung mô tả và giản đồ đầu vào có các thuộc tính liên quan,

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

WebMCPza Maker

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

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

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();
document.modelContext.registerTool(addTodoTool, { signal: controller.signal });

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

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

Để xem các công cụ hiện có, hãy sử dụng document.modelContext.getTools(). Phương thức không đồng bộ này trả về danh sách các công cụ mà tài liệu gọi được phép truy cập.

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

// {
//   annotations: { readOnlyHint: false, untrustedContentHint: true },
//   description: "Add a new item to the to-do list",
//   inputSchema: '{"type":"object","properties":{"text":{"type":"string"}}}',
//   name: "addTodo",
//   origin: "https://example.com",
//   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 nguồn gốc của các công cụ đó 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 nhiều nguồn gốc chỉ được đưa vào nếu:

  1. Nguồn gốc lưu trữ được liệt kê trong tuỳ chọn fromOrigins.
  2. Công cụ này đã đượ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']
});

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() với các đối số đầu vào dưới dạng chuỗi JSON hợp lệ. 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ị null 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ỷ việc 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 nhiều nguồn gốc

WebMCP hỗ trợ iframe nhiều 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 iframe nhiều 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 dùng được cho tài liệu nhiều 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

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

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.