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

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

AI 에이전트가 실제 업무 흐름을 처리할 수 있을 만큼 발전함에 따라 새로운 인프라 과제가 등장했습니다. 바로 인간과 에이전트가 실행 도중 어떻게 소통하느냐는 문제입니다—시작과 끝뿐만 아니라 전체 프로세스 내내.

AG-UI 프로토콜은 바로 이 문제를 해결하기 위해 설계된 개방형 사양입니다. AI 에이전트가 실시간으로 이벤트를 스트리밍하고, 입력을 요청하고, 프론트엔드 애플리케이션과 인간 운영자에게 상태를 제공하는 방법의 표준을 정의합니다. MCP(모델 컨텍스트 프로토콜)가 에이전트의 도구 접근 방식을 표준화했다면, AG-UI는 에이전트가 사용자와 통신하는 방식을 표준화합니다.

이 가이드에서는 AG-UI가 무엇인지, 왜 중요한지, 어떻게 작동하는지, 그리고 에이전트 스택에서 어떻게 사용을 시작하는지 설명합니다.

AG-UI가 해결하는 문제

AG-UI 이전에는 사용자 대면 AI 에이전트 애플리케이션을 구축하는 모든 팀이 자체 통신 프로토콜을 만들어야 했습니다. 에이전트가 프론트엔드에 "생각 중"이라는 것을 어떻게 알릴까요? 인간의 결정을 어떻게 요청할까요? 사용자가 작업 중에 수정 사항을 어떻게 보낼까요? 진행 상황은 어떻게 표시할까요?

답은 팀마다 달랐습니다—종종 임시방편이었고, 문서화가 부족했으며, 재사용하기 어려웠습니다. 이로 인해 파편화된 생태계가 만들어졌습니다.

• 에이전트 프레임워크들이 프론트엔드 컴포넌트를 공유할 수 없었음
• 개발자들이 모든 프로젝트에서 스트리밍 UI 인프라를 처음부터 다시 구축해야 했음
• 사용자들이 에이전트 기반 제품에서 일관성 없는 경험을 받았음
• 에이전트 동작 디버깅을 위해 모든 구현에 맞춤 로깅이 필요했음

AG-UI는 공통 어휘와 이벤트 구조를 확립하여 어떤 에이전트 프레임워크든 AG-UI 호환 프론트엔드가 렌더링할 수 있는 이벤트를 생성할 수 있도록 합니다—맞춤 통합 코드 없이.

AG-UI란 무엇인가?

AG-UI는 AI 에이전트와 사용자 인터페이스 간에 교환되는 메시지의 형식과 의미를 정의하는 개방형 스트리밍 이벤트 프로토콜입니다.

특징:

• 전송 방식에 독립적: HTTP(서버 전송 이벤트), WebSocket, 또는 모든 스트리밍 전송 방식에서 동작
• 프레임워크에 독립적: 어떤 언어나 에이전트 프레임워크에서도 구현 가능
• 양방향: 에이전트가 프론트엔드에 이벤트를 전송하고, 사용자가 에이전트에 메시지와 중단 신호를 전송
• 상태 유지: 프로토콜에 상태 스냅샷이 포함되어 프론트엔드가 언제든 에이전트의 전체 컨텍스트를 재구성 가능

AG-UI가 아닌 것:

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

AG-UI 대 MCP: 차이점 이해하기

AG-UI와 Anthropic의 모델 컨텍스트 프로토콜(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는 에이전트 실행을 **스레드(Thread)**로 구성합니다—여러 실행에 걸쳐 상태를 유지하는 영속적인 대화 컨텍스트입니다. 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 저장소