테크부터 경제, 생활까지. 복잡한 소식을 쉽게 풀어봅니다. 오늘 오전 오픈소스 심층 분석은 GitHub Trending 일간 목록에 다시 오른 ag-ui-protocol/ag-ui, 곧 AG-UI(Agent-User Interaction Protocol)입니다. MCP가 에이전트와 도구를, A2A가 에이전트끼리를 잇는다면, AG-UI는 에이전트 백엔드와 사용자 앞 화면 사이를 잇는 이벤트 기반 프로토콜입니다. 2026년 9월 17일 1.0이 나오면서 처음으로 “사양서”가 생겼고, 지금은 TypeScript 패키지 1.0.4, Python ag-ui-protocol 1.0.0이 그 사양에서 생성된 타입을 씁니다. 이 글은 README 소개가 아니라 1.0 사양이 실제로 무엇을 강제하는지, 레포가 어떻게 짜여 있는지, 그리고 박스에서 Python 서버와 TS 클라이언트를 붙여 인터럽트·재개, 순서 위반, 0.x 호환, 스트림 끊김을 직접 확인한 결과를 실무자 관점으로 정리합니다.

한눈에 보는 기본 정보
| 항목 | 내용 (2026-11-16 KST 확인) |
|---|---|
| 저장소 | github.com/ag-ui-protocol/ag-ui (CopilotKit 팀 주도, 커뮤니티 SDK 다수) |
| 라이선스 | MIT |
| 스타 | 약 1.8만 개(17,983), 오늘 일간 트렌딩 +355 |
| 사양 버전 | AG-UI 1.0 (2026-09-17 공개). docs/spec/1.0/schema.json이 구조의 단일 원천, 정의 98개 |
| TypeScript | @ag-ui/core·client·encoder·proto 1.0.4 (npm, 2026-11-05), create-ag-ui-app 0.0.59 |
| Python | ag-ui-protocol 1.0.0 (PyPI, 2026-09-17), Python 3.9 이상 |
| 릴리스 방식 | 날짜 태그(release/2026-11-13 등)로 통합 패키지를 개별 배포. 최근 사흘 사이에도 LangGraph·Claude Agent SDK 어댑터가 갱신됨 |
| 기본 전송 | HTTP POST + Server-Sent Events. 선택 사항으로 HTTP + Protobuf(길이 접두 프레임) |
AG-UI가 푸는 문제: “에이전트 화면”을 매번 새로 배선하는 일
에이전트를 제품에 넣어 본 팀은 비슷한 코드를 반복해서 씁니다. 토큰 스트리밍, 도구 호출 표시, “이 도구 실행해도 될까요?” 승인 UI, 에이전트가 들고 있는 계획·폼 같은 공유 상태 동기화, 진행 상황 표시, 중간 취소와 재시도까지. 프레임워크마다 스트림 모양이 달라서 LangGraph용 프런트를 Mastra로 옮기면 거의 다시 짜야 합니다.
AG-UI는 이 경계를 약 16종의 표준 이벤트와 하나의 입력 객체(RunAgentInput)로 고정합니다. 앱은 threadId·runId·메시지·상태·프런트엔드 도구 목록·컨텍스트를 POST로 보내고, 에이전트는 RUN_STARTED부터 RUN_FINISHED(또는 RUN_ERROR)까지 이벤트를 흘려 보냅니다. 백엔드가 LangGraph든 Google ADK든 Pydantic AI든, 프런트는 같은 이벤트만 해석하면 됩니다.
이벤트 패밀리 정리
| 패밀리 | 대표 이벤트 | 역할 | 실무 포인트 |
|---|---|---|---|
| 라이프사이클 | RUN_STARTED, RUN_FINISHED, RUN_ERROR, STEP_STARTED/FINISHED |
런의 경계와 단계 | 1.0에서 RUN_FINISHED.outcome(success / interrupt / cancelled)과 토큰 사용량 필드가 추가됨 |
| 텍스트 메시지 | TEXT_MESSAGE_START/CONTENT/END, _CHUNK |
스트리밍 응답 | messageId로 묶임. START 없이 CONTENT가 오면 치명적 오류 |
| 도구 호출 | TOOL_CALL_START/ARGS/END, TOOL_CALL_RESULT |
인자 스트리밍, 결과 전달 | 결과가 문자열뿐 아니라 이미지·문서 같은 콘텐츠 파트 목록도 가능(1.0) |
| 상태 | STATE_SNAPSHOT, STATE_DELTA, MESSAGES_SNAPSHOT |
공유 상태 동기화 | 델타는 RFC 6902 JSON Patch. 적용 실패한 패치는 경고 후 건너뜀 |
| 추론 | REASONING_START … REASONING_ENCRYPTED_VALUE |
모델의 추론 스트림 | 0.x의 THINKING_*를 대체. 암호화된 추론 값은 읽지 않고 보관했다가 되돌려줌 |
| 서브에이전트 | SUBAGENT_STARTED/FINISHED/ERROR, subagentRunId |
위임 작업의 귀속 | 1.0 신설. 소유권·중첩·병렬 규칙이 사양에 있음 |
| 액티비티 | ACTIVITY_SNAPSHOT/DELTA |
구조화된 진행 카드 | 클라이언트 전용 메시지라 에이전트로 되돌아가지 않음 |
| 패스스루 | RAW, CUSTOM |
벤더 확장 | 표준에 자리가 있는 정보(결과·도구 ID 등)를 여기에만 넣으면 안 됨 |
레포 구조: “사양 + 생성된 SDK + 어댑터 공장”
레포는 모노레포(pnpm + Nx)이고, 1.0 이후의 핵심 설계는 스키마가 원천, SDK는 생성물이라는 점입니다. 과거 0.x에서는 동작 규칙이 사실상 TypeScript 클라이언트 코드 안에만 있었고, 그래서 Python·Go 구현이 미묘하게 달랐습니다. 1.0은 이 규칙을 BCP 14(MUST/SHOULD) 문장으로 docs/spec/1.0에 옮겼고, spec/1.0/conformance에 적합성 스트림과 Protobuf 바이트 코퍼스를 둡니다.
| 경로 | 내용 | 읽어야 하는 사람 |
|---|---|---|
docs/spec/1.0/ |
규범 문서(이벤트, 처리 파이프라인, 전송, 버전, 인터럽트–재개, 메타데이터) + schema.json |
SDK·통합 구현자, 리뷰어 |
spec/1.0/ |
스키마, 적합성 스트림, proto-freeze.txt |
새 언어 SDK 작성자 |
sdks/typescript/packages/ |
core(타입·zod 스키마), client(HttpAgent·파이프라인), encoder, proto, cli |
프런트·Node 개발자 |
sdks/python/ |
ag_ui.core(생성 모델은 _generated/models.py), ag_ui.encoder |
Python 에이전트 서버 개발자 |
sdks/dotnet, sdks/community/ |
.NET, 그리고 Go·Java·Kotlin·Rust·Ruby·Dart·Swift·C++ 커뮤니티 SDK | 해당 언어 팀(성숙도 개별 확인 필요) |
integrations/ |
LangGraph, CrewAI, ADK, Mastra, Pydantic AI, Agno, LlamaIndex, AG2, Strands, Claude Agent SDK, Vercel AI SDK 등 23개 디렉터리 | 특정 프레임워크 사용자 |
middlewares/ |
A2A, A2UI, MCP, MCP Apps, 이벤트 스로틀, 스타터 | 스트림 변환이 필요한 플랫폼 팀 |
apps/dojo |
기능별 50~200줄 예제를 모아 보는 데모 뷰어 | 도입 검토자 |
DEPRECATIONS.md |
0.x 호환 shim 목록과 만료일(1.0 공개일로부터 12개월, 2027-09-17) | 0.x 통합을 운영 중인 팀 |
1.0에서 실제로 바뀐 것: 동작 규칙이 생겼다

