들어가며: 에이전트 대화가 '텍스트 벽'에서 벗어나는 순간
지금까지 AI 에이전트와의 대화는 대부분 이랬어요.
User: "3월 발리 패키지 찾아줘." Agent: (숙소, 항공, 날짜가 줄줄이 적힌 텍스트 6개) User: "조식 포함된 5박짜리로." Agent: "링크 여기요. 예약은 운영사 사이트에서 하세요."
여행 계획은 세워주는데, 결과물은 죄다 텍스트 덩어리죠. 선택 가능한 리스트, 지도, 날짜 피커 같은 걸 대화 안에서 렌더링할 표준 방법이 없었어요.
여기서 등장하는 개념이 Generative UI입니다. 에이전트가 런타임에 요청에 맞는 인터페이스를 직접 조립해서 사용자에게 인터랙티브한 경험을 주는 레이어죠. 구현에는 두 가지 축이 필요해요.
- UI를 기술하는 방법 (선언적 스키마)
- 에이전트와 앱을 연결해 UI를 렌더링하는 에이전틱 스택
이 글에서는 그 표준으로 떠오르는 A2UI와 CopilotKit을 실제 코드로 뜯어볼게요. 근거자료는 Google Developers Blog 원문에서 확인하실 수 있습니다.
![]()
A2UI 스펙트럼: 통제형 vs 개방형
Generative UI는 '얼마나 자유롭게 UI를 만들게 할 것인가'의 스펙트럼이에요.
- 통제형(Controlled): 컴포넌트를 미리 다 만들어두고, 에이전트는 어떤 걸 렌더링할지와 데이터만 고릅니다. 브랜드 안전성은 최고, 대신 사용자 의도에 맞춘 깊은 커스터마이징은 어려워요.
- 개방형(Open-ended): 에이전트가 HTML/JS/Dart 원본 코드를 뱉고 샌드박스 iframe에서 렌더링. 예상 못 한 요청도 커버하지만, 디자인 시스템에서 벗어나고 모델이 쓴 코드를 실행하는 리스크가 있죠.
A2UI는 이 스펙트럼 전체에 참여합니다. Typesafe의 Jev 같은 결정 모델과도, 개방형 코드 생성과도 엮일 수 있어요. 가장 인기 있는 건 역시 선언적 모드 — 에이전트가 미리 선언된 컴포넌트와 함수를 조립하는 방식입니다.
A2UI의 핵심 가치는 **프레임워크 불가지론(framework-agnostic)**이에요. 로컬이든 원격이든 에이전트가 공통 언어로 기존 컴포넌트 카탈로그를 조립할 수 있죠. 프론트엔드 개발자는 빌딩 블록을 한 번만 배포하면, 에이전트가 요청마다 조합합니다.
Basic Catalog: 18개 프리미티브
기본 카탈로그는 레이아웃/표시/입력/컨테이너에 걸친 18개의 범용 프리미티브를 제공해요. 이 18개로 완전히 다른 인터페이스를 조립할 수 있습니다. 다만 의도적으로 최소한이라, 실무 앱은 대부분 커스텀 카탈로그를 정의해요. 커스텀 컴포넌트는 프론트엔드가 이미 렌더링하는 거라면 뭐든 가능합니다 — 에이전트가 좌표를 채우면 렌더러가 경로를 그리는 라이브 지도 같은 것도요.
CopilotKit + AG-UI 연결 흐름
CopilotKit은 AG-UI(Agent-User Interaction Protocol) 위에 올라갑니다. A2UI 페이로드를 지원하고, 여러 에이전틱 백엔드용 Agent SDK를 제공하죠.
흐름은 이래요.
- 에이전트가 A2UI 연산(operation)을 emit
- AG-UI가 이를 타입드 이벤트로 클라이언트에 전달
- 사용자가 액션을 취하면 같은 스트림으로 값이 되돌아감
Google ADK, LangChain, Mastra, Strands 모두 AG-UI 호환이라, 어느 백엔드든 셋업은 동일합니다.
1) 에이전트를 AG-UI 엔드포인트로 노출 (Google ADK 예시)
from fastapi import FastAPI
from google.adk.agents import LlmAgent
from ag_ui_adk import ADKAgent, add_adk_fastapi_endpoint
root_agent = LlmAgent(
name="flight_agent",
model="gemini-3.8-flash",
# 에이전트 프롬프트: 결과 표시 시 generate_a2ui 호출 지시
instruction="Help users find and book flights. Call generate_a2ui to show results.",
)
adk_agent = ADKAgent(
adk_agent=root_agent,
app_name="flights",
user_id="demo_user",
use_in_memory_services=True,
)
app = FastAPI()
# FastAPI 앱에 AG-UI 엔드포인트 등록
add_adk_fastapi_endpoint(app, adk_agent, path="/")
앱 쪽에서는 이 엔드포인트를 /api/copilotkit의 CopilotKit 런타임에 등록하면 끝. A2UI 전용 설정은 필요 없어요.
2) 클라이언트에서 카탈로그 정의 (React + Zod)
A2UI는 클라이언트에서 켜집니다. 컴포넌트가 이미 있는 곳이니까요. 에이전트가 그릴 수 있는 걸 정의하고, 각 정의를 렌더러에 매핑해서 카탈로그를 CopilotKit provider에 넘기면 됩니다.
import { CopilotKit, CopilotChat } from '@copilotkit/react-core/v2';
import {
createCatalog,
type CatalogDefinitions,
type CatalogRenderers,
} from '@copilotkit/a2ui-renderer';
import { z } from 'zod';
// 에이전트가 사용할 수 있는 컴포넌트 스키마 정의
const catalogDefinitions = {
FlightCard: {
description: 'A flight result with airline, times, and stops.',
props: z.object({
airline: z.string(),
departs: z.string(),
arrives: z.string(),
stops: z.number(),
}),
},
} satisfies CatalogDefinitions;
const catalogRenderers = {
FlightCard: MyFlightCard, // 실제 React 컴포넌트
} satisfies CatalogRenderers;
// 카탈로그 생성 (Basic Catalog 포함)
const catalog = createCatalog(catalogDefinitions, catalogRenderers, {
catalogId: 'flight-catalog',
includeBasicCatalog: true,
});
포인트는 description이 에이전트 프롬프트로 들어간다는 것. 모델이 일반 카드 대신 FlightCard를 언제 써야 할지 판단하는 근거가 됩니다. Zod 스키마는 되돌아오는 props를 검증하죠.
A2UI 설정은 서버에서 미리 해둘 수도 있고, 클라이언트에서 요청과 함께 동적으로 보낼 수도 있어요. 위 ADK 예시는 동적 설정이라 generate_a2ui를 정의 없이 쓴 겁니다.
CopilotKit 경로가 아니라 @ag-ui/client로 이벤트 스트림을 직접 소비하고 A2UI 연산을 @a2ui/react, Flutter, Lit, Angular 렌더러에 넘길 수도 있습니다.

