Agentation — визуальная обратная связь для AI-агентов

Каждый, кто просил AI-агента поправить интерфейс, знает этот диалог. «Сделай синюю кнопку в сайдбаре заметнее». Агент открывает проект и начинает угадывать: какой именно сайдбар, какая из нескольких синих кнопок. Угадывание стоит агенту лишних ходов, а иногда заканчивается правкой не того компонента.

Agentation заменяет словесные описания точной разметкой. Это React-компонент, который добавляет на страницу панель разметки: вы кликаете по элементам прямо на работающем приложении, оставляете заметки, а на выходе получаете структурированный текст с CSS-селекторами, именами классов и координатами. С таким текстом агент находит нужный код без догадок.

Зачем агенту селекторы

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

Agentation закрывает этот разрыв. Инструмент собирает с размеченного элемента имена классов, CSS-селектор и позицию на странице. Вместо описания «синяя кнопка в сайдбаре» агент получает .sidebar > button.primary и сразу делает grep по коду. Один точный селектор экономит агенту несколько ходов на поиск, а вам — несколько раундов уточнений в духе «нет, не ту кнопку».

Установка

Пакет ставится как dev-зависимость:

npm install agentation -D

Компонент добавляется в разметку приложения рядом с вашим кодом:

import { Agentation } from 'agentation';

function App() {
  return (
    <>
      <YourApp />
      <Agentation />
    </>
  );
}

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

В рантайме у пакета нет сторонних зависимостей. Единственный peer dependency — React версии 18 или новее. Мобильные браузеры не поддерживаются, нужен десктоп.

Что умеет разметка

Базовый сценарий простой: кликнул по элементу — получил заметку. Но набор возможностей шире:

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

Hash-роуты решают ещё одну задачу одностраничных приложений. Если разные состояния интерфейса живут на одном адресе и отличаются только фрагментом после решётки, можно включить отдельные сессии разметки для каждого такого роута. Заметки с одной вкладки не будут мешать заметкам с другой.

Отдельно настраивается интеграция с окружением. Можно включить сбор дополнительных идентифицирующих атрибутов, выбрать формат копирования только с метаданными и открыть найденное место в коде прямо из инструмента через интеграцию с редактором. Полный список props и примеры интеграции — в README пакета: https://github.com/benjitaylor/agentation/blob/main/package/README.md

Типичная сессия

1. Запускаете приложение с подключённым <Agentation />.
2. Активируете разметку и кликаете по кнопке с кривым отступом. Пишете заметку: «отступ сверху слишком большой».
3. Нужное состояние прячется за анимацией? Ставите анимацию на паузу и размечаете конкретный кадр.
4. Копируете готовый markdown со всеми селекторами и заметками.
5. Вставляете текст агенту. Он делает grep по селектору, находит компонент и правит стили.

На весь цикл уходит минута. Без Agentation те же пять шагов заняли бы переписку на десять сообщений с попытками объяснить на словах, о каком элементе речь.

Важна и экономия контекста. Скопированный markdown содержит только то, что нужно для правки: селекторы, позиции, ваши заметки и окружение. Агенту не нужно перебирать файлы в поисках нужного компонента — он сразу делает grep по селектору и попадает в цель.

Два способа передать разметку агенту

Копирование. Разметка выгружается в буфер обмена как markdown со всеми селекторами, позициями и заметками. Дальше вы просто вставляете этот текст в чат с агентом. Способ универсальный: работает с Claude Code, Codex, Gemini, Grok и любым другим инструментом, который принимает текст.

Прямой синк через MCP. Для постоянной связки регистрируете MCP-сервер командой npx -y agentation-mcp server в своём MCP-клиенте и указываете компоненту его HTTP-адрес:

<Agentation endpoint="http://localhost:4747" />

Порядок работы такой. Агент остаётся запущенным. Вы оставляете на странице тестовую заметку и просите агента её прочитать. Копировать ничего не нужно — заметка попадает к агенту напрямую.

Пошаговый гайд по подключению есть на сайте проекта: https://agentation.com/install#agent-integration

Какой способ выбрать? Копирование проще всего в начале: ничего настраивать не нужно, разметка превращается в обычный текст, который понимает любой агент. Это удобный вариант для разовых правок или для инструментов без поддержки MCP. Прямой синк через MCP-сервер выигрывает, когда правки интерфейса идут потоком: связка настраивается один раз, дальше заметки уходят агенту сами, и буфер обмена остаётся свободным для остальной работы.

Как это работает под капотом

Agentation обходит DOM и собирает с каждого размеченного элемента то, что поможет агенту найти его в коде: имена классов, автоматически построенный CSS-селектор и позицию на странице. Агент берёт селектор и делает grep по проекту — так текстовая заметка связывается с конкретным фрагментом кода.

Инструмент работает и с вложенными страницами. Если shadow root открыт или iframe загружен с того же домена, элементы внутри размечаются так же, как и на основной странице.

Отмечу границы применимости. Agentation заточен под React-проекты и десктопные браузеры — на мобильном устройстве работать с разметкой не получится. Зато сам инструмент не привязан к конкретному агенту: текст с разметкой устроен так, что его поймёт и Claude Code, и Codex, и Gemini, и Grok, и любой другой инструмент, которому можно передать текст.

Документация и лицензия

Полная документация — на сайте agentation.com. Проект активно развивается: на GitHub у него около 5,3 тыс. звёзд. Лицензия — PolyForm Shield 1.0.0, автор — Benji Taylor.