AI-агент в production-приложении — это больше, чем чат с потоковым текстом. Клиенту нужно понимать состояние run, отображать tool calls, принимать подтверждения пользователя, синхронизировать thread state и безопасно переживать reconnect. AG-UI — один из протокольных подходов к такому связующему слою между agent backend и интерфейсом.
Когда отдельный agent UI протокол действительно нужен
Один агент обслуживает web и mobile clients.
Ответ состоит из событий, tool calls и промежуточных состояний, а не только текста.
Нужны pause/resume и human approval перед чувствительными действиями.
UI должен обновляться по мере выполнения агента, не ожидая финального ответа.
Thread/run state должен переживать reconnect и повторное открытие приложения.
Базовая архитектура
Практический контур обычно разделяет agent service, protocol/transport layer и frontend. Backend владеет моделью, tools, policy и state transition; AG-UI-подобный слой сериализует события и состояние; frontend только отображает разрешённые компоненты и отправляет пользовательские действия обратно. Такое разделение не даёт модели напрямую управлять DOM или произвольным клиентским кодом.
Streaming и порядок событий
Передавайте устойчивые threadId/runId/messageId, чтобы frontend мог дедуплицировать события.
Сохраняйте порядок событий внутри одного run или используйте sequence number.
Отделяйте token/content streaming от state/tool events.
После reconnect запрашивайте authoritative state, а не продолжайте UI только из локального optimistic cache.
Поддерживайте heartbeat/keepalive, если transport работает через SSE.
Tool calls и действия в интерфейсе
Tool call должен быть типизированным событием с понятным статусом: proposed, running, succeeded, failed или waiting_for_approval. Не превращайте аргументы tool call в произвольный HTML/JavaScript. Frontend должен рендерить только заранее зарегистрированные безопасные компоненты и отправлять назад ограниченный набор действий.
Human approval
Требуйте подтверждение перед оплатой, отправкой сообщения, удалением данных и другими необратимыми действиями.
Показывайте пользователю не внутренний chain-of-thought, а краткое описание запрашиваемого действия, цели и параметров.
Привязывайте approval к конкретному run/tool-call ID, чтобы старое подтверждение нельзя было повторно использовать.
На backend повторно проверяйте права и параметры даже после подтверждения в UI.
State management
Frontend state не должен быть единственным источником истины. Храните canonical thread/run state на сервере или в специализированном store. Клиент может оптимистично показывать промежуточное состояние, но после reconnect, retry или conflict должен сверяться с сервером. Для нескольких вкладок и устройств особенно важно использовать version/sequence контроль.
Retries и идемпотентность
Присваивайте idempotency key действиям, которые могут повториться после сетевого сбоя.
Различайте retry transport delivery и повторный запуск business action.
Не запускайте tool повторно только потому, что frontend не получил acknowledgement.
Сохраняйте terminal status run/tool call и возвращайте его при повторном запросе.
Observability
Коррелируйте frontend event, run, model request и tool execution одним trace/correlation ID.
Измеряйте time-to-first-event, tool latency, approval wait time и total run duration.
Логируйте protocol errors отдельно от model/tool errors.
Следите за dropped/duplicate/out-of-order events и reconnect rate.
Безопасность
Agent UI protocol не заменяет authN/authZ. Каждый tool должен проверять пользователя, tenant, scope и ресурс на backend. Данные из модели считайте недоверенными: валидируйте схемы, ограничивайте размеры payload, фильтруйте ссылки и не позволяйте модели выбирать произвольный компонент или executable code.
AG-UI или обычный streaming chat
Если продукту нужен только поток текста и несколько простых кнопок, отдельный agent protocol может быть лишним. Он становится полезным, когда UI должен отражать длительные runs, tools, approvals, shared state и интерактивные компоненты. Начинайте с минимального event contract и расширяйте его только под реальные сценарии.
Короткий production checklist
Есть стабильные IDs и порядок событий.
Tool events типизированы и не исполняют произвольный UI-код.
Approval привязан к конкретному действию.
Backend остаётся источником истины для state и permissions.
Retries идемпотентны.
Streaming/reconnect покрыты telemetry и failure handling.