Imperative API

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

תאריך פרסום: 18 במאי 2026, תאריך עדכון אחרון: 15 באוקטובר 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}.`;
  },
});

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

תמיכה ב-Angular

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

תמיכה ב-Vue

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

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

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

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