Imperative API

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

תאריך פרסום: 18 במאי 2026, תאריך עדכון אחרון: 16 באוקטובר 2026

הסברים פיתוח אתרים תוספים סטטוס Chrome הרציונל
GitHub גרסת מקור לניסיון גרסת מקור לניסיון תצוגה Intent to Experiment

אתם יכולים להשתמש ב-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}.`;
  },
});

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

טיפול בביטול של כלי

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

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

תמיכה ב-Angular

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

תמיכה ב-Vue

ל-Vue יש תמיכה ניסיונית ב-WebMCP באמצעות החבילה @vueuse/core. אם האפליקציה שלכם כבר כתובה ב-Vue, אתם יכולים לרשום כלים באמצעות ה-composable‏ useWebMCP שקשור למחזור החיים הנוכחי של היקף Vue. הוא גם תומך ברישום כלים תגובתי ומותנה, ומנרמל באופן אוטומטי את תוצאות ההפעלה.

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

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

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