diff --git a/docs-taxonomy.yml b/docs-taxonomy.yml index b07bd012..4fa9b120 100644 --- a/docs-taxonomy.yml +++ b/docs-taxonomy.yml @@ -121,6 +121,13 @@ verification_statuses: [verified, needs-review] required_source_host: learn.microsoft.com official_source_hosts: - learn.microsoft.com + - www.copilotkit.ai + - docs.copilotkit.ai + - docs.ag-ui.com + - dojo.ag-ui.com + - a2ui.org + - generativeui.github.io + - blog.google - openjdk.org - kubernetes.io - www.cncf.io diff --git a/docs/services/application-development/agentic-app-genui/adoption/index.md b/docs/services/application-development/agentic-app-genui/adoption/index.md new file mode 100644 index 00000000..a2804a34 --- /dev/null +++ b/docs/services/application-development/agentic-app-genui/adoption/index.md @@ -0,0 +1,228 @@ +--- +title: Generative UI 도입 아키텍처와 평가 계획 +description: UI 제안과 업무 실행을 분리하고 카탈로그·권한·호환성·지연·접근성을 검증하는 단계적 도입 방안을 제안합니다. +document_type: research +topic_order: 4 +services: [application-development] +technologies: [mcp] +tags: [design, evaluate, ai-agents] +status: current +verification_status: verified +published_at: 2026-09-21 +sources_checked_at: 2026-09-22 +official_sources: + - title: A2UI - A Protocol for Agent-Driven Interfaces + url: https://a2ui.org/ + - title: MCP Apps + url: https://modelcontextprotocol.io/extensions/apps/overview + - title: AG-UI Protocol + url: https://docs.copilotkit.ai/agentic-protocols/ag-ui + - title: AG-UI Integration with Agent Framework + url: https://learn.microsoft.com/agent-framework/integrations/by-component/ui/ag-ui/ + - title: MCP Apps Compatibility with AG-UI + url: https://learn.microsoft.com/agent-framework/integrations/by-component/ui/ag-ui/mcp-apps +--- + +# Generative UI 도입 아키텍처와 평가 계획 + +**기준일: 2026-09-21. Screenshot 확인일: 2026-09-22.** 아래 내용은 +[패턴 비교](../patterns/index.md), +[프로토콜 분석](../protocols/index.md), [Google 연구와 A2UI](../google-a2ui/index.md)를 +바탕으로 한 **설계 권고와 향후 실험 계획**이다. 구현·성능·보안 적합성을 +실증한 결과가 아니다. + +## 질문 + +에이전트가 화면을 제안하면서도 사용자 통제, 브랜드 일관성, 업무 데이터의 +정확성과 프런트엔드 교체 가능성을 유지하려면 무엇을 애플리케이션에 남겨야 하는가? + +## 권장 책임 분리 + +![Controlled 컴포넌트와 A2UI 렌더러, 선택적 MCP Apps를 가진 프런트엔드 아래에서 에이전트의 UI 제안과 서버의 권한 검사를 분리하는 참조 아키텍처](../images/adoption-reference-architecture.svg) + +*그림 5. 이 리서치의 설계 제안. AG-UI·A2UI·MCP Apps를 모두 채택해야 +한다는 요구사항은 아니며, 업무 실행 게이트는 특정 프로토콜 기능이 아니다.* + +| 책임 | 소유 주체 | 계약 | +|---|---|---| +| 사용자 의도 해석과 UI 제안 | 에이전트·오케스트레이터 | 사용 가능한 도구, 카탈로그와 출력 형식 | +| 렌더링·테마·접근성 | 프런트엔드·디자인 시스템 | 버전이 명시된 컴포넌트, 데이터 바인딩, 액션 | +| 인증·인가·입력 검증 | 서버의 업무 실행 계층 | 사용자 권한, 허용 액션, 매개변수 스키마 | +| 가격·재고·주문 등 사실 | 도메인 서비스 | 권위 있는 조회·변경 API | +| 이벤트 전달·상태 동기화 | 프로토콜 어댑터 | 이벤트 순서, 실행·도구 호출 식별자, 재연결 처리 | +| 평가·관측 | 애플리케이션 운영 계층 | 상관관계 ID, 지연·비용·실패·복구 측정 | + +근거가 되는 공식 기능은 제한적이다. [A2UI][a2ui]는 선언적 UI와 클라이언트 +렌더링을, [AG-UI][agui]는 이벤트와 공유 상태를, [MCP Apps][mcp-apps]는 +호스트 내 UI와 도구 상호작용을 제공한다. 위 표의 권한 정책, 멱등성, +업무 감사와 평가 기준은 **애플리케이션에서 별도로 설계할 책임**이다. + +## 가상의 소비자 서비스에 적용 + +### 제품 비교 + +“작은 공간에 맞는 제품 둘을 비교해 줘”라는 요청에서 비교 대상과 항목 선택은 +에이전트가 도울 수 있다. 치수·가격·재고는 제품 API에서 받아 표시하고, +단위·통화·가격 유효 시점을 컴포넌트 계약에 포함한다. + +처음에는 Controlled 비교 카드로 측정한다. 질의마다 비교 항목과 보조 설명 +배치가 달라져야 한다면 Declarative 구성을 비교한다. 모델이 만든 가격이나 +임의 HTML 안의 구매 버튼을 업무 API의 권위로 취급하지 않는다. + +### 서비스 예약 + +증상 설명은 대화로 받고, 가능한 날짜·시간과 방문 조건은 폼으로 전환한다. +날짜 변경과 가용 슬롯 조회는 명시적인 UI 액션으로 처리하는 경로를 설계할 수 +있다. 예약 확정은 서버에서 시간대, 사용자 권한, 슬롯의 최신 상태를 다시 확인한다. + +UI가 “예약 완료”를 먼저 그렸다는 이유로 완료 처리하지 않는다. 실행 응답에 +예약 식별자가 있을 때만 확정 상태로 전환하고, 중복 클릭에는 멱등성 키를 적용한다. + +### 설명과 탐색 + +복잡한 기능을 설명하는 탐색형 시각화에는 Open-ended UI를 실험할 수 있다. +단, 거래 화면과 격리하고 생성 실패·긴 대기·키보드 사용 불가 시에는 텍스트나 +검증된 기존 화면을 제공한다. 논문의 시각적 선호도를 예약 완료율이나 +고객지원 해결률의 향상으로 바꾸어 해석하지 않는다. + +## 프런트엔드 교체 가능성을 만드는 계약 + +프로토콜 이름보다 다음 산출물이 재사용 가능성을 결정한다. + +1. 카탈로그에 컴포넌트 이름·속성·접근성 의미·상태·액션을 정의한다. +2. wire format 버전과 별개로 카탈로그 버전 및 지원 목록을 관리한다. +3. 실제 UI payload와 액션을 비식별화한 계약 테스트 fixture로 보존한다. +4. 동일 fixture를 대상 렌더러에서 재생해 정보, 동작, 오류 처리가 일치하는지 + 검사한다. 픽셀 일치만 요구하지 않는다. +5. 알 수 없는 컴포넌트·기능·버전을 받으면 진단 가능한 오류와 안전한 대체 + 화면을 표시한다. 조용히 항목을 삭제하거나 성공처럼 보여 주지 않는다. +6. 모델 교체와 렌더러 교체를 별도 실험으로 수행한다. 두 가지를 동시에 + 바꾸면 회귀 원인을 구분하기 어렵다. + +[Microsoft Agent Framework의 AG-UI 통합 문서][learn-agui]도 언어별 +SDK 지원이 다름을 명시한다. 프로토콜을 공유한다는 이유로 모든 런타임의 +도구 승인·상태 기능이 동일하다고 가정하면 안 된다. + +또한 [해당 프레임워크의 MCP Apps 연동][learn-mcp]은 Python 에이전트 +엔드포인트 앞의 TypeScript 미들웨어가 UI 리소스와 MCP 요청을 처리하는 +구조다. 이 구조를 다른 호스트·SDK에 자동 적용되는 범용 배포 요건으로 +일반화하지 않고, 실제 선택한 조합의 어댑터를 확인한다. + +## 프로덕션 검토 체크리스트 + +아래는 취약점 감사 결과가 아니라 구현 전후에 검증해야 할 설계 요구사항이다. + +| 영역 | 확인할 동작 | 실패 시 정책 | +|---|---|---| +| 출력 스키마 | 허용 컴포넌트·타입·데이터 경로만 렌더링 | 사용자에게 재시도·대체 화면을 제공하고 오류를 기록 | +| 업무 권한 | 서버가 사용자와 액션마다 권한 검사 | 명시적 거절, 원인에 맞는 사용자 안내 | +| 확인 단계 | 비용·주문·예약 등 부작용이 있는 액션의 확인 | 확인 취소 시 도구 실행 금지 | +| 상태 일관성 | 실행·도구 호출·surface 식별자와 버전 일치 | 오래된 응답 무시 사실을 기록하고 최신 상태 재조회 | +| 중복·재시도 | 요청이 반복되어도 부작용이 중복되지 않음 | 업무 API 멱등성, 처리 결과 조회 | +| 외부 콘텐츠 | iframe·URL·CSP·도구 노출 범위를 제한 | 허용되지 않은 경로 차단 및 이유 표시 | +| 개인정보 | 프롬프트·UI 데이터·로그 각각의 최소 수집 | 비식별화, 접근 제어, 보존·삭제 정책 | +| 접근성 | 키보드 탐색, 이름·역할, 포커스, 업데이트 알림 | 승인된 컴포넌트로 fallback, 완료 전 차단 이슈 해결 | +| 긴 실행 | 진행 상태·취소·타임아웃·최종 결과 구분 | 실패를 완료처럼 표현하지 않고 복구 경로 제공 | + +LLM의 자연어 확신, 화면의 확인 버튼, MCP 도구 목록에 나타난다는 사실은 +서버의 실행 권한을 대체하지 않는다. + +## 단계별 도입 + +| 단계 | 산출물 | 다음 단계 진입 조건 | +|---|---|---| +| 0. 기준선 | 기존 화면과 Controlled UI, 동일한 업무 시나리오·데이터 | 성공·실패·지연을 같은 정의로 측정 가능 | +| 1. 계약 분리 | UI 카탈로그, 데이터·액션 스키마, 업무 실행 게이트 | 잘못된 출력·권한·중복 요청을 일관되게 처리 | +| 2. Declarative 실험 | 제한된 카탈로그의 A2UI 화면, 버전 고정 | 기준선 대비 가치가 있으며 접근성·정확성 회귀가 없음 | +| 3. 선택적 확장 | 두 번째 렌더러 또는 MCP Apps 경로 | 호환성·호스트 지원·격리 정책 검증 | +| 4. Open-ended 실험 | 읽기·설명 중심의 격리된 생성 UI | 대기 시간·비용·실패율을 포함한 평가에서 이점 확인 | + +이 순서는 권장 실험 순서다. 이미 검증된 MCP 도구 UI가 있고 호스트 내 +상호작용이 핵심인 경우에는 MCP Apps를 먼저 평가할 수 있다. + +## 향후 Demo의 검증 설계 + +### 고정할 조건 + +- 같은 제품·서비스 fixture와 같은 사용자 업무를 사용한다. +- 모델·프롬프트·출력 제한·네트워크 조건·클라이언트·카탈로그 버전을 기록한다. +- 처음 방문, 후속 필터 조작, 재연결, 잘못된 입력, 권한 거절을 각각 시험한다. +- 테스트 계정과 가상 데이터만 사용한다. 실제 구매나 장치 제어는 수행하지 않는다. + +### 제품 데모 자료를 근거로 쓰지 않는다 + +[리서치 요약](../index.md)에 수록한 Gemini dynamic view 화면처럼 공개된 제품 +소개 자료는 도입 판단의 **출발점이지 측정값이 아니다.** 해당 영상도 화면 +하단에 시퀀스를 단축하고 화면을 시뮬레이션했으며 호환성과 가용 범위가 +다르다고 고지한다. + +| 데모에서 알 수 있는 것 | 직접 측정해야 하는 것 | +|---|---| +| 어떤 경험이 가능한지, 어떤 화면 구성이 설득력 있는지 | 첫 화면 표시 시간과 처음으로 올바른 액션이 가능한 시간 | +| 어떤 시나리오를 비교군으로 삼을지 | 생성 실패율, 스키마 오류율, 복구 성공률 | +| 어떤 상호작용을 카탈로그로 만들지 | 키보드 탐색과 스크린 리더 동작, 업무 완료율 | + +[패턴 비교](../patterns/index.md)에 수록한 AG-UI Dojo 화면처럼 직접 실행할 수 +있는 공개 데모는 시나리오 후보를 고르는 데 쓴다. 이때도 Dojo의 통합·모델 +조합과 제품의 조합이 다르면 결과를 그대로 옮기지 않는다. + +### 비교군과 지표 + +| 비교 | 검증할 가설 | 측정 항목 | +|---|---|---| +| 기존 화면 vs Controlled | 대화 중 UI 전환이 업무 완료를 돕는가 | 완료율, 완료 시간, 수정 횟수, 사용자 오류 | +| Controlled vs Declarative | 가변 화면 조합이 실제로 필요한가 | 완료율, 이해도, 렌더 실패율, 카탈로그 재사용률 | +| 후속 액션의 모델 경유 vs 직접 도구 호출 | 추가 추론 없는 경로가 비용·지연을 줄이는가 | 액션당 모델 호출 수, p50·p95 지연, 업무 정확성 | +| 두 렌더러 | 동일 계약이 프런트 교체에 유효한가 | fixture 통과율, 빠진 컴포넌트, 액션·접근성 차이 | +| 텍스트 vs Open-ended | 표현 자유도의 가치가 대기 비용보다 큰가 | 첫 사용 가능 UI 시간, 완료 시간, 선호도, 실패율 | + +첫 토큰 시간, 첫 화면 표시 시간, **처음으로 올바른 액션이 가능한 시간**은 +분리해 기록한다. 일부 UI가 빨리 그려졌다는 사실만으로 작업을 더 빨리 +끝낼 수 있다고 판단하지 않는다. + +### 통과 조건을 정하는 방법 + +측정하지 않은 “지연 30% 감소” 같은 수치를 목표의 근거로 만들지 않는다. +실험 전 제품의 기존 SLO·기준선으로 지연·비용 상한과 표본 수를 합의한다. +다음은 운영 SLA가 아닌 **Demo용 제안 조건**이다. + +- 정의한 권한 거절·확인 취소 시나리오에서 허용되지 않은 쓰기가 0건이어야 한다. +- 동일한 멱등성 키를 반복 전송해도 업무 변경은 한 번이어야 한다. +- 선언한 필수 카탈로그 fixture는 대상 렌더러 모두에서 통과해야 한다. +- 직접 호출 경로의 테스트 액션에는 불필요한 모델 호출이 0회인지 trace로 + 확인한다. 이 경로 밖의 첫 자연어 요청과는 합산하지 않는다. +- 성능·사용성 이점이 없으면 Controlled 기준선을 유지한다. 새로운 + 프로토콜을 사용했다는 사실 자체를 성공 지표로 삼지 않는다. + +## 생태계 참여의 구체적인 형태 + +A2UI 참여는 우선 지원 버전을 고정하고, 필요한 카탈로그와 렌더러의 격차를 +공개 이슈·테스트·명세 피드백으로 돌려주는 방식이 적절하다. 호환되지 않는 +독자 필드를 계속 추가한 뒤 이를 “표준 지원”이라고 부르지 않는다. + +AG-UI에는 에이전트 이벤트·상태·도구 호출의 어댑터 호환성 관점으로, +MCP Apps에는 호스트 기능·UI 자원·도구 노출 정책 관점으로 참여한다. +소유해야 할 것은 도메인 계약과 제품 경험이며, 생태계에 맡길 수 있는 것은 +명확한 경계가 있는 통신·표현 계약이다. + +## 한계 + +이 참조 구조는 E2E 구현과 사용자 실험을 거치지 않았다. 프로토콜 채택에 따른 +비용 절감, 성능 향상, 보안 적합성 또는 프런트엔드 전환 성공을 보장하지 않는다. +다음 작업은 [리서치 요약](../index.md)의 결론을 재진술하는 Demo가 아니라, +위 표의 가설을 반증할 수 있는 작은 실험이어야 한다. + +## 공식 출처 + +- [A2UI 공식 문서][a2ui]: 카탈로그 기반 선언적 UI와 클라이언트 렌더링. +- [CopilotKit AG-UI][agui]: 이벤트·상태·프런트엔드 도구의 연결. +- [MCP Apps 공식 개요][mcp-apps]: 호스트 내 UI와 양방향 도구 상호작용. +- [Microsoft Agent Framework AG-UI][learn-agui]: 언어별 구현 범위와 어댑터. +- [MCP Apps Compatibility with AG-UI][learn-mcp]: Microsoft Agent Framework와 + CopilotKit 미들웨어를 조합할 때의 책임 경계. + +[a2ui]: https://a2ui.org/ +[agui]: https://docs.copilotkit.ai/agentic-protocols/ag-ui +[mcp-apps]: https://modelcontextprotocol.io/extensions/apps/overview +[learn-agui]: https://learn.microsoft.com/agent-framework/integrations/by-component/ui/ag-ui/ +[learn-mcp]: https://learn.microsoft.com/agent-framework/integrations/by-component/ui/ag-ui/mcp-apps diff --git a/docs/services/application-development/agentic-app-genui/google-a2ui/index.md b/docs/services/application-development/agentic-app-genui/google-a2ui/index.md new file mode 100644 index 00000000..edbbd701 --- /dev/null +++ b/docs/services/application-development/agentic-app-genui/google-a2ui/index.md @@ -0,0 +1,327 @@ +--- +title: Google Generative UI 연구와 A2UI의 설계 시사점 +description: Yaniv Leviathan 등의 Generative UI 연구 결과와 A2UI의 버전·렌더러·E2E 계약을 구분하고 멀티프런트엔드 설계에 적용합니다. +document_type: research +topic_order: 3 +services: [application-development] +technologies: [mcp] +tags: [design, evaluate, ai-agents] +status: current +verification_status: verified +published_at: 2026-09-21 +sources_checked_at: 2026-09-22 +official_sources: + - title: "Generative UI: LLMs are Effective UI Generators - linked PDF" + url: https://generativeui.github.io/static/pdfs/paper.pdf + - title: Generative UI research project + url: https://generativeui.github.io/ + - title: A2UI - A Protocol for Agent-Driven Interfaces + url: https://a2ui.org/ + - title: A2UI Protocol v0.9.1 - Current + url: https://a2ui.org/specification/v0.9.1-a2ui/ + - title: A2UI Protocol v1.0 - Candidate + url: https://a2ui.org/specification/v1.0-a2ui/ + - title: Evolution Guide v0.9 to v0.9.1 + url: https://a2ui.org/specification/v0.9.1-evolution-guide/ + - title: A2UI Data Flow + url: https://a2ui.org/concepts/data-flow/ + - title: A2UI Renderers + url: https://a2ui.org/reference/renderers/ + - title: AG-UI Integration with Agent Framework + url: https://learn.microsoft.com/agent-framework/integrations/by-component/ui/ag-ui/ + - title: Gemini 3 in the Gemini app + url: https://blog.google/products/gemini/gemini-3-gemini-app/ +--- + +# Google Generative UI 연구와 A2UI의 설계 시사점 + +**기준일: 2026-09-21. Screenshot 확인일: 2026-09-22.** Google의 Generative UI +연구는 “모델이 인터페이스까지 +생성하면 사용자 경험이 개선되는가”를 탐구한다. A2UI는 “에이전트가 만든 UI +표현을 클라이언트가 어떤 계약으로 렌더링하는가”를 다룬다. +**생성 능력의 연구와 UI 표현 프로토콜은 서로 다른 근거이며, 결합은 별도의 +아키텍처 결정이다.** + +## 논문 식별과 조사 기준 + +| 항목 | 확인 결과 | +|---|---| +| 제목 | *Generative UI: LLMs are Effective UI Generators* | +| 첫 저자 | **Yaniv Leviathan**. `Yaniv Levia` 또는 `Yaniv Levi`가 아니다. | +| 공동 저자 | Dani Valevski, Matan Kalman, Danny Lumen, Eyal Segalis, Eyal Molad, Shlomi Pasternak, Vishnu Natchu, Valerie Nygaard, Srinivasan (Cheenu) Venkatachary, James Manyika, Yossi Matias | +| 소속 표기 | Google Research | +| 정량 분석 기준 | [요청된 정적 PDF][paper]의 2026-09-21 조회본, 총 22쪽. 표지에는 “Preprint. Under review.” 표기 | +| 프로젝트 페이지 | [공식 연구 사이트][project]. 논문·결과 예시·PAGEN으로 연결 | + +PDF와 프로젝트 페이지의 수치가 일부 다르므로 두 자료를 하나의 평가 버전으로 +취급하지 않는다. 아래 정량 결과는 **정적 PDF의 페이지·표 번호**에 고정한다. +웹페이지의 BibTeX 연도만으로 출판 시점이나 심사 상태를 확정하지 않는다. + +## 방법론: 모델·도구·후처리의 결합 + +![Google Generative UI 공식 연구 사이트의 시스템 도식. 시스템 지시와 사용자 요청을 받은 모델이 도구를 활용하고 후처리를 거쳐 웹 페이지를 생성하는 구성](../images/google-generative-ui-system-original.svg){ style="background-color: white;" } + +*Screenshot G1. Yaniv Leviathan 외, Google Research, +[공식 연구 사이트의 High Level Method Overview][project]에 게시된 원본 SVG. +[CC BY-SA 4.0](../licenses/google-CC-BY-SA-4.0.txt), 변경 없이 수록. +논문의 Figure 2와 대응하는 시스템 개요이며 A2UI 아키텍처 도식은 아니다.* + +[로컬 원본 확대](../images/google-generative-ui-system-original.svg) + +논문 §2, p.3의 구현은 완성된 웹 페이지와 이미지 등의 자산을 생성하고 +브라우저에서 렌더링한다. 핵심 구성은 세 가지다. + +1. 검색·이미지 생성 등 도구에 접근하는 서버 endpoint. 결과를 모델에 제공하는 + 경로와 브라우저에 직접 제공하는 경로를 구분한다. +2. 목표, 계획 지침, 예시, 기술 규칙과 도구 사용법을 포함하는 시스템 지시. +3. 생성물의 알려진 오류를 보정하고 실행 오류를 관측하는 후처리. + +이 연구는 자유로운 웹 UI 생성에 가깝다. A2UI JSON 카탈로그를 사용한 +실험으로 제시되어 있지 않으며, 논문의 성과를 A2UI의 실증 성과라고 부를 수 없다. +또한 일부 자산이 브라우저에 직접 전달된다는 설명은 자연어 해석과 UI 생성에서 +모델을 사용하지 않는다는 뜻이 아니다. + +부록 A.5의 긴 시스템 프롬프트를 제품의 정답 템플릿으로 복제하기보다, +**과업 정의·도구 계약·표현 규칙·오류 피드백을 함께 설계했다는 원리**를 +적용한다. 부록 A.6의 초기 연구용 후처리에는 API key placeholder 치환도 +포함되지만, 이를 비밀 키의 브라우저 노출을 권장하는 운영 패턴으로 옮겨서는 안 된다. + +## 정량 결과와 해석의 경계 + +### 평가 설계 + +PDF §3, pp.4–5와 부록 A.4, p.15에 따르면 LMArena에서 100개 요청을 +추출한 뒤 8개를 제외했고, 별도로 64개의 정보 탐색 요청을 구성했다. +각 결과는 두 평가자에게 제시하여 좌측 선호·중립·우측 선호로 비교했다. +**미리 생성·캐시한 결과를 제시했기 때문에 생성 대기 시간은 평가에 포함되지 않는다.** + +PAGEN은 이러한 요청에 대응하는 전문가 제작 웹 페이지의 비교 자료다. +외부 제작자 34명에게 연락했고 18명이 작업을 수락했다. 웹 페이지당 비용은 +100–130달러, 평균 작업 시간은 3–5시간이었다. 제작자에게 AI 도구 사용도 +허용했으므로 “AI를 전혀 쓰지 않은 인간과의 비교”라고 표현하지 않는다. + +### 정적 PDF의 주요 수치 + +| 측정 | 결과 | 정확한 적용 범위 | +|---|---|---| +| Markdown 대비 Generative UI 선호 | 82.8% | LMArena 평가, Table 2, p.5 | +| Markdown 대비 Generative UI 선호 | 92.6% | 별도 Info-Seeking 평가, Table 7, p.13 | +| Generative UI ELO | 1710.7 | LMArena의 형식 간 비교, Table 1, p.5 | +| 전문가 웹 페이지 ELO | 1756.0 | 같은 비교. 전문가 결과가 더 높음 | +| 전문가 대비 Generative UI 승리 | 43.0% | Table 2. 초록·논의의 “최소한 동등” 44%와는 중립 포함 여부를 구분 | +| 생성 시간의 한계 | 종종 1–2분 | §6, p.7의 저자 설명. 본 리서치의 실측이 아님 | + +ELO는 해당 비교 집합에서의 상대적 선호 척도이며 UI의 절대 정확도나 +업무 성공률이 아니다. “82.8% 선호”를 구매 전환율·예약 완료율·개발 생산성 +개선 수치로 변환할 근거는 없다. + +### 모델과 프롬프트의 영향 + +PDF Table 3의 LMArena 모델 비교에서는 Gemini 3, Gemini 2.5 Pro, +Gemini 2.5 Flash의 출력 오류가 각각 0%, Gemini 2.0 Flash는 29%, +Gemini 2.0 Flash-Lite는 60%로 보고되었다. +이는 **해당 평가에서 관측한 출력 오류**이며 무오류 시스템이나 보안 검증을 +의미하지 않는다. Info-Seeking의 결과는 다르므로 데이터셋을 섞어 일반화하지 않는다. + +Table 5의 프롬프트 비교 ELO는 Full Prompt 1553.23, Minimal Prompt 1496.00, +No Philosophy 1450.77이다. 별도 비교군으로 계산한 ELO이므로 위 형식 비교의 +1710.7과 직접 순위를 매기지 않는다. 제품 관점에서는 모델 교체와 함께 +시스템 지시·도구·검증기를 공동 평가해야 한다는 시사점이 있다. + +### 프로젝트 페이지와의 수치 불일치 + +| 항목 | 요청된 정적 PDF | 조사일의 프로젝트 페이지 | +|---|---|---| +| 전문가 결과와 최소한 동등 | 44% | 50% | +| 형식 비교의 Generative UI ELO | 1710.7 | 1736.2 | + +두 출처에 서로 다른 값이 실제로 존재한다. 변경 이력과 평가 조건을 확인하지 +않고 한쪽 수치를 다른 쪽 표의 결과로 인용하지 않는다. 이 문서에서는 PDF를 +정량 근거로 유지하고, 프로젝트 사이트는 Screenshot·데모·별도 요약의 출처로 사용한다. + +## 연구에서 제품으로: generative interfaces + +[Gemini 3 앱 소개][gemini-app]는 이 방향을 **generative interfaces**라는 +이름으로 제품에 도입했다고 밝히고, 첫 두 실험으로 visual layout과 dynamic +view를 설명한다. dynamic view 예시 화면은 [리서치 요약](../index.md)에 +GIF로 수록했다. + +제품화 사실에서 다음을 구분한다. + +| 확인한 사실 | 확대 해석하지 않을 것 | +|---|---| +| Gemini 앱이 모델 생성 인터페이스를 실험으로 제공한다 | 모든 사용자·지역·요금제에서 동일하게 제공된다는 뜻은 아니다 | +| 소개 화면이 탐색형 UI의 가능성을 보여 준다 | 소개 영상에 “시퀀스 단축·화면 시뮬레이션” 고지가 있다 | +| Google이 연구와 제품을 연결했다 | 이 제품 기능이 **A2UI로 구현되었다는 공개 근거는 확인하지 않았다** | + +마지막 항목이 특히 중요하다. 연구의 자유 웹 페이지 생성, 제품의 generative +interfaces, 그리고 A2UI의 선언적 카탈로그 렌더링은 같은 목표를 공유하지만 +서로 다른 구현 경로다. 하나의 성과를 다른 쪽의 근거로 사용하지 않는다. + +## A2UI: 생성 결과를 제품 UI 계약으로 제한 + +[A2UI 공식 문서][a2ui]는 에이전트가 실행 코드 대신 선언적 컴포넌트 기술을 +보내고, 클라이언트가 자신의 위젯으로 렌더링하는 방식을 정의한다. 구조와 +데이터를 분리하고, 작은 메시지로 UI를 생성·갱신하는 것이 핵심이다. + +| 책임 | A2UI에서의 의미 | 구현 시 결정할 사항 | +|---|---|---| +| Surface | UI를 구성하는 독립 표시 영역 | 생성·삭제·재연결 수명주기 | +| Components | ID로 연결된 평탄한 컴포넌트 목록 | 허용 카탈로그와 native widget 매핑 | +| Data model | UI 구조와 분리된 상태 | JSON Pointer 바인딩, 데이터 최소 전송 | +| Actions | 사용자의 상호작용을 서버에 전달 | 서버 검증, 업무 실행, 오류·결과 처리 | +| Transport | A2UI 메시지를 전달하는 별도 계층 | 메시지 경계, 순서 보장, capability metadata | + +카탈로그의 `catalogId`는 계약을 식별하는 문자열이다. URI 형태일 수 있지만 +반드시 다운로드 가능한 주소라는 뜻은 아니다. 서버와 클라이언트가 같은 +컴포넌트·함수 계약을 이해하는지가 호환성의 핵심이다.[v0.9.1 명세][spec091] + +## Specification Versions + +| 버전 | 조사일의 공식 상태 | 적용 판단 | +|---|---|---| +| v0.8 | Legacy | 기존 예제·도식에 남아 있는 메시지명을 해석할 때 사용 | +| v0.9 | Stable, 이전 안정 버전 | prompt-first 설계, `createSurface`, 모듈화된 카탈로그 계열 | +| **v0.9.1** | **Current** | 이 문서의 구체적인 메시지·E2E 설명 기준 | +| v1.0 | Candidate | 이전 draft의 v0.10 명칭과 구분. 운영 도입 시 renderer 지원을 별도 확인 | + +상태는 [공식 홈][a2ui]과 [v0.9.1][spec091]·[v1.0 명세][spec10]에서 확인했다. +v0.9.1의 변경은 `application/a2ui+json` MIME type 통일과 활성 surface 사이의 +ID 유일성 조건 정리다. [Evolution Guide][evolution091]는 v0.9와 v0.9.1 +payload 호환을 명시하지만, 이것을 v0.8 또는 v1.0까지의 호환 보증으로 확대하지 않는다. + +v1.0은 진행 중인 후보 명세다. 홈페이지의 짧은 변경 요약과 상세 명세의 기능 +설명이 일치한다고 전제하지 않는다. 구현은 특정 revision의 schema와 renderer를 +함께 고정하고, v0.9.1 예제에 candidate의 필드를 섞지 않는 것이 적절하다. + +## Screenshot으로 보는 E2E + +![A2UI 공식 Screenshot. 서버 JSONL 스트림, 클라이언트 버퍼링과 렌더링, 사용자 액션, 동적 갱신을 설명하며 v0.8 계열 메시지명을 사용한다](../images/a2ui-end-to-end-original.png) + +*Screenshot A1. A2UI 프로젝트, [공식 Data Flow 문서][data-flow]. +[Apache-2.0](../licenses/a2ui-Apache-2.0.txt), 변경 없이 수록. +원본 revision과 재배포 정보는 [이미지 출처 기록](../licenses/third-party-images.txt)에 보존한다.* + +[로컬 원본 확대](../images/a2ui-end-to-end-original.png) + +> [!IMPORTANT] +> 이 Screenshot의 `surfaceUpdate`, `dataModelUpdate`, `beginRendering`, +> `userAction`은 **v0.8 계열**이다. 공식 사이트에 남아 있는 그림이라는 이유로 +> 최신 wire format으로 사용하면 안 된다. SSE와 별도 A2A 메시지는 그림의 +> 전달 방식이며, A2UI 자체가 이 조합만을 강제하는 것은 아니다. + +| Screenshot의 표현 | v0.9.1에서 구분할 계약 | +|---|---| +| `surfaceUpdate` | `updateComponents` | +| `dataModelUpdate` | `updateDataModel` | +| `beginRendering` | 단순 치환이 아님. 먼저 `createSurface`, 이후 `root`와 컴포넌트·데이터를 점진적으로 제공 | +| `userAction` | `action` | +| 원래 SSE stream으로 갱신 | 선택한 transport의 framing·순서·재연결 계약에 맞춰 갱신 | + +### v0.9.1 기준 상호작용 + +![서버의 UI·데이터 기술과 클라이언트 카탈로그 렌더링, 사용자 액션과 업무 실행을 구분한 A2UI 책임 흐름도](../images/a2ui-end-to-end.svg) + +*그림 4. 현재 명세의 책임 경계를 설명하기 위해 직접 작성한 개념도. +Screenshot A1의 과거 메시지명을 그대로 사용하지 않는다.* + +1. 클라이언트와 서버가 지원하는 카탈로그와 버전을 전달 계층의 metadata + 또는 초기화 절차에서 교환한다. +2. 서버가 `createSurface`로 surface와 `catalogId`를 지정한다. +3. `updateComponents`의 평탄한 목록과 ID 참조로 UI 구조를 기술한다. + root 컴포넌트의 ID는 `root`이며, 자식 참조가 나중에 도착할 수 있다. +4. `updateDataModel`로 데이터를 제공한다. 구조를 모두 다시 보내지 않고 + 특정 JSON Pointer 위치의 값을 갱신할 수 있다. +5. renderer가 허용된 native component와 데이터 바인딩을 적용한다. +6. 사용자 입력은 `action`으로 서버에 전달한다. `name`, `surfaceId`, + `sourceComponentId`, `timestamp`, `context`가 포함된다. +7. 애플리케이션이 권한·인자·업무 규칙을 검증하고 실행한다. 후속 UI·데이터 + 갱신 또는 오류를 반환하고, 수명이 끝나면 `deleteSurface`를 보낸다. + +7번의 업무 권한 검사는 A2UI가 제공하는 자동 인가 기능이 아니라 설계 책임이다. +`sendDataModel`을 활성화하면 전체 data model이 metadata로 전송될 수 있으므로, +민감 필드를 UI 상태에 무분별하게 포함하지 않는다. + +v0.9 계열은 prompt-first 생성 접근을 채택했다. 명세도 생성 후 검증의 필요성을 +명시한다. `VALIDATION_FAILED` 오류에 surface·path·message를 담아 수정 경로를 +구성하되, 재생성을 무제한 반복하거나 오류를 빈 화면으로 숨기지 않는다. + +## 프런트엔드 독립성과 실제 renderer 지원 + +[공식 renderer 표][renderers]는 다음 상태를 표시한다. 이는 문서상 지원 +상태이며 본 리서치에서 각 SDK를 설치해 검증한 결과는 아니다. + +| Renderer | 플랫폼 | v0.9.1 | v1.0 | +|---|---|---|---| +| React | Web | Stable | Planned | +| Lit | Web Components | Stable | Planned | +| Angular | Web | Stable | Planned | +| Flutter GenUI SDK | Mobile·Desktop·Web | Stable | Planned | +| SwiftUI | iOS·macOS | 지원 표기 없음 | Planned | +| Jetpack Compose | Android | 지원 표기 없음 | Planned | + +공식 표의 “지원 표기 없음”을 커뮤니티 구현의 부재로 해석하지 않는다. +같은 페이지는 별도의 커뮤니티 renderer도 소개한다. +특히 **Flutter를 통한 모바일 지원**과 **모든 플랫폼 native SDK의 동일 버전 지원**은 +다른 주장이다. + +## AG-UI와 결합할 때의 경계 + +v0.9.1 명세는 A2UI를 transport-agnostic으로 정의하고 A2A·AG-UI 등의 +연결을 설명한다. A2UI는 JSON 표현의 의미, AG-UI는 에이전트와 앱의 이벤트 +연결을 담당한다. 같은 사용자 경험에 조합할 수 있지만 실제 binding·버전· +카탈로그 지원을 검증해야 한다. + +[Microsoft Agent Framework AG-UI 문서][learn-agui]도 이벤트로 도구·상태를 +전달하고 클라이언트가 렌더링을 결정하는 경계를 확인해 준다. +이 사실이 해당 프레임워크의 모든 언어 SDK에 특정 A2UI renderer가 내장되어 +있다는 근거는 아니다. + +## Cutting-edge 설계 시사점 + +| 연구·명세에서 확인한 사실 | 권장하는 적용 | +|---|---| +| 생성 UI는 사전 생성 결과의 선호도 평가에서 높은 점수를 얻음 | 탐색·설명 과업에서 먼저 실험하고, 실제 대기 시간을 포함한 업무 완료율로 재평가 | +| 모델뿐 아니라 도구·지시·후처리가 함께 작동 | 모델 선정과 UI 검증·오류 복구를 하나의 시스템으로 설계 | +| A2UI가 구조·데이터·native renderer를 분리 | 도메인 카탈로그를 자산화하고 두 renderer의 동일 fixture 재생으로 교체 가능성 입증 | +| 버전·renderer 지원 상태가 다름 | schema·catalog·renderer·binding의 호환 조합을 고정 | +| 사용자 액션은 별도 반환 경로를 사용 | 후속 액션을 항상 LLM 추론으로 되돌리지 말고 결정적 처리 경로와 비교 | + +전략의 중심은 **의도 적응형 경험과 검증 가능한 UI 계약의 결합**이다. +생태계 참여는 카탈로그·renderer·접근성·호환성 테스트의 기여로 구체화한다. +참여 자체를 프런트엔드 교체의 자유나 특정 기술의 장기 채택 보증으로 표현하지 않는다. + +## 한계와 재현 범위 + +논문의 사용자 평가는 재현하지 않았다. 실제 서비스의 보안·접근성·지연·비용, +장기간 상태 유지와 업무 완료율도 이 논문의 수치만으로 입증되지 않는다. +논문·프로젝트 사이트의 수치 불일치는 위와 같이 명시하며 통합하지 않았다. + +정적 PDF 조회본의 SHA-256은 +`75aa3ca488b24af95f9d41eb27e834bcc55e68d911b4ce02c08ad73a02f9331a`다. +원문 PDF 전체는 이 저장소에 재배포하지 않는다. 수록한 Google 도식은 +CC BY-SA 4.0이 표시된 연구 사이트의 SVG이며, PDF 전체의 재배포 허가를 +추정한 것이 아니다. + +## 공식 출처 + +- [정적 PDF][paper]: pp.1, 3–7, 13, 15, 21. 저자·방법·평가·PAGEN·한계. +- [연구 사이트][project]: 원천 시스템 도식, 별도의 결과 요약과 라이선스. +- [A2UI 공식 홈][a2ui]: 개념과 Specification Versions. +- [v0.9.1 명세][spec091]와 [Evolution Guide][evolution091]: 메시지·카탈로그·액션·전송 계약. +- [v1.0 Candidate 명세][spec10]: candidate 상태 확인. +- [Data Flow][data-flow]: 원천 E2E 도식과 v0.8·v0.9 예제의 구분. +- [Renderer 지원표][renderers]: 플랫폼·버전별 공개 지원 상태. +- [Microsoft Agent Framework AG-UI][learn-agui]: 이벤트 어댑터와 UI renderer 경계의 보조 사례. +- [Gemini 3 앱 소개][gemini-app]: generative interfaces의 제품 도입과 두 실험. + +[paper]: https://generativeui.github.io/static/pdfs/paper.pdf +[project]: https://generativeui.github.io/ +[a2ui]: https://a2ui.org/ +[spec091]: https://a2ui.org/specification/v0.9.1-a2ui/ +[spec10]: https://a2ui.org/specification/v1.0-a2ui/ +[evolution091]: https://a2ui.org/specification/v0.9.1-evolution-guide/ +[data-flow]: https://a2ui.org/concepts/data-flow/ +[renderers]: https://a2ui.org/reference/renderers/ +[learn-agui]: https://learn.microsoft.com/agent-framework/integrations/by-component/ui/ag-ui/ +[gemini-app]: https://blog.google/products/gemini/gemini-3-gemini-app/ diff --git a/docs/services/application-development/agentic-app-genui/images/a2ui-end-to-end-original.png b/docs/services/application-development/agentic-app-genui/images/a2ui-end-to-end-original.png new file mode 100644 index 00000000..77728afa Binary files /dev/null and b/docs/services/application-development/agentic-app-genui/images/a2ui-end-to-end-original.png differ diff --git a/docs/services/application-development/agentic-app-genui/images/a2ui-end-to-end.svg b/docs/services/application-development/agentic-app-genui/images/a2ui-end-to-end.svg new file mode 100644 index 00000000..1ae3e7b3 --- /dev/null +++ b/docs/services/application-development/agentic-app-genui/images/a2ui-end-to-end.svg @@ -0,0 +1,50 @@ + + A2UI end-to-end interaction and responsibility boundaries + The client advertises supported UI capabilities. An agent or service produces a declarative UI description and data, delivered through a chosen transport. The client validates and maps catalog components to its native renderer. User actions return to the service for validation and business execution, followed by further UI updates. Rendering a UI is not authorization to execute a business action. + + + + + + A2UI: UI descriptions cross the boundary, not arbitrary code + Agree on specification version, catalog, renderer capabilities, and transport integration. + + Agent / application service + Receives request + capabilities + Produces UI + data messages + Model-generated or deterministic + + Action handler + Validate identity and arguments + Execute allowed business action + Produce authoritative result + + Client / native renderer + Validate message + catalog + Bind data to approved widgets + Client owns styling and behavior + + User interaction + Button, form, selection + Create action event + context + Show pending / error / result + + 1. Request + supported capabilities + + 2. Surface / components / data + Chosen transport carries messages + + 3. User action + context + + 4. Updated UI / data / error + + Native rendering is not automatic portability: each target needs compatible catalog implementations. + Conceptual flow. See the document's version table for exact wire message names and status. + diff --git a/docs/services/application-development/agentic-app-genui/images/adoption-reference-architecture.svg b/docs/services/application-development/agentic-app-genui/images/adoption-reference-architecture.svg new file mode 100644 index 00000000..1a11c971 --- /dev/null +++ b/docs/services/application-development/agentic-app-genui/images/adoption-reference-architecture.svg @@ -0,0 +1,63 @@ + + Recommended separation of UI proposal and business execution + Client UI options include controlled components, an A2UI renderer, and optional isolated MCP Apps. An orchestration layer proposes interfaces and calls read tools. A separate application-owned action gateway authorizes and validates side effects before accessing systems of record. Observability and compatibility tests cover all layers. This is an analytical reference architecture, not a measured implementation. + + + + + + Generate the experience; govern the business action + Recommended architecture for evaluation, not a verified production deployment + + Application frontend + + Controlled components + + A2UI renderer + + Optional isolated MCP Apps + + Agent events + + Explicit actions + + Agent orchestration + Model + read tools + UI proposals + Capability-aware generation + Model is not the authority for writes + + Application action gateway + Identity + policy + schema checks + Confirmation and idempotency + Enforced for agent and direct calls + + + Read path + + Authorized execution + + Domain services / systems of record + Products, availability, orders, support cases; authoritative business state + + Cross-cutting checks + Contract versions + Renderer parity + Trace correlation + Sensitive-data limits + Accessibility + Latency and cost + Failure recovery + Task completion + Audit and replay + A protocol is not + an authorization system. + Keep a stable fallback UI. Expand generative freedom only when measured user value justifies it. + Original design recommendation; transport, runtime, and business-service choices remain replaceable. + diff --git a/docs/services/application-development/agentic-app-genui/images/ag-ui-dojo-backend-tool-rendering-screenshot.png b/docs/services/application-development/agentic-app-genui/images/ag-ui-dojo-backend-tool-rendering-screenshot.png new file mode 100644 index 00000000..cef63071 Binary files /dev/null and b/docs/services/application-development/agentic-app-genui/images/ag-ui-dojo-backend-tool-rendering-screenshot.png differ diff --git a/docs/services/application-development/agentic-app-genui/images/ag-ui-overview-original.png b/docs/services/application-development/agentic-app-genui/images/ag-ui-overview-original.png new file mode 100644 index 00000000..8a569cac Binary files /dev/null and b/docs/services/application-development/agentic-app-genui/images/ag-ui-overview-original.png differ diff --git a/docs/services/application-development/agentic-app-genui/images/copilotkit-controlled-original.png b/docs/services/application-development/agentic-app-genui/images/copilotkit-controlled-original.png new file mode 100644 index 00000000..afbe63e6 Binary files /dev/null and b/docs/services/application-development/agentic-app-genui/images/copilotkit-controlled-original.png differ diff --git a/docs/services/application-development/agentic-app-genui/images/copilotkit-declarative-original.png b/docs/services/application-development/agentic-app-genui/images/copilotkit-declarative-original.png new file mode 100644 index 00000000..797a0ee4 Binary files /dev/null and b/docs/services/application-development/agentic-app-genui/images/copilotkit-declarative-original.png differ diff --git a/docs/services/application-development/agentic-app-genui/images/copilotkit-product-overview-screenshot.png b/docs/services/application-development/agentic-app-genui/images/copilotkit-product-overview-screenshot.png new file mode 100644 index 00000000..21a08f9f Binary files /dev/null and b/docs/services/application-development/agentic-app-genui/images/copilotkit-product-overview-screenshot.png differ diff --git a/docs/services/application-development/agentic-app-genui/images/demo-generative-ui.mp4 b/docs/services/application-development/agentic-app-genui/images/demo-generative-ui.mp4 new file mode 100644 index 00000000..538ae392 Binary files /dev/null and b/docs/services/application-development/agentic-app-genui/images/demo-generative-ui.mp4 differ diff --git a/docs/services/application-development/agentic-app-genui/images/gemini-dynamic-view-screencast.gif b/docs/services/application-development/agentic-app-genui/images/gemini-dynamic-view-screencast.gif new file mode 100644 index 00000000..08b11894 Binary files /dev/null and b/docs/services/application-development/agentic-app-genui/images/gemini-dynamic-view-screencast.gif differ diff --git a/docs/services/application-development/agentic-app-genui/images/generative-ui-patterns.svg b/docs/services/application-development/agentic-app-genui/images/generative-ui-patterns.svg new file mode 100644 index 00000000..b0372f0b --- /dev/null +++ b/docs/services/application-development/agentic-app-genui/images/generative-ui-patterns.svg @@ -0,0 +1,54 @@ + + Three Generative UI patterns and two independent control choices + Controlled UI selects developer-owned components. Declarative UI describes a composition rendered from an approved catalog. Open-ended UI supplies HTML or code in an isolated surface. In all three patterns, the developer or the model can decide when to display the UI. These are options, not maturity levels. + + + + + + What can change in the interface? + A spectrum of representation freedom, not a mandatory upgrade path + + Controlled + Developer-owned UI + Stable forms and product cards + + Select component + + typed arguments + + + Render existing component + Layout controlled by the app + + Declarative + Catalog-based composition + Example: A2UI descriptions + + Describe UI + data + Schema + catalog contract + + + Validate and render natively + Client implements the catalog + + Open-ended + HTML / code surface + Authored or model-generated + + Provide rich content + Flexible HTML / code + + + Render in an isolated surface + Host policy and execution controls + Independent question: who decides when to display it? + Deterministic application logic OR model selection can be used in any pattern. + Original synthesis of CopilotKit's taxonomy. MCP Apps do not require model-generated HTML. + diff --git a/docs/services/application-development/agentic-app-genui/images/google-generative-ui-system-original.svg b/docs/services/application-development/agentic-app-genui/images/google-generative-ui-system-original.svg new file mode 100644 index 00000000..3fffcb13 --- /dev/null +++ b/docs/services/application-development/agentic-app-genui/images/google-generative-ui-system-original.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/services/application-development/agentic-app-genui/images/mcp-apps-call-paths.svg b/docs/services/application-development/agentic-app-genui/images/mcp-apps-call-paths.svg new file mode 100644 index 00000000..03b04a9f --- /dev/null +++ b/docs/services/application-development/agentic-app-genui/images/mcp-apps-call-paths.svg @@ -0,0 +1,51 @@ + + Separate the first natural-language request from later UI tool calls + The first request can use a model to choose an MCP tool and display its associated UI resource. Later button clicks can call an allowed tool through the host without a new model inference. Python is a possible server implementation language, not an MCP requirement or natural-language parser. + + + + + + Where is model inference actually needed? + MCP transports structured calls. It does not understand natural language by itself. + A. Initial conversation: model-assisted selection + + Natural-language query + "Compare these products" + + + Agent + model + Select tool + arguments + + + MCP host / server + Tool + UI resource + + + Embedded app + Host renders iframe + B. Later interaction: explicit UI action, no new inference required + + App button or filter + Typed action + arguments + + + Host bridge + Policy / tool visibility checks + + + MCP server tool + Python or another language + + Structured result returns through the host; UI updates + + Optional model-context updates are separate from deciding each UI action. + Skipping inference does not skip authorization, validation, confirmation, or audit logging. + diff --git a/docs/services/application-development/agentic-app-genui/images/protocol-responsibilities.svg b/docs/services/application-development/agentic-app-genui/images/protocol-responsibilities.svg new file mode 100644 index 00000000..9923152f --- /dev/null +++ b/docs/services/application-development/agentic-app-genui/images/protocol-responsibilities.svg @@ -0,0 +1,54 @@ + + AG-UI, A2UI, and MCP Apps have different responsibilities + An application can use AG-UI events to connect to an agent. A2UI descriptions are data rendered by an approved native component catalog. MCP Apps instead associate MCP tools with UI resources rendered in a host-controlled iframe. These are composable, optional routes rather than a universal mandatory stack. + + + + + + Choose contracts by responsibility + CopilotKit is an implementation stack. The protocols are not interchangeable products. + + Application / CopilotKit frontend + Chat, client state, UI components + Host capabilities and backend adapters still matter + + Agent runtime + Models, tools, orchestration + Application-owned permissions + + + AG-UI + Events / state / tools + + Route A: declarative UI + Agent or application + Creates UI descriptions + + A2UI messages + UI + data contract + + Native renderer + catalog + Client-owned components + Transport integration is separate; using A2UI does not by itself require AG-UI or MCP. + + Route B: embedded tool UI + MCP tool + UI resource + Server-provided HTML app + + MCP Apps host + Bridge + policy + resources + + Sandboxed iframe UI + Tool calls through the host + Host support is required. A developer-authored app is not evidence of runtime code generation. + Adopt only the contracts needed for the experience; both routes can coexist. + Original conceptual diagram; not a deployment diagram or a claim of automatic renderer compatibility. + diff --git a/docs/services/application-development/agentic-app-genui/index.md b/docs/services/application-development/agentic-app-genui/index.md new file mode 100644 index 00000000..d724ff6f --- /dev/null +++ b/docs/services/application-development/agentic-app-genui/index.md @@ -0,0 +1,419 @@ +--- +title: Agentic Application의 Generative UI 설계 리서치 +description: Controlled·Declarative·Open-ended UI와 CopilotKit, AG-UI, MCP Apps, A2UI를 비교하고 에이전트 애플리케이션의 cutting-edge 방법론 제안 +document_type: research +services: [application-development] +technologies: [mcp] +tags: [design, evaluate, ai-agents] +status: current +verification_status: verified +published_at: 2026-09-21 +sources_checked_at: 2026-09-22 +official_sources: + - title: "Generative UI: Understanding Agent-Powered Interfaces" + url: https://www.copilotkit.ai/generative-ui + - title: AG-UI Protocol + url: https://docs.copilotkit.ai/agentic-protocols/ag-ui + - title: MCP Apps + url: https://modelcontextprotocol.io/extensions/apps/overview + - title: A2UI - A Protocol for Agent-Driven Interfaces + url: https://a2ui.org/ + - title: Generative UI research project + url: https://generativeui.github.io/ + - title: AG-UI Integration with Agent Framework + url: https://learn.microsoft.com/agent-framework/integrations/by-component/ui/ag-ui/ + - title: Gemini 3 in the Gemini app + url: https://blog.google/products/gemini/gemini-3-gemini-app/ + - title: CopilotKit + url: https://github.com/CopilotKit/CopilotKit + - title: Vue Frontend + url: https://docs.copilotkit.ai/vue + - title: Angular Frontend + url: https://docs.copilotkit.ai/angular + - title: A2UI Renderers + url: https://a2ui.org/reference/renderers/ +--- + +# Agentic Application의 Generative UI 설계 리서치 + +**조사 기준일: 2026-09-21. Screenshot 확인일: 2026-09-22.** 다음 세대 에이전트 +애플리케이션의 차이는 답변을 더 길게 생성하는 데 있지 않다. 사용자가 비교하고, +값을 수정하고, 확인하고, 실행하는 데 필요한 인터페이스를 적절한 시점에 제공하는 +데 있다. + +이때 **UI를 얼마나 생성할 것인지, 어떤 프로토콜로 연결할 것인지, 누가 실제 +업무 실행을 허가할 것인지**는 별개의 설계 결정이다. A2UI는 중요한 UI 표현 +계약 후보지만, 모든 앱을 하나의 프로토콜로 대체하는 해답은 아니다. + +## 30초 요약 + +| 질문 | 핵심 판단 | +|---|---| +| 무엇부터 도입하는가 | 기존 컴포넌트를 재사용하는 Controlled UI를 기준선으로 삼고, 화면 조합의 가변성이 가치가 있을 때 Declarative UI를 비교한다. 이는 이번 리서치의 권고이지 산업 전체의 성숙도 순위가 아니다. | +| 세 패턴은 어떻게 다른가 | Controlled는 개발자가 만든 컴포넌트를 선택하고, Declarative는 허용된 컴포넌트의 조합을 기술하며, Open-ended는 HTML·코드 수준의 표현 자유도를 허용한다. | +| AG-UI와 A2UI 중 하나를 고르는가 | 아니다. AG-UI는 에이전트와 앱의 이벤트·상태·도구 상호작용, A2UI는 선언적 UI 표현을 다룬다. 결합 시에는 실제 어댑터와 버전을 확인한다. | +| MCP Apps는 무엇을 추가하는가 | MCP 도구에 UI 리소스를 연결하고, 지원 호스트가 그 UI를 표시하며 도구와 양방향으로 상호작용하게 한다. 항상 LLM이 HTML을 새로 생성하는 것은 아니다. | +| LLM 없이 도구를 호출할 수 있는가 | 명시적인 버튼·필터 조작은 호스트를 통해 도구에 전달할 수 있다. 임의의 자연어를 이해하고 도구를 선택하는 단계까지 MCP가 대신한다는 뜻은 아니다. | +| A2UI를 채택하면 프런트를 자유롭게 바꾸는가 | UI 계약의 분리는 교체 비용을 줄일 수 있지만, 각 플랫폼의 렌더러·카탈로그·접근성·동작 호환성 구현은 남는다. | +| 논문이 무엇을 입증하는가 | 생성 UI의 가능성을 평가한 연구 결과와, 프로덕션의 지연·비용·안전성·프로토콜 호환성은 구분해야 한다. | + +## 제품에서 확인하는 생성 UI + +![Gemini 앱에서 "Create a Van Gogh gallery with life context for each piece" 프롬프트를 dynamic view로 실행하면, 인터페이스를 계획하는 단계를 거쳐 시대별 탭과 작품 이미지, 생애 맥락 설명과 인용문이 배치된 대화형 갤러리 화면이 생성되는 과정](images/gemini-dynamic-view-screencast.gif) + +*Screenshot S1. Google, [Gemini 3 앱 소개][gemini-app]의 dynamic view 예시 영상을 +GIF로 변환해 수록. 원본 화면 하단 고지처럼 **시퀀스를 단축하고 화면을 시뮬레이션한 +소개 자료**이며 실제 생성 시간, 성공률이나 가용 범위를 나타내지 않는다. +저작권은 Google에 있고 설명을 위한 인용으로만 사용한다.* + +이 화면이 “UI를 생성한다”의 구체적인 모습이다. 같은 프롬프트에 대해 Markdown +답변 대신 시대 구분 탭, 작품 이미지, 생애 맥락과 인용을 배치한 탐색형 화면이 +돌아온다. Google은 이를 **generative interfaces**로 부르며, [Gemini 3 앱 +소개][gemini-app]는 조사일 기준 visual layout과 dynamic view 두 가지를 첫 +실험으로 설명한다. + +다만 이 예시는 세 가지를 동시에 보여 준다. + +- 표현 자유도가 큰 **설명·탐색 업무**다. 결제나 예약 확정이 걸려 있지 않다. +- 화면 배치·구성 요소를 모델이 결정하는 [Open-ended 계열](patterns/index.md)에 + 가깝다. 제품의 디자인 시스템 컴포넌트를 재사용하는 방식이 아니다. +- 소개 영상은 **편집된 자료**다. 도입 판단에는 첫 화면 표시 시간, 실패율, + 접근성을 [직접 측정](adoption/index.md)해야 한다. + +## Generative UI란 무엇인가 + +Generative UI는 모델이 **내용뿐 아니라 그 내용을 다루는 인터페이스까지** +만들어 내는 접근이다. 기존 LLM 애플리케이션은 결과를 Markdown 한 덩어리로 +쏟아 냈다. 사용자는 그 텍스트를 읽고 다시 자연어로 되물어야 했다. + +생성 UI는 이 흐름을 바꾼다. 요청의 성격에 맞는 카드, 비교표, 폼, 탐색형 +화면을 그 자리에서 제시하고 사용자는 **읽는 대신 조작**한다. 값을 바꾸고, +항목을 고르고, 확인 버튼을 누르는 상호작용이 대화 안으로 들어온다. + +여기서 세 가지 결정이 서로 다른 축이라는 점이 중요하다. + +| 결정 축 | 질문 | 선택지 | +|---|---|---| +| **표현 자유도** | 모델이 화면의 무엇을 바꿀 수 있는가 | Controlled · Declarative · Open-ended | +| **연결 계약** | 에이전트와 앱이 무엇을 주고받는가 | AG-UI 이벤트 · A2UI 메시지 · MCP 도구·UI 리소스 | +| **실행 권한** | 누가 업무 변경을 허가하는가 | 애플리케이션 서버(프로토콜이 대신하지 않음) | + +세 축을 한 덩어리로 묶으면 “새 프로토콜을 붙이면 더 좋은 UX가 된다”는 잘못된 +기대가 생긴다. 반대로 축을 나누면 표현은 과감하게, 실행은 보수적으로 설계할 +수 있다. + +## 세 가지 방법론 + +[CopilotKit의 분류][taxonomy]를 기준으로 생성 UI는 세 갈래다. 성숙도 단계가 +아니라 **선택지**이며, 하나의 제품에서 화면마다 다르게 적용해도 된다. + +| 방법론 | 모델이 결정하는 것 | 개발자가 고정하는 것 | 잘 맞는 업무 | 주된 위험 | +|---|---|---|---|---| +| **Controlled** | 어떤 컴포넌트를 언제 어떤 값으로 보여 줄지 | 화면 구조, 상호작용, 디자인 시스템 | 주문·예약·승인처럼 절차가 안정적인 화면 | 필요한 컴포넌트가 없으면 대응 불가 | +| **Declarative** | 허용된 요소를 **어떻게 조합**할지 | 카탈로그, renderer, 속성·액션 계약 | 요청마다 비교 항목·구성이 달라지는 화면 | 카탈로그·버전 불일치, 데이터 검증 누락 | +| **Open-ended** | HTML·코드 수준의 표현 전체 | 격리 경계, 실행·리소스·접근 정책 | 설명·탐색형 시각화 | 생성 시간, 실패, 안전성 검증 비용 | + +위에 수록한 Gemini dynamic view 화면이 Open-ended에 가까운 예라면, +[AG-UI Dojo의 날씨 카드](patterns/index.md)는 Controlled의 예다. 같은 +“생성 UI”라는 말이 전혀 다른 구현과 검증 부담을 가리킨다. + +권고는 단순하다. **Controlled를 기준선으로 두고, 조합의 가변성이 실제 가치를 +만들 때 Declarative를 비교하며, Open-ended는 부작용 없는 업무부터 격리해 +실험한다.** 자세한 비교는 [세 가지 방법론 문서](patterns/index.md)에 있다. + +### 한 화면에서 비교하는 데모 + + + +*Screenshot S4. CopilotKit로 만든 “Generative UI Specs” 데모 애플리케이션의 +화면 녹화(33초, 음성 없음). 이 리서치가 참고용으로 확인한 데모이며 공개 +배포 주소는 확인하지 않았다. 화면의 값은 예시 데이터다.* + +데모는 같은 앱 안에서 세 방식을 나란히 실행한다. 왼쪽 카드에서 방식을 고르고 +오른쪽 채팅에서 요청하면 각 방식으로 UI가 생성된다. + +| 데모의 표기 | 이 문서의 방법론 | 데모가 보여 주는 동작 | +|---|---|---| +| Static GenUI | Controlled | 도구 호출 시 미리 만든 React 컴포넌트(Weather·Stocks·Tasks)를 표시 | +| MCP Apps | Open-ended(호스트 내 도구 UI) | MCP 서버가 제공한 HTML/JS 앱(Flights·Trading·Calculator)을 iframe에 표시 | +| A2UI | Declarative | 에이전트가 만든 JSON UI(Contact Form·Todo List·Profile Card)를 런타임에 렌더링 | + +데모의 Protocol Comparison 표도 같은 축을 쓴다. UI 정의는 React 컴포넌트 · +HTML/JS 앱 · JSON schema로, 통제 주체는 프런트엔드 개발자 · MCP 서버 · +AI 에이전트로 나뉜다. 이 문서가 표현 자유도와 실행 권한을 분리해 설명하는 +이유가 화면으로 드러난다. + +두 가지는 주의해서 읽는다. 첫째, 데모의 **Static GenUI는 현재 CopilotKit +문서의 Controlled와 같은 개념**이며 과거 명칭이다. 둘째, 한 앱이 세 방식을 +모두 지원한다는 사실이 **세 방식을 모두 배포해야 한다는 뜻은 아니다.** + +## CopilotKit 저장소를 어떻게 볼 것인가 + +이후 실제 개발 프레임워크를 고를 때를 대비해 [CopilotKit 공개 +저장소][copilotkit]의 성격만 짧게 정리한다. + +- **위치**: 에이전트와 사용자 사이의 수평 계층을 자처하는 풀스택 SDK다. + React 라이브러리로 시작했고 현재는 React·Angular·Vue·React Native와 + Slack·Microsoft Teams 같은 표면을 함께 다룬다고 설명한다. +- **기능 축**: Chat UI, Backend Tool Rendering, Generative UI, Shared State, + Human-in-the-Loop가 별도 기능으로 나열된다. 생성 UI가 전체가 아니라 + **하나의 축**이라는 점이 이 문서의 구분과 일치한다. +- **프로토콜 관계**: 저장소는 자신을 AG-UI 프로토콜의 주관 주체로 소개하고 + Google·LangChain·AWS·Microsoft 등의 채택을 언급한다. 채택 주장과 개별 + 기능의 동등한 지원은 구분해 확인한다. +- **시작 경로**: `npx copilotkit@latest create`로 새 프로젝트를 만들고, + 기존 앱에는 onboarding CLI를 사용하는 흐름을 안내한다. PoC를 빠르게 세울 + 때 유용한 출발점이다. +- **운영 확장**: 스레드 영속화, 사용자 메모리, 분석 같은 항목은 + CopilotKit Intelligence라는 **별도 제품**으로 분리되어 있고 자체 호스팅 + 옵션을 제공한다. 오픈소스 SDK의 범위와 혼동하지 않는다. + +## 어떤 프레임워크에 적용할 수 있는가 + +프런트엔드 프레임워크 지원은 **계층마다 다르다.** “React·Vue·Angular를 +지원한다”는 말은 어느 계층의 이야기인지 확인해야 한다. 조사일의 공식 문서 +기준은 다음과 같다. + +| 계층 | React | Vue | Angular | 그 밖의 확인 사항 | +|---|---|---|---|---| +| CopilotKit 프런트엔드 | 1st party | 1st party (`@copilotkit/vue`, Vue 3.3+) | 1st party (`@copilotkit/angular`, Angular 22 signal 기반) | React Native·React SPA 별도 가이드 제공 | +| A2UI 공식 renderer | Stable(v0.9.1) | **공식 renderer 없음** | Stable(v0.9.1) | Lit(Web Components), Flutter GenUI SDK도 Stable | +| MCP Apps의 앱(iframe 내부) | 시작 템플릿 제공 | 시작 템플릿 제공 | 공식 템플릿 없음 | 표준 웹 기술이면 프레임워크 무관 | + +읽는 방법은 다음과 같다. + +- **Vue로 A2UI를 쓰려면** 공식 renderer가 없으므로 Lit renderer를 Web + Components로 끼우거나 커뮤니티 구현을 검토해야 한다. CopilotKit이 Vue를 + 지원한다는 사실과는 별개의 문제다. +- **Angular는** CopilotKit과 A2UI 양쪽에 공식 경로가 있다. 다만 Angular 22, + Node.js 22처럼 요구 버전이 명시되어 있으므로 기존 앱의 버전을 먼저 본다. +- **MCP Apps의 앱은** 호스트 안 iframe에서 동작하는 독립 웹 앱이다. 여기서의 + 프레임워크 선택은 호스트가 아니라 앱 개발자의 자유다. + +백엔드 쪽은 프로토콜 어댑터의 문제다. AG-UI는 Microsoft Agent Framework, +LangGraph 등 여러 에이전트 런타임과 연결되지만 **언어별 SDK의 지원 범위가 +다르다.** MCP Apps는 호스트가 지원해야 표시되며, 조사일 공식 문서는 Claude, +Claude Desktop, VS Code GitHub Copilot, Microsoft 365 Copilot 등을 지원 +호스트로 나열한다. + +즉 기술 선택은 “무엇을 지원하는가”가 아니라 **“내가 쓰는 프레임워크·런타임· +호스트의 조합에서 무엇이 Stable인가”**로 좁혀야 한다. 계층별 근거는 +[프로토콜 조합 문서](protocols/index.md)와 +[A2UI renderer 표](google-a2ui/index.md)에서 확인한다. + +## 질문과 독자 + +대상은 에이전트 기반 제품을 설계하는 아키텍트, 프런트엔드 개발자, 에이전트 +개발자와 기술 의사결정자다. 다음 질문에 답하는 것이 목표다. + +1. 채팅 답변을 넘어 언제 UI 자체를 생성·선택해야 하는가? +2. CopilotKit, AG-UI, MCP Apps, A2UI는 어떤 책임을 분리하는가? +3. Google의 Generative UI 연구를 제품 설계에 어떻게 적용하고, 어디까지 + 일반화하지 말아야 하는가? +4. 향후 Demo에서 어떤 가설을 검증해야 도입 여부를 판단할 수 있는가? + +예시는 제품 비교, 서비스 예약, 고객지원 등 가상의 소비자 서비스 업무다. +특정 조직의 로드맵, 내부 시스템, 데이터 또는 도입 결정을 전제하지 않는다. + +## 조사 범위와 방법 + +- CopilotKit의 분류 설명과 공개 저장소, AG-UI 문서, MCP Apps 공식 문서, + A2UI 명세·문서, Google 연구 논문을 1차 자료로 사용한다. +- Microsoft Agent Framework의 공식 AG-UI 문서를 보조 구현 사례로 + 교차 확인한다. 이 문서는 이벤트·상태·도구 호출을 통한 연결을 설명하며, + 언어별 SDK 지원 차이를 명시한다. 모든 런타임의 동일 지원을 뜻하지 않는다. +- 공개 명세의 사실, 논문 저자의 실험 결과, 이 리서치의 설계 권고를 구분한다. +- 버전 번호와 지원 상태는 조사일의 공개 문서 기준이다. 홈페이지의 표현과 + 개별 구현·명세의 적용 범위가 다르면 더 좁은 범위를 따른다. +- SDK를 설치한 E2E 통합, 제품 성능 벤치마크, 실제 사용자 실험은 수행하지 + 않았다. 문서·이미지·사이트 검증을 런타임 검증으로 표현하지 않는다. + +## 프로토콜은 한 줄의 대체 관계가 아니다 + +![AG-UI의 이벤트 연결, A2UI의 선언적 렌더링, MCP Apps의 호스트 내 도구 UI를 서로 다른 책임과 선택 가능한 경로로 구분한 도식](images/protocol-responsibilities.svg) + +*그림 1. 공식 문서의 책임 경계를 바탕으로 직접 작성한 개념도. +모든 블록을 반드시 배포해야 한다는 뜻은 아니다.* + +| 구분 | 담당하는 계약 | 이것만으로 해결하지 않는 문제 | +|---|---|---| +| CopilotKit | 에이전트 UI를 만들기 위한 프런트엔드·런타임 구현 도구 | 업무 도메인 설계, 모든 프레임워크의 자동 호환 | +| AG-UI | 에이전트 실행에서 나오는 메시지·도구·상태 이벤트와 클라이언트 상호작용 | 범용 UI 컴포넌트 카탈로그, 서버 권한 정책 | +| A2UI | UI surface, 컴포넌트, 데이터와 사용자 액션을 기술하는 선언적 계약 | 모든 플랫폼의 렌더러 구현, 전송 계층과 업무 실행 | +| MCP | 도구·리소스 등을 노출하고 호출하는 통신 계약 | 자연어 이해, 업무 의도 추론, 화면 디자인 | +| MCP Apps | 도구와 연결된 UI 리소스 및 앱과 호스트 사이의 상호작용 | 모든 호스트의 지원, 임의 코드의 무조건적 안전성 | + +근거는 [CopilotKit AG-UI 설명][agui], [MCP Apps 공식 개요][mcp-apps], +[A2UI 공식 문서][a2ui]다. “표준”이라는 표현은 여기서 공개 프로토콜·명세를 +의미하며, 단일한 산업 표준의 확정이나 구현 간 무조건적인 상호운용성을 뜻하지 않는다. + +## 목적별 읽는 순서 + +| 문서 | 핵심 질문 | 독자 | +|---|---|---| +| [세 가지 Generative UI 패턴](patterns/index.md) | 생성 자유도와 개발자 통제를 어떻게 선택하는가 | 제품·프런트엔드 설계자 | +| [CopilotKit와 프로토콜 조합](protocols/index.md) | AG-UI, MCP, MCP Apps는 어디에 연결되는가 | 에이전트·플랫폼 개발자 | +| [Google 연구와 A2UI](google-a2ui/index.md) | 논문의 근거와 A2UI 명세·E2E는 무엇이 다른가 | 아키텍트·연구 담당자 | +| [도입 아키텍처와 평가 계획](adoption/index.md) | 어떤 순서와 기준으로 제품에 도입하는가 | 기술 의사결정자·구현팀 | + +방향 판단에는 이 요약과 도입 문서를, 설계에는 패턴·프로토콜·A2UI 문서를 +함께 읽는다. 관련 자식 문서는 하나의 조사 기준일을 공유한다. + +## Frontier 패턴에 대한 판단 + +유망한 방향은 “모든 화면을 매번 생성”하는 것이 아니라 **의도에 맞는 화면을 +제안하되, 제품의 디자인 시스템과 실행 권한은 애플리케이션이 소유**하는 것이다. + +가령 비교 대상과 비교 항목은 동적으로 구성하더라도, 가격·재고는 업무 API에서 +조회하고 구매는 서버의 확인·권한 검사를 통과해야 한다. 설명용 시각화와 거래 +실행 UI에 같은 자유도를 줄 필요가 없다. + +A2UI 생태계 참여는 이 관점에서 평가한다. 실제 화면의 카탈로그를 정의하고, +지원 가능한 버전과 컴포넌트 범위를 공개하며, 렌더러 호환성 테스트와 +접근성 개선에 기여하는 접근이 단순한 로고·프로토콜 채택보다 유용하다. +참여 자체가 프런트엔드 교체 비용을 없애거나 특정 기술의 장기 생존을 +보장한다는 주장은 하지 않는다. + +## 한계와 다음 검증 + +- 제공된 자료는 생태계 전체를 망라한 경쟁 제품 조사 목록이 아니다. +- 공식 프로젝트의 예제와 제품 소개는 통합 가능성을 보여 주는 자료이며, + 독립적인 운영 성능 증명으로 취급하지 않는다. +- UI 표현 계약을 분리해도 업무 데이터 스키마, 사용자 인증과 오류 처리 계약이 + 강하게 결합되어 있으면 프런트엔드 교체 비용은 남는다. +- 이번 산출물은 문서 조사와 화면 확인까지다. 아래 진행 방향은 계획이며 + 구현·측정 결과가 아니다. + +## 향후 Demo 및 진행 방향 + +### 1단계: PoC 컨셉 데모 (code-level) + +목표는 “세 방식이 같은 업무에서 어떻게 다른가”를 **코드로 비교 가능한 상태**로 +만드는 것이다. 위 데모처럼 하나의 앱에서 세 방식을 전환할 수 있으면 충분하다. + +| 항목 | PoC 기준 | +|---|---| +| 업무 시나리오 | 가상의 제품 비교와 예약 확정 하나씩. 읽기와 쓰기를 모두 포함한다 | +| 프런트엔드 | 팀의 주력 프레임워크 하나로 고정한다. React·Vue·Angular 중 A2UI renderer 지원 여부를 먼저 확인한다 | +| 연결 계층 | AG-UI 엔드포인트 하나. 백엔드 런타임은 교체 실험 대상으로 남긴다 | +| Controlled | 기존 디자인 시스템 컴포넌트를 도구 호출에 매핑한다 | +| Declarative | 컴포넌트 5~10개의 최소 A2UI 카탈로그와 버전을 고정한다 | +| Open-ended | 부작용 없는 설명 화면에만 적용하고 iframe·CSP 정책을 명시한다 | +| 실행 게이트 | 예약 확정은 서버에서 권한·슬롯·멱등성 키를 재검증한다 | +| 계측 | 모델 호출 수, 첫 화면 표시 시간, 첫 정상 액션 가능 시간, 실패율 | + +산출물은 화면 몇 개가 아니라 **재생 가능한 fixture**다. UI payload와 액션을 +비식별화해 저장하면 2단계의 렌더러 교체 실험에 그대로 쓸 수 있다. + +시작 경로로는 `npx copilotkit@latest create` 같은 스캐폴딩이 빠르지만, PoC의 +목적은 프레임워크 학습이 아니라 **계약 검증**이다. 카탈로그·스키마·권한 +경계를 우리 코드로 소유하는지 확인하면서 진행한다. + +### 2단계: Global Production 기준 고려 사항 + +PoC가 통과해도 전 세계 사용자를 대상으로 하는 운영은 별도 요구사항을 만든다. + +| 영역 | 확인할 것 | +|---|---| +| 지연·지역 | 모델·런타임·정적 자산의 리전 배치. 생성 지연은 지역별로 다르게 체감된다 | +| 비용 | 화면 1회 생성당 토큰·도구 호출 비용. 직접 액션 경로로 추론을 줄일 여지 | +| 현지화 | 생성된 문구·날짜·통화·단위. 카탈로그 컴포넌트가 RTL과 긴 문자열을 견디는지 | +| 접근성 | 키보드 탐색, 이름·역할, 포커스 이동, 동적 갱신 알림. 지역별 법규 요구 수준 | +| 데이터 보호 | 프롬프트·UI 데이터·로그의 저장 위치와 보존 기간. 지역별 이전 제약 | +| 안전성 | 생성 콘텐츠 검수, 외부 리소스 허용 목록, iframe 격리와 권한 최소화 | +| 가용성 | 생성 실패·타임아웃 시의 검증된 대체 화면. 실패를 완료처럼 보이지 않게 한다 | +| 버전 관리 | schema·카탈로그·renderer·호스트의 호환 조합 고정과 단계적 롤아웃 | +| 운영 관측 | 상관관계 ID로 생성·렌더·액션·업무 실행을 연결한 추적 | +| 조직 | 스레드 영속화·메모리·분석 기능을 직접 만들지, 별도 제품을 쓸지의 경계 | + +특히 **비용과 지연은 기능이 아니라 제품 결정**이다. 모든 화면을 생성하는 +대신 자주 쓰는 조합을 카탈로그로 고정하면 품질과 비용을 함께 잡을 수 있다. +평가 기준과 통과 조건은 [도입 아키텍처와 평가 계획](adoption/index.md)에서 +합의한 뒤 시작한다. + +## 공식 출처 + +| 출처 | 이 페이지에서 사용한 범위 | +|---|---| +| [CopilotKit Generative UI][taxonomy] | 세 패턴과 생성·선택 통제의 구분 | +| [CopilotKit AG-UI][agui] | 앱과 에이전트의 연결, 이벤트와 공유 상태 | +| [MCP Apps][mcp-apps] | 도구 UI 리소스, 호스트 렌더링과 양방향 상호작용 | +| [A2UI][a2ui] | 선언적 UI, 클라이언트 렌더링과 버전별 명세 | +| [Google Generative UI 연구][paper-project] | 연구 범위와 평가 한계의 출발점 | +| [Microsoft Agent Framework AG-UI][learn-agui] | 프로토콜과 런타임 어댑터 경계의 보조 구현 사례 | +| [Gemini 3 앱 소개][gemini-app] | generative interfaces와 dynamic view 화면의 출처 | +| [CopilotKit 저장소][copilotkit] | SDK의 기능 축, 지원 프런트엔드와 시작 경로 | +| [CopilotKit Vue 프런트엔드][ck-vue] | Vue 3.3+ 1st party 지원 범위 | +| [CopilotKit Angular 프런트엔드][ck-angular] | Angular 22 signal 기반 지원 범위 | +| [A2UI Renderer 지원표][renderers] | 프레임워크별 공식 renderer 상태 | + +## 참고 문서 + +### 문서와 자산 구조 + +이 주제는 entry 문서 하나와 자식 문서 넷, 그리고 공용 자산 폴더로 구성한다. +모든 이미지는 `images/` 한 곳에 두며 문서별 하위 폴더를 만들지 않는다. + +```text +agentic-app-genui/ +├── index.md ← 이 문서(전체 요약과 읽는 순서) +├── patterns/index.md ← 세 가지 방법론 비교 +├── protocols/index.md ← CopilotKit·AG-UI·MCP Apps 책임 분리 +├── google-a2ui/index.md ← Google 연구와 A2UI 명세 +├── adoption/index.md ← 도입 아키텍처와 평가 계획 +├── images/ ← 모든 그림과 영상을 한 폴더에 보관 +│ ├── *.svg 직접 작성한 분석용 개념도 5개 +│ ├── *-original.png|svg 재배포가 허용된 공식 원본 도식 5개 +│ ├── *-screenshot.png 공개 페이지·데모 화면 캡처 2개 +│ ├── gemini-dynamic-view-screencast.gif 제품 소개 영상 축약본 +│ └── demo-generative-ui.mp4 세 방식 비교 데모 화면 녹화 +└── licenses/ ← 라이선스 원문과 출처·SHA-256 기록 +``` + +파일 이름이 곧 자산의 성격을 나타낸다. 접미사가 없는 SVG는 이 리서치가 +직접 작성한 도식, `-original`은 공식 프로젝트의 원본 도식, `-screenshot`과 +영상 파일은 공개 페이지·데모를 캡처한 자료다. + +### 수록한 그림 목록 + +| 공식 원본 도식 | 수록 문서 | 재배포 조건 | +|---|---|---| +| CopilotKit Controlled 예시(C1) | [패턴 비교](patterns/index.md) | MIT, 원본 유지 | +| CopilotKit Declarative 개요(C2) | [패턴 비교](patterns/index.md) | MIT, 원본 유지 | +| AG-UI 공식 개요(P1) | [프로토콜 조합](protocols/index.md) | MIT, 원본 유지 | +| Google Generative UI 시스템(G1) | [Google 연구와 A2UI](google-a2ui/index.md) | CC BY-SA 4.0, 원본 유지 | +| A2UI E2E data flow(A1) | [Google 연구와 A2UI](google-a2ui/index.md) | Apache-2.0, v0.8 계열 표현임을 명시 | + +| Screenshot | 수록 문서 | 출처와 사용 조건 | +|---|---|---| +| S1. Gemini dynamic view 화면 녹화(GIF) | 이 문서 | [Gemini 3 앱 소개][gemini-app]. 편집된 소개 영상, 인용 | +| S2. AG-UI Dojo 실행 화면 | [패턴 비교](patterns/index.md) | [AG-UI Dojo][dojo]. 공개 데모 실행 화면, 인용 | +| S3. CopilotKit 제품 소개 화면 | [프로토콜 조합](protocols/index.md) | [제품 페이지][copilotkit-product]. 벤더 주장, 인용 | +| S4. 세 방식 비교 데모 녹화(MP4) | 이 문서 | CopilotKit 기반 데모 애플리케이션. 공개 배포 주소 미확인 | + +Screenshot은 원문의 주장과 화면 구성을 설명하기 위한 인용이며 저작권은 각 +저작자에게 있다. 사용한 조합의 동작을 이 저장소가 검증했다는 뜻이 아니다. +S1의 GIF는 원본 영상을 8fps·680px로, S4의 MP4는 1280px·30fps·무음으로 다시 +인코딩한 축약본이다. Google 연구 사이트의 방법 개요는 같은 그림을 공식 +SVG(G1)로 이미 수록했으므로 화면 캡처를 따로 두지 않는다. + +[이미지 출처·revision·라이선스 기록](licenses/third-party-images.txt)과 +라이선스 원문을 함께 보존한다. 특정 프로젝트의 로고가 포함된 도식은 원문 +설명을 위한 인용 자료이며 해당 프로젝트의 보증·추천을 의미하지 않는다. + +[copilotkit-product]: https://www.copilotkit.ai/product +[dojo]: https://dojo.ag-ui.com/ +[taxonomy]: https://www.copilotkit.ai/generative-ui +[agui]: https://docs.copilotkit.ai/agentic-protocols/ag-ui +[mcp-apps]: https://modelcontextprotocol.io/extensions/apps/overview +[a2ui]: https://a2ui.org/ +[paper-project]: https://generativeui.github.io/ +[learn-agui]: https://learn.microsoft.com/agent-framework/integrations/by-component/ui/ag-ui/ +[gemini-app]: https://blog.google/products/gemini/gemini-3-gemini-app/ +[copilotkit]: https://github.com/CopilotKit/CopilotKit +[ck-vue]: https://docs.copilotkit.ai/vue +[ck-angular]: https://docs.copilotkit.ai/angular +[renderers]: https://a2ui.org/reference/renderers/ diff --git a/docs/services/application-development/agentic-app-genui/licenses/a2ui-Apache-2.0.txt b/docs/services/application-development/agentic-app-genui/licenses/a2ui-Apache-2.0.txt new file mode 100644 index 00000000..38e00abf --- /dev/null +++ b/docs/services/application-development/agentic-app-genui/licenses/a2ui-Apache-2.0.txt @@ -0,0 +1,227 @@ + + Apache License + Version 2.0, January 2004 + https://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +-------------------------------------------------------------------------------- +The file eval/bin/transcrypt is licensed under the MIT License: + +Copyright (c) 2019-2025 James Murty +Copyright (c) 2014-2020 Aaron Bull Schaefer + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +-------------------------------------------------------------------------------- diff --git a/docs/services/application-development/agentic-app-genui/licenses/ag-ui-MIT.txt b/docs/services/application-development/agentic-app-genui/licenses/ag-ui-MIT.txt new file mode 100644 index 00000000..b77bf2ab --- /dev/null +++ b/docs/services/application-development/agentic-app-genui/licenses/ag-ui-MIT.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/docs/services/application-development/agentic-app-genui/licenses/copilotkit-MIT.txt b/docs/services/application-development/agentic-app-genui/licenses/copilotkit-MIT.txt new file mode 100644 index 00000000..b3bf13de --- /dev/null +++ b/docs/services/application-development/agentic-app-genui/licenses/copilotkit-MIT.txt @@ -0,0 +1,21 @@ +The MIT License + +Copyright (c) Atai Barkai + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/docs/services/application-development/agentic-app-genui/licenses/google-CC-BY-SA-4.0.txt b/docs/services/application-development/agentic-app-genui/licenses/google-CC-BY-SA-4.0.txt new file mode 100644 index 00000000..7d4f96c5 --- /dev/null +++ b/docs/services/application-development/agentic-app-genui/licenses/google-CC-BY-SA-4.0.txt @@ -0,0 +1,427 @@ +Attribution-ShareAlike 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution-ShareAlike 4.0 International Public +License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution-ShareAlike 4.0 International Public License ("Public +License"). To the extent this Public License may be interpreted as a +contract, You are granted the Licensed Rights in consideration of Your +acceptance of these terms and conditions, and the Licensor grants You +such rights in consideration of benefits the Licensor receives from +making the Licensed Material available under these terms and +conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. BY-SA Compatible License means a license listed at + creativecommons.org/compatiblelicenses, approved by Creative + Commons as essentially the equivalent of this Public License. + + d. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + e. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + f. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + g. License Elements means the license attributes listed in the name + of a Creative Commons Public License. The License Elements of this + Public License are Attribution and ShareAlike. + + h. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + i. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + j. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + k. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + l. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + m. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. Additional offer from the Licensor -- Adapted Material. + Every recipient of Adapted Material from You + automatically receives an offer from the Licensor to + exercise the Licensed Rights in the Adapted Material + under the conditions of the Adapter's License You apply. + + c. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + b. ShareAlike. + + In addition to the conditions in Section 3(a), if You Share + Adapted Material You produce, the following conditions also apply. + + 1. The Adapter's License You apply must be a Creative Commons + license with the same License Elements, this version or + later, or a BY-SA Compatible License. + + 2. You must include the text of, or the URI or hyperlink to, the + Adapter's License You apply. You may satisfy this condition + in any reasonable manner based on the medium, means, and + context in which You Share Adapted Material. + + 3. You may not offer or impose any additional or different terms + or conditions on, or apply any Effective Technological + Measures to, Adapted Material that restrict exercise of the + rights granted under the Adapter's License You apply. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material, + including for purposes of Section 3(b); and + + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. diff --git a/docs/services/application-development/agentic-app-genui/licenses/third-party-images.txt b/docs/services/application-development/agentic-app-genui/licenses/third-party-images.txt new file mode 100644 index 00000000..63d78574 --- /dev/null +++ b/docs/services/application-development/agentic-app-genui/licenses/third-party-images.txt @@ -0,0 +1,138 @@ +THIRD-PARTY IMAGE ATTRIBUTION +Retrieved and reviewed: 2026-09-21 +Screen captures added and reviewed: 2026-09-22 + +The following original images are reproduced without modification. Local file +renaming and proportional display sizing do not change their content. +These individual assets retain the licenses stated below. Their licenses do +not replace the license of unrelated repository content. Names and logos in +the originals are used for source identification, not endorsement. + +C1: ../images/copilotkit-controlled-original.png +Title: Controlled Generative UI example +Author/project: CopilotKit. Copyright (c) Atai Barkai. +Source revision: cddbf0cc085475ea4836a6241e51ba76799adc20 +Source: https://github.com/CopilotKit/CopilotKit/blob/cddbf0cc085475ea4836a6241e51ba76799adc20/examples/showcases/generative-ui/assets/static-generative-ui-example.png +License: MIT; full notice in copilotkit-MIT.txt. +SHA-256: a1774f0a02c7a0f4e8eb40b6cb9be5065d0e8b7a13d4f98fa30019bbe2b44b38 +Git LFS payload downloaded, not the pointer file. + +C2: ../images/copilotkit-declarative-original.png +Title: Declarative Generative UI overview +Author/project: CopilotKit. Copyright (c) Atai Barkai. +Source revision: cddbf0cc085475ea4836a6241e51ba76799adc20 +Source: https://github.com/CopilotKit/CopilotKit/blob/cddbf0cc085475ea4836a6241e51ba76799adc20/examples/showcases/generative-ui/assets/declarative-generative-ui-overview.png +License: MIT; full notice in copilotkit-MIT.txt. +SHA-256: a1285492c95a79b754db617c57d6918d9857e983d38f4b787eae65fb3fd6bf2c +Git LFS payload downloaded, not the pointer file. + +P1: ../images/ag-ui-overview-original.png +Title: AG-UI Overview +Author/project: AG-UI Protocol contributors. Copyright (c) 2025. +Source revision: f08ccf853497914ef70a5f0197af45bb74915bc2 +Source: https://github.com/ag-ui-protocol/ag-ui/blob/f08ccf853497914ef70a5f0197af45bb74915bc2/docs/images/ag-ui-overview-with-partners.png +Context: https://docs.ag-ui.com/introduction +License: MIT; full notice in ag-ui-MIT.txt. + +G1: ../images/google-generative-ui-system-original.svg +Title: High Level Method Overview / System Diagram +Authors: Yaniv Leviathan, Dani Valevski, Matan Kalman, Danny Lumen, +Eyal Segalis, Eyal Molad, Shlomi Pasternak, Vishnu Natchu, Valerie Nygaard, +Srinivasan (Cheenu) Venkatachary, James Manyika, Yossi Matias; Google Research. +Source: https://generativeui.github.io/static/images/sys_diagram_dotted.svg +Context and license declaration: https://generativeui.github.io/ +License: Creative Commons Attribution-ShareAlike 4.0 International. +License URL: https://creativecommons.org/licenses/by-sa/4.0/ +Full legal code: google-CC-BY-SA-4.0.txt +SHA-256: ea495ecffb50c5cd26705d7b3eff1cd63671cd086c9573db2abae8f2b06402bd +This is the website-published SVG, not a reproduction of the complete PDF. +No changes made. The asset remains available under CC BY-SA 4.0. + +A1: ../images/a2ui-end-to-end-original.png +Title: The End-to-End Data Flow +Author/project: A2UI project contributors. +Source revision: 2d2a714dafd22590e705c32a47cd5390ab96fdc5 +Source: https://github.com/a2ui-project/a2ui/blob/2d2a714dafd22590e705c32a47cd5390ab96fdc5/docs/public/assets/end-to-end-data-flow.png +Context: https://a2ui.org/concepts/data-flow/ +License: Apache License 2.0; upstream license copy in a2ui-Apache-2.0.txt. +SHA-256: a960d0dce8a0af633adec75941589967ab65432e82152afc9e76ad76c83c95e8 +Version note: Original graphic uses v0.8-era surfaceUpdate, dataModelUpdate, +beginRendering and userAction names. See the adjacent document's v0.9.1 +mapping before using it as implementation guidance. + +Licensing boundaries +------------------- +CopilotKit marketing-site images are not presumed to inherit the software +repository license. C1 and C2 are files in the licensed GitHub repository. +The Google website's license is not presumed to license the entire paper. +No PDF, unrelated generated demo artwork, or complete third-party article is +redistributed here. Original analytical SVGs elsewhere in this topic are +separately authored diagrams, not altered copies of these source figures. + +Screen captures (quotation for commentary) +----------------------------------------- +The following assets are screen captures of publicly reachable product, +demo and research pages. They are included to describe and critique the +claims and interfaces those pages present. Copyright stays with each owner; +inclusion is not a license grant, an endorsement, or a compatibility +certification. No credentials, personal data, customer identifiers or +private screens appear in them. Browser chrome showing a local profile was +cropped out before publication. + +S1: ../images/gemini-dynamic-view-screencast.gif +Title: Generative UI in dynamic view - Van Gogh gallery example +Author/project: Google. Copyright (c) Google. +Source page: https://blog.google/products/gemini/gemini-3-gemini-app/ +Source asset: Dynamic_View_Van_Gogh_1920x1080_1.mp4 (Google blog video) +Captured: 2026-09-22 +Processing: re-encoded to GIF at 8 fps and 680 px width from a 17.8 s, +1424x888 recording. Frames are not otherwise altered; no frames added. +Notice retained from the original: "Sequences shortened and screen images +simulated. Check responses. Compatibility and availability varies. 18+." +License: no open license. Used as a short quotation for commentary. + +S2: ../images/ag-ui-dojo-backend-tool-rendering-screenshot.png +Title: AG-UI Interactive Dojo - Backend Tool Rendering demo +Author/project: AG-UI Protocol contributors and demo authors. +Source: https://dojo.ag-ui.com/langgraph/feature/backend_tool_rendering +Captured: 2026-09-22 +Processing: cropped to remove browser chrome and the local browser profile +indicator. No content changes inside the application area. +License: public demo screen, no separate license grant located. Used as a +quotation for commentary on the Controlled pattern. + +S3: ../images/copilotkit-product-overview-screenshot.png +Title: "Any frontend. Any agent." product overview +Author/project: CopilotKit. Copyright (c) CopilotKit. +Source: https://www.copilotkit.ai/product +Captured: 2026-09-22 +Processing: proportional downscale to 1400 px width. No content changes. +License: marketing-site content, no open license. Vendor product and +ecosystem logos identify the claim under discussion, not an endorsement. + +S4: ../images/demo-generative-ui.mp4 +Title: "Generative UI Specs" demo application walkthrough +Author/project: demo application built with CopilotKit; author not stated on +screen. No public distribution URL for this recording was confirmed. +Captured: 2026-09-22 +Processing: re-encoded to 1280 px width, 30 fps, audio removed, from a 33.5 s +3680x2160 60 fps recording. No frames added, removed or reordered. +Content note: the demo compares Static GenUI, MCP Apps and A2UI in one app. +All on-screen records are example data (example.com addresses, 555 phone +numbers, explicitly fictional place names). +License: no license grant located. Retained because it documents the three +approaches this topic compares; remove on request of the author. + +Materials reviewed but not redistributed +---------------------------------------- +"AG-UI and A2UI Explained" (CopilotKit, Google Docs PDF export) was read to +summarize the vendor's own framing of AG-UI, A2UI, Open-JSON-UI and MCP-UI. +The PDF itself is not committed. Its substantive claims were located in +public documentation and are cited from there instead: +https://docs.ag-ui.com/concepts/generative-ui-specs and +https://www.copilotkit.ai/ag-ui-and-a2ui. Remaining claims were cross-checked +against a2ui.org, docs.copilotkit.ai and modelcontextprotocol.io. +The source recordings behind S1 and S4 are not committed at original size; +only the reduced GIF and the re-encoded MP4 are published. A capture of the +generativeui.github.io method overview was dropped because the same figure is +already included as the CC BY-SA licensed original SVG (G1). diff --git a/docs/services/application-development/agentic-app-genui/patterns/index.md b/docs/services/application-development/agentic-app-genui/patterns/index.md new file mode 100644 index 00000000..d542dd32 --- /dev/null +++ b/docs/services/application-development/agentic-app-genui/patterns/index.md @@ -0,0 +1,265 @@ +--- +title: Controlled·Declarative·Open-ended Generative UI 패턴 +description: CopilotKit의 세 가지 Generative UI 패턴을 표현 자유도, 개발자 통제, 구현 경계와 적용 업무로 비교합니다. +document_type: research +topic_order: 1 +services: [application-development] +technologies: [mcp] +tags: [design, evaluate, ai-agents] +status: current +verification_status: verified +published_at: 2026-09-21 +sources_checked_at: 2026-09-22 +official_sources: + - title: "Generative UI: Understanding Agent-Powered Interfaces" + url: https://www.copilotkit.ai/generative-ui + - title: CopilotKit + url: https://github.com/CopilotKit/CopilotKit + - title: CopilotKit Generative UI showcase + url: https://github.com/CopilotKit/CopilotKit/blob/cddbf0cc085475ea4836a6241e51ba76799adc20/examples/showcases/generative-ui/README.md + - title: CopilotKit display-only components + url: https://docs.copilotkit.ai/generative-ui/your-components/display-only + - title: A2UI - A Protocol for Agent-Driven Interfaces + url: https://a2ui.org/ + - title: MCP Apps + url: https://modelcontextprotocol.io/extensions/apps/overview + - title: AG-UI Integration with Agent Framework + url: https://learn.microsoft.com/agent-framework/integrations/by-component/ui/ag-ui/ + - title: AG-UI Interactive Dojo + url: https://dojo.ag-ui.com/ +--- + +# Controlled·Declarative·Open-ended Generative UI 패턴 + +**기준일: 2026-09-21. Screenshot 확인일: 2026-09-22.** +[CopilotKit의 Generative UI 분류][taxonomy]는 +에이전트 기반 인터페이스의 표현 방식을 이해하기 위한 틀이다. 세 패턴은 +서로 배타적인 제품 목록도, Controlled에서 Open-ended로 이동해야 한다는 +성숙도 단계도 아니다. + +조사일의 원문은 **Open**을 현재 이름, **Open-ended**를 이전 이름으로 함께 +설명한다. 이 문서는 요청 범위와의 연결을 위해 Open-ended 표기를 유지한다. +Controlled도 과거 자료에서는 Static으로 나타난다. 현재 소개 페이지는 +MCP Apps를 세 패턴 옆의 **special case**로 분리한다. + +## 질문 + +모델이 **무엇을 바꿀 수 있도록 허용할 것인가?** 컴포넌트 선택만 허용할지, +컴포넌트 조합을 허용할지, HTML·코드까지 생성하게 할지에 따라 테스트 대상과 +실패 방식이 달라진다. + +![Controlled는 기존 컴포넌트 선택, Declarative는 카탈로그 기반 UI 기술, Open-ended는 HTML·코드 표현을 사용하며 표시 시점의 결정 주체는 별개임을 보여 주는 도식](../images/generative-ui-patterns.svg) + +*그림 2. CopilotKit의 분류를 바탕으로 직접 작성한 비교도. +패턴의 이름과 실제 적용 권고를 구분한다.* + +## 결과: 세 패턴 비교 + +| 축 | Controlled | Declarative | Open-ended | +|---|---|---|---| +| 주된 표현 | 이미 구현된 UI 컴포넌트와 인자 | 허용된 UI 요소의 선언적 구성과 데이터 | HTML·코드 등 더 자유로운 표현 | +| 개발자가 고정하는 것 | 컴포넌트의 화면 구조·상호작용 | 카탈로그, renderer, 속성·액션 계약 | 호스트 경계, 실행·리소스·접근 정책 | +| 에이전트에 허용하는 선택 | 어떤 컴포넌트를 언제 어떤 값으로 표시할지 | 어떤 허용 요소를 어떻게 구성할지 | 허용된 실행 환경 내 콘텐츠·표현 방식 | +| 대표적인 연결 방식 | 도구 호출과 기존 UI의 매핑 | A2UI 같은 선언적 UI 계약 | 생성 HTML 또는 별도로 작성된 도구 UI | +| 주된 테스트 단위 | 도구 스키마, 인자, 컴포넌트 상태 | payload, 카탈로그, 데이터·액션 바인딩 | 생성물 동작, 격리, 외부 리소스, 콘텐츠 품질 | +| 적합성을 검토할 업무 | 가격 카드, 예약 폼, 승인 UI | 요청에 따라 달라지는 비교·요약·다단계 화면 | 설명용 시각화, 탐색형 콘텐츠 | + +분류·표현 방식은 [CopilotKit][taxonomy]에 근거한다. 테스트 단위와 업무 예시는 +이를 제품 개발에 적용하기 위한 이번 리서치의 분석이다. + +## Controlled: 만들어 둔 UI를 올바른 순간에 제공 + +![CopilotKit 공식 Controlled Generative UI 예시. 개발자가 정의한 날씨 UI를 도구 호출에 연결하는 구조](../images/copilotkit-controlled-original.png) + +*Screenshot C1. CopilotKit, 공식 Generative UI showcase의 +[Controlled 예시][showcase]. [MIT](../licenses/copilotkit-MIT.txt), 변경 없이 수록. +그림·샘플의 API 이름은 해당 revision의 예시이며 최신 SDK 전체에 대한 API 보증이 아니다.* + +[로컬 원본 확대](../images/copilotkit-controlled-original.png) + +개발자가 제품 카드, 비교표, 예약 폼을 미리 구현한다. 에이전트의 도구 호출이나 +애플리케이션 상태에 맞춰 컴포넌트를 선택하고 구조화된 값을 전달한다. + +![AG-UI Dojo의 Backend Tool Rendering 데모 실행 화면. 왼쪽에 LangGraph(Python) 통합과 데모 목록이 있고, 오른쪽 대화 영역에는 도구 결과로 채워진 뉴욕 날씨 카드와 온도·습도·풍속 값, 그 아래 같은 내용을 설명하는 문장과 후속 질문 버튼이 표시된다](../images/ag-ui-dojo-backend-tool-rendering-screenshot.png) + +*Screenshot S2. [AG-UI Dojo][dojo]의 Backend Tool Rendering 데모를 조사일에 실행한 +화면. 저작권은 각 프로젝트에 있으며 설명을 위한 인용이다. 브라우저 표시 영역은 +제외했다.* + +이 화면은 Controlled를 이해하는 데 유용하다. 날씨 카드의 레이아웃, 아이콘, 지표 +배치는 모두 미리 구현된 컴포넌트다. 에이전트는 도구를 호출하고 도시와 측정값을 +전달할 뿐이며, 카드 아래 텍스트 답변과 후속 질문 버튼도 개발자가 정의한 +표현이다. 같은 Dojo에서 Human in the loop, Agentic Generative UI 같은 시나리오를 +별도 데모로 제공한다는 점도 함께 읽어야 한다. **생성 UI 도입은 하나의 화면 생성 +API를 붙이는 일이 아니라 시나리오별로 다른 계약을 설계하는 일**이다. + +Dojo는 공개 데모이므로 도입 검토 시 기준선 비교의 출발점으로 쓸 수 있다. +다만 데모의 동작이 선택한 런타임·모델·renderer 조합에서 그대로 재현된다는 +보증은 아니다. + +장점은 기존 디자인 시스템, 접근성 검사, 오류·로딩 상태를 재사용할 수 +있다는 점이다. 반면 요청에 맞는 컴포넌트가 없으면 새로운 UI를 구현해야 한다. +카탈로그가 크다고 조합의 자유도까지 높아지는 것은 아니다. + +예를 들어 제품 세 개를 비교하는 카드가 있다면 에이전트는 제품 ID와 비교 +항목을 선택할 수 있다. 재고·가격·호환 여부는 모델이 추측해 채우는 대신 +업무 API의 값을 받아야 한다. 이는 패턴이 자동 보장하는 기능이 아니라 설계 규칙이다. + +### 권고 + +- 기존 제품의 안정적인 화면을 기준선으로 유지하고 대화에서 그 화면으로 + 자연스럽게 전환하는 효과부터 측정한다. +- 컴포넌트의 준비·진행·실패·완료 상태를 명시한다. 도구 호출이 시작됐다는 + 이유만으로 성공 UI를 표시하지 않는다. +- 화면을 표시하는 도구와 실제로 주문·예약을 변경하는 도구의 책임을 구분한다. + +## Declarative: 허용된 언어 안에서 화면을 조합 + +![CopilotKit 공식 Declarative Generative UI 개요. 에이전트의 구조화된 UI 표현을 클라이언트가 렌더링하는 접근](../images/copilotkit-declarative-original.png) + +*Screenshot C2. CopilotKit, 공식 Generative UI showcase의 +[Declarative 개요][showcase]. [MIT](../licenses/copilotkit-MIT.txt), 변경 없이 수록. +그림 속 spec·payload는 패턴 이해용이며 A2UI v0.9.1의 wire schema로 사용하지 않는다.* + +[로컬 원본 확대](../images/copilotkit-declarative-original.png) + +UI 전체 코드를 출력하는 대신, 허용된 컴포넌트와 데이터·액션을 기술한다. +클라이언트는 이 기술을 자신이 구현한 컴포넌트에 매핑해 렌더링한다. +[A2UI][a2ui]가 이 방식을 다루는 주요 공개 명세다. + +가령 요청마다 비교 항목, 안내 문구, 입력 폼의 조합이 달라질 수 있다. 그러나 +지원하지 않는 결제 컴포넌트나 실행 코드를 임의로 추가하는 권한까지 부여하는 +것은 아니다. 어떤 요소와 액션을 허용하는지는 카탈로그와 클라이언트가 결정한다. + +“선언적이면 안전하다”는 표현도 제한해서 사용해야 한다. 임의 코드 실행의 +범위를 줄일 수 있지만, 잘못된 가격·오해를 부르는 설명·허용되지 않은 업무 +액션은 별개의 문제다. 데이터와 액션 검증은 여전히 필요하다. + +### 권고 + +- 여러 화면에서 반복되는 조합부터 카탈로그화한다. 모든 UI 요소를 처음부터 + 모델에 노출하지 않는다. +- 카탈로그의 속성뿐 아니라 액션, 로딩 상태, 접근성 의미를 계약에 포함한다. +- 같은 UI 기술을 다른 프런트엔드에서 쓰려면 해당 renderer와 컴포넌트 구현을 + 마련하고 [호환성 fixture](../adoption/index.md)로 검증한다. +- 스키마 오류를 자동 복구했으면 복구 사실을 기록한다. 복구에 실패하면 + 사용자에게 대체 화면과 진단 가능한 오류를 제공한다. + +## Open-ended: 표현 자유도와 검증 비용을 함께 인수 + +HTML·코드 등 더 자유로운 결과물을 표시한다. 질의별 설명용 시각화처럼 +기존 카탈로그로 표현하기 어려운 경험을 실험할 때 의미가 있다. 대신 생성물의 +상호작용, 외부 자원, 렌더링 실패, 긴 생성 시간까지 평가해야 한다. + +여기서 두 가지를 혼동하지 않는다. + +1. **표현 형식이 자유로운 것**과 **매번 LLM이 코드를 작성하는 것**은 다르다. + 개발자가 미리 작성한 HTML도 에이전트가 선택해서 표시할 수 있다. +2. **MCP Apps로 HTML UI를 전달하는 것**과 **모델이 임의 HTML을 생성하는 것**도 + 다르다. MCP Apps의 핵심은 도구에 연결된 UI 리소스와 호스트 상호작용이다. + +[MCP Apps 공식 문서][mcp-apps]는 호스트가 UI 리소스를 가져와 격리된 환경에 +표시하는 구조를 설명한다. 이 구조가 모든 생성 코드와 비즈니스 액션을 자동으로 +안전하게 만든다고 해석하면 안 된다. + +### 권고 + +- 처음에는 부작용 없는 설명·탐색 업무로 범위를 제한한다. +- 호스트·iframe 정책, 외부 URL과 리소스 허용 범위, 도구 접근 범위를 + 실제 배포 환경에서 검증한다. +- 생성에 걸린 시간도 사용자 경험에 포함한다. 시간 제한 없이 선호한 + 결과가 실시간 서비스에서도 선호된다고 가정하지 않는다. +- 구매·예약 확정은 검증된 업무 실행 경로에 남겨 둔다. + +## 독립된 두 축: 표현과 선택 + +[CopilotKit의 원문][taxonomy]은 UI 표현뿐 아니라 **에이전트와 개발자 중 +누가 표현을 결정하는가**라는 축을 별도로 설명한다. + +| 표현 | 개발자가 결정하는 경로 | 모델이 결정하는 경로 | +|---|---|---| +| 기존 컴포넌트 | 특정 단계가 되면 항상 같은 폼 표시 | 의도에 맞는 카드를 선택 | +| 선언적 UI | 업무 규칙으로 카탈로그 payload 생성 | 모델이 허용 카탈로그에서 조합 생성 | +| HTML UI | 도구가 미리 작성된 HTML 앱 반환 | 모델이 질의별 HTML 생성 | + +따라서 “Generative UI이므로 모든 클릭에 LLM을 호출해야 한다”는 결론은 +성립하지 않는다. 다만 규칙 기반으로 생성한 화면을 LLM의 자율 생성 성과라고 +표현하는 것도 부정확하다. + +## 최신 설계 방향: Chat에서 Chat+와 Chatless로 + +CopilotKit 원문은 **어디에 UI가 나타나는가**도 별도의 축으로 구분한다. +새로운 앱을 설계할 때 패턴 선택과 사용자 경험의 배치를 혼동하지 않아야 한다. + +| Surface | 사용자 경험 | 설계 초점 | +|---|---|---| +| Chat | 대화 안에 카드·폼·도구 결과 삽입 | 턴과 실행 상태의 연결, 메시지 흐름 유지 | +| Chat+ | 대화와 별도의 작업 캔버스를 함께 제공 | 에이전트·사용자의 공동 편집, 선택·상태 동기화 | +| Chatless | 기존 앱 안에 적응형 UI를 통합 | 앱이 표시 시점과 위치를 결정하고 필요한 순간에만 개입 | + +세 가지는 원문이 제시한 설계 표면이지 시장 점유율의 추세 데이터가 아니다. +권고는 채팅창 확대보다 **사용자의 실제 작업 공간에 에이전트를 통합**하는 데 +무게를 둔다. 제품 비교는 Chat+의 비교 캔버스, 상황별 추천은 Chatless의 +기존 탐색 화면에서 먼저 검증할 수 있다. + +## CopilotKit를 어떻게 읽어야 하는가 + +[CopilotKit 공개 저장소][copilotkit]는 프런트엔드와 에이전트를 연결하고 +UI를 구성하는 구현 자료다. 소개 페이지의 세 패턴은 개념 지도, 저장소의 +코드·예제는 구현 후보로 나누어 읽는다. 저장소의 데모가 자체 앱의 모든 +런타임·모델·renderer 조합에서 그대로 작동한다고 가정하지 않는다. + +조사일의 [표시 전용 컴포넌트 문서][display-only]는 `useComponent`로 React +컴포넌트를 도구로 등록하고, 호출 인자를 props로 받아 채팅 안에 렌더링하는 +진입점을 제공한다. 이는 사용자가 조작하는 폼이나 승인 중단까지 처리하는 +단일 API라는 뜻은 아니다. 원천 그림의 `useAgent` 표현을 최신 hook 사용법으로 +그대로 복사하지 않고, 표시·상호작용·승인 요구사항에 맞는 문서를 선택한다. + +[Microsoft Agent Framework의 AG-UI 문서][learn-agui]는 실제 통합 예에서 +backend tool rendering, tool-based generative UI, shared state를 별도 +시나리오로 다룬다. 즉, 생성 UI를 도입한다는 것은 단일한 “화면 생성 API”를 +붙이는 작업이 아니라 도구 실행·상태·렌더링을 연결하는 작업이다. +이 교차 확인은 A2UI 지원이나 세 패턴의 동일한 SDK 지원을 보증하지 않는다. + +## 선택 기준과 안티패턴 + +| 조건 | 먼저 비교할 선택 | 피할 오해 | +|---|---|---| +| 작업 순서·폼 구조가 안정적 | Controlled | 최신 패턴으로 바꿔야 더 좋은 UX라는 가정 | +| 데이터와 사용자 의도에 따라 조합이 달라짐 | Declarative | JSON이면 어떤 renderer에서도 동일하게 동작한다는 가정 | +| 기존 요소로 표현하기 어려운 탐색·설명 | 격리된 Open-ended | 표현 품질을 업무 정확성·안전성과 동일시 | +| 외부 호스트의 대화 안에서 도구 UI 필요 | MCP Apps | 반드시 모델이 HTML을 새로 만들어야 한다는 가정 | +| 자연어 요청 뒤 필터·버튼 조작이 반복됨 | 직접 액션 경로와 모델 경유 경로 비교 | 모든 후속 조작을 다시 자연어 추론에 맡김 | + +처음부터 하나로 통일할 필요는 없다. 제품 비교는 Declarative, 주문 확정은 +Controlled, 기능 설명은 격리된 Open-ended로 나누는 혼합 설계도 가능하다. +이는 예시 설계이며, 결합 구현은 별도로 검증해야 한다. + +## 한계 + +패턴별 성능·비용 순위는 측정하지 않았다. 자유도가 커질수록 구현·검증 부담이 +넓어진다는 설계 분석과, 실제 개발 기간·오류율에 대한 수치 주장은 다르다. +최종 선택은 [도입·평가 계획](../adoption/index.md)의 동일 업무 비교로 결정한다. + +## 공식 출처 + +- [CopilotKit Generative UI][taxonomy]: 패턴 분류와 개발자·모델 통제 축. +- [CopilotKit 저장소][copilotkit]: 구현·예제의 공식 진입점. +- [표시 전용 컴포넌트][display-only]: 현재 문서의 `useComponent` 사용 범위. +- [CopilotKit Generative UI showcase][showcase]: 수록한 두 Screenshot의 출처. + showcase가 MCP Apps를 Open-ended에 연결하는 설명은 최신 소개 페이지의 + “special case” 분류와 구분해 읽는다. +- [A2UI][a2ui]: 선언적 UI와 native renderer 개념. +- [MCP Apps][mcp-apps]: UI 리소스 전달과 호스트 렌더링. +- [Microsoft Agent Framework AG-UI][learn-agui]: 도구 렌더링·공유 상태를 + 분리한 실제 에이전트 프레임워크 통합 사례. +- [AG-UI Dojo][dojo]: 시나리오별 공개 데모와 수록한 실행 화면의 출처. + +[taxonomy]: https://www.copilotkit.ai/generative-ui +[copilotkit]: https://github.com/CopilotKit/CopilotKit +[a2ui]: https://a2ui.org/ +[mcp-apps]: https://modelcontextprotocol.io/extensions/apps/overview +[learn-agui]: https://learn.microsoft.com/agent-framework/integrations/by-component/ui/ag-ui/ +[showcase]: https://github.com/CopilotKit/CopilotKit/blob/cddbf0cc085475ea4836a6241e51ba76799adc20/examples/showcases/generative-ui/README.md +[display-only]: https://docs.copilotkit.ai/generative-ui/your-components/display-only +[dojo]: https://dojo.ag-ui.com/ diff --git a/docs/services/application-development/agentic-app-genui/protocols/index.md b/docs/services/application-development/agentic-app-genui/protocols/index.md new file mode 100644 index 00000000..4c9a0caa --- /dev/null +++ b/docs/services/application-development/agentic-app-genui/protocols/index.md @@ -0,0 +1,315 @@ +--- +title: CopilotKit·AG-UI·MCP Apps의 책임과 호출 경로 +description: 에이전트 이벤트와 UI 표현, MCP 도구 호출을 구분하고 모델을 거치는 경로와 UI의 직접 도구 호출 경로를 비교합니다. +document_type: research +topic_order: 2 +services: [application-development] +technologies: [mcp] +tags: [design, evaluate, ai-agents] +status: current +verification_status: verified +published_at: 2026-09-21 +sources_checked_at: 2026-09-22 +official_sources: + - title: AG-UI Overview + url: https://docs.ag-ui.com/introduction + - title: AG-UI Events + url: https://docs.ag-ui.com/concepts/events + - title: CopilotKit + url: https://github.com/CopilotKit/CopilotKit + - title: AG-UI Protocol + url: https://docs.copilotkit.ai/agentic-protocols/ag-ui + - title: MCP Apps + url: https://modelcontextprotocol.io/extensions/apps/overview + - title: AG-UI Integration with Agent Framework + url: https://learn.microsoft.com/agent-framework/integrations/by-component/ui/ag-ui/ + - title: MCP Apps Compatibility with AG-UI + url: https://learn.microsoft.com/agent-framework/integrations/by-component/ui/ag-ui/mcp-apps + - title: CopilotKit Products & Features + url: https://www.copilotkit.ai/product + - title: "A2UI - Google's Generative UI Spec" + url: https://docs.copilotkit.ai/generative-ui/a2ui + - title: A2UI - A Protocol for Agent-Driven Interfaces + url: https://a2ui.org/ + - title: AG-UI Generative UI Specs + url: https://docs.ag-ui.com/concepts/generative-ui-specs + - title: AG-UI and A2UI + url: https://www.copilotkit.ai/ag-ui-and-a2ui +--- + +# CopilotKit·AG-UI·MCP Apps의 책임과 호출 경로 + +**기준일: 2026-09-21. Screenshot 확인일: 2026-09-22.** CopilotKit는 구현 +도구이며, AG-UI와 MCP는 서로 다른 상호작용 계약이다. MCP Apps는 MCP 도구에 +연결된 UI와 호스트의 상호작용을 다룬다. 이 구분이 있어야 UI 전환 비용과 +모델 호출 비용을 독립적으로 설계할 수 있다. + +## 질문 + +“자연어 질의가 Python을 거쳐 MCP 도구를 호출하고 UI를 만든다”는 설명에서 +자연어 해석, 도구 선택, 실행, UI 표시 중 어느 단계가 모델을 필요로 하는가? +프로토콜 이름만으로 이 실행 정책이 결정되지는 않는다. + +## CopilotKit와 AG-UI + +![AG-UI 공식 개요. 사용자 대면 애플리케이션과 에이전트 프레임워크 사이의 이벤트 기반 연결을 보여 주는 생태계 도식](../images/ag-ui-overview-original.png){ style="background-color: white;" } + +*Screenshot P1. AG-UI 프로젝트, [공식 Overview][agui-overview]. +[MIT](../licenses/ag-ui-MIT.txt), 변경 없이 수록. +도식의 프로젝트·로고는 원문에 나타난 생태계 관계이며, 모든 조합의 호환성이나 +개별 기능 지원을 검증한 인증표가 아니다.* + +[로컬 원본 확대](../images/ag-ui-overview-original.png) + +[CopilotKit][copilotkit]는 에이전트와 연결되는 프런트엔드·런타임을 구성하기 +위한 스택이다. [공식 AG-UI 설명][agui]에 따르면 AG-UI를 통해 지원하는 +에이전트 프레임워크와 앱 사이의 연결을 추상화한다. + +![CopilotKit 제품 소개 화면. "Any frontend. Any agent." 제목 아래 Web(React·Vue·Angular·Svelte), Mobile(iOS·Android·React Native·Flutter), Team chat(Slack·MS Teams·Google Chat·Discord), Messaging(WhatsApp·Telegram·iMessage·SMS) 그룹이 중앙의 CopilotKit + AG-UI 블록으로 모이고, 아래에는 Microsoft MAF·LangChain·Google ADK·OpenAI Agent SDK·LlamaIndex·Claude Agent SDK·AWS Strands·mastra·AG2 백엔드가 연결된 도식](../images/copilotkit-product-overview-screenshot.png) + +*Screenshot S3. CopilotKit, [제품 소개 페이지][copilotkit-product]의 조사일 화면. +저작권은 CopilotKit에 있으며 벤더의 주장을 설명하기 위한 인용이다.* + +이 화면은 CopilotKit의 포지셔닝을 한 번에 보여 준다. 위쪽은 **사용자 표면**의 +다양성, 아래쪽은 **에이전트 백엔드**의 교체 가능성이며 그 사이를 AG-UI가 잇는 +구조다. 다만 다음 두 가지를 분리해 읽어야 한다. + +- 표면과 백엔드 목록은 생태계의 연결 대상이지 **조합별 기능 동등성의 인증표가 + 아니다.** 승인·상태 동기화·생성 UI 지원 범위는 SDK와 버전마다 다르다. +- 로고가 있다는 사실이 해당 제품의 보증이나 상호 추천을 뜻하지 않는다. + +즉 이 도식은 “무엇을 연결할 수 있는가”의 지도이며, “무엇이 같은 방식으로 +동작하는가”는 선택한 조합의 공식 문서와 실제 trace로 확인해야 한다. + +AG-UI가 다루는 것은 단순한 답변 텍스트가 아니다. + +- 에이전트 메시지의 실시간 전달 +- 프런트엔드 도구 호출과 사용자 상호작용 +- 에이전트와 클라이언트 사이의 공유 상태 +- 도구 실행·승인 등을 UI에 연결하는 이벤트 + +이 통신 경계가 분리되면 백엔드 변경에 대한 UI의 결합도를 줄일 수 있다. +그러나 이벤트를 실제로 어떤 화면으로 렌더링할지, 어떤 상태를 공유할지, +누가 도구를 승인할지는 구현과 정책으로 남는다. + +### 이벤트를 화면 상태와 연결 + +[AG-UI Events][agui-events]는 실행 수명주기와 텍스트·도구·상태 등의 +이벤트를 구분한다. 클라이언트는 도착한 문자열만 붙이는 대신 이벤트의 +의미에 맞춰 로딩·진행·실패·승인 대기 상태를 표현해야 한다. + +실행 수명주기의 시작은 `RunStarted`, 종료는 `RunFinished` 또는 +`RunError`로 설명된다. 특히 최신 이벤트 문서의 `RunFinished`에는 +`outcome.type: "interrupt"`인 사용자 입력 대기도 포함될 수 있다. +따라서 이벤트 이름만 보고 모든 업무가 성공했다고 표시하지 않고, +선택한 SDK 버전의 outcome과 업무 응답을 함께 확인해야 한다. + +이는 승인 UI와 최종 업무 상태를 분리해야 하는 구체적인 이유다. 실행 +종료와 예약·주문 확정은 같은 의미가 아니며, thread·run·도구 호출의 +상관관계를 유지해야 재연결과 늦은 응답을 처리할 수 있다. + +### 프레임워크 어댑터와 UI renderer는 다르다 + +[Microsoft Agent Framework의 공식 통합 문서][learn-agui]는 에이전트 응답을 +AG-UI 이벤트로 바꾸는 어댑터와 클라이언트의 렌더링을 분리한다. 같은 문서가 +언어별 SDK 지원 차이도 명시한다. + +따라서 “AG-UI endpoint에 연결된다”는 사실만으로 다음을 결론 내리지 않는다. + +- A2UI의 특정 버전과 모든 카탈로그를 렌더링할 수 있다. +- MCP Apps의 iframe·리소스·도구 요청을 호스트가 처리한다. +- 모든 backend에서 승인·상태·취소가 동일하게 동작한다. + +## AG-UI는 생성 UI 명세가 아니다 + +[AG-UI 공식 문서의 Generative UI 설명][agui-genui]은 이 구분을 명시한다. +“**AG-UI는 생성 UI 명세가 아니라** 에이전트와 애플리케이션 사이의 양방향 +런타임 연결을 제공하는 User Interaction 프로토콜”이라는 것이다. 같은 문서가 +생성 UI 명세를 따로 분류한다. CopilotKit도 [AG-UI와 A2UI의 관계][ck-a2ui-page]를 +별도 페이지로 설명한다. + +| 공식 문서의 분류 | 문서가 밝힌 출처·목적 | 이 리서치에서 주의할 점 | +|---|---|---| +| AG-UI | 프런트엔드와 임의의 에이전트 백엔드를 잇는 범용 양방향 연결 | 이벤트·상태 계약이며 컴포넌트 카탈로그를 정의하지 않음 | +| A2UI | Google 출처의 선언적·스트리밍 생성 UI 명세 | 조사일 기준 v0.9.1 Current, v1.0 Candidate | +| Open-JSON-UI | OpenAI 내부 선언적 생성 UI 스키마의 공개 표준화 | 이 리서치에서 1차 명세를 확인하지 않음 | +| MCP-UI | MCP를 확장한 iframe 기반 생성 UI 표준 | MCP Apps와 **이름이 다르므로** 관계를 확인하고 인용 | + +표의 명칭·소속 표기는 해당 문서의 설명이다. 특히 이름 문제는 실무에서 +혼동을 부르기 쉬우므로 두 가지를 구분한다. + +- [MCP Apps][mcp-apps]는 `modelcontextprotocol.io`가 게시한 **공식 확장**이며 + 도구에 연결된 UI 리소스와 호스트 상호작용을 정의한다. +- `MCP-UI`는 별개의 이름이지만 무관하지 않다. MCP Apps 공식 문서는 클라이언트를 + 만들 때 `@mcp-ui/client` 패키지를 쓰거나 SDK의 App Bridge 모듈로 직접 + 구현하는 두 가지 경로를 안내한다. + +즉 “MCP 계열 생성 UI”를 말할 때는 **명세(MCP Apps)**와 **구현 라이브러리 +(MCP-UI 등)**를 나눠서 적어야 지원 범위를 오해하지 않는다. + +같은 문서는 AG-UI가 위 생성 UI 명세들을 지원하며 개발자가 자체 생성 UI 표준을 +정의할 수도 있다고 설명한다. 이는 AG-UI가 표현 계약을 **고정하지 않는다**는 +뜻이지, 어떤 조합이든 렌더링이 보장된다는 뜻이 아니다. + +### 벤더 자료는 시점을 함께 확인한다 + +CopilotKit이 배포한 설명 자료 『AG-UI and A2UI Explained』는 A2UI를 “곧 +공개될(soon to be released)” 명세로 소개하며 출시에 맞춰 지원할 예정이라고 +밝힌다. 조사일의 공개 문서는 다른 단계를 보여 준다. + +- [A2UI 공식 홈][a2ui]은 v0.9.1을 Current, v1.0을 Candidate로 표시한다. +- [CopilotKit A2UI 문서][ck-a2ui]는 런타임에 `a2ui` 옵션을 켜면 에이전트의 + A2UI 출력이 렌더링된다고 설명한다. + +따라서 배포본 자료는 작성 시점의 로드맵으로 읽고, 현재 지원 범위는 명세·제품 +문서에서 다시 확인해야 한다. 이 차이를 구분하지 않으면 “아직 없는 기능”과 +“이미 있는 기능”을 같은 근거로 인용하게 된다. + +## MCP와 MCP Apps + +[MCP Apps 공식 개요][mcp-apps]는 일반 MCP 도구 응답의 텍스트·이미지·리소스· +구조화 데이터와, 도구에 연결된 상호작용 UI를 구분한다. + +MCP Apps의 주요 연결 지점은 다음과 같다. + +| 요소 | 역할 | +|---|---| +| 도구 설명의 `_meta.ui.resourceUri` | 연결된 `ui://` UI 리소스를 가리킴 | +| UI 리소스 | HTML과 필요한 자산으로 구성한 앱의 표현 | +| 지원 호스트 | 리소스 조회, 표시, 앱과 도구 사이의 요청 중개 | +| 웹 호스트의 sandboxed iframe | 호스트 화면과 앱의 실행 경계를 분리 | +| JSON-RPC 기반 앱·호스트 통신 | 도구 호출, UI 초기화, 컨텍스트 갱신 등 | +| CSP·권한 설정 | 외부 자원과 추가 기능 사용 범위를 제한 | + +도구 결과는 데이터이고 UI 리소스는 그 결과를 표시·조작할 앱일 수 있다. +도구를 호출할 때마다 새로운 UI 코드를 생성해야 하는 것은 아니다. 지원 +호스트는 도구 설명을 통해 UI 리소스를 미리 가져오는 경로도 가질 수 있다. + +격리는 위험을 줄이는 경계다. 서버 측 업무 권한, 개인정보 처리, 결과의 +정확성까지 자동으로 해결하는 보증으로 표현하지 않는다. + +## 두 호출 경로를 분리해서 본다 + +![첫 자연어 요청은 에이전트와 모델의 도구 선택을 거칠 수 있고, 이후 버튼·필터 액션은 호스트를 통해 MCP 서버 도구를 직접 호출할 수 있음을 구분한 흐름도](../images/mcp-apps-call-paths.svg) + +*그림 3. MCP Apps 공식 개요의 도구·UI 상호작용을 바탕으로 직접 작성한 +개념도. 직접 호출도 호스트 정책과 서버 권한 검사 안에서 실행한다.* + +### A. 자연어에서 시작하는 에이전트 경로 + +1. 사용자가 “조건에 맞는 제품을 비교해 줘”라고 요청한다. +2. 에이전트가 요청을 해석하고 도구와 인자를 선택한다. 이 단계에 LLM을 + 사용한다면 모델 호출 비용과 지연이 발생한다. +3. 호스트·런타임이 MCP 서버의 도구를 호출한다. +4. 도구의 데이터와 연결된 UI 리소스를 이용해 호스트가 앱을 표시한다. +5. 사용자는 결과를 읽거나 앱에서 다음 액션을 수행한다. + +규칙 기반 파서로 2번을 구현할 수도 있지만, 이는 애플리케이션이 지원하는 +제한된 입력 범위의 설계 선택이다. MCP 자체가 임의의 자연어를 해석하지 않는다. + +### B. 화면 조작에서 시작하는 명시적 액션 경로 + +1. 사용자가 필터를 변경하거나 “다음 페이지” 버튼을 누른다. +2. 앱이 도구 이름과 구조화된 인자를 가진 호출을 호스트에 요청한다. +3. 호스트가 허용된 요청을 MCP 서버에 전달한다. +4. 결과가 돌아오면 앱이 화면을 갱신한다. +5. 대화 맥락에 반영할 정보가 있다면 별도로 모델 컨텍스트 갱신을 고려한다. + +이 경로는 매번 모델에게 “사용자의 클릭이 무슨 뜻인가”를 다시 물을 필요가 없다. +그러나 실제 구현이 모델을 다시 호출하는지 여부는 호스트·워크플로에 달려 +있으므로 trace로 확인해야 한다. 가능성과 실측 성능을 구분한다. + +## Python에 대한 정정 + +Python은 에이전트나 MCP 서버의 구현 언어로 선택할 수 있다. 그러나 다음 +등식은 성립하지 않는다. + +```text +MCP 사용 = 자연어 해석 생략 = Python 실행 = LLM 호출 없음 +``` + +언어, 호출 프로토콜, 의사결정 정책은 서로 다른 축이다. 특히 +[Microsoft Agent Framework와 CopilotKit의 MCP Apps 연동 설명][learn-mcp]은 +다음 경계를 명시한다. + +```text +Frontend + -> CopilotKit runtime / Node.js proxy + MCPAppsMiddleware + -> standard AG-UI request + -> Python Agent Framework endpoint +``` + +이 **특정 통합 구조**에서 MCP 도구 발견, iframe 리소스 요청 중개와 UI +리소스 해석은 TypeScript 미들웨어가 처리한다. Python endpoint는 일반 AG-UI +요청을 받으며 MCP Apps 전용 설정이 필요하지 않다는 설명이다. + +따라서 “MCP Apps가 Python에서 LLM을 자동 우회한다”는 해석은 부정확하다. +반대로 모든 MCP Apps 구현에 이 Node.js 미들웨어가 반드시 필요하다는 +뜻도 아니다. 선택한 호스트·런타임의 구현 경계로만 읽어야 한다. + +## 구현할 때 구분할 상태 + +다음은 프로토콜의 자동 보장 목록이 아니라 통합 테스트 항목이다. + +| 상황 | 확인할 계약 | +|---|---| +| 도구 인자가 여러 조각으로 전달됨 | 완성 전에는 부작용 있는 도구 실행 금지 | +| UI는 표시됐지만 도구는 실행 중 | 로딩·취소·실패·완료를 구분 | +| 사용자 승인 거절 | 실행하지 않고 명시적인 거절 상태 반환 | +| 이전 실행 응답이 늦게 도착 | 실행·도구·화면 식별자로 현재 상태와 구분 | +| UI 리소스 지원이 없는 호스트 | 지원 여부를 확인하고 텍스트·기존 화면 경로 제공 | +| 직접 도구 호출 | 모델을 거치지 않아도 권한·입력 검증 수행 | +| 연결 종료 후 재개 | 이벤트 전달과 업무 재실행을 구분하고 중복 쓰기 방지 | + +## Best practice와 피할 설계 + +| 권고 | 이유 | 피할 설계 | +|---|---|---| +| 도구 실행과 UI 렌더링을 분리 | 재사용과 오류 구분이 쉬움 | HTML 안에 업무 권한·정책을 숨김 | +| 직접 액션 경로를 별도 관측 | 추론 횟수와 지연의 원인을 구분 | 모든 버튼을 다시 자연어로 변환 | +| 프로토콜·미들웨어·SDK 버전 기록 | 기능 지원 범위가 서로 다름 | “AG-UI 지원”만으로 전체 호환 선언 | +| 앱용 도구 접근을 최소화 | 화면이 의도하지 않은 작업에 접근하지 않게 함 | iframe 격리만으로 충분하다고 판단 | +| 사용자 승인과 서버 권한을 모두 검증 | 확인 UI는 인증·인가가 아님 | 버튼 클릭만으로 임의 도구 실행 | +| 실패를 사용자와 로그에 표시 | 원인별 복구와 운영 진단 가능 | UI 리소스 실패를 빈 카드로 숨김 | + +MCP Apps가 더 나은 선택인지도 따져야 한다. 호스트의 대화 맥락과 도구 +연결이 필요하지 않은 독립 서비스라면 일반 웹 앱이 더 단순할 수 있다는 +점은 [공식 개요][mcp-apps]도 설명한다. + +## 한계와 다음 읽기 + +공식 문서상의 구조를 조사했으며, 특정 CopilotKit·AG-UI·MCP SDK 조합을 +설치해 검증하지 않았다. 라이브러리의 함수 시그니처를 복사한 실행 예제 대신 +책임과 메시지 경로를 제시한다. + +UI 표현 자체의 계약은 [A2UI 분석](../google-a2ui/index.md), 도입 순서와 +측정 기준은 [적용·평가 계획](../adoption/index.md)을 참고한다. + +## 공식 출처 + +- [CopilotKit 저장소][copilotkit]: 구현 스택과 예제의 공식 진입점. +- [CopilotKit AG-UI][agui]: 이벤트·상태·프런트엔드 도구 연결. +- [AG-UI Overview][agui-overview]와 [Events][agui-events]: 공식 개요 도식과 실행 수명주기. +- [MCP Apps][mcp-apps]: UI 리소스 metadata, 호스트 흐름, 격리와 용도. +- [Microsoft Agent Framework AG-UI][learn-agui]: 런타임 어댑터와 언어별 지원 범위. +- [MCP Apps Compatibility with AG-UI][learn-mcp]: Python endpoint와 + TypeScript 미들웨어의 구체적인 책임 경계. +- [CopilotKit 제품 소개][copilotkit-product]: 수록한 제품 화면의 출처와 + 표면·백엔드 연결 주장. +- [CopilotKit A2UI 문서][ck-a2ui]: 런타임의 A2UI 렌더링 지원 범위. +- [A2UI 공식 홈][a2ui]: 조사일의 명세 버전 상태. +- [AG-UI Generative UI Specs][agui-genui]: 생성 UI 명세 분류와 AG-UI의 위치. +- [AG-UI and A2UI][ck-a2ui-page]: 두 이름의 역할 차이에 대한 CopilotKit 설명. + +[copilotkit]: https://github.com/CopilotKit/CopilotKit +[agui]: https://docs.copilotkit.ai/agentic-protocols/ag-ui +[mcp-apps]: https://modelcontextprotocol.io/extensions/apps/overview +[learn-agui]: https://learn.microsoft.com/agent-framework/integrations/by-component/ui/ag-ui/ +[learn-mcp]: https://learn.microsoft.com/agent-framework/integrations/by-component/ui/ag-ui/mcp-apps +[agui-overview]: https://docs.ag-ui.com/introduction +[agui-events]: https://docs.ag-ui.com/concepts/events +[copilotkit-product]: https://www.copilotkit.ai/product +[ck-a2ui]: https://docs.copilotkit.ai/generative-ui/a2ui +[a2ui]: https://a2ui.org/ +[agui-genui]: https://docs.ag-ui.com/concepts/generative-ui-specs +[ck-a2ui-page]: https://www.copilotkit.ai/ag-ui-and-a2ui