Действия агента на сайте

Подготовьте разметку целей и включите у агента действия с элементами сайта.

Действия и ограничения

После явного запроса пользователя агент может вызвать один из восьми типов:

Тип	Результат	Ограничение
`highlight`	Подсвечивает цель.	Не открывает скрытую панель автоматически.
`scroll_to`	Прокручивает страницу к цели.	Не открывает скрытую панель автоматически.
`focus`	Переводит фокус на элемент.	Цель должна поддерживать фокус.
`click`	Нажимает кнопку, ссылку или другой доступный HTMLElement.	Отключённый элемент блокируется; опасные последствия должен подтверждать сам сайт.
`fill`	Заполняет текстовый `input`, `textarea` или `contenteditable`.	Парольные, карточные и другие чувствительные поля блокируются.
`clear`	Очищает `input`, `textarea`, `select` или `contenteditable`.	Цель должна поддерживать очистку.
`select`	Выбирает вариант в HTML `select` или нестандартном списке с разметкой combobox/listbox.	Вариант должен быть однозначным и доступным. Произвольная кнопка без контракта списка не поддерживается.
`toggle`	Меняет checkbox, radio или элемент с `role="switch"`.	Не применяется к произвольным кнопкам.

Действие использует точный data-ai-context-id, а не нечёткий поиск по подписи. Можно передать одну цель либо цепочку до 12 целей, но не оба варианта одновременно. Цепочка поддерживает только highlight и scroll_to: виджет находит самый дальний доступный шаг и продолжает подсказку после изменения DOM или клика пользователя.

Если одинаковый ключ встречается несколько раз, у цели должна быть полная пара entity_type и entity_id. Без неё неоднозначное действие блокируется.

Если точный элемент не найден или несколько элементов подходят одинаково, агент не выбирает случайный вариант и объясняет путь словами.

Несколько вкладок и история диалога

Автоматическое действие выполняет только тот экземпляр виджета, из которого отправлен запрос. Если один диалог открыт в нескольких вкладках, команда не выполняется одновременно на всех страницах. Открытие истории или перезагрузка страницы не запускает старые действия заново.

Чтобы снова увидеть подсветку, нажмите «Показать на странице» в карточке действия. Такой повтор работает на текущей странице: нужный элемент должен быть доступен здесь. Он не изменяет сохранённый результат первоначального выполнения. Медленный ответ сам по себе не делает команду недействительной, пока запрос принадлежит этому открытому виджету.

Как понять результат

Во время действия виджет показывает карточку с целью, состоянием и деталями выполнения.

Итоговые состояния:

готово — страница подтвердила выполнение;
не найдено — элемента нет на текущем экране;
заблокировано — действие нельзя выполнить автоматически;
ошибка — действие завершилось ошибкой.

Во время выполнения интерфейс может показывать промежуточное состояние, но результатом считаются только success, not_found, blocked или failed. Не считайте действие выполненным, пока карточка не показывает успешное состояние.

Диагностика

Если выбор элемента или действие не работает:

Проверьте, включён ли «Выбор элемента» в настройках виджета.
Убедитесь, что на странице загружен актуальный код виджета.
Проверьте, что у элемента есть понятный текст, data-ai-label или data-ai-context-id.
Не используйте один data-ai-context-id для нескольких элементов без пары data-ai-entity-type / data-ai-entity-id.
Для скрытой цели проверьте стандартную связь с переключателем или data-ai-reveals-context-id.
Для поиска инструкции проверьте совпадение ключа в элементе и Markdown; при необходимости добавьте data-ai-kb-query.
При состоянии «не найдено» убедитесь, что пользователь находится на нужной странице и элемент уже отрисован.

Что подключать дальше

Для обычной подсветки и работы с DOM достаточно разметки этой страницы. Если ответ агента должен запускать самостоятельную бизнес-операцию сайта, например открыть заказ через маршрутизатор сайта или подготовить оплату, используйте custom action. Для редактирования текста в поле с просмотром результата до применения используйте inline-правки.