처리 파이프라인은 전송 디코딩 → 호환 경계(구형 모양 번역) → 미들웨어 → 강제(enforcement) → 적용 순서입니다. 여기서 1.0의 가장 중요한 원칙이 나옵니다. “모르는 것은 오류가 아니고, 알려진 필드의 잘못된 값은 오류다.” 새 버전 상대가 보낸 낯선 이벤트나 필드는 런을 깨뜨리면 안 되고(경고 후 제거), messageId에 숫자가 들어오는 식의 결함은 고치거나 무시하지 말고 런을 실패시켜야 합니다. 프로토콜이 자라는 방식과 버그를 분리한 셈입니다.
| 변경 | 0.x | 1.0 | 마이그레이션 영향 |
|---|---|---|---|
| 사양 | 타입만 있고 동작은 TS 클라이언트 코드에 | 규범 문서 + 스키마에서 SDK 생성 | 언어별 구현 차이가 줄어듦 |
| 런 종료 | 성공/에러만 | outcome: success / interrupt / cancelled |
승인 대기를 “성공”으로 보고하면 비적합 |
| 추론 | THINKING_* |
REASONING_* + 암호화 값 |
클라이언트가 자동 번역(경고 출력) |
| null 처리 | 선택 필드에 null 흔함 |
“없으면 아예 생략” | Python 모델은 기본으로 생략. 직접 JSON을 만들면 주의 |
| 버전 협상 | 없음 | 입력과 RUN_STARTED에 각자 protocolVersion |
Python은 자동으로 넣어 주지 않음. PROTOCOL_VERSION 상수를 명시 |
| 바이너리 전송 | 비공식 | HTTP + Protobuf, 4바이트 빅엔디언 길이 프레임 | 바이트 코퍼스로 인코더 간 일치 검증 |
| 도구 결과 | 문자열 | 문자열 또는 콘텐츠 파트 목록 | InputContent → ContentPart 등 이름 변경(별칭 유지) |
| 서브에이전트 | 없음 | subagentRunId + 전용 이벤트 |
구형 상대에게는 무손실로 평탄화 |
Python 쪽에서 버전 선언은 이렇게 명시해야 합니다. SDK 문서도 “기본값을 넣으면 그 버전을 말하지 않는 생산자까지 버전을 사칭하게 된다”며 일부러 자동화하지 않았다고 설명합니다.
from ag_ui.core import PROTOCOL_VERSION, RunStartedEvent
RunStartedEvent(
thread_id=inp.thread_id,
run_id=inp.run_id,
protocol_version=PROTOCOL_VERSION, # "1.0"
)
인터럽트–재개: 연결을 붙잡지 않는 사람 승인

