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

Imperative API

Alexandra Klepper

François Beaufort

Дата публикации: 18 мая 2026 г. Дата последнего обновления: 15 октября 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 с использованием пакета usewebmcp. Если ваше приложение уже написано на 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