UI SDK от Vercel и shadcn: библиотека низкоуровневых интерфейсных поведений для ИИ-агентовСтатья · дайджест за 14 ноября
Взрыв-схема механизма интерфейсной кнопки, отделяющая внешнюю декоративную оболочку от внутреннего кинематического привода
Статья4 раздела≈ 7 мин

UI SDK от Vercel и shadcn: библиотека низкоуровневых интерфейсных поведений для ИИ-агентов

В этом разборе мы выясним, почему современные нейросетевые агенты промахиваются мимо выпадающих меню и как научить их управлять веб-интерфейсом быстро, безошибочно и без огромных счетов за токены. Я покажу, как устроена открытая библиотека UI SDK от команды Vercel и автора дизайн-системы shadcn и за счёт чего она позволяет переключать и тестировать компоненты напрямую из кода без открытия браузера.

Когда я изучил документацию релиза UI SDK, о котором рассказали выпуски Bytes и React Status, меня зацепила смена самой оптики. До сих пор мы заставляли искусственный интеллект притворяться человеком с мышкой и разглядывать экран по пикселям. Авторы нового инструмента убрали эту прослойку и дали алгоритмам прямой пульт управления логикой интерфейса.

Почему скриншоты и сырой DOM разоряют быстрых агентов

Подумай, что происходит, когда ты просишь браузерного ассистента в режиме Computer Use поставить огонёк под постом и отметить комментарий. Человек делает это мгновенно, потому что глаз сразу видит нужную иконку. А нейросети приходится запускать длинный конвейер: сделать снимок экрана, отправить картинку в визуальную модель, вычислить координаты кнопки в пикселях и сэмулировать клик курсора.

Здесь возникают три инженерных тупика:

  • Колоссальный расход контекста. Один скриншот высокого разрешения требует от 1500 до 3000 токенов на каждый единичный шаг. Чтобы открыть меню и нажать пару кнопок, агент сжигает тысячи токенов на разглядывание отступов и шрифтов.
  • Ошибки координат и задержки. Стоит странице чуть сдвинуться при прокрутке или масштабировании экрана, как виртуальный курсор бьёт мимо цели, а каждый шаг тратит секунды на визуальный инференс.
  • Хрупкость разметки. Если вместо картинок отдать модели сырое дерево элементов страницы (DOM), агент вязнет во вложенных обёртках <div> и длинных цепочках CSS-классов, которые ломаются при первом же редизайне.

О том, как меняются способы общения алгоритмов с программами, мы уже говорили в материале про эволюцию интерфейсов ИИ-агентов от диалоговых окон к автономной работе, и на уровне клиентской вёрстки эта проблема встала особенно остро.

Анатомия примитива: как разделить поведение и внешний вид

Чтобы избавить и разработчиков, и нейросети от борьбы с пикселями, создатели UI SDK вынесли механику работы элементов в каталог из более чем 50 низкоуровневых поведенческих примитивов (headless behaviors — «безголовых» поведений без готового дизайна). Сюда входят управление фокусом, ловушки фокуса в модальных окнах, всплывающие подсказки, перетаскивание drag-and-drop и клавиатурные цепочки.

Такой примитив работает как врезной механизм дверного замка. Ему всё равно, какую ручку ты прикрутишь снаружи — бронзовую или стеклянную: пружина и защёлка двигаются по одним и тем же правилам. Пакет ядра @ui-sdk/core описывает чистую логику на TypeScript, а адаптер @ui-sdk/react связывает её с конкретными тегами (npm install @ui-sdk/core @ui-sdk/react).

Соберём наш сквозной пример — интерактивную панель реакций к публикации, где пользователь или агент выбирает эмодзи, а повторным нажатием снимает отметку:

import { definePrimitive } from '@ui-sdk/core';
import { createParts } from '@ui-sdk/react/primitive';

// 1. Описание поведенческого примитива блока реакций
export const reactionsPrimitive = definePrimitive({
  name: 'reactions-panel',
  state: () => ({
    activeEmoji: null as string | null,
    count: 0,
  }),
  api: (context) => ({
    selectEmoji: (emoji: string) => {
      const current = context.store.get();
      if (current.activeEmoji === emoji) {
        context.store.set({ activeEmoji: null, count: Math.max(0, current.count - 1) });
      } else {
        context.store.set({ activeEmoji: emoji, count: current.count + 1 });
      }
    },
  }),
  slots: (slot) => ({
    root: slot({
      attrs: () => ({
        role: 'toolbar',
        'aria-label': 'Оценки публикации',
      }),
    }),
    reactionBtn: slot<{ emoji: string }>({
      attrs: (state, props) => ({
        type: 'button',
        'aria-pressed': state.activeEmoji === props.emoji,
      }),
      press: ({ api, props }) => {
        api.selectEmoji(props.emoji);
      },
    }),
  }),
});

