AG-UI Event

• AG-UI 이벤트 시스템은 에이전트-UI 간 실시간 통신을 위한 typed 이벤트 스트림 프로토콜
• 28개 활성 이벤트 타입과 3가지 설계 패턴으로 구성된 표준화된 에이전트 인터페이스
• Thread(대화 세션) > Run(사용자 1턴) > Step(선택적 단계) > Streaming Item 의 4계층 구조

해당 개념이 필요한 이유

• LangGraph, CrewAI 등 다양한 프레임워크를 하나의 UI에서 연결할 표준 인터페이스 부재 해결
• LLM 응답의 실시간 스트리밍을 위한 이벤트 기반 비동기 통신 필요
• MCP(에이전트 도구) · A2A(에이전트 간 통신)와 함께 에이전트 프로토콜 스택의 UI 계층 담당

AS-IS — REST 요청/응답 방식

sequenceDiagram
    autonumber
    participant User
    participant UI
    participant Agent

    User->>UI: 메시지 입력
    UI->>Agent: HTTP POST /chat
    Note over Agent: 전체 응답 생성 (waiting...)
    Agent-->>UI: 완성된 응답 반환
    UI->>User: 응답 표시 (한 번에)

TO-BE — AG-UI 이벤트 스트리밍

sequenceDiagram
    autonumber
    participant User
    participant UI
    participant Agent

    User->>UI: 메시지 입력
    UI->>Agent: RunAgentInput (threadId + runId)
    Agent-->>UI: RUN_STARTED
    Agent-->>UI: TEXT_MESSAGE_START
    Agent-->>UI: TEXT_MESSAGE_CONTENT (delta)
    Agent-->>UI: TEXT_MESSAGE_CONTENT (delta)
    Agent-->>UI: TEXT_MESSAGE_END
    Agent-->>UI: RUN_FINISHED
    UI->>User: 실시간 스트리밍 표시

4계층 구조: Thread > Run > Step > Item

flowchart TD
    subgraph THREAD["Thread (threadId — 대화 세션)"]
        subgraph RUN["Run (runId — 사용자 1턴)"]
            RUN_STARTED([RUN_STARTED])
            RUN_FINISHED([RUN_FINISHED])
            RUN_ERROR([RUN_ERROR])
            subgraph STEP["Step (선택적, N개 순차)"]
                STEP_STARTED[STEP_STARTED]
                STEP_FINISHED[STEP_FINISHED]
                subgraph MSG["Text Message"]
                    TMS[TEXT_MESSAGE_START]
                    TMC[TEXT_MESSAGE_CONTENT]
                    TME[TEXT_MESSAGE_END]
                end
                subgraph TOOL["Tool Call"]
                    TCS[TOOL_CALL_START]
                    TCA[TOOL_CALL_ARGS]
                    TCE[TOOL_CALL_END]
                    TCR[TOOL_CALL_RESULT]
                end
                subgraph REASON["Reasoning"]
                    RST[REASONING_START]
                    RMC[REASONING_MESSAGE_CONTENT]
                    REN[REASONING_END]
                end
            end
        end
    end
    RUN_STARTED --> STEP_STARTED
    STEP_STARTED --> TMS
    STEP_STARTED --> TCS
    STEP_STARTED --> RST
    TMS --> TMC
    TMC -->|반복| TMC
    TMC --> TME
    TCS --> TCA
    TCA -->|반복| TCA
    TCA --> TCE
    TCE --> TCR
    RST --> RMC
    RMC -->|반복| RMC
    RMC --> REN
    TME --> STEP_FINISHED
    TCR --> STEP_FINISHED
    REN --> STEP_FINISHED
    STEP_FINISHED -->|다음 Step| STEP_STARTED
    STEP_FINISHED --> RUN_FINISHED
    RUN_STARTED -->|치명적 에러| RUN_ERROR
    RUN_FINISHED -->|다음 사용자 턴| RUN_STARTED

28개 활성 이벤트 (카테고리별)

Lifecycle — 5개

이벤트	핵심 필드	의미
RUN_STARTED	threadId, runId	에이전트 실행 시작
RUN_FINISHED	threadId, runId	실행 정상 완료
RUN_ERROR	message, code	실행 오류 종료
STEP_STARTED	stepName	하위 단계 시작
STEP_FINISHED	stepName	하위 단계 완료

Text Message — 4개

이벤트	핵심 필드	의미
TEXT_MESSAGE_START	messageId, role	텍스트 스트림 시작
TEXT_MESSAGE_CONTENT	messageId, delta	텍스트 청크 누적
TEXT_MESSAGE_END	messageId	텍스트 스트림 완료
TEXT_MESSAGE_CHUNK	messageId, delta	Start+Content+End 자동 확장 편의 이벤트

Tool Call — 5개

이벤트	핵심 필드	의미
TOOL_CALL_START	toolCallId, toolCallName	툴 호출 시작
TOOL_CALL_ARGS	toolCallId, delta	툴 인자 JSON 청크
TOOL_CALL_END	toolCallId	툴 인자 전송 완료
TOOL_CALL_RESULT	toolCallId, content	툴 실행 결과 (스트리밍 아님)
TOOL_CALL_CHUNK	toolCallId, delta	Start+Args+End 자동 확장 편의 이벤트

