AI 에이전트가 실제 워크플로를 처리할 만큼 충분히 강력해지면서 새로운 인프라 과제가 등장했습니다. 인간과 에이전트는 실행 도중에 어떻게 소통해야 할까요? 시작과 끝에서만이 아니라, 작업이 진행되는 내내 어떻게 상호작용해야 할까요?
AG-UI 프로토콜은 바로 이 문제를 해결하기 위해 설계된 오픈 스펙입니다. AI 에이전트가 이벤트를 스트리밍하고, 입력을 요청하고, 상태를 프런트엔드 애플리케이션과 인간 운영자에게 실시간으로 드러내는 방식을 표준화합니다. MCP(Model Context Protocol)가 에이전트의 도구 접근 방식을 표준화했다면, AG-UI는 에이전트가 사용자와 대화하는 방식을 표준화합니다.
이 가이드에서는 AG-UI가 무엇인지, 왜 중요한지, 어떻게 작동하는지, 그리고 에이전트 스택에서 어떻게 도입할 수 있는지 설명합니다.
AG-UI가 해결하는 문제
AG-UI 이전에는 사람과 직접 상호작용하는 AI 에이전트 애플리케이션을 만드는 모든 팀이 자체 통신 프로토콜을 발명해야 했습니다. 에이전트가 지금 생각 중이라는 사실을 프런트엔드에 어떻게 알릴까요? 사람의 결정을 어떻게 요청할까요? 사용자는 작업 도중에 어떻게 수정 사항을 보낼까요? 진행 상황은 어떻게 표시할까요?
이에 대한 답은 팀마다 달랐고, 대개 임시방편이었으며, 문서화가 부족했고, 재사용도 어려웠습니다. 그 결과 다음과 같은 파편화된 생태계가 만들어졌습니다.
- 에이전트 프레임워크끼리 프런트엔드 컴포넌트를 공유할 수 없었다
- 개발자는 프로젝트마다 스트리밍 UI 인프라를 처음부터 다시 만들어야 했다
- 사용자는 에이전트 기반 제품마다 일관되지 않은 경험을 했다
- 에이전트 동작을 디버깅하려면 구현마다 별도의 로깅이 필요했다
AG-UI는 공통 어휘와 이벤트 구조를 정의함으로써 어떤 에이전트 프레임워크든 이벤트를 생성하고, 어떤 AG-UI 호환 프런트엔드든 그것을 렌더링할 수 있게 합니다. 별도의 커스텀 통합 코드는 필요하지 않습니다.
AG-UI란 무엇인가
AG-UI는 AI 에이전트와 사용자 대면 인터페이스 사이에서 교환되는 메시지의 형식과 의미를 정의하는 오픈 스트리밍 이벤트 프로토콜입니다.
AG-UI의 특징은 다음과 같습니다.
- 전송 방식 비종속적: HTTP(Server-Sent Events), WebSocket 또는 어떤 스트리밍 전송 방식에서도 동작
- 프레임워크 비종속적: 어떤 언어와 어떤 에이전트 프레임워크로도 구현 가능
- 양방향: 에이전트는 프런트엔드로 이벤트를 보내고, 사용자는 에이전트에 메시지와 인터럽트를 보냄
- 상태 유지형: 프로토콜에 상태 스냅샷이 포함되어 있어 프런트엔드가 어느 시점에서든 전체 에이전트 컨텍스트를 재구성할 수 있음
반면 AG-UI는 다음이 아닙니다.
- 도구 프로토콜이 아님. 그 역할은 MCP가 담당함
- 에이전트 프레임워크 자체가 아님
- UI 컴포넌트 라이브러리가 아님. 다만 레퍼런스 구현은 존재함
AG-UI와 MCP: 차이 이해하기
많이 혼동되는 부분은 AG-UI가 Anthropic의 Model Context Protocol(MCP)과 어떤 관계에 있는가입니다.
| 구분 | MCP | AG-UI |
|---|---|---|
| 목적 | 에이전트 ↔ 도구 통신 | 에이전트 ↔ 인간/프런트엔드 통신 |
| 방향 | 에이전트가 도구를 호출하고 결과를 받음 | 에이전트가 이벤트를 스트리밍하고 인간이 메시지를 보냄 |
| 대상 | 도구/서버 개발자 | 프런트엔드 및 에이전트 프레임워크 개발자 |
| 초점 | 에이전트가 사용할 수 있는 기능이 무엇인가 | 에이전트가 자신의 상태와 진행 상황을 어떻게 전달하는가 |
| 관계 | 에이전트의 도구 측면을 담당 | 에이전트의 사용자 인터페이스 측면을 담당 |
두 프로토콜은 상호보완적입니다. 실제 운영 환경의 에이전트는 보통 MCP로 도구, 예를 들어 웹 검색, 이미지 생성, 코드 실행에 접근하고, AG-UI로 진행 상황을 전달하며 사람의 입력을 요청합니다.
AG-UI의 핵심 개념
이벤트 유형
AG-UI는 에이전트가 내보내는 표준 이벤트 유형 집합을 정의합니다.
라이프사이클 이벤트:
RUN_STARTED/RUN_FINISHED— 에이전트가 실행을 시작했거나 완료함STEP_STARTED/STEP_FINISHED— 워크플로 안의 개별 단계가 시작되었거나 종료됨RUN_ERROR— 에이전트가 복구할 수 없는 오류를 만남
메시지 이벤트:
TEXT_MESSAGE_START/TEXT_MESSAGE_CONTENT/TEXT_MESSAGE_END— 에이전트의 스트리밍 텍스트 출력TOOL_CALL_START/TOOL_CALL_ARGS/TOOL_CALL_END— 에이전트가 도구를 호출 중임
상태 이벤트:
STATE_SNAPSHOT— 현재 에이전트 상태의 전체 스냅샷STATE_DELTA— 상태에 대한 증분 업데이트MESSAGES_SNAPSHOT— 특정 시점의 전체 대화 기록
커스텀 이벤트:
CUSTOM— 표준 세트에 포함되지 않는 애플리케이션별 이벤트용
사람의 개입 턴
AG-UI는 실행 중인 에이전트와 사람이 상호작용하는 방식도 표준화합니다. 프런트엔드는 AgentInput을 보내 실행 도중 에이전트를 중단시키거나, 방향을 바꾸거나, 추가 정보를 제공할 수 있습니다. 이는 새로운 대화 턴과는 다릅니다. 에이전트는 이미 실행 중이고, 사람은 현재 작업에 영향을 주고 있는 것입니다.
스레드 기반 아키텍처
AG-UI는 에이전트 실행을 스레드 단위로 구성합니다. 스레드는 여러 실행에 걸쳐 상태를 유지하는 영속적인 대화 컨텍스트입니다. AG-UI의 스레드는 다른 프레임워크의 세션 또는 대화와 비슷하지만, 재개, 분기, 리플레이를 위한 명시적 프로토콜 지원이 있다는 점이 다릅니다.
AG-UI 작동 방식: 일반적인 흐름
1. 사용자가 프런트엔드를 통해 작업을 제출한다
2. 프런트엔드는 RunAgentInput과 함께 InitialRun 요청을 에이전트 백엔드로 보낸다
3. 에이전트가 실행을 시작하고 RUN_STARTED 이벤트를 발생시킨다
4. 에이전트는 각 계획 단계마다 STEP_STARTED를 발생시킨다
5. 에이전트가 도구를 호출한다 → TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END를 발생시킨다
6. 에이전트가 텍스트를 생성한다 → TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT(스트리밍), TEXT_MESSAGE_END를 발생시킨다
7. 에이전트는 STATE_DELTA를 발생시켜 프런트엔드 상태를 실시간으로 업데이트한다
8. 사용자가 에이전트의 방향을 바꾸기로 결정한다 → 수정 내용을 담은 AgentInput을 보낸다
9. 에이전트가 수정 내용을 반영하고 계속 진행한다
10. 에이전트가 RUN_FINISHED를 발생시킨다
프런트엔드는 이러한 이벤트를 스트림으로 받아 점진적으로 렌더링합니다. 도구 호출이 일어나는 순간 이를 보여주고, 텍스트를 실시간으로 스트리밍하며, 단계 이벤트를 기반으로 진행 표시기를 업데이트합니다.
AG-UI 구현하기
프레임워크 지원
AG-UI는 주요 에이전트 프레임워크 전반에서 지원이 확대되고 있습니다.
- LangGraph: AG-UI Python SDK를 사용해 그래프 노드에서 AG-UI 이벤트를 발생시킬 수 있음
- AG-UI CopilotKit integration: CopilotKit, AI용 React 프런트엔드 프레임워크는 기본 AG-UI 지원을 제공함
- 커스텀 구현: AG-UI 스펙은 오픈되어 있으므로 어떤 프레임워크든 이벤트 유형 정의에 맞춰 구현할 수 있음
빠른 시작(Python)
from ag_ui.core import (
RunAgentInput, EventType,
RunStartedEvent, TextMessageStartEvent,
TextMessageContentEvent, TextMessageEndEvent,
RunFinishedEvent,
)
import uuid
async def run_agent(input: RunAgentInput):
run_id = str(uuid.uuid4())
yield RunStartedEvent(
type=EventType.RUN_STARTED,
thread_id=input.thread_id,
run_id=run_id,
)
msg_id = str(uuid.uuid4())
yield TextMessageStartEvent(type=EventType.TEXT_MESSAGE_START, message_id=msg_id, role="assistant")
for chunk in agent.stream(input.messages):
yield TextMessageContentEvent(
type=EventType.TEXT_MESSAGE_CONTENT,
message_id=msg_id,
delta=chunk
)
yield TextMessageEndEvent(type=EventType.TEXT_MESSAGE_END, message_id=msg_id)
yield RunFinishedEvent(type=EventType.RUN_FINISHED, thread_id=input.thread_id, run_id=run_id)
AnyCap과 연결하기
AG-UI 기반 에이전트에 웹 검색, 이미지 생성, 파일 저장 같은 실제 기능이 필요할 때 AnyCap은 오케스트레이션 아래의 도구 계층으로 통합됩니다. 에이전트는 실행 루프 중 AnyCap 도구를 호출하고, 이에 대응하는 TOOL_CALL_* 이벤트를 발생시켜 프런트엔드가 현재 무슨 일이 일어나는지 보여줄 수 있게 합니다.
User: "상위 5개 AI 프레임워크를 조사하고 요약 이미지를 만들어줘"
Agent emits: TOOL_CALL_START (tool: "anycap_search", args: {...})
Agent emits: TOOL_CALL_END (result: search results)
Agent emits: TOOL_CALL_START (tool: "anycap_image_generate", args: {...})
Agent emits: TOOL_CALL_END (result: image URL)
Agent emits: TEXT_MESSAGE (streaming summary with embedded image)
AG-UI 이벤트를 통해 드러나는 이러한 완전한 투명성은 신뢰할 수 있는 인간-에이전트 인터페이스와 블랙박스를 가르는 핵심 요소입니다.
프로덕션 에이전트 애플리케이션에서 AG-UI가 중요한 이유
에이전트 기반 제품을 만든다면 AG-UI는 다음을 제공합니다.
컴포넌트 재사용성. AG-UI 스펙에 맞춰 만든 프런트엔드 컴포넌트는 어떤 호환 백엔드와도 동작합니다. 스트리밍 채팅 UI를 한 번만 만들고 LangGraph, CrewAI, AutoGen에서 수정 없이 사용할 수 있습니다.
일관된 사용자 경험. 이벤트 유형이 표준화되어 있기 때문에 사용자는 서로 다른 에이전트 워크플로에서도 비슷한 상호작용 패턴을 경험합니다.
디버깅. AG-UI의 상태 스냅샷과 이벤트 스트림은 에이전트 실행에 대한 완전한 기록을 제공합니다. 이벤트 스트림을 재생하면 각 단계에서 에이전트가 무엇을 보고 무엇을 했는지 정확히 확인할 수 있습니다.
인간 감독. 작업 도중 인간이 개입할 수 있는 AgentInput 메커니즘이 사후적으로 덧붙여진 것이 아니라, 프로토콜에 기본 내장되어 있습니다.
결론
AG-UI는 에이전트형 AI 인프라 스택의 실제 공백을 메웁니다. 에이전트가 더 강력해지고 더 사용자 지향적으로 변할수록, 자신의 상태를 어떻게 전달하고 사람의 입력을 어떻게 받는지에 대한 프로토콜은 접근 가능한 도구만큼이나 중요해집니다.
2026년에 에이전트 기반 제품을 만드는 개발자에게 AG-UI를 일찍 도입한다는 것은 생태계가 수렴하고 있는 기반 위에 구축한다는 뜻입니다. 제품이 성장할수록 부담이 되는 맞춤형 통신 계층을 유지하는 대신 말입니다.
추가로 읽어볼 자료:
- AI 오케스트레이션 프레임워크 비교
- MCP vs. Skills: 무엇을 사용해야 할까?
- AnyCap 기능
- AG-UI GitHub 저장소
- 자동화 오케스트레이션 도구 가이드 2026 — Zapier vs n8n vs Temporal vs LangGraph: 선택 방법
- 데이터 오케스트레이션 도구 2026 — Airflow부터 AI 네이티브 오케스트레이션까지, 에이전트 파이프라인 관점에서 보기