Accueil / Articles

Interface utilisateur générative avec les ADK Agents via le protocole A2UI : messages et exemples

Découvrez comment A2UI permet à un agent de retourner une interface utilisateur interactive sous forme de JSON, en quoi il diffère d’AG-UI, et comment exécuter localement l’exemple de recherche de restaurants Google ADK.

Éditeur : REACTAPP.TOP6 min de lecture1361 mots

Sources: Agent to UI Protocol (A2UI) with Agent Development Kit (ADK)

Quatre protocoles reviennent fréquemment lorsque des agents sont intégrés à des applications réelles : MCP, A2A, A2UI et AG-UI. AG-UI relie une application frontale à un backend d’agent, et il s’associe bien au Google Agent Development Kit (ADK). L’attention se porte ici sur A2UI, un protocole au nom trompeusement similaire, ainsi que sur la manière de le faire fonctionner à partir d’un agent ADK.

Qu’est-ce que A2UI ?

A2UI est un protocole d’interface utilisateur générative de Google. Il permet aux agents IA de créer des interfaces interactives riches qui peuvent apparaître sur le web, les appareils mobiles et les ordinateurs de bureau. Supposons qu’un utilisateur demande : « Quels sont de bons restaurants à New York ? » L’agent peut aller au-delà de la simple restitution d’une liste textuelle : il peut également fournir une description de l’interface, et un moteur de rendu du côté client transforme cette description en une présentation interactive des restaurants.

Les concepts fondamentaux sont documentés sur a2ui.org, et les éléments essentiels peuvent être expliqués en quelques paragraphes.

Quatre types de messages

Tout ce que l’agent envoie est au format JSON, et il n’existe que quatre types de messages :

  • createSurface crée une nouvelle surface et indique quel catalogue de composants elle utilise.
  • updateComponents ajoute ou modifie des composants UI à l’intérieur d’une surface.
  • updateDataModel modifie l’état de l’application.
  • deleteSurface supprime une surface.

Tous ensemble, ils décrivent à la fois l’interface et les données qui la sous-tendent :

{
  "version": "v0.9",
  "createSurface": {
    "surfaceId": "main",
    "catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json"
  }
}
{
  "version": "v0.9",
  "updateComponents": {
    "surfaceId": "main",
    "components": [...]
  }
}
{
  "version": "v0.9",
  "updateDataModel": {
    "surfaceId": "main",
    "path": "/user",
    "value": { "name": "Alice" }
  }
}

Le catalogue des composants

A2UI fournit un catalogue standard, classé par fonction :

  • Agencement : Ligne, Colonne et Liste, qui organisent d’autres composants
  • Affichage : Texte, Image, Icone, Vidéo et Délimiteur, qui présentent des informations
  • Interactif : Bouton, Champ de texte, Case à cocher, Entrée de date et heure et Glissière, qui permettent d’entrer des données
  • Conteneur : Carte, Onglets et Modal, qui regroupent du contenu

La référence aux composants dans la documentation contient toute une galerie d’exemples.

Une conversation de réservation, message par message

L’exemple de réservation dans un restaurant présenté dans la documentation illustre bien le cycle de vie.

D’abord, l’agent crée une surface :

{
  "version": "v0.9",
  "createSurface": {
    "surfaceId": "booking",
    "catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json"
  }
}

Deuxièmement, il définit la structure de l’interface utilisateur :

{
  "version": "v0.9",
  "updateComponents": {
    "surfaceId": "booking",
    "components": [
      {
        "id": "root",
        "component": "Column",
        "children": ["header", "guests-field", "submit-btn"]
      },
      {
        "id": "header",
        "component": "Text",
        "text": "Confirm Reservation",
        "variant": "h1"
      },
      {
        "id": "guests-field",
        "component": "TextField",
        "label": "Guests",
        "value": { "path": "/reservation/guests" }
      },
      {
        "id": "submit-btn",
        "component": "Button",
        "child": "submit-text",
        "variant": "primary",
        "action": {
          "event": {
            "name": "confirm",
            "context": {
              "details": { "path": "/reservation" }
            }
          }
        }
      }
    ]
  }
}

Troisièmement, il remplit les données :

{
  "version": "v0.9",
  "updateDataModel": {
    "surfaceId": "booking",
    "path": "/reservation",
    "value": {
      "datetime": "2025-12-16T19:00:00Z",
      "guests": "2"
    }
  }
}

Quatrièmement, l’utilisateur change le nombre d’invités à 3, et le client met à jour automatiquement /reservation/guests. Cinquièmement, l’utilisateur appuie sur Confirmer, et le client envoie une action en retour :

{
  "version": "v0.9",
  "action": {
    "name": "confirm",
    "surfaceId": "booking",
    "context": {
      "details": {
        "datetime": "2025-12-16T19:00:00Z",
        "guests": "3"
      }
    }
  }
}

Sixièmement, l’agent répond soit en mettant à jour à nouveau l’interface utilisateur, soit en fermant l’interface :

{
  "version": "v0.9",
  "deleteSurface": { "surfaceId": "booking" }
}

Transport et rendu

A2UI se moque de la manière dont les messages sont transmis, puisque tout ce qui peut gérer du JSON fonctionne. Actuellement, les transports A2A et AG-UI sont pris en charge, tandis que REST, WebSockets et SSE sont prévus ou proposés. La page des transports dans la documentation liste ce qui est actuel.

Lorsque l’agent a généré le JSON, un rendeur le convertit en composants natifs. Sur le web, il existe des rendeurs Lit et Angular, tandis que le SDK GenUI de Flutter couvre les appareils mobiles, les postes de travail et le web. La page des rendeurs maintient cette liste à jour.

A2UI et AG-UI côte à côte

