Imperative API

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

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

ดูเดโม WebMCP Page Agent เพื่อดูตัวอย่างวิธีดึงข้อมูลเครื่องมือจาก iframe และเรียกใช้ภายในอินเทอร์เฟซแชทบนเว็บ ดูตัวอย่างส่วนขยาย WebMCP เพื่อดูวิธีที่ Agent ในส่วนขยายเบราว์เซอร์ค้นหาและเรียกใช้เครื่องมือใน iframe ต้นทางเดียวกันและ 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 เวอร์ชันทดลองโดยใช้แพ็กเกจ use-webmcp-tool หากแอปพลิเคชันของคุณเขียนด้วย React อยู่แล้ว คุณสามารถลงทะเบียนเครื่องมือโดยใช้ฮุก useWebMCP ที่เชื่อมโยงกับวงจรการต่อเชื่อมและการยกเลิกการต่อเชื่อมของคอมโพเนนต์ นอกจากนี้ ยังรองรับการลงทะเบียนเครื่องมือแบบมีเงื่อนไข และปรับผลลัพธ์การดำเนินการให้เป็นมาตรฐานโดยอัตโนมัติ

การรองรับ Angular

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

การสนับสนุน Vue

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

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

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

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