AG-UI

• **AG-UI(Agent–User Interaction Protocol)**는 AI 에이전트와 사용자 대면 애플리케이션 사이의 실시간 통신을 표준화하는 오픈 이벤트 기반 프로토콜
• 에이전트 백엔드가 ~16개의 표준 이벤트 타입을 스트리밍으로 emit하는 경량 추상화 레이어
• MCP(도구 연결), A2A(에이전트 간 통신)와 함께 에이전트 프로토콜 스택의 3번째 축 (Agent ↔ User)
• CopilotKit에서 LangGraph·CrewAI 파트너십을 기반으로 탄생한 MIT 라이선스 오픈소스

AG-UI가 해결하려는 문제

AG-UI 공식 문서에서는 다음 두 가지 핵심 문제를 명시한다.

1. 전통적 클라이언트-서버 모델의 한계

Agentic applications break the simple request/response model that dominated frontend-backend development in the pre-agentic era.

에이전트는 일반 소프트웨어와 다른 특성을 갖고 있어 기존 REST/GraphQL API로는 대응이 어렵다:

• Long-running + streaming: 에이전트는 장기 실행되며 중간 작업을 스트리밍한다 (멀티턴 세션)
• Nondeterministic UI control: 에이전트가 비결정적으로 애플리케이션 UI를 제어할 수 있다
• Mixed IO: 텍스트·음성 같은 비구조화 데이터와 tool call·state update 같은 구조화 데이터를 동시에 혼합한다
• Recursive composition: 서브 에이전트를 재귀적으로 호출하며 사용자와 상호작용해야 한다

2. 벤더별 이벤트/프로토콜 파편화

LangGraph, CrewAI, Google ADK, AWS Strands, Mastra 등 각 에이전트 프레임워크는 자체 네이티브 이벤트 포맷을 사용한다. 프론트엔드 개발자가 각 벤더마다 별도의 ad-hoc 연결 코드를 작성해야 하는 문제를 AG-UI는 두 가지 메커니즘으로 해결한다:

• Flexible Event Structure: 이벤트가 AG-UI 포맷과 정확히 일치하지 않아도 됨 — AG-UI 호환이면 충분. 기존 프레임워크가 최소한의 수정으로 네이티브 이벤트를 적응시킬 수 있다
• Middleware Layer: 느슨한 이벤트 포맷 매칭을 통해 다양한 에이전트와 앱 간의 광범위한 상호운용성을 보장

“This allows existing agent frameworks to adapt their native event formats with minimal effort.” — AG-UI Architecture Docs

해당 개념이 필요한 이유

• 프레임워크마다 ad-hoc으로 프론트 연결 코드를 작성하는 대신 표준화된 이벤트 프로토콜이 필요
• 벤더 교체 시 프론트엔드 코드 변경 없이 백엔드 에이전트만 교체할 수 있는 추상화 레이어 확보
• 하나의 앱에서 여러 에이전트 프레임워크를 동시에 사용해야 할 때 통합 인터페이스 역할

AS-IS: 벤더별 ad-hoc 스트리밍 구현

ad-hoc: “이것을 위해”라는 라틴어. 범용적인 표준 없이 특정 상황에 맞춰 즉석에서 만든 일회성 구현을 뜻한다. 여기서는 각 벤더 프레임워크마다 별도로 작성하는 전용 어댑터·파싱 코드를 의미.

sequenceDiagram
    autonumber
    participant App as Frontend App
    participant A1 as LangGraph Adapter
    participant A2 as CrewAI Adapter
    participant A3 as Google ADK Adapter
    participant LG as LangGraph Agent
    participant CR as CrewAI Agent
    participant GK as Google ADK Agent

    App->>A1: LangGraph 전용 SSE 연결
    A1->>LG: LangGraph 네이티브 이벤트
    LG-->>A1: astream_events() 포맷
    A1-->>App: 파싱 로직 A

    App->>A2: CrewAI 전용 SSE 연결
    A2->>CR: CrewAI 네이티브 이벤트
    CR-->>A2: kickoff() 포맷
    A2-->>App: 파싱 로직 B

    App->>A3: ADK 전용 연결
    A3->>GK: ADK 네이티브 이벤트
    GK-->>A3: ADK 자체 포맷
    A3-->>App: 파싱 로직 C

    Note over App: 벤더마다 어댑터·파싱 로직 별도 구현<br/>백엔드 교체 시 프론트엔드도 전면 수정

