AG-UI 프로토콜 완벽 해설: 인간-에이전트 인터페이스의 새로운 표준

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 에이전트와 사용자 대면 인터페이스 간에 교환되는 메시지의 형식과 의미를 정의하는 오픈 스트리밍 이벤트 프로토콜입니다.

특징:

• 전송 방식 무관: HTTP(Server-Sent Events), WebSocket, 또는 모든 스트리밍 전송 방식에서 작동
• 프레임워크 무관: 모든 언어 또는 에이전트 프레임워크에서 구현 가능
• 양방향: 에이전트는 프론트엔드에 이벤트를 전송하고; 사용자는 에이전트에 메시지와 중단 신호를 전송
• 상태 유지: 프로토콜에는 상태 스냅샷이 포함되어 있어 프론트엔드가 언제든지 완전한 에이전트 컨텍스트를 복원할 수 있음

다음에 해당하지 않습니다:

• 도구 프로토콜(그것은 MCP의 역할)
• 에이전트 프레임워크 자체
• UI 컴포넌트 라이브러리(참조 구현은 존재하지만)

AG-UI vs. MCP: 차이점 이해하기

흔한 혼란의 원인은 AG-UI가 Anthropic의 Model Context Protocol(MCP)와 어떻게 연관되는지입니다.

두 가지는 상호 보완적입니다. 프로덕션에서 실행되는 에이전트는 일반적으로 도구 접근(웹 검색, 이미지 생성, 코드 실행)에 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 — 표준 집합에 포함되지 않는 애플리케이션 특정 이벤트용

인간 차례(Human Turn)

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 통합: 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_* 이벤트를 발행하여 프론트엔드에 진행 상황을 표시합니다:

사용자: "상위 5개 AI 프레임워크를 조사하고 요약 이미지를 만들어줘"

에이전트 발행: TOOL_CALL_START (tool: "anycap_search", args: {...})
에이전트 발행: TOOL_CALL_END (result: 검색 결과)
에이전트 발행: TOOL_CALL_START (tool: "anycap_image_generate", args: {...})
에이전트 발행: TOOL_CALL_END (result: 이미지 URL)
에이전트 발행: TEXT_MESSAGE (이미지가 포함된 스트리밍 요약)

이러한 완전한 투명성——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 저장소