State Management — 3개

이벤트	핵심 필드	의미
STATE_SNAPSHOT	snapshot	전체 상태 (프론트엔드 교체)
STATE_DELTA	delta (RFC 6902)	JSON Patch 증분 업데이트
MESSAGES_SNAPSHOT	messages	대화 히스토리 전체 스냅샷

Activity — 2개

이벤트	핵심 필드	의미
ACTIVITY_SNAPSHOT	messageId, activityType, content	진행 활동 전체 스냅샷 (PLAN, SEARCH 등)
ACTIVITY_DELTA	messageId, patch	활동 JSON Patch 증분 업데이트

Special — 2개

이벤트	핵심 필드	의미
RAW	event, source	외부 시스템 이벤트 pass-through
CUSTOM	name, value	애플리케이션 확장 이벤트

Reasoning — 7개

이벤트	핵심 필드	의미
REASONING_START	messageId	추론 프로세스 시작
REASONING_MESSAGE_START	messageId, role	추론 메시지 스트림 시작
REASONING_MESSAGE_CONTENT	messageId, delta	추론 청크
REASONING_MESSAGE_END	messageId	추론 메시지 완료
REASONING_MESSAGE_CHUNK	messageId, delta	편의 이벤트 (자동 확장)
REASONING_END	messageId	추론 프로세스 완료
REASONING_ENCRYPTED_VALUE	subtype, entityId, encryptedValue	암호화된 chain-of-thought

Deprecated 5개: THINKING_* → 모두 REASONING_*으로 대체 (v1.0.0 제거 예정)

3가지 설계 패턴

1. Start-Content-End 패턴 (스트리밍)
   TEXT_MESSAGE_START → TEXT_MESSAGE_CONTENT (반복) → TEXT_MESSAGE_END
   TOOL_CALL_START    → TOOL_CALL_ARGS (반복)       → TOOL_CALL_END
   REASONING_START    → REASONING_MESSAGE_CONTENT   → REASONING_END

2. Snapshot-Delta 패턴 (상태 동기화)
   STATE_SNAPSHOT → STATE_DELTA (반복) → STATE_SNAPSHOT (재동기화 시)

3. Lifecycle 패턴 (실행 경계)
   RUN_STARTED → (Steps/Items) → RUN_FINISHED | RUN_ERROR

AG-UI vs Codex vs Claude CLI 이벤트 매핑

의미	AG-UI	Codex	Claude CLI (NDJSON)
세션(대화)	threadId (RUN_STARTED 포함)	thread.started	프로세스 spawn
턴 시작	RUN_STARTED	turn.started	system { subtype:"init" }
텍스트 시작	TEXT_MESSAGE_START	item.started	content_block_start { type:"text" }
텍스트 청크	TEXT_MESSAGE_CONTENT	item.updated	content_block_delta { type:"text_delta" }
텍스트 종료	TEXT_MESSAGE_END	item.completed	content_block_stop
툴 시작	TOOL_CALL_START	item.started	content_block_start { type:"tool_use" }
툴 인자	TOOL_CALL_ARGS	item.updated	content_block_delta { type:"input_json_delta" }
툴 종료	TOOL_CALL_END	item.completed	content_block_stop
툴 결과	TOOL_CALL_RESULT	—	없음 (Claude 내부 실행)
추론 시작	REASONING_START + REASONING_MESSAGE_START	—	content_block_start { type:"thinking" }
추론 청크	REASONING_MESSAGE_CONTENT	—	content_block_delta { type:"thinking_delta" }
추론 종료	REASONING_MESSAGE_END + REASONING_END	—	content_block_stop
턴 성공	RUN_FINISHED	turn.completed	result { subtype:"success" }
턴 실패	RUN_ERROR	turn.failed	result { subtype:"error_*" }
인터럽트	(커스텀 이벤트)	—	result { subtype:"error_during_execution" }
치명적 에러	RUN_ERROR	error	프로세스 crash (stdout 종료)
상태 동기화	STATE_SNAPSHOT / STATE_DELTA	—	—
단계 구분	STEP_STARTED / STEP_FINISHED	—	—

설계 철학 비교

항목	AG-UI	Codex	Claude CLI
컨텐츠 타입 구분	타입별 별도 이벤트	단일 item.* 통합	content_block.type 필드 구분
툴 결과	TOOL_CALL_RESULT 존재	—	없음 (에이전트 내부 실행)
추론(Thinking)	7개 전용 이벤트	—	thinking 블록 타입
상태 동기화	전용 이벤트 3종	—	—
Step 개념	명시적 이벤트 쌍	—	—
세션 vs 턴 분리	threadId + runId 명시 분리	thread + turn 분리	프로세스=세션, result=턴 종료

참고 문서

• ag-ui-protocol/ag-ui
• docs/concepts/events.mdx
• sdks/typescript/packages/core/src/events.ts