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

State Management — 역할과 라이프사이클

목적: 에이전트와 프론트엔드 간 양방향 공유 상태 동기화. 단순 저장이 아니라 양쪽 모두 읽고 쓸 수 있는 collaborative state로, Human-in-the-Loop 워크플로우의 기반이 된다.

핵심 특성

• 방향: 양방향 (agent ↔ frontend 모두 수정 가능)
• 목적: 에이전트의 제안(proposal)을 UI가 표시 → 사용자가 승인/거부/수정 → 다시 에이전트에 반영
• UI 반영: 메인 UI (폼, 에디터, 문서 뷰 등)
• 지속성: Run 경계를 넘어 누적

실전 예시: Shared State — 레시피 에디터

AI와 사용자가 같은 레시피를 함께 편집하는 시나리오.

state = {
    "recipe": {
        "skill_level": "Advanced",
        "ingredients": [{"name": "chicken breast", "amount": "1"}, ...],
        "instructions": ["Season chicken...", "Sear until...", ...]
    }
}
yield StateSnapshotEvent(type=EventType.STATE_SNAPSHOT, snapshot=state)

CopilotKit의 useCoAgent hook이 이 state를 양방향으로 바인딩한다:

const { state: agentState, setState: setAgentState } = useCoAgent({
  name: "agent",
  initialState: { someProperty: "initialValue" },
})

• 에이전트가 레시피 초안을 STATE_SNAPSHOT으로 공유
• UI가 폼으로 렌더링 → 사용자가 재료 수정
• setAgentState로 변경이 에이전트에 전달되어 다음 생성에 반영

왜 필요한가: 메시지로는 “재료 목록, 조리 단계, 난이도” 같은 구조화된 공동 편집 문서를 표현할 수 없다.

라이프사이클 다이어그램

sequenceDiagram
    autonumber
    participant Agent
    participant UI
    participant User

    Note over Agent: Run 시작
    Agent->>UI: STATE_SNAPSHOT (초기 전체 상태)
    UI->>User: 폼 렌더링

    Note over Agent: 일부 필드 업데이트
    Agent->>UI: STATE_DELTA (JSON Patch)
    UI->>User: 해당 필드만 갱신

    User->>UI: 필드 수정
    UI->>Agent: setState (역방향 반영)

    Note over Agent: 대규모 변경/재동기화 필요
    Agent->>UI: STATE_SNAPSHOT (재동기화)
    UI->>User: 전체 재렌더링

---

Activity — 역할과 라이프사이클

목적: 채팅 메시지 사이에 구조화된 진행 상황을 표시. 에이전트가 현재 하고 있는 작업을 프로그레스 바, 카드, 플랜 트리 같은 별도 UI 컴포넌트로 시각화하기 위한 단방향 스트림.

핵심 특성

• 방향: 단방향 (agent → frontend, 사용자 수정 불가)
• 목적: 작업 진행 상황의 구조화된 읽기 전용 뷰
• UI 반영: 메시지 스트림 중간 (Plan 박스, 검색 결과 패널 등)
• 지속성: role: "activity" 메시지로 히스토리 누적, Run을 넘어 보존

실전 예시: Plan 모드

에이전트가 작업 계획을 수립하면서 UI에 별도의 Plan 박스로 실시간 표시.

{
  type: EventType.ACTIVITY_SNAPSHOT,
  messageId: "activity-1",
  activityType: "PLAN",
  content: { tasks: ["task 1"] }
}

• activityType이 "PLAN"이면 UI는 Plan 전용 렌더러를 선택
• 같은 messageId의 ACTIVITY_DELTA로 tasks 배열에 추가/수정
• Run이 끝나도 role: "activity" 메시지로 히스토리에 남음

왜 필요한가:

• 메시지는 자연어 텍스트 버블 — Plan/Search 같은 구조화된 진행 뷰에 부적합
• State Management는 양방향 편집용이라 읽기 전용 진행 상황 표시에는 과한 설계
• Activity = “에이전트만 쓰고 사용자는 보기만 하는 구조화된 뷰”의 전용 프리미티브

메시지 vs State vs Activity 비교

항목	TEXT_MESSAGE	STATE	ACTIVITY
용도	대화 텍스트	공유 편집 상태	진행 상황 뷰
내용	자연어 문자열	구조화된 JSON	구조화된 JSON
편집 방향	—	양방향	단방향 (agent→UI)
UI 위치	채팅 버블	메인 UI (폼/에디터)	메시지 사이 (카드/패널)
증분 업데이트	delta (문자 append)	JSON Patch	JSON Patch
히스토리	role: "assistant"	상태로 누적	role: "activity" 메시지

라이프사이클 다이어그램

sequenceDiagram
    autonumber
    participant Agent
    participant UI
    participant User

    Note over Agent: 작업 시작
    Agent->>UI: ACTIVITY_SNAPSHOT (activityType PLAN)
    UI->>User: Plan 박스 렌더링

    loop 작업 진행
        Agent->>UI: ACTIVITY_DELTA (tasks 추가)
        UI->>User: Plan 박스 실시간 갱신
    end

    Note over Agent: 새 Plan으로 교체
    Agent->>UI: ACTIVITY_SNAPSHOT (replace true)
    UI->>User: Plan 박스 전체 교체

    Note over Agent: Run 종료 후에도 role activity 메시지로 히스토리 보존

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