AGenUI

AGenUI
AGenUI는 iOS, Android, HarmonyOS 전반에서 네이티브 생성형 UI 경험을 구축하기 위한 고성능 A2UI SDK입니다.

공식 웹사이트 · 빠른 시작 · API 레퍼런스 · 기여하기

English | 中文

이 프로젝트는 활발히 개발 중이며 빠르게 발전하고 있습니다. 기여, 피드백, 논의를 진심으로 환영합니다.

v1.7.0의 새로운 기능

2026-10-19 릴리스

resolveCalls 내장 함수 : JSON에 중첩된 FunctionCall을 재귀적으로 실행하고 각 호출 노드를 반환값으로 대체합니다.
action에 대한 심층 파싱 : registerDeepParseProperty가 이제 함수 인자 및 이벤트 컨텍스트 내에서 중첩된 바인딩 해석을 지원합니다.
크로스 플랫폼 폼 레이블 : ChoicePicker와 Slider의 레이블 렌더링 및 측정을 완료하여 줄바꿈, 동적 업데이트, 초기화를 지원합니다.
(Android) 동적 텍스트 업데이트 후 line-height가 손실되는 문제를 수정했습니다.
(HarmonyOS) action이 있는 Image를 탭할 때 발생하던 크래시를 수정하고, RichText 및 Tabs 콜백에 이벤트 타입 검사를 추가했습니다.
(HarmonyOS) 올바른 파괴 순서를 보장하도록 ChoicePicker 노드 정리를 조정했습니다.
(Playground) 기본 카탈로그 URL 및 관련 테스트 참조를 업데이트했습니다.

AGenUI란 무엇인가?
AGenUI는 iOS, Android, HarmonyOS를 동시에 지원하는 A2UI SDK입니다. Google이 오픈소스로 공개한 A2UI v0.9 프로토콜을 기반으로 하며 이를 완전히 구현하여, LLM이 생성한 인터랙티브 UI의 스트리밍 데이터를 모바일 기기에서 실시간으로 렌더링합니다. 내부적으로는 크로스 플랫폼 공유 C++ 코어 엔진 으로 구동되며, 세 플랫폼의 렌더링 엔진이 코어 엔진이 전달하는 컴포넌트 프로토콜을 소비하고 네이티브 시스템 기능을 사용해 그리기를 수행합니다.

AGenUI는 네이티브 시스템 UI 기능을 활용하여 인터랙티브 카드, 폼, 리스트, 이미지, 미디어 플레이어 등을 렌더링하며, 고성능의 부드러운 사용자 경험을 제공합니다.

주요 기능

실시간 스트리밍 렌더링 — 구조화된 컴포넌트 설명이 LLM에 의해 생성되어 점진적으로 도착하고 실시간으로 업데이트됩니다
고성능 — iOS, Android, HarmonyOS에서 네이티브 렌더링을 수행하며, 페이지 스크롤과 같은 핵심 시나리오에서 120 fps의 주사율을 유지합니다
22개의 내장 컴포넌트 — 18개의 A2UI 프로토콜 컴포넌트 + 4개의 SDK 확장 컴포넌트
커스텀 컴포넌트 API — 커스텀 컴포넌트 API를 통해 네이티브 컴포넌트를 등록하고 확장하여, LLM이 컴포넌트 이름으로 컴포넌트 설명을 출력할 수 있습니다
Function Call 통합 — LLM이 필요에 따라 호출할 수 있는 클라이언트 측 도구/함수를 등록합니다
Design Token & 테마 — 세 플랫폼 전반에 걸친 통합 Design Token 시스템 및 테마 모드
라이트 / 다크 모드 — 내장된 라이트/다크 외관 전환

아키텍처
AGenUI는 공유 C++ 코어 엔진 + 세 플랫폼 컴포넌트 렌더링 엔진 설계를 채택합니다.
C++ 계층은 스트리밍 데이터 파싱, 가상 컴포넌트 트리 관리, 렌더 데이터 캐싱, 테마/스타일 해석, 컴포넌트 변경 diffing을 포함하여 세 플랫폼 모두에서 공유되는 기능을 구현합니다. C++ 계층은 파싱된 컴포넌트 프로토콜을 세 플랫폼 렌더링 엔진에 동기화하여 그리기를 트리거합니다.

