AG-UI 프로토콜
프론트엔드 연동, CopilotKit, 실시간 이벤트 스트리밍
AG-UI 프로토콜
프론트엔드 연동, CopilotKit, 실시간 이벤트 스트리밍
연결의 표준화
에이전트 ↔ 도구, 에이전트 ↔ 에이전트, 에이전트 ↔ 사용자
AG-UI
Agent ↔ Frontend · 이벤트 스트리밍 · 실시간 동기화
AG-UI
에이전트 백엔드의 동작을 프론트엔드에 실시간 전달하는 표준 — SSE(대표 전송) 위의 typed 이벤트
Agent ↔ Frontend 이벤트 스트리밍
에이전트의 모든 동작을 typed JSON events로 프론트엔드에 실시간 전달합니다.
- SSE(대표) — 전송 무관(WebSocket·webhook 가능)
- TEXT_MESSAGE · TOOL_CALL · STATE_DELTA · LIFECYCLE
- CopilotKit 개발 — 오픈 표준
- 프레임워크 무관 — Strands · LangGraph · CrewAI
텍스트만 흘리는 채팅 API와 달리 도구 호출과 상태 변경까지 이벤트로 전달합니다 — UI가 에이전트를 완전히 시각화합니다.
AG-UI 개요
에이전트 백엔드의 모든 동작을 프론트엔드에 실시간으로 전달하는 이벤트 프로토콜
AG-UI = Agent-User Interaction Protocol. CopilotKit이 개발한 오픈 표준으로, SSE를 통해 typed JSON events를 스트리밍합니다. 프레임워크 무관 — Strands, LangGraph, CrewAI 모두 지원.
-
1
에이전트 실행
- 백엔드에서 에이전트가 작업 수행
- Strands Agent, LangGraph 등 어떤 프레임워크든
- 실행 중 이벤트를 AG-UI 포맷으로 방출
-
2
SSE 스트리밍
- Server-Sent Events로 이벤트 전송
- messages, tool_calls, state_patches, lifecycle
- 단일 HTTP 연결로 모든 이벤트 전달
-
3
프론트엔드 수신
- React/Vue/Svelte 등 프론트엔드가 이벤트 소비
- 채팅 UI 실시간 업데이트
- 상태 동기화 — 에이전트 상태를 UI에 반영
AG-UI 이벤트 유형
에이전트 동작의 모든 단면을 이벤트로 표현
| 이벤트 | 역할 | 예시 |
|---|---|---|
| TEXT_MESSAGE_* | 텍스트 메시지 스트리밍 | start → content(토큰) → end |
| TOOL_CALL_* | 도구 호출과 결과 | start → args → end (실행 결과) |
| STATE_DELTA | 에이전트 상태 변경 | JSON Patch로 UI 상태 동기화 |
| LIFECYCLE | 실행 생명주기 | RUN_STARTED → RUN_FINISHED |
| CUSTOM | 애플리케이션 정의 이벤트 | 진행률, 알림, UI 명령 등 |
메시지·도구·상태·생명주기 네 계열이 표준 이벤트로 정의되고, 그 밖의 요구는 CUSTOM 이벤트로 확장합니다.
AG-UI vs 일반 채팅 API
단순 텍스트 스트리밍을 넘어, 에이전트의 전체 동작을 UI와 동기화
일반 채팅 API
- 텍스트 토큰만 스트리밍
- 도구 호출 시 UI가 알 수 없음
- 에이전트 내부 상태 비가시
- 프론트엔드가 수동으로 상태 추적
기본 LLM API(Converse, Chat Completions)는 텍스트만 스트리밍합니다. 에이전트가 무엇을 하고 있는지 프론트엔드가 알 수 없습니다.
AG-UI
- 텍스트 + 도구 호출 + 상태 전부 스트리밍
- 도구 실행 중 UI에 실시간 표시
- STATE_DELTA로 공유 상태 자동 동기화
- 에이전트와 UI가 같은 상태를 공유
AG-UI는 에이전트의 모든 동작(생각, 도구 호출, 상태 변경)을 이벤트로 전달합니다. 프론트엔드가 에이전트를 완전히 시각화합니다.
일반 채팅 API는 텍스트 토큰만 보내지만, AG-UI는 STATE_DELTA로 에이전트와 UI가 같은 상태를 공유하게 만듭니다.
선택 가이드
언제 어떤 프로토콜을 — 의사 결정 흐름
선택 가이드
연결 대상이 무엇인지에 따라 프로토콜을 고르고 조합하는 판단 기준
무엇을 연결하는가가 프로토콜을 결정
도구를 연결하면 MCP, 에이전트에 위임하면 A2A, 사용자 앞에 노출하면 AG-UI입니다.
- 의사 결정 흐름 — 연결 대상 3가지 질문
- 조합 패턴 — 기반(MCP) · 확장(A2A) · 표면(AG-UI)
- 도입 순서 — MCP → A2A → AG-UI
세 프로토콜을 모두 갖출 필요는 없습니다 — 연결하려는 대상이 무엇인지가 유일한 판단 기준입니다.
의사 결정 흐름
무엇을 연결하려는지에 따라 결정되는 프로토콜
-
1
도구/데이터를 연결?
- 외부 API, DB, 파일에 접근해야 하는가?
- → MCP 서버를 만들어 에이전트에 연결
- 가장 먼저, 가장 자주 필요한 프로토콜
-
2
다른 에이전트에 위임?
- 독립 배포된 전문 에이전트에게 작업을 맡기는가?
- 결과를 비동기로 받아도 되는가?
- → A2A로 에이전트 간 태스크 위임
-
3
사용자 UI와 연동?
- 에이전트 동작을 실시간으로 보여줘야 하는가?
- 공유 상태(장바구니, 폼 등)를 동기화해야 하는가?
- → AG-UI로 프론트엔드 이벤트 스트리밍
프로토콜 조합 패턴
실제 프로덕션에서 세 프로토콜이 한 아키텍처에 공존 — 기반(MCP) · 확장(A2A) · 표면(AG-UI)
-
1
MCP (기반)
- 모든 에이전트가 도구를 사용 — 기본 레이어
- Gateway로 중앙 관리 + 인증 + 관측
- 예: 날씨 API, DB 쿼리, 파일 읽기
-
2
A2A (확장)
- 전문 에이전트를 팀처럼 조직
- 오케스트레이터가 specialist에게 위임
- 예: 코드 리뷰어, 보안 스캐너, 번역기
-
3
AG-UI (표면)
- 최종 사용자에게 에이전트를 노출
- 채팅, 대시보드, 코파일럿 UI
- 예: Streamlit + CopilotKit + React
MCP가 기반, A2A가 확장, AG-UI가 표면입니다 — 프로덕션에서는 세 프로토콜이 한 아키텍처 안에서 공존합니다.
도입 순서
모든 것을 한 번에 갖출 필요 없는 단계적 도입 순서
MCP 먼저 → A2A 필요할 때 → AG-UI 사용자 앞에
MCP 없이 A2A를 쓸 이유가 없고, 사용자 UI가 없으면 AG-UI도 불필요합니다. 순서를 지키세요.
- 1. MCP — 도구 연결
- 2. A2A — 에이전트 위임
- 3. AG-UI — 사용자 인터페이스
각 프로토콜의 역할을 구분하면 아키텍처가 명확해집니다.