Инструменты

Оркестратор ничего не знает о вашем сайте, кроме инструментов, которые вы ему даёте. Инструмент — это функция, которая выполняется в браузере посетителя: поиск по каталогу, добавление номера в бронирование, выбор размера пиццы, открытие заказа. Вы регистрируете инструменты через WebMCP (document.modelContext); виджет читает их, а оркестратор строит план вокруг них.

Регистрация инструмента

await document.modelContext.registerTool({
  name: "search_products",
  description: "Search the shop catalog by free-text query.",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string", description: "What to look for" },
      maxPrice: { type: "number", description: "Upper price limit" },
    },
    required: ["query"],
  },
  async execute({ query, maxPrice }) {
    const items = await shop.search(query, { maxPrice });
    return {
      content: [{ type: "text", text: items.map((i) => `- ${i.name} - $${i.price}`).join("\n") }],
    };
  },
});
js
ПолеОбязательноПримечания
nameдаСоответствует ^[a-zA-Z0-9_.-]{1,128}$. Уникально на странице; повторная регистрация имени выбрасывает исключение.
descriptionдаНепустая строка.
inputSchemaнетJSON Schema с type: "object", properties и, при необходимости, required. Должна сериализоваться в JSON.
execute(args, options)да, чтобы инструмент можно было вызватьПолучает объект с аргументами. Возвращает результат (см. ниже).
annotationsнетСохраняются полифилом. См. Аннотации .

registerTool также принимает { signal } вторым аргументом; прерывание сигнала снимает инструмент с регистрации. Регистрируйте и снимайте с регистрации свободно: каталог страницы может меняться вместе с её состоянием (инструмент корзины — только пока корзина существует, инструмент оформления заказа — только на шаге оформления).

Результаты

Возвращайте объект в стиле MCP, обычную строку или любое JSON-значение:

return { content: [{ type: "text", text: "Added 2 x Margherita to the order." }] };
return { content: [{ type: "text", text: "Size 'huge' does not exist. Try: small, medium, large." }], isError: true };
js

Оркестратор сохраняет текст ответа (части content[].text, строку или, в крайнем случае, JSON; обрезается до 4000 символов) и читает его на следующих шагах, например чтобы выбрать первый товар из результатов поиска. С isError: true шаг считается неудачным. Пишите текст ошибки как совет: если в нём назван другой ваш инструмент («Магазин не открыт. Сначала вызовите choose_store»), планировщик запустит этот инструмент и повторит попытку.

Как оркестратор читает инструмент

Оркестратор понимает инструмент по его имени и схеме, а не по коду, специфичному для сайта.

  1. Когда панель открывается, виджет вызывает getTools() и один раз для треда отправляет каталог (он отправляет его повторно, с задержкой (debounce) 300 мс, когда страница вызывает toolchange и каталог действительно изменился). Отправляются name, description и inputSchema (type, properties, required).
  2. Оркестратор классифицирует каждый инструмент. Сначала решает имя: слова в add_to_cart, addToCart и add-to-cart одинаковы. Инструмент с именем вроде search_*, find_*, checkout, remove_*, get_* распознаётся по глаголу. Если имя ничего не решает, небольшая модель решений выбирает по имени и описанию. О том, какие сегодня существуют категории, см. Намерения .
  3. Для сообщения планировщик выбирает инструменты и их порядок. Отдельная небольшая модель заполняет аргументы каждого вызова по вашей схеме (значения enum, required, описания).

Практические следствия:

  • Используйте понятные имена вида verb_object. Дополнительные уточнения в имени (add_recipe_to_cart рядом с add_to_cart) помечают специалиста: он используется, когда посетитель называет одно из его значений enum, а в остальных случаях выигрывает обычный инструмент.
  • Помещайте в схему в виде enum варианты, которые может назвать посетитель. Описывайте каждый параметр в description.
  • Имя, содержащее remove, delete, clear, empty или cancel, считается удалением; checkout, pay, purchase или place + order — оформлением заказа. Эти два вида модель никогда не выбирает сама, поэтому называйте такие инструменты честно.
  • Инструменты только для чтения (get_, list_, view_, check_, status, history) сообщают планировщику, что сейчас хранит сайт; это важно для запросов про «всё».

Ограничения каталога

Каталог отправляется через POST /v1/widget/tools ( Widget API ). Сериализованный массив webmcpTools по умолчанию может занимать не более 20 000 символов (WIDGET_MAX_WEBMCP_TOOLS_CHARS); при превышении возвращается 413. Делайте описания короткими.

Примеры из разных предметных областей

Интернет-магазин

document.modelContext.registerTool({
  name: "add_to_cart",
  description: "Add a product to the cart.",
  inputSchema: {
    type: "object",
    properties: {
      productId: { type: "string" },
      quantity: { type: "number", description: "Defaults to 1" },
    },
    required: ["productId"],
  },
  async execute({ productId, quantity = 1 }) {
    await cart.add(productId, quantity);
    return { content: [{ type: "text", text: `Added ${quantity} x ${productId}.` }] };
  },
});
js

