Créer et personnaliser des catalogues de composants

Dans l'architecture A2UI, chaque surface est pilotée par un catalogue de composants. Un catalogue est un contrat formel qui définit les composants d'UI, les schémas de propriétés et les fonctions de client local disponibles pour un agent d'IA. Plutôt que de générer du code arbitraire ou d'inventer des éléments inconnus, l'agent doit construire des interfaces utilisateur en utilisant exclusivement les composants déclarés dans le catalogue.

En d'autres termes, le catalogue déclare les composants, et l'agent les utilise pour créer l'UI de votre application.

Lorsque vous créez une application Android avec le moteur de rendu A2UI Jetpack Compose, vous disposez de plusieurs options pour fournir des catalogues :

  • Catalogue de base : le projet A2UI définit une spécification standardisée et à usage général appelée catalogue de base, qui inclut des éléments courants tels que des boutons, du texte, des champs de texte, des cartes et des listes. La bibliothèque AndroidX androidx.compose.material3:material3-a2ui fournit une implémentation prête à l'emploi de cette spécification de catalogue de base à l'aide de composants natifs Material Design 3. La bibliothèque androidx.a2ui.compose:compose-ui fournit également une définition de schéma générique pour le catalogue de base, ce qui vous aide à implémenter le catalogue de base pour votre propre système de conception.
  • Catalogues personnalisés : pour les applications de production dotées de leurs propres systèmes de conception distincts, vous pouvez créer un catalogue personnalisé de toutes pièces. Cela limite l'agent aux composants, aux jetons de style et au langage visuel exacts de votre application.
  • Sous-ensemble ou hybride : vous pouvez combiner des implémentations de composants spécifiques du catalogue de base fourni avec vos propres composants personnalisés, ou remplacer des implémentations de composants individuels dans la suite du catalogue de base.

Utiliser le catalogue de base fourni

Pour commencer rapidement sans créer de schéma de composant à partir de zéro, vous pouvez utiliser l'implémentation fournie de la spécification A2UI Basic Catalog. La bibliothèque androidx.compose.material3:material3-a2ui implémente le catalogue de base à l'aide des composants Material Design 3.

Lorsque vous instanciez materialA2uiBasicCatalogV1, fournissez des renderers et des gestionnaires pour les éléments suivants :

  • Composants multimédias, tels que des lecteurs d'images, de vidéos et audio
  • Outil d'ouverture d'URL
  • Mise en forme des messages localisée

Les bibliothèques A2UI ne regroupent pas intentionnellement les dépendances externes de réseau et de contenu multimédia, telles que Coil, Glide ou Media3. À la place, vous fournissez vos propres renderers. Cela permet d'éviter les conflits de dépendances en fournissant des bibliothèques uniques. Par exemple, si votre application utilise déjà Coil pour le chargement d'images ou Media3 pour la lecture, vous pouvez brancher ces bibliothèques existantes directement dans le catalogue.

L'exemple suivant montre comment instancier le catalogue de base et connecter vos bibliothèques multimédias, votre ouvreur d'URL et votre formateur de messages préférés :

// 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,
)

Assembler un catalogue de composants personnalisés de A à Z

Si votre application utilise un système de conception personnalisé, vous pouvez définir votre propre catalogue contenant vos propres implémentations A2uiComponent personnalisées. Cette approche vous permet de contrôler entièrement les schémas de composants exposés à l'agent et l'UI Compose native émise :

// 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()),
)

Pour savoir comment définir des schémas de composants individuels et leur logique de rendu de l'UI Compose, consultez Implémenter des composants A2UI personnalisés.

Utiliser un sous-ensemble de composants du catalogue de base avec des composants personnalisés

Vous n'avez pas besoin de choisir entre tout créer de A à Z ou adopter l'intégralité du catalogue de base. Vous pouvez assembler un catalogue qui combine des composants sélectionnés de l'implémentation du catalogue de base fournie avec vos propres composants personnalisés :

// 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(...),
)

Vous pouvez également personnaliser la suite de catalogue de base fournie en remplaçant des emplacements de composants spécifiques :

// 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,
    
)

Gérer le versionnage du catalogue et l'évolution du schéma

Les catalogues A2UI sont explicitement versionnés en fonction de leur contrat de schéma JSON. Une mise à jour de version est requise lorsque vous apportez des modifications destructives au schéma :

// 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),
)

Pour permettre des migrations fluides sans temps d'arrêt, votre client peut enregistrer simultanément plusieurs versions de catalogue compatibles avec le processeur de messages :

private val processor = A2uiMessageProcessor(
    catalogs = listOf(
        customCatalogV1(),
        customCatalogV2(),
    ),
)

Lors de la négociation du catalogue, l'agent découvre tous les ID de catalogue compatibles et cible la version appropriée pour chaque surface.

Détails de mise en œuvre

Les sections suivantes expliquent la validation interne du catalogue et la négociation de schéma.

Les parcours utilisateur de gestion du catalogue présentent les API clés suivantes :

  • A2uiCatalog : interface et fonction de fabrique de premier niveau pour définir des catalogues de composants.
  • materialA2uiBasicCatalogVX : fonctions de fabrique versionnées (telles que materialA2uiBasicCatalogV1) qui fournissent l'implémentation Material 3 de la spécification standard du catalogue de base A2UI.
  • A2uiReadinessEvaluator et asReadinessEvaluator() : A2uiReadinessEvaluator est l'interface permettant d'évaluer l'état de préparation des composants. La fonction d'extension asReadinessEvaluator() résout les états de préparation à l'aide des composants enregistrés dans un catalogue.

Catalogue des versions A2UI et schémas des composants

Une définition de schéma de catalogue est associée à une version de protocole spécifique. Lorsque le protocole évolue, la définition du catalogue passe à une version supérieure. Les implémentations de composants pour cette prochaine version peuvent utiliser des API de rendu mises à jour, tandis que les versions inférieures restent opérationnelles côte à côte.

Précédent
Aperçu
Suivant
Surfaces de rendu