주의사항: 원샷 UI의 함정과 양방향 흐름
대부분의 에이전트 생성 UI는 **원샷(one-shot)**이에요. 에이전트가 뭔가 그리고, 사용자가 읽고, 뭔가 바뀌는 순간 낡아버리죠.
A2UI 서피스는 **양방향(bi-directional)**이고 컴포넌트가 리액티브해서 멀티스텝 플로우가 가능합니다. 사용자가 인터페이스에서 취하는 모든 액션(날짜 선택, 항공편 선택, 탑승객 정보 입력)이 같은 스트림으로 되돌아가고, 에이전트가 그 값으로 서피스를 다시 emit해요.
라운드트립을 성립시키는 두 가지 장치:
- 데이터 경로에 바인딩된 입력
- 어떤 경로를 되돌려 보낼지 지정한 액션을 가진 버튼
{ "id": "cabin", "component": "ChoicePicker", "variant": "mutuallyExclusive",
"options": [ { "label": "Economy", "value": "eco" },
{ "label": "Business", "value": "biz" } ],
"value": { "path": "/booking/cabin" } },
{ "id": "confirm", "component": "Button", "child": "confirm_label",
"action": { "event": { "name": "confirmBooking",
"context": { "cabin": { "path": "/booking/cabin" },
"email": { "path": "/booking/email" } } } } }
검증은 클라이언트에서 돌아요. 잘못된 이메일은 모델 호출 없이 인라인 에러로 표시되고, 버튼이 발화하기 전엔 아무것도 에이전트에 도달하지 않습니다. 그리고 클라이언트가 바인딩된 값을 보내면 에이전트가 같은 surfaceId에 다시 emit하죠. 이렇게 하나의 서피스에서 항공편 검색 → 결과 → 탑승객 정보 → 확정까지 전 과정이 이어집니다.
실무에서 주의할 점
- 카탈로그를 너무 넓히지 마세요. Basic Catalog 18개를 다 열어두면 모델이 엉뚱한 프리미티브를 고르기 쉬워요. 도메인에 필요한 컴포넌트만 노출하는 게 정확도를 높입니다.
description품질이 곧 성능입니다. 모델은 description을 보고 컴포넌트를 고르므로, 애매한 설명은 잘못된 렌더링으로 이어져요.- 개방형 모드(HTML/JS 생성)는 샌드박스 필수. 모델이 쓴 코드를 실행하는 구조라 CSP와 iframe 격리를 반드시 점검하세요.
- 국내 SI 환경에서는 사내 디자인 시스템 컴포넌트를 카탈로그로 감싸는 작업이 선행되어야 합니다. 기존 컴포넌트 재사용이 A2UI의 최대 장점이니, 처음부터 새로 만들지 마세요.

마무리: 한 번 배포하고, 계속 조립하세요
A2UI + CopilotKit 조합의 핵심은 **"프론트엔드 개발자가 빌딩 블록을 한 번 배포하면, 에이전트가 요청마다 조립한다"**는 겁니다. 스타터 앱은 한 줄로 생성돼요.
npx copilotkit@latest create --name my-app --framework a2ui
CopilotKit Dojo에는 실행 가능한 A2UI 데모가 있습니다 — 고정 서버 사이드 스키마, 커스텀 카탈로그 대비 동적 스키마, 그리고 첫 렌더가 실패했다가 유효한 렌더로 스스로 치유되는 에러 복구 예제까지요.
다음 단계 학습 방향
- A2UI 스펙 문서를 읽고 선언적 메시지 포맷을 익히기
- AG-UI 프로토콜의 이벤트 타입 이해 (스트림 설계의 기반)
- 커스텀 카탈로그 설계 — 도메인 컴포넌트를 Zod 스키마로 감싸는 연습
- 에러 복구 패턴 — 잘못된 렌더를 모델이 스스로 고치는 루프 설계
함께 보면 좋은 글
- Spotify는 왜 베이지안 A/B 테스트를 도입하지 않았을까? (실무자 관점 완전 분석) — 에이전트 UI의 실험 설계를 고민한다면 반드시 읽어볼 것.
- NVIDIA CUDA 13.3 드디어 공개 Tile C++, Python 1.0, CompileIQ 오토튜닝까지 핵심 요약 — 에이전트 백엔드의 성능 레이어를 이해하고 싶다면.