TO-BE: AG-UI 표준 이벤트로 통합

sequenceDiagram
    autonumber
    participant App as Frontend App
    participant Client as AG-UI Client
    participant MW as AG-UI Middleware
    participant LG as LangGraph Agent
    participant CR as CrewAI Agent
    participant GK as Google ADK Agent

    App->>Client: runAgent(input)
    Client->>MW: 표준 RunAgentInput

    alt LangGraph 사용 시
        MW->>LG: 네이티브 호출
        LG-->>MW: LangGraph 이벤트 → AG-UI 변환
    else CrewAI 사용 시
        MW->>CR: 네이티브 호출
        CR-->>MW: CrewAI 이벤트 → AG-UI 변환
    else Google ADK 사용 시
        MW->>GK: 네이티브 호출
        GK-->>MW: ADK 이벤트 → AG-UI 변환
    end

    MW-->>Client: 동일한 AG-UI 표준 이벤트
    Client-->>App: Observable BaseEvent
    Note over App: 백엔드 교체해도<br/>프론트엔드 코드 변경 없음

Agentic Protocol Stack에서의 위치

프로토콜	연결 대상	역할
MCP	Agent ↔ Tools & Data	에이전트가 외부 도구·데이터 소스에 연결
A2A (Agent to Agent)	Agent ↔ Agent	에이전트 간 조율·작업 위임
AG-UI	Agent ↔ User	에이전트를 사용자 대면 애플리케이션에 연결

세 프로토콜은 상호보완적이며 하나의 에이전트가 동시에 세 가지 모두를 사용할 수 있다. AG-UI는 MCP/A2A와의 핸드셰이크도 제공하여 AG-UI 클라이언트 앱이 MCP/A2A 기반 에이전트를 투명하게 사용할 수 있다.

핵심 아키텍처

설계 원칙

1. Event-Driven Communication: 에이전트가 16개 표준 이벤트 타입을 스트리밍으로 emit
2. Bidirectional Interaction: 사용자 입력을 에이전트에 전달하여 협업 워크플로 지원
3. Transport Agnostic: SSE, WebSocket, Webhook 등 전송 방식에 무관
4. Flexible Event Structure: 네이티브 이벤트 포맷을 AG-UI 호환하게 매핑만 하면 됨

구성 요소

graph LR
    subgraph Frontend
        A[Application] --> B[AG-UI Client]
    end
    subgraph Backend
        C[AI Agent A]
        D[AI Agent B]
        E[Secure Proxy]
    end
    B <-->|AG-UI Protocol| E
    E --> C
    E --> D

• Application: 사용자 대면 앱 (채팅 UI, AI 기능이 있는 앱)
• AG-UI Client: HttpAgent 등 통신 클라이언트. run(input) → Observable<BaseEvent> 인터페이스
• Agents: 요청 처리 후 스트리밍 이벤트를 생성하는 백엔드 에이전트
• Secure Proxy: 보안 프록시 (API 키 보호 등)

16개 이벤트 타입 체계

AG-UI의 모든 통신은 BaseEvent를 상속하는 타입드 이벤트로 이루어진다.

interface BaseEvent {
  type: EventType;
  timestamp?: number;
  rawEvent?: any;
}

Lifecycle Events (실행 생명주기)

이벤트	설명
RUN_STARTED	에이전트 실행 시작. threadId, runId 포함
RUN_FINISHED	실행 성공 완료. 선택적 result 포함
RUN_ERROR	실행 중 복구 불가 에러. message, code 포함
STEP_STARTED	실행 내 단계 시작. stepName (노드/함수명)
STEP_FINISHED	단계 완료

Text Message Events (텍스트 메시지 스트리밍)

Start → Content(반복) → End 패턴:

이벤트	설명
TEXT_MESSAGE_START	메시지 시작. messageId, role
TEXT_MESSAGE_CONTENT	텍스트 청크. delta (non-empty)
TEXT_MESSAGE_END	메시지 완료
TEXT_MESSAGE_CHUNK	편의 이벤트 — Start/Content/End 자동 확장. 첫 청크에서 TEXT_MESSAGE_START 자동 생성, 각 delta마다 TEXT_MESSAGE_CONTENT 자동 emit, 스트림 종료 시 TEXT_MESSAGE_END 자동 생성. LLM API의 청크 스트리밍 포맷을 거의 그대로 매핑할 수 있어 백엔드 어댑터 구현 복잡도를 줄이는 sugar syntax

