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

Imperative API

Alexandra Klepper

François Beaufort

เผยแพร่: 18 พฤษภาคม 2026, อัปเดตล่าสุด: 11 กันยายน 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 ตัวเลือก อาร์เรย์นี้รองรับเฉพาะต้นทางที่ปลอดภัย

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

ต้นทางการโฮสต์จะแสดงในตัวเลือก 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']
});

ดูตัวอย่างวิธีดึงเครื่องมือจาก iframe และเรียกใช้เครื่องมือภายในอินเทอร์เฟซแชทบนเว็บได้ที่การสาธิตเอเจนต์หน้าเว็บ WebMCP

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

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

นโยบายสิทธิ์

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

การรองรับ Angular

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

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

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

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

เริ่มใช้งาน

Declarative API