Les noms sont similaires, et les fonctions sont différentes mais complémentaires. AG-UI constitue la liaison entre une application destinée aux utilisateurs et le backend agentic. A2UI est une spécification déclarative que les agents utilisent pour inclure des widgets UI dans leurs réponses.

Essayer les exemples

Le dépôt A2UI contient des exemples d’agents ADK qui peuvent être générés et affichés localement. Clonez-le d’abord :

git clone https://github.com/google/a2ui.git
cd a2ui

Définir une clé API Gemini :

export GEMINI_API_KEY="your_gemini_api_key_here"

Chaque échantillon comprend une partie serveur (l’agent) et une partie client (le rendeur), et les deux doivent être en cours d’exécution. Les échantillons d’agents ADK se trouvent dans le dossier adk, sous samples/agent, tandis que les rendeurs clients se trouvent dans samples/client.

Recherche de restaurants

Dans le dossier samples/client/lit, une seule commande suffit pour lancer la démonstration :

npm run demo:restaurant

Ouvrez http://localhost:5173/?app=restaurant et commencez à formuler des requêtes, par exemple « Top 5 restaurants chinois à New York ». L’agent génère l’interface utilisateur qui est ensuite affichée par le client :

Les journaux montrent le JSON A2UI brut envoyé par l’agent :

[REST] LiteLLM completion() model= gemini-2.5-flash; provider = gemini
[REST] INFO:agent:Event from runner: model_version='gemini-2.5-flash' content=Content(
[REST]   parts=[
[REST]     Part(
[REST]       text="""<a2ui-json>
[REST] [
[REST]   {
[REST]     "beginRendering": {
[REST]       "surfaceId": "default",
[REST]       "root": "root-column",
[REST]       "styles": {
[REST]         "primaryColor": "#FF0000",
[REST]         "font": "Roboto"
[REST]       }
[REST]     }
[REST]   },
[REST]   {
[REST]     "surfaceUpdate": {
[REST]       "surfaceId": "default",
[REST]       "components": [
[REST]         {
[REST]           "id": "root-column",
[REST]           "component": {
[REST]             "Column": {
[REST]               "children": {
[REST]                 "explicitList": [
[REST]                   "title-heading",
[REST]                   "item-list"
[REST]                 ]
[REST]               }
[REST]             }
[REST]           }
[REST]         },
...

Que se passe-t-il à l’intérieur

Le code de l’agent se trouve dans samples/agent/adk/restaurant_finder. prompt_builder.py montre comment le prompt est construit afin que l’agent réponde en A2UI. La description du rôle commence par une instruction stricte stipulant que la sortie finale doit être une réponse JSON A2UI :

ROLE_DESCRIPTION = (
    "You are a helpful restaurant finding assistant. Your final output MUST be a a2ui"
    " UI JSON response."
)

UI_DESCRIPTION = """
-   If the query is for a list of restaurants, use the restaurant data you have already received from the `get_restaurants` tool to populate the `dataModelUpdate.contents` array (e.g., as a `valueMap` for the "items" key).
-   If the number of restaurants is 5 or fewer, you MUST use the `SINGLE_COLUMN_LIST_EXAMPLE` template.
-   If the number of restaurants is more than 5, you MUST use the `TWO_COLUMN_LIST_EXAMPLE` template.
-   If the query is to book a restaurant (e.g., "USER_WANTS_TO_BOOK..."), you MUST use the `BOOKING_FORM_EXAMPLE` template.
-   If the query is a booking submission (e.g., "User submitted a booking..."), you MUST use the `CONFIRMATION_EXAMPLE` template.
"""

La classe A2uiSchemaManager charge des catalogues de composants et génère des prompts système qui guident le modèle concernant les formats JSON A2UI valides. L’appel à generate_system_prompt combine la description du rôle de l’agent avec le schéma ainsi que quelques exemples concrets, ce qui permet au modèle de disposer de directives de formatage précises :

version = VERSION_0_9
restaurant_prompt = A2uiSchemaManager(
    version,
    catalogs=[
        BasicCatalog.get_config(
            version=version,
            examples_path=f"examples/{version}",
        )
    ],
    schema_modifiers=[remove_strict_validation],
).generate_system_prompt(
    role_description=ROLE_DESCRIPTION,
    ui_description=UI_DESCRIPTION,
    include_schema=True,
    include_examples=True,
    validate_examples=True,
)

agent.py crée ensuite l’agent avec ce prompt système :

return LlmAgent(
    model=LiteLlm(model=LITELLM_MODEL),
    name="restaurant_agent",
    description="An agent that finds restaurants and helps book tables.",
    instruction=instruction,
    tools=[get_restaurants],
)

Après que l’agent ait généré du JSON, celui-ci doit être validé selon le schéma A2UI avant d’être transmis au client :

# --- Validation Steps ---
# Check if it validates against the A2UI_SCHEMA
# This will raise jsonschema.exceptions.ValidationError if it fails
logger.info(
    "--- RestaurantAgent.stream: Validating against A2UI_SCHEMA... ---"
)
selected_catalog.validator.validate(parsed_json_data)

La documentation ADK dispose d’une page d’intégration A2UI offrant plus de détails. Du côté client, renderers/lit contient l’implémentation Lit qui prend le JSON généré et le rend.

Outils pour commencer

CopilotKit publie un modèle de démarrage A2UI, ainsi qu’un A2UI Composer pour expérimenter avec les composants.

Des ressources utiles pour continuer à lire sont la documentation et la spécification du protocole A2UI, le répertoire GitHub, l’article d’annonce de Google sur les interfaces pilotées par des agents, la page d’intégration ADK, le Composer et le modèle de démarrage CopilotKit, ainsi que quelques vidéos YouTube sur des agents créant des interfaces en temps réel.