Imperative API

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

פורסם: 18 במאי 2026, עדכון אחרון: 21 בספטמבר 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, המשמעות היא שהפעלת הכלי גורמת לפעולות משמעותיות, אמיתיות או בלתי הפיכות (למשל, הזמנת טיסה, העברת כסף או מחיקת נתונים). כך סוכנים ודפדפנים יכולים לאכוף הנחיות למשתמשים לאשר פעולות לפני הפעלת כלים עם השלכות משמעותיות, ולצמצם את הסיכון להצגה שגויה של כוונת המשתמש בטעות או בזדון.
  • ‫debugging (בוליאני, ברירת המחדל היא false, זמין מגרסה 156 של Chrome): אם הערך הוא true, הכלי מיועד במיוחד לבדיקה ולכלים למפתחים (לדוגמה, מסגרות בדיקה או סיוע מבוסס-AI בכלי הפיתוח ל-Chrome) ולא לאינטראקציות של משתמשי קצה. כך סוכנים לשימוש כללי ולמשתמשי קצה יכולים לסנן כלים שמיועדים למפתחים.
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 כארגומנט השני שלה, כדי לטפל בצורה תקינה בביטולים של ביצוע שהמשתמש או הסוכן יזמו. העברת האות הזה למשימות אסינכרוניות או לפעולות רשת שפועלות לאורך זמן (כמו 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 ומפעילים אותם בממשק צ'אט מבוסס-אינטרנט.

הפעלת הכלי

כדי להפעיל ידנית כלי שאותר ב-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();

אירועים

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

אינטראקציה ושיתוף משוב

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

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