A2UI 아키텍처에서 모든 화면은 구성요소 카탈로그에 의해 구동됩니다. 카탈로그는 AI 에이전트가 사용할 수 있는 UI 구성요소, 속성 스키마, 로컬 클라이언트 함수를 정의하는 공식 계약입니다. 에이전트는 임의의 코드를 생성하거나 알 수 없는 요소를 발명하는 대신 카탈로그에 선언된 구성요소만 사용하여 사용자 인터페이스를 구성해야 합니다.
즉, 카탈로그는 구성요소를 선언하고 에이전트는 이를 사용하여 앱의 UI를 빌드합니다.
Jetpack Compose A2UI 렌더러로 Android 앱을 빌드할 때 카탈로그를 제공하는 방법에 관한 유연한 옵션이 있습니다.
- 기본 카탈로그: A2UI 프로젝트는 버튼, 텍스트, 텍스트 필드, 카드, 목록과 같은 일반 요소를 포함하는 기본 카탈로그라는 표준화된 범용 사양을 정의합니다. AndroidX 라이브러리
androidx.compose.material3:material3-a2ui는 네이티브 Material Design 3 구성요소를 사용하여 이 기본 카탈로그 사양을 기본적으로 구현합니다.androidx.a2ui.compose:compose-ui라이브러리는 기본 카탈로그의 일반 스키마 정의도 제공하므로 자체 디자인 시스템의 기본 카탈로그를 구현하는 데 도움이 됩니다. - 맞춤 카탈로그: 자체 디자인 시스템이 있는 프로덕션 애플리케이션의 경우 처음부터 맞춤 카탈로그를 빌드할 수 있습니다. 이렇게 하면 에이전트가 앱의 정확한 구성요소, 스타일 지정 토큰, 시각적 언어로 제한됩니다.
- 하위 집합 또는 하이브리드: 제공된 기본 카탈로그의 특정 구성요소 구현을 자체 맞춤 구성요소와 결합하거나 기본 카탈로그 제품군 내에서 개별 구성요소 구현을 재정의할 수 있습니다.
제공된 기본 카탈로그 사용
처음부터 구성요소 스키마를 작성하지 않고 빠르게 시작하려면 제공된 A2UI 기본 카탈로그 사양 구현을 사용하면 됩니다. androidx.compose.material3:material3-a2ui 라이브러리는 Material Design 3 구성요소를 사용하여 기본 카탈로그를 구현합니다.
materialA2uiBasicCatalogV1를 인스턴스화할 때 다음의 렌더러와 핸들러를 제공합니다.
- 이미지, 동영상, 오디오 플레이어와 같은 미디어 구성요소
- URL 오프너
- 현지화된 메시지 형식
A2UI 라이브러리는 Coil, Glide, Media3과 같은 외부 미디어 및 네트워킹 종속 항목을 번들로 묶지 않습니다. 대신 자체 렌더러를 제공합니다. 이렇게 하면 고유한 라이브러리를 제공하여 종속 항목 충돌을 방지할 수 있습니다. 예를 들어 앱에서 이미지를 로드하는 데 Coil을 사용하거나 재생에 Media3를 사용하는 경우 기존 라이브러리를 카탈로그에 직접 연결할 수 있습니다.
다음 예시는 기본 카탈로그를 인스턴스화하고 선호하는 미디어 라이브러리, URL 오프너, 메시지 포맷터를 연결하는 방법을 보여줍니다.
// Instantiate the provided Basic Catalog (implemented with Material 3)
val basicCatalog = materialA2uiBasicCatalogV1(
// Example: Wire up Coil for image loading (via AsyncImage)
image = MaterialA2uiBasicCatalogV1Defaults.image {
url, description, scale, modifier, onError ->
AsyncImage(
model = url,
contentDescription = description,
contentScale = scale,
modifier = modifier,
onError = { state -> onError(state.result.throwable) },
)
},
// Example: Use ExoPlayer/Media3 for video
video = MaterialA2uiBasicCatalogV1Defaults.video { url, modifier, onError ->
// Custom ExoPlayer video integration here
},
// Example: Use an audio player
audioPlayer = MaterialA2uiBasicCatalogV1Defaults.audioPlayer {
url, description, modifier, onError ->
// Custom audio integration here
},
// Handle outbound URLs, such as using an app navigator or context intents.
urlOpener = { url ->
appNavigator.openUrl(url)
},
// Handle localized message formatting
messageFormatter = { pattern, locale, args ->
MessageFormat.format(context, locale, pattern, args)
},
localeProvider = A2uiLocaleProvider.Default,
)
처음부터 맞춤 구성요소 카탈로그 조립
앱에서 맞춤 디자인 시스템을 사용하는 경우 자체 맞춤 A2uiComponent 구현이 포함된 자체 카탈로그를 정의할 수 있습니다. 이 접근 방식을 사용하면 에이전트에 노출되는 구성요소 스키마와 내보내지는 네이티브 Compose UI를 완전히 제어할 수 있습니다.
// Define a custom catalog that mirrors your app's design system
val CustomDesignSystemCatalog = A2uiCatalog(
catalogId = "https://example.com/catalogs/my-design-system/v1/catalog.json",
components = listOf(
CustomButtonComponent,
CustomCardComponent,
CustomTextFieldComponent,
),
functions = listOf(MyCustomLocalFunction()),
)
개별 구성요소 스키마와 Compose UI 렌더링 로직을 정의하는 방법은 맞춤 A2UI 구성요소 구현을 참고하세요.
맞춤 구성요소와 함께 기본 카탈로그 구성요소의 하위 집합 사용
모든 것을 처음부터 빌드하거나 전체 기본 카탈로그를 채택하는 것 중에서만 선택할 필요는 없습니다. 제공된 기본 카탈로그 구현의 일부 구성요소를 자체 맞춤 구성요소와 결합하는 카탈로그를 어셈블할 수 있습니다.
// Assemble a catalog using select Basic Catalog components alongside custom components
val hybridCatalog = A2uiCatalog(
catalogId = "https://example.com/catalogs/my-app/v1/catalog.json",
components = listOf(
// Use provided Basic Catalog components (built with Material 3)
MaterialA2uiBasicCatalogV1Defaults.text,
MaterialA2uiBasicCatalogV1Defaults.card,
// Add proprietary components from your app's design system
CustomChartComponent,
CustomProductCardComponent,
),
functions = createBasicCatalogFunctions(...),
)
또는 특정 구성요소 슬롯을 재정의하여 제공된 기본 카탈로그 스위트를 맞춤설정할 수 있습니다.
// Override specific components within the Basic Catalog suite
val customizedBasicCatalog = materialA2uiBasicCatalogV1(
// Supply required renderers (such as Coil or ExoPlayer) as shown earlier
image = MaterialA2uiBasicCatalogV1Defaults.image(myImageRenderer),
video = MaterialA2uiBasicCatalogV1Defaults.video(myVideoRenderer),
audioPlayer = MaterialA2uiBasicCatalogV1Defaults
.audioPlayer(myAudioRenderer),
urlOpener = { url -> /* Open URL */ },
messageFormatter = { pattern, _, _ -> pattern },
localeProvider = A2uiLocaleProvider.Default,
// Replaces the default button. If you use this, implement the
// A2uiBasicCatalogV1.Button interface.
button = MyCustomBrandButtonComponent,
)
카탈로그 버전 관리 및 스키마 진화 관리
A2UI 카탈로그는 JSON 스키마 계약에 따라 명시적으로 버전이 지정됩니다. 브레이킹 스키마 변경사항을 도입할 때는 버전 업그레이드가 필요합니다.
// Original component (v1 catalog)
object CustomButtonComponent : A2uiComponent { ... }
// Unchanged component across versions
object CustomTextComponent : A2uiComponent { ... }
// Future breaking schema change (v2 catalog)
object CustomButtonComponentV2 : A2uiComponent { ... }
// Assembles the v1 catalog
fun customCatalogV1(
button: A2uiComponent = CustomButtonComponent,
text: A2uiComponent = CustomTextComponent,
): A2uiCatalog = A2uiCatalog(
catalogId = "https://example.com/catalogs/my-app/v1/catalog.json",
components = listOf(button, text),
)
// Assembles the v2 catalog
fun customCatalogV2(
button: A2uiComponent = CustomButtonComponentV2,
text: A2uiComponent = CustomTextComponent,
): A2uiCatalog = A2uiCatalog(
catalogId = "https://example.com/catalogs/my-app/v2/catalog.json",
components = listOf(button, text),
)
다운타임 없이 원활한 마이그레이션을 지원하려면 클라이언트가 메시지 프로세서에 지원되는 카탈로그 버전을 여러 개 동시에 등록하면 됩니다.
private val processor = A2uiMessageProcessor(
catalogs = listOf(
customCatalogV1(),
customCatalogV2(),
),
)
카탈로그 협상 중에 에이전트는 지원되는 모든 카탈로그 ID를 검색하고 각 표시 경로에 적합한 버전을 타겟팅합니다.
구현 세부정보
다음 섹션에서는 내부 카탈로그 검증 및 스키마 협상을 설명합니다.
카탈로그 관리 사용자 여정에서는 다음 주요 API를 소개합니다.
A2uiCatalog: 구성요소 카탈로그를 정의하기 위한 인터페이스 및 최상위 팩토리 함수입니다.materialA2uiBasicCatalogVX: 표준 A2UI 기본 카탈로그 사양의 Material 3 구현을 제공하는 버전이 지정된 팩토리 함수 (예:materialA2uiBasicCatalogV1)입니다.A2uiReadinessEvaluator및asReadinessEvaluator():A2uiReadinessEvaluator는 구성요소 준비 상태를 평가하는 인터페이스입니다.asReadinessEvaluator()확장 함수는 카탈로그에 등록된 구성요소를 사용하여 준비 상태를 확인합니다.
A2UI 버전 카탈로그 및 구성요소 스키마
카탈로그 스키마 정의는 특정 프로토콜 버전과 연결됩니다. 프로토콜이 발전하면 카탈로그 정의의 버전이 업데이트됩니다. 이 다음 버전의 구성요소 구현은 업데이트된 렌더러 API를 사용할 수 있으며 하위 버전은 나란히 작동합니다.