프로젝트 디렉터리

경로
내용

core/
C++ 코어 엔진 — 파서, differ, 레이아웃, Function Call 프레임워크

core/include/
플랫폼 브리징 계층이 소비하는 공개 C++ API

platforms/ios/
iOS 컴포넌트 렌더러 + Objective-C 브리지

platforms/android/
Android 컴포넌트 렌더러 + JNI 브리지

platforms/harmony/
HarmonyOS 컴포넌트 렌더러 + NAPI 브리지

playground/
개발 및 디버깅을 위한 세 플랫폼 데모 앱

scripts/
각 플랫폼의 빌드 스크립트

컴포넌트

A2UI 프로토콜 컴포넌트
다음 18개의 컴포넌트는 A2UI 프로토콜 사양을 구현하며 세 플랫폼 모두에서 지원됩니다.

컴포넌트
설명

Text
변형(h1–h5, body, caption 등)을 지원하는 스타일 텍스트

Image
스케일 모드와 둥근 모서리를 지원하는 네트워크 이미지

Icon
Unicode / SVG 매핑을 통해 렌더링되는 아이콘

Divider
가로 또는 세로 구분선

Video
탐색 및 자동 숨김 컨트롤을 지원하는 네이티브 비디오 플레이어

AudioPlayer
진행 표시줄이 있는 오디오 플레이어

Button
Action 이벤트를 트리거하는 탭 가능한 버튼

Row
가로 플렉스 컨테이너

Column
세로 플렉스 컨테이너

Card
그림자가 있는 카드 컨테이너

List
정적 또는 템플릿 기반 자식을 가진 스크롤 가능한 리스트

Tabs
전환 가능한 패널이 있는 탭 바

Modal
네이티브 다이얼로그 오버레이

TextField
선택적 유효성 검사를 지원하는 텍스트 입력

CheckBox
불리언 토글

Slider
숫자 범위 입력

ChoicePicker
단일 / 다중 선택 피커

DateTimeInput
날짜 및 시간 피커

SDK 내장 확장 컴포넌트
다음 4개의 컴포넌트는 SDK에 번들로 포함되어 있지만 A2UI 프로토콜 사양의 일부는 아닙니다.

컴포넌트
설명

Table
Yoga 서브 레이아웃을 사용하는 데이터 테이블

Carousel
이미지 / 콘텐츠 캐러셀

Web
임베디드 WebView

RichText
HTML 리치 텍스트 렌더링

Playground 예제 컴포넌트
다음 3개의 컴포넌트는 API를 통해 커스텀 컴포넌트를 통합하는 방법을 시연하기 위해 Playground에서 등록되고 적용됩니다.

컴포넌트
설명

Chart
막대, 선, 원형 차트

Markdown
스트리밍을 지원하는 Markdown 렌더링

Lottie
Lottie 애니메이션 재생

동일한 API를 사용하여 런타임에 자체 컴포넌트를 등록할 수 있습니다 — 빠른 시작 섹션을 참조하세요.

카탈로그 파일
저장소 루트에는 A2UI v0.9 사양 을 준수하는 자체 포함( freestanding ) Catalog JSON Schema 파일인 agenui_catalog.json 이 포함되어 있습니다. 모든 외부 $ref 가 인라인되었으므로 외부 의존성 없이 독립적으로 사용할 수 있습니다.

포함 범위:

25개 컴포넌트 : 18개의 A2UI 프로토콜 표준 컴포넌트 + 4개의 SDK 내장 확장 컴포넌트( Table , Carousel , Web , RichText ), 그리고 3개의 Playground 예제 컴포넌트( Chart , Markdown , Lottie )
14개 함수 : 유효성 검사, 포맷팅, 논리 연산자, URL 탐색을 포함
공유 타입 정의 : 모든 A2UI v0.9 표준 타입과, AGenUI가 확장한 Styles (일반 스타일 속성) 및 TextStyles (텍스트 전용 스타일 속성)를 포함

