Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

Imperative API

Alexandra Klepper

François Beaufort

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

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

คุณสามารถนำเครื่องมือออกด้วย 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, 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 ตัวเลือก อาร์เรย์นี้รองรับเฉพาะต้นทางที่ปลอดภัย

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

ต้นทางการโฮสต์จะแสดงในตัวเลือก fromOrigins
เครื่องมือนี้เปิดเผยต่อต้นทางของคุณอย่างชัดเจน

// 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 เพื่อดูตัวอย่างวิธีดึงเครื่องมือจาก 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 อยู่แล้ว คุณจะลงทะเบียนเครื่องมือได้โดยใช้ Hook แบบสแตนด์อโลนที่เชื่อมโยงกับวงจรการติดตั้งและการเลิกติดตั้งของคอมโพเนนต์ ฮุก useWebMCP ยังให้การอนุมานประเภทที่ขับเคลื่อนด้วยสคีมา และแสดงสถานะการดำเนินการในเครื่องด้วย

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

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

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

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

อ่านคำอธิบายของ WebMCP ถามคำถาม และเข้าร่วมการสนทนา
อ่านแนวทางปฏิบัติแนะนำสำหรับ WebMCP
ดูการติดตั้งใช้งานสำหรับ Chrome ได้ที่ สถานะของ Chrome
เข้าร่วมโปรแกรมเวอร์ชันตัวอย่างก่อนเปิดตัว เพื่อดู API ใหม่ๆ ก่อนใครและรับสิทธิ์เข้าถึงรายชื่ออีเมลของเรา
หากมีความคิดเห็นเกี่ยวกับการติดตั้งใช้งานของ Chrome โปรดรายงานข้อบกพร่องของ Chromium

เริ่มใช้งาน

Declarative API