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

Александра Клеппер
Alexandra Klepper
GitHub Bluesky

Опубликовано: 18 мая 2026 г.

Пояснительная записка Веб Расширения Статус Chrome Намерение
GitHub Пробная версия для разработчиков Пробная версия для разработчиков Пробная версия для разработчиков Пробная версия для разработчиков Вид Намерение провести эксперимент

Используйте декларативный API для преобразования стандартных HTML-форм в инструменты WebMCP путем добавления аннотаций. Аннотации определяют имя и назначение инструмента в элементе <form> , а поля выступают в качестве параметров инструмента. Браузер преобразует эти элементы в структурированное представление, которое агенты могут использовать аналогично императивным инструментам .

Перед использованием этого API ознакомьтесь с примерами его применения .

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

Добавьте в форму следующие HTML-атрибуты:

  • toolname : Четко назовите инструмент, исходя из его назначения.
  • tooldescription : Опишите, какие действия выполняет инструмент и для чего он предназначен.

Например, следующая форма находится по адресу example.com/get-customer-support :

<form toolname="supportRequestTool" tooldescription="Submit a request for support.">
</form>

Когда агент вызывает toolname , браузер фокусируется на форме и заполняет её поля. Форма остаётся видимой для пользователя.

Если удалить HTML-атрибут toolname или tooldescription , инструмент будет дерегистрирован.

(Необязательно) Параметры инструмента

Для повышения точности добавьте следующие HTML-атрибуты к отдельным элементам формы:

  • toolparamdescription : Сопоставляет элементы с описанием свойства в JSON-схеме. Без этого атрибута браузер использует содержимое связанного элемента <label> и пропускает потомков, для которых можно задать метку. Если метки нет, браузер обращается к атрибуту aria-description .

В следующей форме используются необязательные параметры для элемента <select> .

<form toolname="supportRequestTool"
  tooldescription="Submit a request for support."
  action="/submit">

  <label for="firstName">First Name</label>
  <input type=text name=firstName>

  <label for="lastName">Last Name</label>
  <input type=text name=lastName>

  <select name="select" required toolparamtitle="Support type" 
    toolparamdescription="Determines what team this request is routed to.">
    <option value="Customer happiness team">Return my purchase.</option>
    <option value="Distribution team">Check where my package is.</option>
    <option value="Website support team">Get help on the website.</option>
  </select>

  <button type=submit>Submit</button>
</form>

Браузер интерпретирует эту форму как инструмент, представленный следующим JSON-объектом:

[
  {
    "name": "supportRequestTool",
    "description": "Submit a request for support.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "title": "firstName",
          "description": "First name"
        },
        "text": {
          "type": "string",
          "title": "lastName",
          "description": "Last name"
        },
        "select": {
          "type": "string",
          "anyOf": [
            {
              "const": "Customer happiness team",
              "title": "Return my purchase."
            },
            {
              "const": "Distribution team",
              "title": "Check where my package is."
            },
            {
              "const": "Website support team",
              "title": "Get help on the website."
            }
          ],
          "enum": [
            "Customer happiness team",
            "Distribution team",
            "Website support team"
          ],
          "title": "Support type",
          "description": "Determines what team this request is routed to."
        }
      },
      "required": [
        "select"
      ]
    }
  }
]

Отправьте форму

У вас есть два варианта отправки формы:

  • Для завершения задания пользователю необходимо вручную нажать кнопку «Отправить» .
  • Добавить toolautosubmit для запуска отправки формы и внести изменения в навигацию.

Интерфейс SubmitEvent вводит логический атрибут agentInvoked . Этот атрибут устанавливается в значение true всякий раз, когда форма запускается агентом ИИ, чтобы адаптировать поведение вашего веб-приложения специально для взаимодействий с агентами.

Кроме того, SubmitEvent включает метод respondWith(Promise<any>) , позволяющий передавать браузеру промис, который разрешается с результатами заполнения формы. Полученное значение затем сериализуется и возвращается в модель в качестве выходных данных инструмента. Для использования этого метода необходимо сначала вызвать preventDefault() чтобы остановить стандартную отправку формы браузером.

<form toolautosubmit toolname="search_tool"
  tooldescription="Search the web" action="/search">
  <input type=text name=query>
</form>
<script>
  document.querySelector("form").addEventListener("submit", (e) => {
    e.preventDefault();
    if (!myFormIsValid()) {
      if (e.agentInvoked) { e.respondWith(myFormValidationErrorPromise) };
      return;
    }
    if (e.agentInvoked) { e.respondWith(Promise.resolve("Search is done!")); }
  });
</script>

Браузер сигнализирует о том, что агент ИИ выполнил инструмент, с помощью события "toolactivated" . Это событие срабатывает в окне после предварительного заполнения полей формы. И наоборот, если пользователь отменяет операцию агента или вызывается метод reset() , срабатывает событие "toolcancel" . Оба этих события не подлежат отмене и предоставляют атрибут toolName для идентификации.

window.addEventListener('toolactivated', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was activated.`);
  // TODO: Update UI or validate form if needed.
});

window.addEventListener('toolcancel', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was cancelled.`);
  // TODO: Let the user know. Update UI.
});

Изменить индикатор фокусировки

Визуальный индикатор фокуса крайне важен для информирования пользователей и агентов о том, где они находятся на странице. Когда агент успешно вызывает инструмент, фокусируется на соответствующей форме и автоматически заполняет ее поля, браузер запускает определенные псевдоклассы CSS для визуальной обратной связи:

  • К HTML-элементу form инструмента применяется свойство :tool-form-active .
  • :tool-submit-active применяется к кнопке отправки формы, если она присутствует.

Эти классы деактивируются после отправки формы, отмены действия агентом или сброса формы пользователем. Вы можете настроить CSS для этих состояний или использовать стиль браузера по умолчанию.

/* Chrome default declarative form styles. */
form:tool-form-active {
  outline: light-dark(blue, cyan) dashed 1px;
  outline-offset: -1px;
}

input:tool-submit-active {
  outline: light-dark(red, pink) dashed 1px;
  outline-offset: -1px;
}

Узнайте больше о передовых методах и стиле фокусировки .

Принимайте участие и делитесь отзывами.

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