Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Imperative API

Alexandra Klepper

François Beaufort

Дата публикации: 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, это указывает на то, что выходные данные инструмента содержат ненадежные данные с точки зрения автора инструмента (например, пользовательский контент, отзывы или внешние веб-данные). Это сигнализирует агенту и клиенту, что возвращенная полезная нагрузка требует повышенных мер безопасности, таких как очистка или разграничение, для снижения риска косвенного внедрения запроса.
consequentialHint (логическое значение, по умолчанию false). Если задано значение true, это указывает на то, что выполнение инструмента приводит к значительным, реальным или необратимым действиям (например, бронированию рейса, переводу денег или удалению данных). Это позволяет агентам и браузерам запрашивать обязательное подтверждение пользователя перед выполнением действий с высоким риском, снижая вероятность случайного или злонамеренного искажения намерений пользователя.
debugging (логическое значение, по умолчанию false, доступно в Chrome 156). Если задано значение true, это указывает, что инструмент предназначен специально для проверки и разработки (например, фреймворки тестирования или помощь от ИИ в инструментах разработчика в 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 вы можете отменить регистрацию инструмента, не прерывая текущие выполнения. Это позволяет избежать непредвиденных побочных эффектов при управлении жизненными циклами инструментов в фреймворках компонентов.

Обработка отмены инструмента

Функция 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. Этот массив поддерживает только защищенные источники.

Инструменты из документов, размещенных в разных источниках, включаются, только если:

Источник хостинга указан в параметре 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']
});

Посмотрите демоверсию агента страницы WebMCP, чтобы узнать, как получать инструменты из 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 Permissions Policy:

<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, вы можете зарегистрировать инструменты с помощью хука useWebMCP, привязанного к жизненному циклу монтирования и размонтирования компонента. Он также поддерживает условную регистрацию инструментов и автоматически нормализует результаты выполнения.

Поддержка Angular

В Angular есть экспериментальная поддержка WebMCP. Если ваше приложение уже написано на Angular, вы можете зарегистрировать инструменты, привязанные к жизненному циклу внедрения зависимостей приложения, и превратить Signal Forms в инструменты WebMCP.

Поддержка Vue

Vue имеет экспериментальную поддержку WebMCP с использованием пакета @vueuse/core. Если ваше приложение уже написано на Vue, вы можете зарегистрировать инструменты с помощью composable-функции useWebMCP, привязанной к текущему жизненному циклу области видимости Vue. Он также поддерживает реактивную и условную регистрацию инструментов и автоматически нормализует результаты выполнения.

Взаимодействие и отзывы

Протокол WebMCP активно обсуждается и может измениться в будущем. Если вы попробуете этот API и у вас появятся отзывы, мы будем рады их услышать.

Прочитайте пояснение к WebMCP, задайте вопросы и примите участие в обсуждении.
Прочитайте, как создавать эффективные инструменты WebMCP и как работать с WebMCP.
Ознакомьтесь с реализацией для Chrome на странице Chrome Status.
Присоединяйтесь к программе предварительной версии, чтобы первыми узнавать о новых API и получать новости по электронной почте.
Если у вас есть отзыв о реализации в Chrome, сообщите об ошибке в Chromium.

Начать

Декларативный API