// 2. Адаптация примитива под компоненты React
const { Root: ReactionsToolbar, ReactionBtn } = createParts(reactionsPrimitive, {
  root: 'div',
  reactionBtn: 'button',
});

// 3. Использование в интерфейсе приложения
export function PostReactions() {
  const emojis = ['🔥', '👍', '🚀'];

  return (
    <ReactionsToolbar className="reactions-container">
      {emojis.map((emoji) => (
        <ReactionBtn key={emoji} emoji={emoji} className="emoji-button">
          {emoji}
        </ReactionBtn>
      ))}
    </ReactionsToolbar>
  );
}

Внутри definePrimitive роли чётко разграничены. Фабрика state создаёт реактивное хранилище с выбранным символом activeEmoji и счётчиком count, а блок api описывает действие selectEmoji: если эмодзи уже выбран, сбрасываем его и уменьшаем счётчик, иначе активируем и прибавляем единицу. В секции slots мы объявляем функциональные роли элементов: контейнер root и кнопку reactionBtn, которая при нажатии (press) сама вызывает api.selectEmoji(props.emoji).

Функция-адаптер createParts связывает примитив с тегами div и button, возвращая готовые компоненты ReactionsToolbar и ReactionBtn. В PostReactions остаётся только передать массив эмодзи и навесить свои CSS-классы: вся логика переключения уже работает внутри слотов, а сам reactionsPrimitive не зависит от React и подходит для других фреймворков или Web Components.

Агентный протокол вместо прицеливания курсором

Зачем нужна структура со слотами и api, если обычный хук состояния пишется в три строчки? Главная причина — встроенный программный интерфейс для ИИ-агентов, который получает каждый примитив.

Вместо запуска браузера агент общается с компонентом через три метода:

  • agent.subscribe() — подписывает агента на реактивные изменения состояния компонента без постоянного опроса страницы;
  • agent.snapshot() — возвращает компактное JSON-дерево активных элементов и их состояний без визуального CSS-шума;
  • agent.act(action, payload) — вызывает семантическое действие напрямую по имени метода из блока api.

Когда автономному агенту нужно поставить реакцию в нашем блоке, он вызывает reactionsPrimitive.agent.snapshot(), видит структуру панели и выполняет команду reactionsPrimitive.agent.act('selectEmoji', { emoji: '🔥' }). Экономия токенов достигает 95% по сравнению с Computer Use, а тестировать поведение интерфейса можно за миллисекунды прямо в Node.js без запуска headless-браузера. О том, как подобные жёсткие контракты защищают проекты от сбоев, мы рассказывали в разборе инженерных обвязок harness для автономных ИИ-агентов.

Доступность из коробки и границы применимости

Ещё один выигрыш от декларативных слотов — автоматическая поддержка стандарта доступности WAI-ARIA (атрибутов для скринридеров и клавиатурной навигации). В нашем коде слот root сам выставляет role="toolbar", а кнопка reactionBtn реактивно обновляет aria-pressed при смене state.activeEmoji. В сложных меню примитивы сами генерируют aria-haspopup и aria-controls, избавляя разработчика и кодинг-агента от ручной возни со спецификацией.

Впрочем, тянуть UI SDK в каждый проект не нужно. Библиотека отлично подходит, когда ты строишь собственную дизайн-систему с кастомным оформлением, которую должны собирать и тестировать ИИ-агенты, или когда компании нужен единый слой поведений для нескольких фронтенд-фреймворков.

А вот где такой подход будет избыточен:

  • Небольшие лендинги и простые сайты. Там, где достаточно пары стандартных форм, описание слотов через definePrimitive только усложнит код.
  • Проекты, которым нужны готовые визуальные компоненты. В UI SDK нет стилей, поэтому всю внешнюю часть придётся верстать самостоятельно.
  • Системы с жёсткими требованиями к зрелости зависимостей. Сейчас проект находится в бета-версии: набор из 50+ примитивов лучше всего стабилизирован для React, а при передаче кастомных обёрток в createParts нужно следить, чтобы они корректно пробрасывали ref и обработчики (onKeyDown, onClick) в базовый DOM-элемент.

Универсального рецепта, который подружит нейросети с любым веб-интерфейсом, пока нет: по чужим закрытым сайтам агентам всё равно придётся кликать в режиме эмуляции экрана. Но правила игры для собственных продуктов уже ясны: если ты хочешь, чтобы ИИ-агенты тестировали и пилотировали твой интерфейс без сжигания бюджета на скриншоты, закладывать семантический API в фундамент компонентов стоит уже сейчас.

Хочу подробный разборГолоса помогают выбрать, что разобрать подробно. За этот материал 0 голосов.
Источники · 3