Imperative API

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

เผยแพร่เมื่อวันที่ 18 พฤษภาคม 2026 อัปเดตล่าสุดเมื่อวันที่ 15 ตุลาคม 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 ได้ คำอธิบายประกอบเหล่านี้จะช่วยให้ Agent และเบราว์เซอร์เข้าใจลักษณะด้านความปลอดภัยของเครื่องมือ ผลข้างเคียงที่คาดการณ์ได้ ความน่าเชื่อถือของเอาต์พุต และกลุ่มเป้าหมายที่ต้องการ

  • readOnlyHint (บูลีน ค่าเริ่มต้นคือ false): เมื่อเป็น true จะบ่งบอกว่าเครื่องมืออ่านข้อมูลเท่านั้นและไม่ได้แก้ไขสถานะของแอปพลิเคชันหรือระบบ (เช่น การค้นหาแคตตาล็อกสินค้าหรือการดึงข้อมูลสถานะการสั่งซื้อ) ซึ่งจะช่วยให้ Agent ระบุได้ว่าสามารถเรียกใช้เครื่องมือได้อย่างปลอดภัยโดยไม่มีผลข้างเคียง
  • untrustedContentHint (บูลีน ค่าเริ่มต้นคือ false): เมื่อเป็น true จะบ่งบอกว่าเอาต์พุตของเครื่องมือมีข้อมูลที่ไม่น่าเชื่อถือจากมุมมองของผู้เขียนเครื่องมือ (เช่น เนื้อหาที่ผู้ใช้สร้างขึ้น ความคิดเห็น หรือข้อมูลเว็บภายนอก) ซึ่งจะส่งสัญญาณไปยัง Agent และไคลเอ็นต์ว่าเพย์โหลดที่แสดงผล ต้องมีการจัดการด้านความปลอดภัยที่เข้มงวดขึ้น เช่น การล้างข้อมูลหรือการกำหนดขอบเขต เพื่อ ลดการแทรกพรอมต์ทางอ้อม
  • consequentialHint (บูลีน ค่าเริ่มต้นคือ false): เมื่อเป็น true จะบ่งบอกว่าการเรียกใช้เครื่องมือจะส่งผลให้เกิดการดำเนินการที่สำคัญ ในโลกแห่งความเป็นจริง หรือไม่สามารถย้อนกลับได้ (เช่น การจองเที่ยวบิน การโอนเงิน หรือการลบข้อมูล) ซึ่งจะช่วยให้ Agent และเบราว์เซอร์บังคับใช้ข้อความแจ้งการยืนยันจากผู้ใช้ที่ต้องแสดงก่อนที่จะเรียกใช้เครื่องมือที่มีความเสี่ยงสูง ซึ่งจะช่วยลดความเสี่ยงของการแสดงเจตนาของผู้ใช้ที่คลาดเคลื่อนโดยไม่ได้ตั้งใจหรือโดยเจตนาร้าย
  • debugging (บูลีน ค่าเริ่มต้นคือ false ใช้ได้ตั้งแต่ Chrome 156): เมื่อเป็น true จะบ่งบอกว่าเครื่องมือได้รับการออกแบบมาโดยเฉพาะสำหรับการตรวจสอบและเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์ (เช่น เฟรมเวิร์กการทดสอบหรือความช่วยเหลือจาก AI ในเครื่องมือสำหรับนักพัฒนาเว็บใน Chrome) แทนที่จะเป็นการโต้ตอบของผู้ใช้ปลายทาง ซึ่งจะช่วยให้ Agent อเนกประสงค์และ User Agent ของผู้ใช้ปลายทางกรองเครื่องมือที่เน้นนักพัฒนาซอฟต์แวร์ออกได้
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}.`;
  },
});

ดูตัวอย่างวิธีที่คำอธิบายประกอบอาจส่งผลต่อลักษณะการทำงานของ Agent ได้ที่ส่วนขยาย WebMCP ตัวอย่าง

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

คุณสามารถนำเครื่องมือออกได้ด้วย 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 เพื่อจัดการการยกเลิกการดำเนินการที่ผู้ใช้หรือ Agent เริ่มต้นอย่างเหมาะสม การส่งสัญญาณนี้ไปยังงานแบบอะซิงโครนัสหรือการดำเนินการเครือข่ายที่ใช้เวลานาน (เช่น 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, 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, …},
// }

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

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

หากต้องการเรียกใช้เครื่องมือที่ค้นพบใน getTools() ด้วยตนเอง ให้เรียกใช้ document.modelContext.executeTool() โดยมีออบเจ็กต์ JavaScript ที่ไม่บังคับสำหรับอาร์กิวเมนต์อินพุตซึ่งสามารถแปลงเป็นสตริง 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

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 อยู่แล้ว คุณสามารถลงทะเบียนเครื่องมือที่ผูกกับวงจรการทำงานของการแทรกการพึ่งพาของแอปพลิเคชัน และเปลี่ยนแบบฟอร์มสัญญาณให้เป็นเครื่องมือ WebMCP ได้

การรองรับ Vue

Vue รองรับ WebMCP ในเวอร์ชันทดลอง โดยใช้แพ็กเกจ @vueuse/core หากแอปพลิเคชันเขียนด้วย Vue อยู่แล้ว คุณสามารถลงทะเบียนเครื่องมือโดยใช้ useWebMCP composable ที่ผูกกับวงจรการทำงานของขอบเขต Vue ปัจจุบัน นอกจากนี้ยังรองรับการลงทะเบียนเครื่องมือแบบโต้ตอบและแบบมีเงื่อนไข รวมถึงทำให้ผลลัพธ์การดำเนินการเป็นมาตรฐานโดยอัตโนมัติ

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

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

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