Подходит и для продуктового магазина, и для магазина электроники, и для магазина одежды; различаются только имена и описания.

Бронирование отеля

document.modelContext.registerTool({
  name: "search_rooms",
  description: "Find available rooms for a stay.",
  inputSchema: {
    type: "object",
    properties: {
      checkIn: { type: "string", description: "Date, YYYY-MM-DD" },
      checkOut: { type: "string", description: "Date, YYYY-MM-DD" },
      guests: { type: "number" },
      roomType: { type: "string", enum: ["single", "double", "suite"] },
    },
    required: ["checkIn", "checkOut", "guests"],
  },
  async execute(args) {
    const rooms = await hotel.availability(args);
    if (rooms.length === 0) {
      return { isError: true, content: [{ type: "text", text: "No rooms free on those dates. Try other dates." }] };
    }
    return { content: [{ type: "text", text: rooms.map((r) => `- ${r.id}: ${r.type}, $${r.rate}/night`).join("\n") }] };
  },
});

document.modelContext.registerTool({
  name: "book_room",
  description: "Reserve a room found by search_rooms.",
  inputSchema: {
    type: "object",
    properties: { roomId: { type: "string" }, guestName: { type: "string" } },
    required: ["roomId", "guestName"],
  },
  async execute(args) { /* ... */ },
});
js
Expand code

Конструктор пиццы

document.modelContext.registerTool({
  name: "set_pizza_size",
  description: "Set the size of the pizza being built.",
  inputSchema: {
    type: "object",
    properties: { size: { type: "string", enum: ["small", "medium", "large"] } },
    required: ["size"],
  },
  async execute({ size }) {
    builder.setSize(size);
    return { content: [{ type: "text", text: `Size is now ${size}.` }] };
  },
});

document.modelContext.registerTool({
  name: "add_topping",
  description: "Add a topping to the pizza.",
  inputSchema: {
    type: "object",
    properties: { topping: { type: "string", enum: ["mushrooms", "olives", "pepperoni", "basil"] } },
    required: ["topping"],
  },
  async execute({ topping }) { builder.addTopping(topping); return "ok"; },
});
js

Декларативная форма

Форма может быть инструментом без JavaScript. Полифил читает toolname, tooldescription и toolparamdescription и строит схему по полям формы (обязательные поля становятся required; <select> становится enum):

<form toolname="request_callback" tooldescription="Ask the clinic to call the visitor back." toolautosubmit>
  <input name="phone" required toolparamdescription="Phone number to call" />
  <select name="topic" toolparamdescription="What the call is about">
    <option>appointment</option>
    <option>results</option>
  </select>
  <button type="submit">Send</button>
</form>
html

Без toolautosubmit полифил заполняет поля и ждёт, пока посетитель отправит форму.

Ошибки инструментов

Инструмент может завершиться ошибкой двумя способами.

  • Сообщить об ошибке как о результате. Верните { isError: true, content: [{ type: "text", text: "..." }] }. Запуск продолжается: шаг помечается как неудачный, а текст сохраняется как ответ сайта. Если запуск не может достичь цели, поток завершается error / task_failed, а последний ответ сайта передаётся в hint (не более 400 символов), и виджет показывает его посетителю.
  • Выбросить исключение. В полифиле выброшенная ошибка с числовым status (100-599) и необязательным retryAfter (секунды, число или числовая строка) сохраняет оба поля при передаче вызова между окнами (WEBMCP_EXECUTE_TOOL_RESPONSE); запрашивающее окно повторно проверяет их и выбрасывает ошибку с теми же полями. Используйте это, чтобы сигнализировать об ограничении частоты запросов:
async execute(args) {
  const res = await fetch("/api/search?q=" + encodeURIComponent(args.query));
  if (res.status === 429) {
    throw Object.assign(new Error("Search is rate limited"), {
      status: 429,
      retryAfter: Number(res.headers.get("retry-after") ?? 30),
    });
  }
  // ...
}
js

Аннотации

annotations (например, { readOnlyHint: true } из предложения WebMCP) принимаются registerTool, сохраняются полифилом и передаются другим окнам, которые запрашивают список ваших инструментов. Виджет не пересылает аннотации оркестратору: он отправляет только name, description и inputSchema, а схема запроса на сервере отбрасывает остальные поля. Сегодня аннотации на планирование не влияют.

Инструменты в других окнах

По умолчанию полифил не открывает ваши инструменты ни одному другому окну. Чтобы позволить встраивающей странице, открывшему окну (opener) или iframe получать список инструментов этой страницы и запускать их через postMessage, перечислите их origin'ы в виджете:

<pleiades-chat agent-url="..." publishable-key="pk_..." expose-tools-to="https://shop.example,https://pay.example"></pleiades-chat>
html

Ответы всегда адресуются origin'у того, кто спросил, а не *. Это нужно только странице, на которой размещены инструменты. Странице, которая потребляет инструменты из <iframe allow="tools" src="...">, это не нужно.