Imperative API

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

เผยแพร่: 18 พฤษภาคม 2026, อัปเดตล่าสุด: 2 มิถุนายน 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>

การเปิดเผยแหล่งที่มา

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

// https://partner.org

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

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

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