AG-UI에는 실행 중인 런에 앱이 끼어드는 채널이 없습니다. 그래서 사람 승인이 필요하면 런은 기다리지 않고 끝납니다. RUN_FINISHED의 outcome을 interrupt로 하고, 무엇을 기다리는지 Interrupt 객체(고유 id, 자유 문자열 reason, 사람용 message, 관련 toolCallId, 답의 모양을 설명하는 responseSchema, 만료 expiresAt)로 남깁니다. 다음 런은 같은 threadId로 시작하면서 입력의 resume 목록에 답을 싣습니다.
핵심 규칙은 두 가지입니다. 첫째, resume 목록은 열린 인터럽트를 전부 덮어야 하고, 빠뜨린 것은 “포기”로 간주되지 않습니다. 포기하려면 명시적으로 상태를 적어야 합니다(1.0.0 Python 모델의 상태값은 resolved/cancelled). 둘째, 이 검사는 소비자(앱)의 의무이며 보내기 전에 거절해야 합니다. 생산자는 이전 런을 기억하지 않아도 적합합니다. 서버를 무상태로 수평 확장하기 쉬운 대신, 승인 상태의 진실은 앱이 쥐게 됩니다.
또 하나 구분해야 할 경로가 있습니다. 프런트엔드 도구를 호출하고 멈춘 런은 인터럽트가 아니라 성공으로 끝나고, 답하지 않은 호출은 pendingToolCallIds로 표시하며 답은 다음 입력의 메시지로 갑니다. “승인 요청”과 “브라우저에서 실행할 도구”를 같은 메커니즘으로 섞으면 사양 위반이 됩니다.
박스 실측: Python 1.0.0 서버 ↔ TS 클라이언트 1.0.4
LLM 없이 프로토콜 자체를 검증하려고, FastAPI + ag-ui-protocol 1.0.0으로 시나리오별 엔드포인트를 만들고 Node 24에서 @ag-ui/client 1.0.4의 HttpAgent로 붙였습니다(2026-11-16 KST, 로컬 루프백).
# 서버 (Python 3.13 venv)
pip install ag-ui-protocol==1.0.0 fastapi uvicorn
uvicorn server:app --port 8765
# 클라이언트 (Node 24)
npm i @ag-ui/client@1.0.4 @ag-ui/core@1.0.4 rxjs
node client.mjs
서버의 핵심은 이벤트 모델을 EventEncoder로 SSE 한 줄씩 내보내는 것뿐입니다.
enc = EventEncoder(accept=req.headers.get("accept"))
async def gen():
yield enc.encode(RunStartedEvent(thread_id=t, run_id=r, protocol_version=PROTOCOL_VERSION))
yield enc.encode(StateSnapshotEvent(snapshot={"plan": {"steps": []}}))
yield enc.encode(TextMessageStartEvent(message_id="m1", role="assistant"))
yield enc.encode(TextMessageContentEvent(message_id="m1", delta="배포 계획을 세웠습니다."))
yield enc.encode(TextMessageEndEvent(message_id="m1"))
yield enc.encode(StateDeltaEvent(delta=[{"op": "add", "path": "/plan/steps/0",
"value": {"name": "migrate", "status": "pending"}}]))
yield enc.encode(RunFinishedEvent(thread_id=t, run_id=r,
outcome=RunFinishedInterruptOutcome(interrupts=[
Interrupt(id="int-1", reason="approval", message="users 테이블 삭제 승인?", tool_call_id="tc1")])))
return StreamingResponse(gen(), media_type=enc.get_content_type())
// 클라이언트: 인터럽트 후 resume 누락 → 보내기 전 거절
const agent = new HttpAgent({ url: "http://127.0.0.1:8765/agent/interrupt" });
await agent.runAgent({}, { onEvent: ({ event }) => log(event.type) });
await agent.runAgent({ resume: [] }); // throws
await agent.runAgent({ resume: [{ interruptId: "int-1", status: "resolved", payload: { approved: false } }] });