사용 방법:

LLM Agent를 통합할 때, 이 파일의 내용 또는 호스팅된 URL을 A2UI ClientCapabilities 의 supportedCatalogIds 필드에 catalogId 로 제공하세요. Agent는 이 Schema를 제약 조건으로 사용하여 엄격히 준수하는 A2UI JSON 메시지를 생성하므로, 렌더러가 전달된 모든 UI 컴포넌트를 올바르게 파싱하고 렌더링할 수 있습니다.

A2UI 생성 Skill
skills/a2ui-generation/ 디렉터리에는 Agent Skills 메커니즘을 지원하는 모든 Agent(예: Claude Code, Cursor, Codex, Gemini CLI, Windsurf, GitHub Copilot 등)에 마운트할 수 있는 독립형 A2UI 생성 Skill이 포함되어 있습니다. 이 Skill은 내장된 설계 규칙과 제약을 통해 LLM이 자연어 쿼리를 AGenUI가 직접 렌더링할 수 있는 A2UI 프로토콜 메시지( updateComponents / updateDataModel )로 변환하도록 안내합니다.

설치
원 커맨드 설치 (권장)

npx skills add AGenUI/AGenUI
Claude Code, Cursor, Codex, Gemini CLI, Windsurf, GitHub Copilot 등 55개 이상의 AI 코딩 에이전트 런타임을 지원합니다.

수동 설치

git clone https://github.com/AGenUI/AGenUI.git
cp -r AGenUI/skills/a2ui-generation ~ /.claude/skills/

다른 런타임의 경우 skills/a2ui-generation/ 디렉터리를 해당 skills 디렉터리(예: ~/.cursor/skills/ , ~/.codex/skills/ )에 복사하세요.

사용 방법
설치 후 에이전트에서 쿼리를 통해 원하는 UI를 설명하세요. Skill이 LLM을 구동하여 A2UI v0.9를 준수하는 JSON 프로토콜을 출력합니다.

레이아웃 & 스타일링

기본 형태 : 핵심 정보에 집중한 단일 Card .
커스텀 레이아웃 & 스타일링 : 쿼리에서 다른 형태(전체 페이지, 리스트, 테이블 등)나 특정 시각적 요구사항(팔레트, 간격, 폰트 크기, 테마)을 명시적으로 요청할 수 있습니다. 명시적 지시가 Skill의 기본값과 충돌할 경우 명시적 지시가 우선합니다.

LLM 선택
A2UI 출력을 생성할 때 LLM마다 다소 다른 결과를 낼 수 있습니다. 자체 시나리오에 여러 모델을 시도해보고 가장 적합한 모델을 선택하는 것을 권장합니다.

AGenUI Studio
AGenUI Studio는 자연어 설명을 렌더링 가능한 A2UI 프로토콜로 변환하는 로컬 bring-your-own-key 워크벤치로, 스트리밍 생성, 실시간 프로토콜 미리보기, 유효성 검사, QR 코드를 통한 실제 기기의 AGenUI Playground로의 원탭 푸시를 위한 브라우저 UI를 제공합니다. 오픈소스 A2UI 생성 Skill(설계 규칙과 검증기 재사용)을 기반으로 하며, 여러 LLM 제공자(DeepSeek, Qwen, GLM, OpenAI, Gemini 등)를 지원하고 전적으로 사용자의 머신에서 실행됩니다.

npx agenui-studio
👉 설치, 구성, 아키텍처 세부 사항은 playground/studio/README.md 를 참조하세요.

빠른 시작
툴체인 요구사항

플랫폼
툴체인

Android
Android Studio Hedgehog+, NDK 27.3.13750724, API 35 SDK, JDK 11

iOS
Xcode 15+, CocoaPods, CMake

HarmonyOS
DevEco Studio 4.0+, ohpm

소스에서 빌드
모든 빌드 스크립트는 scripts/ 디렉터리에 있습니다. core/ 의 C++ 엔진은 자동으로 컴파일되므로 별도의 준비 단계가 필요하지 않습니다.

Android

# Release AAR (기본)
./scripts/android/build.sh

