--- title: "§A2UI (Agent-to-User Interface) #에이전트 #동적 #사용자경험 #패러다임" url: "https://notes.junghanacs.com/notes/20250702T164630" author: "Junghan Kim" date: "2025-07-02T16:46:00+09:00" lastmod: "2026-02-17T00:00:00+09:00" tags: ["agent","bib","frontend","hci","interface","uiux"] description: "에이전트가 상황에 따라 인터페이스를 동적으로 바꾸는 A2UI 패러다임과 구현 맥락을 추적하는 노트다." --- > [!abstract] 이 노트에 대하여 > > A2UI라는 발상 아래 에이전트가 사용자 인터페이스를 동적으로 재구성하는 패러다임을 탐색한다. 에이전트 시대 HCI와 UI/UX의 변화를 사유하는 개념 노트다. ## 히스토리 - [2026-02-18 Wed] OpenClaw Canvas A2UI v0.8 구현체 코드 분석 추가 - [2026-02-17 Tue 17:32] A2UI. - [@homeagent-config ML 파이프라인 도구세트 운영전략](https://notes.junghanacs.com/notes/20260209T183036) - [2025-07-02 Wed 16:46] Created! - [#IoT #플랫폼: ¤Thingsboard 대시보드 풀스택 오픈소스](https://notes.junghanacs.com/bib/20250701T180733) ## 관련메타 - [†#프레임워크](https://notes.junghanacs.com/meta/20230715T165900) - [† #디자인 #사용자경험 #사용자인터페이스](https://notes.junghanacs.com/meta/20240816T072714) - [†#HCI #인간 #컴퓨터 #인터페이스](https://notes.junghanacs.com/meta/20240516T163116) ## 관련노트 ### 에이전트 편재성 / HomeAgent - [@힣: AI 에이전트 편재성 - 기억 연결](https://notes.junghanacs.com/notes/20250904T075937) — 편재성(Ubiquity), OpenClaw, meta-agent-shell 수렴점 - [@homeagent-config ML 파이프라인 도구세트 운영전략](https://notes.junghanacs.com/notes/20260209T183036) — HomeAgent UI 철학 원문 - [지능형홈 허브 아키텍처 연결고리](https://notes.junghanacs.com/notes/20251218T113249) — IoT/Matter/Thread 허브 - [#IoT #플랫폼: ¤Thingsboard 대시보드 풀스택 오픈소스](https://notes.junghanacs.com/bib/20250701T180733) — Angular Material 기반 대시보드 ### 에이전트 아키텍처 / 프로토콜 - [@힣: 워크스페이스 에이전트 서비스 통합](https://notes.junghanacs.com/notes/20251114T100441) — Google MCP, 멀티디바이스, OAuth - [존재대존재 오케스트레이션 서브에이전트 설계](https://notes.junghanacs.com/notes/20251120T090634) — 에이전트 계층 구조 - [@힣: 멀티 에이전트 인간 눈귀코혀몸뜻](https://notes.junghanacs.com/notes/20251207T154723) — 육감 표현, 에이전트 감각 인터페이스 - [존재대존재 협업 SDD 패러다임](https://notes.junghanacs.com/notes/20251127T123739) — 스펙 중심 개발 - [Emacs-AI 통합 패러다임: MCP, REPL, 그리고 진정한 협업](https://notes.junghanacs.com/notes/20251121T132314) — MCP 프로토콜 통합 ### 프론트엔드 / UI 기반 - [자바스크립트 프레임워크 리엑트](https://notes.junghanacs.com/notes/20230718T104400) — React 기초 - [스타트업 네모유엑스 폐업 사용자경험 인터렉티브 라지디스플레이](https://notes.junghanacs.com/notes/20250403T080746) — 인터랙티브 Surface/디스플레이 HCI - [비서 개인 AI 가상 비서 §second-me §mycroft](https://notes.junghanacs.com/notes/20250512T131934) — 개인 AI 비서, 데이터 소유권 ### 에이전트 개발 도구 - [Efrit: 왜 Emacs에서 멀티에이전트인가? Steve Yegge의 비전](https://notes.junghanacs.com/notes/20251126T120729) — 에이전트 프론트엔드 비전 - [Beads Agent Mail 멀티에이전트 병렬작업 도입](https://notes.junghanacs.com/notes/20251124T164312) — 멀티에이전트 통신 - [§orgmode-skills: 에이전트를 위한 Denote PKM 조직모드 통합](https://notes.junghanacs.com/notes/20251030T011106) — 에이전트 Skills 프레임워크 ## BIBLIOGRAPHY - NO_ITEM_DATA:googleA2UI ### google/A2UI (NO_ITEM_DATA:googleA2UI) ## 2026-02 A2UI + CopilotKit: 에이전트 동적 UI 패러다임 전환 [2026-02-17 Tue 16:30] ### 배경: 정적 홈페이지에서 에이전트 뷰어로 - junghanacs.com (Hugo 정적 사이트) → 에이전트가 UI를 동적으로 생성하는 방식으로 전환 검토 - HomeAgent UI 철학: "UI는 뷰어일 뿐. 에이전트가 무엇을 어떻게 보여줄지 결정한다" - 기존 SSG, Chatwoot(채팅 위젯), Quarto 등은 이 패러다임에 부적합 - 핵심 요구: 에이전트가 "장미"를 말하면 배경이 붉어지는, UI 자체가 eval되는 동적 구성 ### A2UI (Agent-to-User Interface) — Google - | - Apache 2.0 | v0.8 Public Preview (2026-02) - 선언적 JSON 프로토콜: 실행 코드가 아닌 데이터로 UI를 기술 - JSONL 스트리밍 (SSE/WebSocket): 점진적 렌더링 지원 - 4가지 메시지 타입: `surfaceUpdate`, `dataModelUpdate`, `beginRendering`, `deleteSurface` - 컴포넌트 카탈로그: 클라이언트가 지원하는 컴포넌트 목록을 선언, 에이전트는 그 안에서 구성 - 보안: 에이전트는 사전 승인된 컴포넌트만 사용 가능 (UI 인젝션 방지) - LLM 최적화: 평탄한 JSON 구조, 스트리밍 생성에 적합 ```json { "surfaceUpdate": { "surfaceId": "main", "components": [ { "id": "bg", "component": { "Canvas": { "color": { "path": "/scene/bg" } } } } ] } } ``` ### CopilotKit — 에이전트 UI 프레임워크 - | - MIT | 28K+ GitHub stars - AG-UI (Agent↔User) 프로토콜로 에이전트 연결 - A2UI, Open-JSON-UI, MCP Apps 3가지 Generative UI 스펙 지원 - React 기반 컴포넌트: CopilotChat, CopilotPopup, CopilotSidebar - Copilot Runtime: 셀프호스팅 가능한 백엔드 - 에이전트 프레임워크 연동: A2A, ADK, AWS Strands, Direct-to-LLM - Human-in-the-Loop 내장 ### 아키텍처 구상 ```text OpenClaw (에이전트, Oracle VM) │ A2UI JSONL ▼ CopilotKit + AG-UI (프론트엔드) │ React 렌더링 ├→ junghanacs.com (웹 브라우저) ├→ HomeAgent RPi5 (디스플레이) └→ 모바일 ``` | HomeAgent 철학 | A2UI 대응 | |------------------|--------------------------| | 프론트엔드를 코드로 고정하지 않음 | 선언적 JSON, 코드가 아닌 데이터 | | 에이전트가 동적으로 시각화 | surfaceUpdate로 실시간 UI 스트리밍 | | 빛과 형태로 소통 | 커스텀 컴포넌트 카탈로그 확장 | | 입력 대기가 아닌 능동적 표현 | 에이전트가 먼저 beginRendering | | 토큰 세이빙 | 평탄한 JSON, LLM 생성 최적화 설계 | ### 관련 프로젝트 - [@힣: AI 에이전트 편재성 - 기억 연결](https://notes.junghanacs.com/notes/20250904T075937) — 편재성(Ubiquity) 개념 - [@homeagent-config ML 파이프라인 도구세트 운영전략](https://notes.junghanacs.com/notes/20260209T183036) — HomeAgent - E2B Fragments: (오픈소스 Artifacts) - Vercel AI SDK streamUI: (React 컴포넌트 스트리밍) ### 다음 단계 1. CopilotKit 로컬 프로토타입 (Next.js + CopilotKit + A2UI) 2. OpenClaw → AG-UI 연동 3. 커스텀 컴포넌트 카탈로그 (배경색, 캔버스, 웨이브 등 표현 컴포넌트) 4. Oracle VM 배포 (Copilot Runtime 셀프호스팅) 5. HomeAgent RPi5 디스플레이 뷰어와 동일 프로토콜 공유 ## 2026-02 OpenClaw Canvas: A2UI v0.8 구현체 분석 [2026-02-18 Wed] 이미 사용 중인 OpenClaw에 A2UI v0.8 호스트가 완전히 내장되어 있다. 별도 프레임워크 없이 에이전트 → 선언적 JSON → 뷰어 패턴이 구현됨. ### 아키텍처 ```text Agent (LLM) ↓ A2UI JSONL (선언적 JSON) Gateway (WebSocket, port 18789) ↓ Canvas Host (HTTP: /__openclaw__/a2ui/) ↓ Lit Renderer () ↓ 네이티브 브릿지 macOS / iOS / Android / Web ``` ### A2UI v0.8 메시지 4종 `vendor/a2ui/specification/0.8/json/server_to_client.json` 에 정의: | 메시지 | 역할 | 필수 필드 | |----------------|---------------------|---------------------| | `beginRendering` | 서피스 렌더링 시작 | surfaceId, root | | `surfaceUpdate` | UI 컴포넌트 추가/수정 | surfaceId, components[] | | `dataModelUpdate` | 데이터 바인딩 업데이트 (동적 콘텐츠) | surfaceId, contents[] | | `deleteSurface` | 서피스 제거 | surfaceId | `createSurface` (v0.9)는 미지원. ### 표준 컴포넌트 카탈로그 (37개+) `vendor/a2ui/specification/0.8/json/standard_catalog_definition.json`: - **Layout**: Column, Row, Card, List, Tabs, Modal, Divider - **Text**: Text (usageHint: h1~h5, body, caption) - **Media**: Image (icon/avatar/feature/header), Icon, Video, AudioPlayer - **Input**: TextField, Button, CheckBox, Slider, DateTimeInput, MultipleChoice 컴포넌트 구조: ```json { "id": "title", "component": { "Text": { "text": { "literalString": "Hello" }, "usageHint": "h1" } } } ``` ### 양방향 액션 흐름 ```text 사용자 버튼 클릭 → Lit 이벤트 (a2uiaction) → 네이티브 브릿지 (WebKit/Android/JS) → Gateway → Agent → Agent가 새 A2UI 메시지 생성 → Canvas 업데이트 ``` User Action 메시지: ```json { "userAction": { "id": "uuid", "name": "actionName", "surfaceId": "main", "sourceComponentId": "btnId", "context": { "key": "value" } } } ``` ### CLI 명령어 ```bash # A2UI 텍스트 푸시 openclaw nodes canvas a2ui push --node --text "Hello from A2UI" # JSONL 파일로 복잡한 UI 전송 openclaw nodes canvas a2ui push --node --jsonl /path/to/a2ui.jsonl # 캔버스 리셋 openclaw nodes canvas a2ui reset --node # 캔버스 스냅샷 openclaw nodes canvas snapshot --node --format png # 캔버스 표시/숨기기 openclaw nodes canvas present --node openclaw nodes canvas hide --node # JavaScript 실행 openclaw nodes canvas eval --node --js "document.title" ``` ### Lit 렌더러 (bootstrap.js) `apps/shared/OpenClawKit/Tools/CanvasA2UI/bootstrap.js`: - 커스텀 엘리먼트: `` (LitElement 확장) - 전역 API: `globalThis.openclawA2UI` ```javascript const api = { applyMessages: (messages) => this.applyMessages(messages), reset: () => this.reset(), getSurfaces: () => Array.from(this.#processor.getSurfaces().keys()), }; globalThis.openclawA2UI = api; ``` - `v0_8.Data.createSignalA2uiMessageProcessor()` 로 메시지 처리 - 네이티브 브릿지: iOS(WebKit), Android(JS Interface), Web(globalThis.OpenClaw) ### JSONL 검증 로직 `src/cli/nodes-cli/a2ui-jsonl.ts`: ```typescript const A2UI_ACTION_KEYS = [ "beginRendering", "surfaceUpdate", "dataModelUpdate", "deleteSurface", "createSurface" // v0.9 전용 — v0.8에서는 거부 ]; // 각 줄: 유효한 JSON, 정확히 하나의 액션 키, v0.8/v0.9 혼합 불가 ``` ### 핵심 소스 파일 | 파일 | 역할 | |-------------------------------------------------------|-----------------------| | `src/canvas-host/a2ui.ts` | A2UI HTTP 서버, 에셋 서빙 | | `src/canvas-host/server.ts` | Canvas 호스트 서버, WS 업그레이드 | | `src/infra/canvas-host-url.ts` | 호스트 URL 결정 (프록시 지원) | | `src/agents/tools/canvas-tool.ts` | 에이전트 도구 구현 | | `src/cli/nodes-cli/register.canvas.ts` | CLI 명령 등록 | | `src/cli/nodes-cli/a2ui-jsonl.ts` | JSONL 검증, 텍스트 빌더 | | `apps/shared/OpenClawKit/Tools/CanvasA2UI/bootstrap.js` | Lit 렌더러 (메인) | | `apps/macos/.../CanvasA2UIActionMessageHandler.swift` | iOS WebKit 브릿지 | | `apps/android/.../A2UIHandler.kt` | Android JS 인터페이스 | | `vendor/a2ui/specification/0.8/json/` | A2UI v0.8 JSON 스키마 | | `vendor/a2ui/renderers/lit/` | Lit v0.8 렌더러 구현 | ### Canvas 호스트 URL ```text http://:18789/__openclaw__/a2ui/?platform=android ``` 호스트 결정 순서: hostOverride → Host 헤더 → 로컬 주소. HTTPS 프록시(Tailscale Serve) 시 포트 매핑: 18789 → 443. ### 보안 설계 - **선언적 JSON**: 실행 코드 아님, 에이전트가 임의 코드 주입 불가 - **카탈로그 제한**: 사전 승인된 컴포넌트만 요청 가능 - **iOS 브릿지**: 로컬 canvas URL만 허용 (localhost, .local, .ts.net, private IP) - **디렉토리 탈출 차단**: 세션 루트 밖 파일 접근 불가 ### 시사점 1. CopilotKit 없이도 A2UI 뷰어 구현 가능 — OpenClaw이 이미 Lit 렌더러 내장 2. HomeAgent(RPi5)와 동일 프로토콜 공유 가능 — 동일 JSONL 메시지 형식 3. 홈페이지 전환 시 Gateway Tailscale Funnel로 공개하면 웹 Canvas 즉시 접근 가능 4. 단, 보안 우려로 현재는 Telegram 봇 경유 방식 채택 ([시간과정신의방](https://notes.junghanacs.com/notes/20251015T093311)) ## 로그 ### [|2025-07-02 Wed 16:46|](https://notes.junghanacs.com/journal/20250630T000000#2025-07-02-wed) #### @user coreui가 Angular와 무슨 관계야인가? @assistant CoreUI는 Angular를 포함한 여러 프론트엔드 프레임워크(React, Vue 등)를 지원하는 **UI 컴포넌트 라이브러리** 입니다. - **Angular와의 관계**: CoreUI는 Angular용으로 최적화된 테마와 컴포넌트(버튼, 폼, 카드 등)를 제공하여 개발 효율성을 높여줍니다. - **주요 기능**: 미리 디자인된 템플릿, 반응형 레이아웃, Angular와의 호환성 강조. 즉, CoreUI는 Angular 프로젝트에서 **UI 개발을 빠르게 진행할 수 있도록 도와주는 도구** 입니다. #### @user CoreUI와 유사한 개념의 컴포넌트 라이브러리는 특히 Angular에 특화되어 있는 것들을 중심으로 조사해줘 @assistant CoreUI와 유사한 Angular 특화 UI 컴포넌트 라이브러리로는 다음이 대표적입니다. | 라이브러리명 | 특징 및 설명 | |---------------------|--------------------------------------------------------------------------------------------------| | **Angular Material** | Google 공식 Angular UI 라이브러리로, Material Design 기반의 고품질 컴포넌트 제공. 커스터마이징 가능하며, 간단한 API와 크로스플랫폼 지원이 강점[3]. | | **PrimeNG** | Angular 전용 UI 컴포넌트 라이브러리로 다양한 UI 요소와 테마를 제공하며, Angular 프로젝트에 최적화되어 있음[2]. | | **NG-ZORRO** | Ant Design 기반의 엔터프라이즈급 Angular UI 라이브러리. 70개 이상의 고품질 컴포넌트, 타입스크립트 완전 지원, 테마 커스터마이징 가능[4]. | | **Ignite UI for Angular** | Angular 네이티브 머티리얼 기반 UI 컴포넌트 라이브러리로, 특히 빠른 데이터 그리드 컴포넌트가 특징[1]. | 이들 라이브러리는 모두 Angular에 특화되어 있으며, CoreUI처럼 Angular 프로젝트에서 UI 개발을 빠르고 효율적으로 할 수 있도록 다양한 컴포넌트와 테마를 제공합니다. 특히 Angular Material과 NG-ZORRO는 Google과 Ant Design이라는 강력한 디자인 시스템을 기반으로 하여 신뢰성과 확장성이 높습니다. PrimeNG는 Angular 전용으로 폭넓은 컴포넌트를 제공하며, Ignite UI는 데이터 그리드 등 고성능 컴포넌트에 강점이 있습니다. 따라서 Angular 프로젝트에서 CoreUI와 유사한 UI 컴포넌트 라이브러리를 찾는다면 위 네 가지를 우선 고려할 수 있습니다. - Citations: [1] [2] [3] [4] [5] #### @user 이 중에서 Thingsboard에서 활용하는 라이브러리가 있는가? 대시보드의 경우 다 유사한 것 같다. @assistant ThingsBoard에서는 **Angular Material** 라이브러리를 활용하고 있습니다. 특히 ThingsBoard의 위젯 개발과 UI 구성에 Angular Material 버전 15가 사용되어, Angular Material의 다양한 UI 컴포넌트를 이용해 대시보드와 위젯을 보다 세련되고 기능적으로 구현할 수 있습니다[2]. - ThingsBoard Rule Nodes UI 구성도 Angular 기반이며, TypeScript와 SCSS를 사용해 Angular 생태계 내에서 개발되고 있습니다[1]. - 공식 문서와 튜토리얼에서도 Angular Material을 활용한 커스텀 위젯 제작 방법을 안내하고 있어, Angular Material이 ThingsBoard UI 개발에 핵심적인 역할을 한다고 볼 수 있습니다[2][3]. 따라서 CoreUI 같은 다른 라이브러리 대신, ThingsBoard에서는 **Angular Material** 을 주로 활용하는 것으로 확인됩니다. 요약하자면: | 라이브러리 | ThingsBoard 활용 여부 | 비고 | |-------------|-------------------|-----------------| | Angular Material | 예 | 공식 UI 컴포넌트로 사용 중 | | CoreUI | 확인 불가 | 공식 문서나 코드에서 언급 없음 | | PrimeNG | 확인 불가 | 공식 문서나 코드에서 언급 없음 | | NG-ZORRO | 확인 불가 | 공식 문서나 코드에서 언급 없음 | | Ignite UI | 확인 불가 | 공식 문서나 코드에서 언급 없음 | 즉, ThingsBoard 대시보드 및 위젯 개발 시 Angular Material이 핵심 라이브러리로 활용되고 있습니다[1][2][3]. - Citations: [1] [2] [3] [4] [5] #### @user UI 컴포넌트 라이브러리의 의미가 무엇인가? 프레임워크와 개념 상의 어떤 차이가 있는가? @assistant #### **UI 컴포넌트 라이브러리 vs 프레임워크** ##### **1. UI 컴포넌트 라이브러리 (Component Library)** - **의미**: 재사용 가능한 UI 요소(버튼, 폼, 테이블 등)를 모아놓은 **"도구 상자"** - **목적**: 빠른 UI 개발 (디자인 시스템 적용, 일관성 유지) - **특징**: - 프레임워크에 **종속적** (예: Angular Material → Angular 전용) - **유연한 사용** (필요한 컴포넌트만 선택 적용 가능) - **스타일링/기능** 만 제공 (프로젝트 구조 X) ##### **2. 프레임워크 (Framework)** - **의미**: 애플리케이션의 **전체 구조** 를 제공하는 **"뼈대"** - **목적**: 프로젝트 아키텍처 규격화 (라우팅, 상태 관리 등) - **특징**: - **강한 제약** (규칙에 따른 개발 필수, 예: Angular, React) - **통합 솔루션** (컴포넌트 라이브러리 + 라우팅 + HTTP 클라이언트 등) #### **차이점 요약** | 구분 | UI 컴포넌트 라이브러리 | 프레임워크 | |-------|----------------------------------|----------------------| | **역할** | UI 조각 제공 | 애플리케이션 전체 구조 제공 | | **종속성** | 프레임워크에 의존 (예: Angular Material ↔ Angular) | 독립적 실행 환경 (예: Angular 자체) | | **유연성** | 선택적 사용 가능 | 전체 구조에 강제 적용 | 예시: - **Angular (프레임워크)** + **Angular Material (라이브러리)** 조합 → 구조는 Angular가, UI는 Material이 담당. 따라서, **프레임워크는 "집을 짓는 방법"**, **컴포넌트 라이브러리는 "미리 만든 벽돌/창문"** 이라 비유할 수 있습니다. #### @user Angular Material를 Thingsboard 대시보드 및 위젯에서 어떻게 활용하고 있는지 분석해줘. @assistant ThingsBoard에서 Angular Material의 활용 방식은 다음과 같습니다. #### 1. UI 구조 및 레이아웃 - 대시보드, 위젯, 팝업, 설정창 등 주요 UI의 레이아웃을 Angular Material의 `mat-toolbar`, `mat-sidenav`, `mat-card`, `mat-grid-list` 등으로 구성합니다. - 반응형 레이아웃과 일관된 디자인을 쉽게 구현할 수 있습니다. #### 2. 폼 및 입력 처리 - 위젯 설정, 대시보드 생성/수정 등에서 `mat-form-field`, `mat-input`, `mat-select`, `mat-checkbox`, `mat-radio-button` 등 다양한 폼 컴포넌트를 사용합니다. - 유효성 검사, 에러 메시지, UX 개선에 활용됩니다. #### 3. 데이터 표시 및 상호작용 - 테이블(`mat-table`), 리스트(`mat-list`), 탭(`mat-tab-group`), 버튼(`mat-button`), 아이콘(`mat-icon`) 등으로 데이터와 기능을 시각적으로 제공합니다. - 대시보드 내 위젯의 설정, 데이터 소스 선택, 필터링 등에서 Material 컴포넌트가 적극적으로 사용됩니다. #### 4. 다이얼로그 및 알림 - 설정 변경, 삭제 확인, 정보 안내 등에서 `mat-dialog`, `mat-snackbar` 를 활용해 사용자와 상호작용합니다. #### 5. 테마 및 일관성 - Angular Material의 테마 시스템을 적용하여 ThingsBoard 전체 UI의 색상, 폰트, 버튼 스타일 등을 일관성 있게 유지합니다. #### 6. 코드 예시 (공식 위젯 코드 일부) ```typescript import { MatDialog } from '@angular/material/dialog'; import { MatSnackBar } from '@angular/material/snack-bar'; @Component({...}) export class WidgetEditorComponent { constructor(private dialog: MatDialog, private snackBar: MatSnackBar) {} openSettingsDialog() { this.dialog.open(SettingsDialogComponent, { ... }); } showSaveMessage() { this.snackBar.open('저장되었습니다.', '닫기', { duration: 2000 }); } } ``` #### 7. 공식 문서 및 코드 참고 - [ThingsBoard 위젯 개발 가이드]() - [GitHub 소스코드]() - [Angular Material 공식 문서]() **요약:** ThingsBoard는 Angular Material의 다양한 컴포넌트를 적극적으로 활용하여, 대시보드와 위젯의 UI/UX를 일관성 있고 효율적으로 구현하고 있습니다. #### @user ThingsBoard가 Angular 버전 15