Когда бэкенд ИИ-агента уже стабильно работает, попытка подключить его к реальному веб-приложению, мобильному клиенту или терминалу почти неизбежно оборачивается хрупким «клеем»: текст идёт по одному самописному формату, вызовы инструментов в середине ответа используют отдельную JSON-схему, общее состояние рассинхронизируется, а паузы на подтверждение пользователя зависают на ненадёжных соединениях.
AG-UI (Agent-User Interaction Protocol), развиваемый в репозитории ag-ui-protocol/ag-ui под лицензией MIT, определяет открытый, лёгкий и событийно-ориентированный протокол связи ИИ-агентов с пользовательскими интерфейсами. Он объединяет поточную выдачу текста, вызовы инструментов в середине ответа, синхронизацию состояния приложения и паузы для подтверждения человеком в единый контракт для веба, мобильных устройств и терминала.
Важно
- Единый типизированный поток событий: Стандартные семейства событий (
RUN_STARTED,TEXT_MESSAGE_CONTENT,TOOL_CALL_START,STATE_DELTA) отвязывают фронтенд от конкретного фреймворка агента на сервере. - Чистые прерывания для Human-in-the-Loop: Вместо подвешивания сокета на время ожидания клика выполнение штатно завершается событием
RUN_FINISHEDс исходомinterruptи затем возобновляется через структуруresume. - Чёткое разделение ролей с MCP и A2A: MCP связывает агента с инструментами и данными, A2A — агентов друг с другом, а AG-UI стандартизирует границу агент <-> пользовательский интерфейс.
Для компаний, внедряющих решения искусственного интеллекта и мультиплатформенную разработку программного обеспечения, жёсткая привязка клиентского кода к одному фреймворку (LangChain, CrewAI, Google ADK или Microsoft Agent Framework) создаёт дорогостоящий техдолг. Стоит сменить оркестратор на бэкенде — и приходится переписывать парсеры потока в React, iOS, Android и CLI. AG-UI снимает эту зависимость и претендует на роль отраслевого стандарта взаимодействия агента с интерфейсом.
Почему классический REST не справляется с интерфейсами ИИ-агентов
Обычный цикл «запрос — ответ» рассчитан на один атомарный ответ сервера. Современный ИИ-агент ломает эту модель сразу в четырёх точках:
- Переплетение текста и инструментов: Агент начинает потоковую генерацию пояснения, на полпути вызывает внешний или клиентский инструмент и продолжает ответ после получения результата.
- Инкрементальное общее состояние: Списки шагов, формы и статусы субагентов меняются по ходу работы и должны обновляться плавно без пересылки всего состояния целиком.
- Контроль человеком (Human-in-the-Loop): Чувствительные операции — удаление записей в базе, отправка писем клиентам или подтверждение платежей — требуют явной паузы и одобрения оператора.
- Двунаправленная мультимодальность: Интерфейсы передают типизированные файлы, изображения и контекст экрана наравне с текстовыми сообщениями.
В рамках трендов экосистемы открытых ИИ-агентов ноября 2026 года зоопарк несовместимых потоковых форматов стал заметным тормозом. Развиваемый вместе с CopilotKit под открытым управлением ag-ui-protocol, AG-UI закрывает эту фрагментацию единым контрактом.
Место AG-UI рядом с протоколами MCP и A2A
В современной архитектуре ИИ-агентов три открытых протокола не конкурируют, а закрывают разные слои стека:
| Протокол / Подход | Стандартизируемая граница | Ключевой инженерный вопрос | Транспорт и модель данных | Основная роль |
|---|---|---|---|---|
| AG-UI | Агент <-> Интерфейс | «Как агент общается с веб-, мобильным или терминальным UI?» | Транспортно-независимый SSE или WebSocket + события + RFC 6902 JSON Patch | Потоковый UI, live-инструменты, общее состояние и паузы HITL |
| MCP | Агент <-> Инструменты и данные | «Как агент безопасно находит и вызывает внешние инструменты и БД?» | JSON-RPC (stdio / Streamable HTTP) | Базы данных, API, локальные ресурсы и инструменты вроде REA MCP |
| A2A | Агент <-> Агент | «Как распределённые агенты делегируют задачи между сервисами?» | Контракты задач HTTP / JSON-RPC (Google / Linux Foundation) | Мультиагентная оркестрация между доменами |
| Самописный REST / SSE | Один бэкенд <-> Один UI | «Как быстро связать одиночный прототип?» | Недокументированные JSON-фреймы проекта | Небольшие демо; высокий долг поддержки на нескольких клиентах |
В зрелом продакшен-стеке бэкенд-агент подключает инструменты и память через MCP (например, опираясь на слой постоянной памяти claude-mem), делегирует подзадачи через A2A и транслирует весь пользовательский цикл в клиент через AG-UI.
Семейства событий и независимость от транспорта
AG-UI намеренно не привязан к одному транспорту: для лёгкой односторонней потоковой выдачи с сервера используется Server-Sent Events (SSE), а при необходимости полноценного двунаправленного обмена в реальном времени (мгновенная отмена, передача контекста, клиентские инструменты) — WebSockets.
Спецификация раскладывает взаимодействие на четыре основные группы типизированных событий:
1. Жизненный цикл запусков и шагов (Runs & Steps)
RUN_STARTED: сигнализирует о старте выполнения с метаданнымиthreadIdиrunId.STEP_STARTEDиSTEP_FINISHED: показывают прохождение узлов графа агента для прозрачной индикации прогресса.RUN_FINISHEDиRUN_ERROR: фиксируют штатное завершение, структурированную паузу для человека (interrupt) или ошибку.
2. Потоковые текстовые сообщения (Text Messages)
TEXT_MESSAGE_START,TEXT_MESSAGE_CONTENT,TEXT_MESSAGE_ENDиTEXT_MESSAGE_CHUNK: передают фрагменты текста (дельты) с привязкой к конкретному ID сообщения, исключая смешивание параллельных потоков.
3. Вызовы инструментов внутри ответа (Tool Calls)
TOOL_CALL_START,TOOL_CALL_ARGS,TOOL_CALL_END,TOOL_CALL_RESULTиTOOL_CALL_CHUNK: транслируют намерение вызова и поток JSON-аргументов по мере генерации, позволяя сразу рисовать карточки выполнения и генеративные UI-компоненты прямо в потоке.
4. Синхронизация общего состояния (State Management)
STATE_SNAPSHOT: передаёт полный снимок состояния при подключении или восстановлении связи.STATE_DELTA: отправляет только точечные изменения в формате RFC 6902 JSON Patch, экономя трафик и избавляя сложные таблицы и формы от полных перерисовок.
Совет
Крупнейшие фреймворки агентов — LangChain, CrewAI, Microsoft Agent Framework, Google ADK, LlamaIndex и Pydantic AI — поддерживают встроенные или официальные адаптеры AG-UI. Стандартизация клиента на AG-UI позволяет менять серверный движок без переписывания интерфейсов.
Паузы на подтверждение человеком (HITL) и надёжное возобновление
Удержание открытого HTTP-соединения в ожидании клика пользователя регулярно рвётся на таймаутах обратного прокси или при сворачивании мобильного приложения. AG-UI решает задачу Human-in-the-Loop (HITL) через терминальные прерывания: запуск корректно завершается событием RUN_FINISHED с исходом interrupt и массивом interruptId.
После решения пользователя клиент запускает новый прогон через HttpAgent из @ag-ui/client, передавая массив resume:
import { HttpAgent } from "@ag-ui/client";
const agent = new HttpAgent({
url: "https://api.example.com/agent",
headers: {
Authorization: `Bearer ${process.env.AGUI_TOKEN}`,
},
threadId: "thread-ops-4821",
});
agent.messages.push({
id: "msg-user-1",
role: "user",
content: "Очистить архивные временные черновики счетов старше 90 дней.",
});
async function executeWithApproval() {
// 1. Первый запуск чисто завершается с исходом interrupt в ожидании одобрения
await agent.runAgent();
// Идентификатор из события RUN_FINISHED и выбор пользователя в UI:
const pendingInterruptId = "intr-clean-drafts-01";
const approvedByReviewer = true;
// 2. Корректное возобновление на том же threadId с объектом resume
const resumed = await agent.runAgent({
resume: [
{
interruptId: pendingInterruptId,
status: approvedByReviewer ? "resolved" : "cancelled",
payload: {
approved: approvedByReviewer,
comment: approvedByReviewer
? "Одобрено через панель операций."
: "Отклонено по политике хранения данных.",
},
},
],
});
return resumed;
}
Независимо от того, ответит рецензент через три секунды или через три часа, на сервере не остаётся зависшего сокета — выполнение возобновляется с контрольной точки того же threadId.
Экосистема SDK для веба, мобильных приложений и терминала
Отделение протокола событий от слоя отрисовки позволяет одному бэкенд-эндпоинту обслуживать сразу все клиентские платформы:
- Веб (официальная поддержка): Пакеты TypeScript (
@ag-ui/core,@ag-ui/client) и CopilotKit для React, Angular и Vue с поддержкой патчей состояния и восстановления снимков. - Мобильные и кроссплатформенные клиенты: SDK на Kotlin Multiplatform (Android, iOS, JVM), нативные реализации на Swift (
async/awaitиCodable), поддержка React Native, а также пакеты сообщества для Flutter с SSE и HITL-формами. - Терминал и CLI: Интерактивные консольные клиенты и мониторы агентов на Node.js/TypeScript, Python или .NET, подключающиеся напрямую к тому же потоку событий.
- Базовые языки спецификации 1.0: Первоклассные схемы для TypeScript, Python и .NET, дополненные SDK сообщества для Go, Rust, Java, Dart/Flutter, Ruby и C++.
Предупреждение
Безопасность и разграничение прав: AG-UI стандартизирует транспорт событий, но не заменяет авторизацию. Никогда не доверяйте слепо флагу approved: true из клиентского resume — повторно проверяйте на сервере сессию, роли RBAC и принадлежность interruptId и threadId. Для контроля расходов на токены в высоконагруженных потоковых агентах изучите также обзор сжатия токенов Caveman.
Когда стоит стандартизировать архитектуру на AG-UI
Для одиночной генерации статического текста достаточно обычного HTTP. Внедрение AG-UI окупается, если для вашего продукта актуальны хотя бы два из трёх пунктов:
- Один агент обслуживает веб, мобильные приложения и терминал без дублирования логики потоков.
- Пользователям нужны живое отображение вызовов инструментов, синхронное состояние и паузы одобрения человеком.
- Команде важна свобода менять серверный фреймворк агента без переписывания фронтенда.
Оценить масштаб и бюджет мультиплатформенного агентного интерфейса можно через калькулятор стоимости, а для проектирования промышленных решений на базе AG-UI и MCP обратитесь к архитекторам через страницу контактов Kling Digital.




