Imperative API

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

เผยแพร่เมื่อ: 18 พฤษภาคม 2026, อัปเดตล่าสุด: 1 กันยายน 2026

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

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

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

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

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

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

WebMCPza Maker

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

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

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

คำอธิบายประกอบของเครื่องมือ (ไม่บังคับ)

เมื่อลงทะเบียนเครื่องมือ คุณสามารถเพิ่มคำแนะนำข้อมูลเมตาในพร็อพเพอร์ตี้ annotations ได้ คำแนะนำเหล่านี้จะช่วยให้ตัวแทนและเบราว์เซอร์เข้าใจลักษณะด้านความปลอดภัยของเครื่องมือ ผลข้างเคียงที่คาดการณ์ไว้ และความน่าเชื่อถือของเอาต์พุต

  • readOnlyHint (บูลีน ค่าเริ่มต้นคือ false): เมื่อเป็น true จะบ่งชี้ว่าเครื่องมืออ่านข้อมูลเท่านั้นและไม่ได้แก้ไขสถานะของแอปพลิเคชันหรือระบบ (เช่น การค้นหาแคตตาล็อกผลิตภัณฑ์หรือการดึงข้อมูลสถานะการสั่งซื้อ) ซึ่งจะช่วยให้ตัวแทนพิจารณาได้ว่าสามารถเรียกใช้เครื่องมือได้อย่างปลอดภัยโดยไม่มีผลข้างเคียง
  • untrustedContentHint (บูลีน ค่าเริ่มต้นคือ false): เมื่อเป็น true จะบ่งชี้ว่าเอาต์พุตของเครื่องมือมีข้อมูลที่ไม่น่าเชื่อถือจากมุมมองของผู้เขียนเครื่องมือ (เช่น เนื้อหาที่ผู้ใช้สร้างขึ้น ความคิดเห็น หรือข้อมูลเว็บภายนอก) ซึ่งจะส่งสัญญาณไปยังตัวแทนและไคลเอ็นต์ว่าเพย์โหลดที่แสดงผล ต้องมีการจัดการด้านความปลอดภัยที่เข้มงวดขึ้น เช่น การล้างข้อมูลหรือการกำหนดขอบเขต เพื่อ ลดการแทรกข้อความแจ้งทางอ้อม
  • consequentialHint (บูลีน ค่าเริ่มต้นคือ false): เมื่อเป็น true จะบ่งชี้ว่าการเรียกใช้เครื่องมือจะส่งผลให้เกิดการดำเนินการที่สำคัญ เป็นจริง หรือไม่สามารถย้อนกลับได้ (เช่น การจองเที่ยวบิน การโอนเงิน หรือการลบข้อมูล) ซึ่งจะช่วยให้ตัวแทนและเบราว์เซอร์บังคับใช้ข้อความแจ้งการยืนยันจากผู้ใช้ก่อนที่จะเรียกใช้เครื่องมือที่มีความเสี่ยงสูง ซึ่งจะช่วยลดความเสี่ยงของการสื่อให้เข้าใจผิดถึงความตั้งใจของผู้ใช้โดยไม่ได้ตั้งใจหรือโดยเจตนา
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,
  },
  execute: async ({ flightId, passengers }) => {
    // Add your flight booking transaction logic here.
    return `Booked ${passengers} passenger(s) on flight ${flightId}.`;
  },
});

ยกเลิกการลงทะเบียนเครื่องมือ

คุณสามารถนำเครื่องมือออกด้วย 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();
await document.modelContext.registerTool(addTodoTool, { signal: controller.signal });

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

ตั้งแต่ Chrome 153 เป็นต้นไป คุณสามารถยกเลิกการลงทะเบียนเครื่องมือได้โดยไม่ต้องยกเลิกและหยุดการดำเนินการที่กำลังดำเนินการอยู่ ซึ่งจะช่วยป้องกันผลข้างเคียงที่ไม่คาดคิดเมื่อจัดการวงจรการทำงานของเครื่องมือในเฟรมเวิร์กของคอมโพเนนต์

จัดการการยกเลิกเครื่องมือ

ฟังก์ชัน execute จะรับพารามิเตอร์ AbortSignal ที่ชื่อว่า signal เป็นอาร์กิวเมนต์ที่ 2 เพื่อจัดการการยกเลิกการดำเนินการที่ผู้ใช้หรือตัวแทนเป็นผู้เริ่มได้อย่างราบรื่น การส่งสัญญาณนี้ไปยังงานแบบอะซิงโครนัสหรือการดำเนินการเครือข่ายที่ใช้เวลานาน (เช่น fetch()) จะช่วยป้องกันการทำงานที่ไม่จำเป็น ปรับปรุงการจัดการทรัพยากรโดยรวม และหลีกเลี่ยงการรั่วไหลที่อาจเกิดขึ้น

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

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

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

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

// {
//   annotations: { consequentialHint: 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, …},
// }

โดยค่าเริ่มต้น 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 ที่ถูกต้อง เมธอดแบบอะซิงโครนัสนี้จะแสดงผลลัพธ์ของการเรียกใช้เครื่องมือ หรือค่าว่างเมื่อมีการทริกเกอร์การนำทาง

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

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

การรองรับ React

React รองรับ WebMCP ในขั้นทดลองโดยใช้แพ็กเกจ usewebmcp หากแอปพลิเคชันเขียนด้วย React อยู่แล้ว คุณสามารถลงทะเบียนเครื่องมือโดยใช้ฮุกแบบสแตนด์อโลนที่เชื่อมโยงกับวงจรการทำงานของการติดตั้งและการถอนการติดตั้งคอมโพเนนต์ ฮุก useWebMCP ยังมีการอนุมานประเภทที่ขับเคลื่อนด้วยสคีมาและเปิดเผยสถานะการดำเนินการในเครื่อง

การรองรับ Angular

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

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

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

ก่อนหน้า
เริ่มใช้งาน
ถัดไป
Declarative API