TEXT_MESSAGE_CHUNK 코드 예제

// ❌ Start/Content/End 수동 관리 (보일러플레이트)
yield { type: EventType.TEXT_MESSAGE_START, messageId: "msg-1", role: "assistant" };
for await (const chunk of llmStream) {
  yield { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "msg-1", delta: chunk.text };
}
yield { type: EventType.TEXT_MESSAGE_END, messageId: "msg-1" };
 
// ✅ TEXT_MESSAGE_CHUNK로 단순화 (클라이언트가 자동 확장)
for await (const chunk of llmStream) {
  yield {
    type: EventType.TEXT_MESSAGE_CHUNK,
    messageId: "msg-1",   // 첫 청크에서만 role 포함 시 START 자동 생성
    role: "assistant",
    delta: chunk.text,
  };
}
// 스트림 종료 시 END 자동 생성

Tool Call Events (도구 호출 스트리밍)

Start → Args(반복) → End → Result 패턴:

이벤트	설명
TOOL_CALL_START	도구 호출 시작. toolCallId, toolCallName
TOOL_CALL_ARGS	인자 청크(JSON fragment). delta
TOOL_CALL_END	도구 호출 완료
TOOL_CALL_RESULT	도구 실행 결과. content
TOOL_CALL_CHUNK	편의 이벤트 — Start/Args/End 자동 확장. 첫 청크에서 TOOL_CALL_START 자동 생성, 각 delta(JSON fragment)마다 TOOL_CALL_ARGS 자동 emit, 스트림 종료 시 TOOL_CALL_END 자동 생성. LLM API의 tool call 스트리밍 포맷을 거의 그대로 매핑할 수 있어 백엔드 어댑터 구현 복잡도를 줄이는 sugar syntax

TOOL_CALL_CHUNK 코드 예제

// ❌ Start/Args/End 수동 관리 (보일러플레이트)
yield { type: EventType.TOOL_CALL_START, toolCallId: "tc-1", toolCallName: "search_web" };
for await (const chunk of llmStream) {
  yield { type: EventType.TOOL_CALL_ARGS, toolCallId: "tc-1", delta: chunk.arguments };
}
yield { type: EventType.TOOL_CALL_END, toolCallId: "tc-1" };
 
// ✅ TOOL_CALL_CHUNK로 단순화 (클라이언트가 자동 확장)
for await (const chunk of llmStream) {
  yield {
    type: EventType.TOOL_CALL_CHUNK,
    toolCallId: "tc-1",          // 첫 청크에서만 toolCallName 포함 시 START 자동 생성
    toolCallName: "search_web",
    delta: chunk.arguments,      // JSON fragment: '{"q' → '":"hello' → '"}'
  };
}
// 스트림 종료 시 END 자동 생성

State Management Events (상태 동기화)

Snapshot-Delta 패턴:

이벤트	설명
STATE_SNAPSHOT	전체 상태 스냅샷
STATE_DELTA	JSON Patch (RFC 6902) 기반 증분 업데이트
MESSAGES_SNAPSHOT	대화 히스토리 전체 스냅샷

Activity Events

이벤트	설명
ACTIVITY_SNAPSHOT	활동 메시지 전체 상태. activityType (예: “PLAN”, “SEARCH”)
ACTIVITY_DELTA	JSON Patch 기반 활동 증분 업데이트

Reasoning Events (추론 과정 시각화)

이벤트	설명
REASONING_START / REASONING_END	추론 과정 시작/종료
REASONING_MESSAGE_START / CONTENT / END	추론 메시지 스트리밍
REASONING_ENCRYPTED_VALUE	암호화된 chain-of-thought (ZTR 지원)

Special Events

이벤트	설명
RAW	외부 시스템 이벤트 패스스루. event, source
CUSTOM	앱 전용 커스텀 이벤트. name, value

3가지 이벤트 흐름 패턴

1. Start-Content-End: 스트리밍 콘텐츠용 (텍스트 메시지, 도구 호출)
2. Snapshot-Delta: 상태 동기화용 (전체 스냅샷 → JSON Patch 증분)
3. Lifecycle: 실행 모니터링용 (Started → Finished/Error)

