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 רגיל. הכלים יכולים לבצע פונקציות שונות, כמו הזנת טופס, ניווט באתר וניהול מצב.

לפני שמשתמשים ב-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, המשמעות היא שהפלט של הכלי מכיל נתונים לא מהימנים מנקודת המבט של יוצר הכלי (לדוגמה, תוכן שנוצר על ידי משתמשים, ביקורות או נתוני אינטרנט חיצוניים). האות הזה מציין לסוכן וללקוח שהמטען הייעודי (payload) שמוחזר דורש טיפול אבטחתי מוגבר, כמו ניקוי או הגבלת תוכן, כדי לצמצם את הסיכון להחדרת פרומפטים עקיפה.
  • ‫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 כארגומנט השני שלה, כדי לטפל בצורה תקינה בביטולי ביצוע שהמשתמש או הסוכן יזמו. העברת האות הזה למשימות אסינכרוניות ארוכות טווח או לפעולות ברשת (כמו 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']
});

בהדגמה של סוכן דפים ב-WebMCP אפשר לראות דוגמה לאופן שבו מאחזרים כלים מ-iframe ומריצים אותם בממשק צ'אט מבוסס-אינטרנט.

הפעלת הכלי

כדי להפעיל ידנית כלי שזוהה ב-getTools(), קוראים ל-document.modelContext.executeTool() עם ארגומנטים של קלט כמחרוזת 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();

אירועים

אפשר להגדיר ל-Frames להאזין לאירוע toolchange ב-document.modelContext כדי לקבל הודעה כשרשימת הכלים הזמינים משתנה.

document.modelContext.addEventListener("toolchange", (event) => {
  // Tools have changed.
});

מסגרות iframe חוצות-מקורות

‫WebMCP תומך במסגרות iframe ממקורות שונים שמשתמשות גם במדיניות הרשאות וגם בסינון מפורש של מקורות.

מדיניות ההרשאות

כברירת מחדל, רישום כלי מושבת ב-iframes חוצי-מקורות. דף צריך להעביר גישה באמצעות 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, אתם יכולים לרשום כלים באמצעות hooks עצמאיים שקשורים למחזור החיים של הרכיב שלכם (mount ו-unmount). ה-hook‏ useWebMCP מספק גם היסק סוגים מבוסס-סכמה וחושף את מצב ההרצה המקומית.

תמיכה ב-Angular

ל-Angular יש תמיכה ניסיונית ב-WebMCP. אם האפליקציה שלכם כבר כתובה ב-Angular, אתם יכולים לרשום כלים שקשורים למחזור החיים של הזרקת התלות של האפליקציה ולהפוך את טפסי האותות שלכם לכלים של WebMCP.

השתתפות ושיתוף משוב

הפיתוח של WebMCP נמצא בעיצומו, ויכול להיות שהוא ישתנה בעתיד. אם תנסו את ה-API הזה ויהיה לכם משוב, נשמח לשמוע אותו.

הקודם
מתחילים
הבא
Declarative API