Imperative API

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky
François Beaufort
François Beaufort
GitHub

Published: May 18, 2026, Last updated: June 18, 2026

วิดีโออธิบาย เว็บ ส่วนขยาย สถานะ Chrome ความตั้งใจ
GitHub ช่วงทดลองใช้จากต้นทาง ช่วงทดลองใช้จากต้นทาง ดู ความตั้งใจที่จะทดลองใช้

คุณสามารถใช้ WebMCP Imperative API เพื่อกำหนดเครื่องมือหลายประเภทด้วย JavaScript มาตรฐาน เครื่องมือของคุณสามารถเรียกใช้ฟังก์ชันต่างๆ ได้ เช่น การป้อนข้อมูลในแบบฟอร์ม การไปยังส่วนต่างๆ ของเว็บไซต์ และการจัดการสถานะ

โปรดอ่านเกี่ยวกับตัวอย่าง Use Case ก่อนใช้ API นี้

ระบุบริบทของโมเดล

ใช้อินเทอร์เฟซ modelContext เพื่อลงทะเบียนเครื่องมือ การลงทะเบียนเครื่องมือต้องใช้ชื่อ คำอธิบาย และสคีมาอินพุตที่มีพร็อพเพอร์ตี้ที่เกี่ยวข้อง

ใช้ registertool เพื่อเพิ่มเครื่องมือเดียวลงในบริบทของโมเดล

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

รับสถานะการสั่งซื้อ

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

คุณสามารถนำเครื่องมือออกด้วย AbortSignal เมื่อส่งผ่านเป็นพารามิเตอร์ที่ไม่บังคับ

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();

ค้นพบเครื่องมือ

ใช้ document.modelContext.getTools() เพื่อดึงข้อมูลเครื่องมือที่พร้อมใช้งาน เมธอดแบบไม่พร้อมกันนี้จะแสดงรายการเครื่องมือที่เรียงตามตัวอักษรซึ่งเอกสารที่เรียกมีสิทธิ์เข้าถึง

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, ...},
// }

โดยค่าเริ่มต้น getTools() จะแสดงเฉพาะเครื่องมือที่มีต้นทางเดียวกันซึ่งลงทะเบียนโดยเอกสารที่เรียกหรือเอกสารอื่นๆ ที่มีต้นทางเดียวกันในแผนผังเฟรม หากต้องการดึงข้อมูลเครื่องมือแบบข้ามต้นทาง คุณต้องระบุต้นทางของเครื่องมือเหล่านั้นอย่างชัดเจนในตัวเลือก fromOrigins อาร์เรย์นี้รองรับเฉพาะต้นทางที่ปลอดภัย

ระบบจะรวมเครื่องมือจากเอกสารแบบข้ามต้นทางไว้ก็ต่อเมื่อ

  1. ต้นทางที่โฮสต์แสดงอยู่ในตัวเลือก fromOrigins
  2. เครื่องมือได้รับการเปิดเผยต่อต้นทางของคุณอย่างชัดเจน
// 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']
});

ดูตัวอย่างวิธีดึงข้อมูลเครื่องมือจาก iframe และเรียกใช้เครื่องมือเหล่านั้นภายในอินเทอร์เฟซการแชทบนเว็บได้ที่เดโม WebMCP Page Agent

เรียกใช้เครื่องมือ

หากต้องการเรียกใช้เครื่องมือที่ค้นพบใน getTools() ด้วยตนเอง ให้เรียก document.modelContext.executeTool() พร้อมอาร์กิวเมนต์อินพุตเป็นสตริง JSON ที่ถูกต้อง เมธอดแบบไม่พร้อมกันนี้จะแสดงผลลัพธ์ของการเรียกใช้เครื่องมือ หรือแสดงค่า Null เมื่อมีการทริกเกอร์การไปยังส่วนต่างๆ

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

// 'Added to-do: Buy milk'

คุณสามารถยกเลิกการเรียกใช้เครื่องมือที่รอดำเนินการด้วย AbortSignal เมื่อส่งผ่านเป็นพารามิเตอร์ที่ไม่บังคับ

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

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

กิจกรรม

เฟรมสามารถรับฟังเหตุการณ์ toolchange ใน document.modelContext เพื่อรับการแจ้งเตือนเมื่อรายการเครื่องมือที่พร้อมใช้งานมีการเปลี่ยนแปลง

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

iframe แบบข้ามต้นทาง

WebMCP รองรับ iframe แบบข้ามต้นทางที่ใช้นโยบายสิทธิ์และการควบคุมต้นทางอย่างชัดเจน

นโยบายสิทธิ์

ระบบจะปิดใช้การลงทะเบียนเครื่องมือใน iframe แบบข้ามต้นทางโดยค่าเริ่มต้น หน้าเว็บต้อง มอบสิทธิ์เข้าถึงโดยใช้ tools นโยบายสิทธิ์ ดังนี้

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

การเปิดเผยต้นทาง

เครื่องมือจะไม่พร้อมใช้งานสำหรับเอกสารแบบข้ามต้นทางโดยค่าเริ่มต้น คุณสามารถใช้อาร์เรย์ exposedTo ภายใน registerTool เพื่อแสดงรายการต้นทางที่เฉพาะเจาะจงซึ่งได้รับอนุญาตให้ดูและเรียกใช้เครื่องมือ อาร์เรย์นี้รองรับเฉพาะต้นทางที่ปลอดภัย

// https://partner.org

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

การรองรับ Angular

Angular รองรับ WebMCP ในขั้นทดลอง หากแอปพลิเคชันเขียนด้วย Angular อยู่แล้ว คุณสามารถลงทะเบียนเครื่องมือที่เชื่อมโยงกับวงจรการใช้งานการแทรกทรัพยากร Dependency ของแอปพลิเคชัน และเปลี่ยน Signal Forms เป็นเครื่องมือ WebMCP ได้

มีส่วนร่วมและแชร์ความคิดเห็น

เรากำลังพูดคุยเกี่ยวกับ WebMCP อย่างจริงจังและอาจมีการเปลี่ยนแปลงในอนาคต หากคุณลองใช้ API นี้และมีความคิดเห็น โปรดแจ้งให้เราทราบ