Агентные формы

Веб-функции: Атрибуты WebMCP, связанные с формами

Declarative API преобразует стандартные элементы HTML <form> в инструменты WebMCP с помощью атрибутов. Браузер синтезирует схему JSON из входных данных формы и обрабатывает взаимодействия агента.

Формы Angular Signal. НЕ добавляйте toolname/tooldescription в формы, созданные с помощью form() из @angular/forms/signals. Вместо этого добавьте provideExperimentalWebMcpForms() к поставщикам приложения и передайте параметр experimentalWebMcpTool: { name, description } в form(). Затем Angular регистрирует форму через Imperative API, создавая схему на основе модели сигналов и связывая ее с проверкой и отправкой. Если вы используете оба подхода, одна и та же форма будет зарегистрирована дважды.

Атрибуты формы

  • toolname: уникальное название инструмента.
  • tooldescription – что делает инструмент и когда агент должен его использовать. Не перечисляйте поля, параметры и ограничения формы. Браузер уже включает их в схему, которую создает на основе элементов управления формой.
  • toolautosubmit – необязательный атрибут. Если он указан, агент может отправить форму, не дожидаясь действий пользователя.
  • toolparamdescription – необязательный параметр, позволяющий задать описание свойства в схеме JSON. Используйте его, чтобы объяснить, что означает значение (например, с помощью примеров значений), а не для повторения параметров или ограничений элемента управления.
    • Порядок разрешения. Браузер использует toolparamdescription, если он есть. Если его нет, используется textContent связанного элемента <label> (потомки, которым можно присвоить ярлык, пропускаются). Если ярлыка нет, используется aria-description.
    • Группировка (наборы полей). Чтобы добавить описание к группе связанных элементов (например, кнопок <input type="radio">), поместите toolparamdescription в ближайший родительский элемент <fieldset>, чтобы оно применялось ко всей группе параметров.

Пример

<form toolname="search-cars" 
      tooldescription="Perform a car make/model search" 
      toolautosubmit>
  <label for="make">Vehicle Make</label>
  <input type="text" id="make" name="make" required>
  
  <label for="model">Vehicle Model</label>
  <input type="text" id="model" name="model" toolparamdescription="e.g., 330i, F-150" required>
  
  <button type="submit">Search</button>
</form>

Обработка отправки данных в JavaScript

Когда агент отправляет форму, SubmitEvent включает agentInvoked (логическое значение) и respondWith(promise).

document.querySelector('form').addEventListener('submit', (event) => {
  event.preventDefault();

  // Validate the form
  const formValidationErrors = myFormIsValid();

  if (formValidationErrors.length > 0) {
    if (event.agentInvoked) {
      const errorString =
        'Validation failed: ' +
        formValidationErrors
          .map((err) => `${err.field} (${err.message})`)
          .join(', ');

      event.respondWith(Promise.resolve(errorString));
    }
    return;
  }

  const resultPromise = performAsyncSearch(new FormData(event.target));

  // Return the result directly to the agent without navigation
  if (event.agentInvoked) {
    event.respondWith(resultPromise);
  }
});

События жизненного цикла

document.modelContext генерирует события, когда агенты начинают или прекращают взаимодействие с инструментом: toolactivated срабатывает, когда начинается выполнение инструмента, а toolcancel – когда оно отменяется.

// Starting in Chrome 156, these events are dispatched on `document.modelContext`.
// Older versions dispatch them on `window`. Feature-detect the event handler
// property to pick the right target for backward compatibility.
const targetFor = (type, listener, options) =>
  (`on${type}` in (document.modelContext ?? {}) ? document.modelContext : window)
    .addEventListener(type, listener, options);

targetFor('toolactivated', ({ toolName }) => {
  console.log(`Tool "${toolName}" started execution.`);
});

targetFor('toolcancel', ({ toolName }) => {
  console.log(`Tool "${toolName}" execution is cancelled.`);
});

Визуальная обратная связь (CSS)

Используйте псевдоклассы, чтобы выделять формы, когда агент взаимодействует с ними:

  • :tool-form-active – применяется к элементу <form>, который активно используется агентом.
  • :tool-submit-active: применяется к кнопке отправки, когда браузер приостанавливает работу для проверки пользователем (если toolautosubmit не указан).
form:tool-form-active {
  outline: 2px dashed blue;
  background-color: rgba(0, 0, 255, 0.05);
}

button:tool-submit-active {
  outline: 2px dashed red;
  animation: pulse 2s infinite;
}

Когда не стоит использовать формы

Декларативный API лучше всего подходит для автономных стандартных форм. Этот вариант не подходит в следующих случаях:

  • Поля с высокой зависимостью. Формы, в которых варианты или видимость полей меняются в зависимости от введенных данных. Синтезированная схема не может правильно выразить эти зависимости.
  • Специальные компоненты интерфейса. Формы, в которых используются нестандартные элементы ввода (например, canvas, редакторы форматированного текста), не выполняющие автоматическую сериализацию значений.
  • Многоэтапные мастера. Сложные рабочие процессы, требующие отправки нескольких форм. В этом случае лучше использовать императивный API или стандартное взаимодействие с DOM.

Когда использовать toolautosubmit

  • Операции и запросы только для чтения. Поиск, фильтрация, получение сведений или проверка статуса (например, поиск модели автомобиля, поиск в каталоге, проверка наличия на складе).
  • Действия с низким риском и обратимые действия. Действия с формами, которые пользователь может легко отменить или уточнить вручную (например, добавление товаров в корзину, применение промокода, сохранение черновика или настройка временных параметров макета).

Когда не нужно использовать toolautosubmit

  • Деструктивные или необратимые действия. Удаление записей, сброс конфигураций системы или очистка баз данных.
  • Финансовые и транзакционные действия. Отправка формы оплаты, перевод средств, авторизация платежей по подписке или окончательное оформление заказа.
  • Важные действия, связанные с общением. Отправка заявки на вакансию, отправка электронных писем или сообщений другим пользователям, публикация общедоступного контента.
  • Настройки конфиденциального аккаунта: Смена паролей, изменение ролей пользователей/разрешений или обновление платежных данных/данных профиля.

Резервные стратегии

Декларативный API WebMCP можно безопасно использовать во всех браузерах. Браузеры, которые не поддерживают WebMCP, будут игнорировать атрибуты tool*, а <form> продолжит работать как обычная HTML-форма. Распознавание объектов не требуется.