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

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

Published: May 18, 2026

Пояснительная записка Веб Расширения Chrome Status Намерение
GitHub Origin trialOrigin trial Вид Intent to Experiment

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

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

Tool registration

Add the following HTML attributes to your form:

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

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

<form toolname="createSupportRequest" tooldescription="Submits a request for customer support.">
</form>

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

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

(Optional) Tool parameters

Для повышения точности добавьте следующие 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 
    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": {
        "firstName": {
          "type": "string"
        },
        "lastName": {
          "type": "string"
        },
        "select": {
          "type": "string",
          "anyOf": [
            {
              "type": "string",
              "const": "Customer happiness team",
              "title": "Return my purchase."
            },
            {
              "type": "string",
              "const": "Distribution team",
              "title": "Check where my package is."
            },
            {
              "type": "string",
              "const": "Website support team",
              "title": "Get help on the website."
            }
          ],
          "enum": [
            "Customer happiness team",
            "Distribution team",
            "Website support team"
          ],
          "description": "Determines what team this request is routed to."
        }
      },
      "required": [
        "select"
      ]
    }
  }
]

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

You have two choices for form submission:

  • Для завершения задания пользователю необходимо вручную нажать кнопку «Отправить» .
  • Добавьте 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.
});

Modify focus indicator

Визуальный индикатор фокуса крайне важен для информирования пользователей и агентов о том, где они находятся на странице. Когда агент успешно вызывает инструмент, фокусируется на соответствующей форме и автоматически заполняет ее поля, браузер запускает определенные псевдоклассы 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;
}

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

Engage and share feedback

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