사용자 질의 시 이벤트 흐름 예시

“오늘 날씨 어때?” 질의 시 실제 이벤트 순서:

RUN_STARTED

REASONING_START
REASONING_MESSAGE_CONTENT  { delta: "날씨 도구를 써야겠다..." }
REASONING_END

TOOL_CALL_START  { toolCallId: "tc-1", toolCallName: "get_weather" }
TOOL_CALL_ARGS   { delta: '{"location":"seoul"}' }
TOOL_CALL_END
TOOL_CALL_RESULT { content: "서울 맑음 22도" }

TEXT_MESSAGE_START   { messageId: "m1", role: "assistant" }
TEXT_MESSAGE_CONTENT { delta: "오늘 서울은 맑고 22도입니다." }
TEXT_MESSAGE_END

RUN_FINISHED
(MESSAGES_SNAPSHOT)  ← 선택적. 전체 대화 히스토리 동기화

이벤트 역할 분리

이벤트 종류	UI 표현	대화 히스토리 기록
REASONING_*	접을 수 있는 “Thinking…” 영역	❌
TOOL_CALL_*	작은 배지/인디케이터	❌
TEXT_MESSAGE_*	메인 응답 영역	✅

핵심: 과정(REASONING/TOOL_CALL)과 결과(TEXT_MESSAGE)는 모두 이벤트로 전달된다. 단, TEXT_MESSAGE만 messages 배열에 기록되어 다음 LLM 호출 시 컨텍스트로 전달된다. 과정 이벤트를 “숨긴다”는 것은 프로토콜 동작이 아니라 프론트엔드의 UI 설계 선택이다.

Building Blocks (기능 블록)

기능	설명
Streaming Chat	실시간 토큰·이벤트 스트리밍, 취소/재개
Multimodality	파일, 이미지, 오디오, 트랜스크립트 등 다중 모달
Generative UI (static)	모델 출력을 앱이 제어하는 안정적 컴포넌트로 렌더링
Generative UI (declarative)	에이전트가 UI 트리와 제약을 제안, 앱이 검증·마운트
Shared State	에이전트↔앱 간 타입드 스토어. 이벤트 소싱 diff + 충돌 해결
Frontend Tool Calls	에이전트 → 프론트엔드 실행 액션 핸드오프
Interrupts (HITL)	중간에 승인·편집·재시도·에스컬레이션
Sub-agents	스코프된 상태·트레이싱·취소가 있는 중첩 위임

코드 예제: HttpAgent 사용

import { HttpAgent, EventType } from '@ag-ui/core';
 
const agent = new HttpAgent({
  url: "https://your-agent-endpoint.com/agent",
  agentId: "unique-agent-id",
  threadId: "conversation-thread"
});
 
agent.runAgent({
  tools: [...],
  context: [...]
}).subscribe({
  next: (event) => {
    switch(event.type) {
      case EventType.TEXT_MESSAGE_CONTENT:
        // UI에 스트리밍 텍스트 표시
        break;
      case EventType.TOOL_CALL_START:
        // 도구 호출 시작 표시
        break;
      case EventType.STATE_DELTA:
        // JSON Patch로 로컬 상태 업데이트
        break;
    }
  },
  error: (err) => console.error("Agent error:", err),
  complete: () => console.log("Agent run complete")
});

지원 통합 현황

Agent 프레임워크

프레임워크	상태	비고
LangGraph	✅ Supported	파트너십
CrewAI	✅ Supported	파트너십
Microsoft Agent Framework	✅ Supported	1st Party
Google ADK	✅ Supported	1st Party
AWS Strands Agents	✅ Supported	1st Party
Mastra	✅ Supported	1st Party
Pydantic AI	✅ Supported	1st Party
Agno, LlamaIndex, AG2	✅ Supported	1st Party
OpenAI Agent SDK	🛠️ In Progress	커뮤니티

SDK

TypeScript(공식), Python, Kotlin, Golang, Dart, Java, Rust, Ruby 지원

클라이언트

클라이언트	상태
CopilotKit	✅ Supported (1st Party)
Terminal + Agent	✅ Supported (Community)
React Native	🛠️ Help Wanted

참고 문서

• AG-UI Official Documentation
• AG-UI GitHub Repository
• AG-UI Dojo (데모 앱)
• Agentic Protocols (MCP, A2A, AG-UI)
• Core Architecture
• Events Specification