1. AG-UI란?
AGUI(Agent User Interaction Protocol)란 AI Agent와 사용자 인터페이스 간의 표준화된 통신 프로토콜입니다. 기존의 요청/응답 방식을 이벤트 기반의 양방향 통신으로 전환하여 에이전트와 프론트엔드의 상태를 동기화하는 프로토콜입니다.
표준 HTTP(또는 바이너리 채널) 위로 JSON 이벤트의 단일 시퀀스를 스트리밍합니다. 에이전트 백엔드가 실행 중에 표준 이벤트를 방출하면, 프론트엔드는 그 이벤트 타입에 반응해 UI를 그립니다.
2. AG-UI가 필요한 이유
기존의 웹 개발의 상호작용은 단발성이었습니다. 클라이언트가 요청 -> 서버가 데이터를 반환 -> 렌더 -> 상호작용으로 동작했지만 Agent를 활용한 상호작용은 다르게 동작합니다.
- Long-running: 중간 작업을 스트리밍한다.
- 비결정적: 응답뿐 아니라 UI 제어까지 비결정적으로 발생한다.
- 컴포지션: 서브 에이전트를 재귀적으로 호출한다.
청크(토큰)이 흘러나오고, 도구(Tool)을 호출하고, 사람의 인터렉션을 기다렸다가 다시 흐름을 이어가는 방식은 단발성 REST로는 해결할 수 없었습니다.
AG-UI는 이 사이를 잇는 통신 규약이 되어 어떤 에이전트든 백엔드든 UI와 통신할 수 있게됩니다.
3. 구성 요소
1. 컴포넌트
AG-UI는 다음과 같은 핵심 컴포넌트로 구성되어 있습니다:
- Events - 비동기 통신의 기반
run, 텍스트 전송, 툴 호출과 같은 타입 기반의 실행 이벤트. 모든 이벤트는 BaseEvent(type, timestamp, rawEvent)를 상속하고 5개의 카테고리 16개의 타입으로 나뉩니다.
- Lifecycle:
RUN_STARTED,RUN_FINISHED,RUN_ERROR,STEP_STARTED,STEP_FINISHED - Text message:
TEXT_MESSAGE_START,TEXT_MESSAGE_CONTENT,TEXT_MESSAGE_END - Tool call:
TOOL_CALL_START,TOOL_CALL_ARGS,TOOL_CALL_END - State management:
STATE_SNAPSHOT,STATE_DELTA,MESSAGES_SNAPSHOT - Special:
RAW,CUSTOM
const response = await fetch("/chat", {
method: "POST",
headers: { "Content-Type": "application/json", "Accept": "text/event-stream" },
body: JSON.stringify(runAgentInput)
});
// data: {"type":"RUN_STARTED", ...}
// data: {"type":"TEXT_MESSAGE_CONTENT","delta":"The"}
// data: {"type":"TOOL_CALL_START", ...}
// data: {"type":"RUN_FINISHED", ...}- Agents - Agent 추상화
Agent는 프로토콜의 기반입니다.AbstractAgent클래스를 확장하고Observable<BaseEvent>를 반환하는 run() 메서드를 구현합니다. 이 추상화를 통해 어떤 AI 서비스든 일관된 인터페이스로 통합할 수 있습니다.
class SimpleAgent extends AbstractAgent {
run(input: RunAgentInput): RunAgent {
const { threadId, runId } = input
return () => new Observable<BaseEvent>((observer) => {
observer.next({ type: EventType.RUN_STARTED, threadId, runId })
const messageId = Date.now().toString()
observer.next({ type: EventType.TEXT_MESSAGE_START, messageId, role: "assistant" })
observer.next({ type: EventType.TEXT_MESSAGE_CONTENT, messageId, delta: "Hello, world!" })
observer.next({ type: EventType.TEXT_MESSAGE_END, messageId })
observer.next({ type: EventType.RUN_FINISHED, threadId, runId })
observer.complete()
})
}
}-
Messages - 대화 컨텍스트와 히스토리
대화 상태를 전송하는 단위입니다. 타입은Developer,System,Assitant,User,Tool,Activity,Reasoning으로 나뉩니다. -
State Management - 상태 동기화
에이전트와 UI간의 실시간 동기화 레이어입니다.
STATE_SNAPSHOT: 특정 시점의 완전한 상태STATE_DELTA: JSON Patch(RFC 6902) 기반 증분 변경MESSAGES_SNAPSHOT: 완전한 대화 히스토리
-
Tools - 도구/함수 정의
에이전트가 호출할 수 있는 함수를 표준화합니다. 툴 정의는runAgent파라메터로 전달되고, 호출은TOOL_CALL_START → TOOL_CALL_ARGS → TOOL_CALL_END시퀀스로 스트리밍됩니다. -
Middleware - 미들웨어 레이어
호환성을 보장하는 어댑터 계층입니다.
- 유연한 이벤트 구조: 이벤트가 AG-UI 포맷과 정확히 일치할 필요 없이, 호환되기만 하면 가능합니다. 기존 프레임워크가 가진 네이티브 이벤트를 적응시킬 수 있습니다.
- Transport: SSE, webhook, WebSocket등 어떤 전송 방식이든 지원합니다.
3. 마치며
AG-UI는 스트리밍 프로세스에서 UI에 연결하는 표준을 만들기 위한 Agent 전용 프로토콜입니다. 출시된지 얼마 안됐지만 AG-UI를 통한 A2UI가 나오는 등 활발하게 커뮤니케이션이 발생하는 분야라고 생각됩니다. 기존의 LLM 프로젝트를 진행해보신 프론트엔드 개발자분들이라면 스트리밍 통신 규약을 만드는게 까다롭고 복잡하게 느껴지셨을텐데요. AG-UI의 사용을 고려해보시고 더 나은 개발을 해보셨으면 좋겠습니다. 오늘도 글 읽어주셔서 감사합니다!