# Debug AAR
./scripts/android/build.sh --debug

# Release AAR + 네이티브 디버그 심볼 동반물 (아래 "네이티브 디버그 심볼" 참조)
./scripts/android/build.sh --with-symbols

# 로컬 Maven(~/.m2)에 게시
./scripts/android/build.sh --publish-local

# Debug AAR을 로컬 Maven에 게시
./scripts/android/build.sh --debug --publish-local

# 원격 Maven에 게시 (MAVEN_URL / MAVEN_USERNAME / MAVEN_PASSWORD 환경 변수 필요)
./scripts/android/build.sh --publish-maven

# 빌드 전 정리
./scripts/android/build.sh --clean
AAR은 dist/android/release/ 에 기록됩니다.

네이티브 디버그 심볼 (Android, 선택적)

호스트에서 릴리스 크래시를 심볼화하려면 ./scripts/android/build.sh --with-symbols 를 실행하세요. 그러면 릴리스 빌드가 다음을 수행합니다:

링커 출력이 DWARF 정보를 유지하도록 -Wl,--strip-all 을 건너뜁니다.
objcopy --only-keep-debug (CMake POST_BUILD)를 통해 DWARF를 형제 lib<name>.so.debug 로 분리한 다음, .so를 스트립하고 .gnu_debuglink 를 통해 연결합니다.
.so.debug 파일을 일반 릴리스 AAR과 함께 build/outputs/aar/ 아래의 <rootProject.name>-symbols.aar 로 패키징합니다.

릴리스 AAR 크기는 영향을 받지 않습니다 — AGP가 패키징 전에 어차피 .so를 스트립하기 때문입니다. .so.debug 접미사는 GNU/LLVM 관례(objcopy의 기본 디버그 확장자)를 따르며 Android의 debug buildType과는 무관합니다.

크래시 주소를 심볼화하려면 심볼 AAR의 압축을 풀고 .so.debug를 표준 도구에 제공하세요:

unzip -j < name > -symbols.aar ' jni/arm64-v8a/*.so.debug ' -d ./symbols/

# 단일 주소
$ANDROID_NDK /toolchains/llvm/prebuilt/ < host > /bin/llvm-addr2line \
-e ./symbols/lib < name > .so.debug -f -C 0xADDR

# logcat의 전체 백트레이스
$ANDROID_NDK /toolchains/llvm/prebuilt/ < host > /bin/ndk-stack \
-sym ./symbols/ -dump crash.log
이 플래그는 기본적으로 OFF입니다 — 명시적으로 활성화하지 않는 한 오픈소스 빌드에는 변화가 없습니다.

iOS

# XCFramework (Release, 기본)
./scripts/ios/build.sh

# 단일 아키텍처 Framework, Debug
./scripts/ios/build.sh -t framework -c Debug

# pod install 강제 실행 후 빌드
./scripts/ios/build.sh --pod-install
HarmonyOS

# HAR 패키지 (Release, 기본)
./scripts/harmony/build.sh

# Debug 빌드
./scripts/harmony/build.sh --mode debug

# 사용자 지정 출력 디렉터리
./scripts/harmony/build.sh -o /path/to/output
Playground로 디버깅
playground 아래에 각 플랫폼별 독립형 Playground 프로젝트가 제공됩니다. 아무 Playground 프로젝트나 열어 실행하면 전체 A2UI 컴포넌트 렌더링을 경험할 수 있습니다. 각 Playground는 AGenUI 소스 코드를 직접 참조하므로 브레이크포인트 디버깅이 지원됩니다.

Android Playground

Android Studio로 playground/android/ 열기
Gradle이 의존성을 설치하고 소스 파일을 인덱싱하도록 허용
gradle.properties 를 통해 의존성 모드 전환:

# 소스 모드: C++ 엔진 및 Android 렌더러 변경 사항이 즉시 적용됨
agenui.sdk.source=true

# AAR 모드: 더 이상 소스를 참조하지 않고 사전 패키징된 SDK 빌드를 소비함 (Playground 자체를 디버깅할 때만 권장)
agenui.sdk.…