| 시나리오 | 결과 | 해석 |
|---|---|---|
| 정상 런 (스냅샷 + 텍스트 + 패치) | 이벤트 10개, 약 84ms. 상태가 {"plan":{"steps":[{"name":"migrate","status":"pending"}]}}로 반영 |
스냅샷→델타 순서가 그대로 적용됨. 클라이언트는 protocolVersion: "1.0"을 입력에 자동 기입 |
| 존재하지 않는 경로를 바꾸는 패치 | 경고(“Failed to apply state patch”) 후 건너뛰고 런은 계속 | 사양의 “적용 실패 패치는 경고 후 skip”과 일치. 상태가 조용히 어긋날 수 있으니 경고를 모니터링하거나 스냅샷으로 재동기화 |
| 인터럽트 런 | 이벤트 13개, 약 37ms. 에이전트 객체에 pendingInterrupts 보관 |
도구 호출 drop_table이 메시지에 남고 런은 닫힘 |
resume: []로 재개 |
0.2ms 만에 예외: “Thread has 1 pending interrupt(s) not addressed by resume: int-1”. 서버 로그에 요청 없음 | 커버리지 검사가 “보내기 전” 소비자 쪽에서 이뤄짐 |
| 올바른 resume | 요청 본문에 resume:[{"interruptId":"int-1","status":"resolved",...}], 이전 상태·메시지도 함께 전송 |
스레드·상태 연속성은 입력에 실려 가므로 서버는 무상태로 둘 수 있음 |
START 없는 TEXT_MESSAGE_CONTENT |
3ms 만에 AGUIError “No active text message found with ID ‘m-x'” | 순서 위반은 치명적. 어댑터 버그가 화면에 조용히 섞이지 않음 |
0.x 생산자 흉내 (THINKING_*, outcome:null, 벤더 이벤트) |
REASONING_*로 번역돼 reasoning 메시지 생성, 경고 7건, 벤더 이벤트는 “Dropping unrecognised event” | 구형 백엔드는 당장 깨지지 않지만 shim 만료(2027-09-17) 전까지 옮겨야 함. SUPPRESS_TRANSFORMATION_WARNINGS=true는 경고만 끔 |
| 종료 이벤트 없이 끊긴 스트림 | runAgent()가 예외 없이 resolve, onRunFailed 미호출, result 없음(빈 assistant 메시지만 남음) |
사양은 “합성 RUN_FINISHED 금지, 성공 보고 금지”만 정하고 표면화 방식은 구현에 맡김. 앱에서 종료 이벤트 수신 여부를 직접 확인해야 함 |
| Accept에 protobuf 포함 | Python EventEncoder는 SSE로만 응답 |
바이너리 전송이 필요하면 TS @ag-ui/encoder/proto 쪽을 쓰거나 직접 구현. 클라이언트는 SSE 폴백이 의무라 호환은 문제없음 |
실측에서 하나 더 배운 점: 서버가 런마다 같은 messageId(“m1”)를 재사용하자 두 번째 런의 텍스트가 같은 메시지에 이어 붙었습니다. 메시지 ID는 스레드 전체에서 고유해야 한다는 걸 몸으로 확인한 셈이니, 어댑터를 직접 쓸 때 UUID를 쓰는 게 안전합니다.
빠르게 시작하는 세 가지 경로
# 1) 스캐폴드: 프레임워크를 골라 앱+에이전트 템플릿 생성
npx create-ag-ui-app my-agent-app
# 2) Dojo를 로컬에서 (pnpm 필수)
git clone https://github.com/ag-ui-protocol/ag-ui && cd ag-ui
pnpm i
pnpm build --projects=demo-viewer
cd apps/dojo && pnpm dev
# 3) 기존 Python 에이전트에 직접 붙이기
pip install ag-ui-protocol
# FastAPI 등에서 POST 본문을 RunAgentInput.model_validate()로 검증하고
# EventEncoder로 SSE를 흘려 보내면 끝
LangGraph·ADK·Mastra 같은 프레임워크를 이미 쓰고 있다면 직접 이벤트를 만들기보다 integrations/의 어댑터부터 확인하는 편이 낫습니다. 다만 어댑터마다 버전 축이 따로 놀아서(예: @ag-ui/langgraph 0.0.46은 2026-11-13 배포에서 @ag-ui/client 1.0 이상을 요구하도록 바뀜), 조합을 잠그지 않으면 피어 의존성 충돌을 겪기 쉽습니다.
비슷한 도구·규격과 비교
| 구분 | AG-UI | MCP | A2A | Vercel AI SDK UI 스트림 | A2UI / MCP Apps |
|---|---|---|---|---|---|
| 잇는 대상 | 에이전트 ↔ 사용자 앱 | 에이전트(모델) ↔ 도구·데이터 | 에이전트 ↔ 에이전트 | 서버 함수 ↔ React 등 UI 훅 | 에이전트가 그릴 UI의 선언적 기술 |
| 성격 | 이벤트 스트림 프로토콜 + 사양 | JSON-RPC 기반 프로토콜 | 작업(task) 중심 프로토콜 | 특정 SDK의 스트림 포맷 | UI 페이로드 규격 |
| 상태 동기화 | 스냅샷 + JSON Patch, 양방향 루프 | 범위 밖 | 작업 상태/아티팩트 | 메시지·데이터 파트 중심 | UI 트리 갱신 |
| 사람 승인 | interrupt outcome + resume | elicitation 등 별도 기능 | input-required 같은 작업 상태 | 도구 승인 패턴(SDK 의존) | 해당 없음(표현 계층) |
| 관계 | A2A·MCP·A2UI·MCP Apps를 미들웨어로 흡수 | AG-UI의 MCP 미들웨어로 연결 | AG-UI A2A 미들웨어로 연결 | AG-UI 통합(vercel-ai-sdk) 존재 |
AG-UI 위에서 운반되는 페이로드 |
| 강점 | 프레임워크 중립, 다언어 SDK, 적합성 코퍼스 | 생태계 최대 | 조직 간 에이전트 협업 | Next.js와의 밀착도 | 생성형 UI 표준화 |
요점은 “경쟁”보다 “층”입니다. AG-UI는 MCP나 A2A를 대체하지 않고, 그 결과를 사람이 보는 화면으로 운반하는 마지막 구간을 맡습니다. 실제로 경쟁 관계에 가까운 것은 각 프레임워크의 자체 스트리밍 포맷과 Vercel AI SDK 같은 SDK 종속 포맷이며, 프레임워크를 하나로 고정할 수 있는 팀이라면 그쪽이 더 단순할 수 있습니다.
트레이드오프: 언제 쓰고 언제 미룰까
| 상황 | 판단 | 이유 |
|---|---|---|
| 백엔드 프레임워크가 둘 이상이거나 바뀔 예정 | 적극 도입 | 프런트를 한 번만 짜고 어댑터만 갈아 끼움 |
| CopilotKit 기반 프런트 | 사실상 기본값 | 1st party 클라이언트이며 Dojo 예제가 이 조합 중심 |
| 사람 승인·공유 상태가 핵심인 워크플로 | 도입 가치 큼 | interrupt–resume과 스냅샷/패치가 규칙으로 정해져 있음 |
| Next.js + Vercel AI SDK 단일 스택, 단순 채팅 | 보류 가능 | 추가 계층 대비 이득이 작음 |
| Go·Rust·Swift 등 커뮤니티 SDK가 필요 | 개별 검증 후 | 1st party는 TS·Python·.NET. 커뮤니티 SDK는 1.0 사양 반영 시점이 다를 수 있음 |
| 대역폭·지연이 민감한 고빈도 스트림 | Protobuf 바인딩 검토 | 다만 Python 인코더 1.0.0은 SSE만 출력. 이벤트 스로틀 미들웨어도 선택지 |
보안·운영 주의점
| 위험 | 사양/관찰 | 권장 대응 |
|---|---|---|
| 도구 인자 주입 | 사양: 도구 인자는 모델이 만든 신뢰할 수 없는 입력(MUST) | 스키마 검증, 셸·쿼리·마크업에 그대로 넣지 않기 |
| 승인 위조 | 사양: 사용자가 승인하지 않은 호출을 승인된 것처럼 표시 금지 | 부작용 있는 도구는 interrupt로 받고, 승인 기록을 앱이 보관 |
| 상태를 통한 원격 쓰기 | 사양: 상태 이벤트는 앱 상태에 대한 원격 쓰기 | 렌더링·실행 전에 상태 값 검증, HTML로 바로 렌더 금지 |
| 도구 결과 속 지시문 | 사양: 결과 텍스트를 프로토콜이나 명령으로 취급 금지 | 결과는 데이터로만 표시, 프롬프트 인젝션 방어 별도 |
| 인증 부재 | 프로토콜은 인증을 규정하지 않음. 사전 거절은 HTTP 에러 상태로 | 엔드포인트 앞단에 인증·레이트 리밋, forwardedProps로 비밀 전달 금지 |
| 스트림 끊김 | 실측: 클라이언트 1.0.4는 예외 없이 resolve | 종료 이벤트 미수신을 실패로 처리하는 래퍼 추가 |
| 조용한 패치 실패 | 실측: 경고 후 skip | 경고 수집, 주기적 STATE_SNAPSHOT으로 재동기화 |
| SSE 버퍼 | 클라이언트 코드상 단일 미완성 이벤트 버퍼 상한 10MB | 큰 산출물은 URL 참조나 분할 전송 |
라이선스는 MIT라 상업적 사용·수정·재배포에 제약이 거의 없습니다. 취약점은 공개 이슈 대신 security@copilotkit.ai로 제보하도록 안내돼 있고, 48시간 내 확인·30일 내 수정 목표를 밝히고 있습니다. 프로젝트의 무게중심이 CopilotKit에 있다는 점은 장점(빠른 개발, 1st party 클라이언트)이자 거버넌스 측면의 고려 사항이므로, 장기 의존 전에 사양 문서와 적합성 코퍼스를 기준으로 삼는 게 좋습니다.
정리
AG-UI 1.0의 의미는 이벤트 종류가 늘었다는 데보다, “무엇이 오류이고 무엇이 성장인지”를 처음으로 문서로 못 박았다는 데 있습니다. 실측에서도 순서 위반은 즉시 실패, 모르는 이벤트는 경고 후 제거, 구형 모양은 번역, resume 누락은 요청 전에 거절로 사양대로 움직였습니다. 남는 숙제는 끊긴 스트림을 앱이 직접 실패로 처리해야 한다는 점, Python 쪽은 아직 SSE만 내보낸다는 점, 어댑터 버전이 따로 움직인다는 점입니다. 에이전트 화면을 여러 백엔드에 걸쳐 오래 운영할 팀이라면, 지금이 0.x 스타일 코드를 1.0 규칙으로 옮기기 좋은 시점입니다.