Expériences frontend avec ADK et A2UI

1. Présentation

La plupart des agents d'IA répondent par écrit. Dans cet atelier de programmation, vous allez utiliser A2UI pour permettre à votre agent de répondre avec une interface utilisateur. L'agent décrit les cartes, les listes, les boutons et les formulaires au format JSON à l'aide d'un catalogue de composants standards. Le client les affiche avec ses propres widgets natifs. Il n'est donc pas nécessaire d'écrire du code frontend pour les nouvelles mises en page.

Vous allez créer l'agent avec Agent Development Kit (ADK).

Ce que vous allez faire

Tableau de bord d'infrastructure cloud fictif en trois étapes :

  1. Un agent standard qui renvoie les données de ressources sous forme de texte brut
  2. Un agent A2UI qui renvoie les mêmes données que le JSON A2UI structuré
  3. Un agent rendu qui affiche le JSON A2UI sous forme de composants d'UI interactifs dans l'UI de développement ADK

Agent A2UI ADK

Points abordés

  • Fonctionnement d'A2UI : 18 primitives, les messages qui créent une UI et le modèle de composant plat
  • Utiliser le SDK A2UI pour inviter un agent ADK à générer du JSON A2UI
  • Afficher les composants A2UI dans adk web

Prérequis

  • Un projet Google Cloud avec facturation activée
  • Un navigateur Web (par exemple, Chrome)
  • Python 3.12+ et uv, si vous exécutez le code sur votre propre machine au lieu de Cloud Shell

Cet atelier de programmation s'adresse aux développeurs intermédiaires qui connaissent déjà Python et Google Cloud.

Cet atelier de programmation prend environ 20 minutes.

Les ressources créées dans cet atelier de programmation devraient coûter moins de 5 $.

2. Configurer votre environnement

Créer un projet Google Cloud

  1. Dans la console Google Cloud, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.
  2. Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet.

Démarrer l'éditeur Cloud Shell

Pour lancer une session Cloud Shell à partir de la console Google Cloud, cliquez sur Activer Cloud Shell dans la console Google Cloud.

Une session s'ouvre dans le volet inférieur de la console Google Cloud.

Pour lancer l'éditeur, cliquez sur Ouvrir l'éditeur dans la barre d'outils de la fenêtre Cloud Shell.

Activer les API

Dans la barre d'outils de l'éditeur Cloud Shell, cliquez sur Terminal, puis sur Nouveau terminal. Exécutez ensuite la commande suivante pour activer les API requises :

gcloud services enable aiplatform.googleapis.com

Installer des dépendances

Dans le terminal, exécutez les commandes suivantes pour créer un dossier pour cet atelier de programmation, avec un dossier a2ui_agent à l'intérieur pour le code de votre agent, et installez Agent Development Kit (ADK) et le SDK A2UI :

mkdir -p ~/adk-a2ui/a2ui_agent
cd ~/adk-a2ui
uv init --bare
uv add google-adk a2ui-agent-sdk

uv crée un environnement Python isolé pour cet atelier de programmation. Vous n'avez donc rien à activer. Faites précéder les commandes Python de uv run.

3. Créer l'agent

Commencez par un agent ADK standard qui renvoie du texte brut. Voici à quoi ressemble la plupart des applications d'agent aujourd'hui.

Configurer les paramètres de votre projet

Dans le terminal, exécutez la commande suivante pour créer a2ui_agent/.env avec votre projet et votre emplacement, et pour que ADK appelle Gemini via votre projet Google Cloud. ADK charge automatiquement ce fichier, ce qui permet aux paramètres de fonctionner également dans les nouveaux terminaux.

cat > ~/adk-a2ui/a2ui_agent/.env <<EOF
GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_ENTERPRISE=True
EOF

Définir l'outil et les données fictives

Créez a2ui_agent/resources.py avec le contenu suivant. Cet outil renvoie une liste des ressources cloud avec leur état.

RESOURCES = [
    {
        "name": "auth-service",
        "type": "Cloud Run",
        "region": "us-west1",
        "status": "healthy",
        "cpu": "2 vCPU",
        "memory": "1 GiB",
        "instances": 3,
        "url": "https://auth-service-abc123.run.app",
        "last_deployed": "2026-04-18T14:22:00Z",
    },
    {
        "name": "events-db",
        "type": "Cloud SQL",
        "region": "us-east1",
        "status": "warning",
        "tier": "db-custom-8-32768",
        "storage": "500 GB SSD",
        "connections": 195,
        "version": "PostgreSQL 16",
        "issue": "Storage usage at 92%",
    },
    {
        "name": "analytics-pipeline",
        "type": "Cloud Run",
        "region": "us-west1",
        "status": "error",
        "cpu": "2 vCPU",
        "memory": "4 GiB",
        "instances": 0,
        "url": "https://analytics-pipeline-ghi789.run.app",
        "last_deployed": "2026-04-10T16:45:00Z",
        "issue": "CrashLoopBackOff: OOM killed",
    },
]

def get_resources() -> list[dict]:
    """Get all cloud resources in the current project.
    Returns a list of cloud infrastructure resources including their
    name, type, region, status, and type-specific details.
    Status is one of: healthy, warning, error. Resources with
    warning or error status include an 'issue' field describing
    the problem.
    """
    return RESOURCES

Définir l'agent

Créez a2ui_agent/agent.py avec le contenu suivant :

from google.adk.agents import Agent
from google.adk.models import Gemini
from google.genai import types
from .resources import get_resources

root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that reports on project resources.",
    instruction=(
        "You are a cloud infrastructure assistant. When users ask about their "
        "cloud resources, use the get_resources tool to fetch the current state. "
        "Summarize the results clearly in plain text."
    ),
    tools=[get_resources],
)

4. Tester l'agent

ADK inclut une UI de développement que vous pouvez utiliser pour interagir avec votre agent et lui envoyer des requêtes dans un navigateur à des fins de test.

Démarrer l'UI de développement ADK

Dans le terminal de l'éditeur Cloud Shell, exécutez la commande suivante pour démarrer l'UI de développement ADK :

uv run adk web --port 8080 --allow_origins "*" --reload_agents

Un message semblable au suivant doit s'afficher :

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8080.                         |
+-----------------------------------------------------------------------------+

Ouvrir l'UI de développement ADK

Vous pouvez ouvrir l'interface utilisateur de développement ADK dans votre navigateur en cliquant sur l'URL de test local tout en appuyant sur Ctrl ou Cmd, ou en cliquant sur le bouton Aperçu sur le Web et en sélectionnant Prévisualiser sur le port 8080.

Une fois que vous êtes dans l'UI de développement d'ADK, sélectionnez a2ui_agent dans le menu déroulant.

Envoyer des exemples de requêtes

Envoyez un exemple de requête à l'agent :

What's running in my project?

Essayez maintenant un autre exemple de requête. Vous obtiendrez plus de texte :

Does anything need my attention?

Votre conversation devrait ressembler à ceci :

Agent de texte ADK

La réponse est exacte, mais elle est trop longue.

5. Générer du code JSON A2UI

Ensuite, passez de texte brut à A2UI.

Le SDK Python A2UI inclut un générateur de prompts qui rédige des prompts système pour vous. Il enseigne au LLM le catalogue complet des composants A2UI, les noms et types de propriétés corrects, ainsi que la structure JSON.

Mettre à jour l'agent

Remplacez le contenu de a2ui_agent/agent.py par le code suivant :

from google.adk.agents import Agent
from google.adk.agents.callback_context import CallbackContext
from google.adk.models import Gemini
from google.adk.models.llm_response import LlmResponse
from google.genai import types
from a2ui.inference_formats.direct_json import DirectJsonFormat
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources

a2ui_format = DirectJsonFormat(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = a2ui_format.prompt_generator.generate(
    role_description=(
        "You are a cloud infrastructure assistant. When users ask about "
        "their cloud resources, use the get_resources tool to fetch the "
        "current state."
    ),
    workflow_description=(
        "Analyze the user's request and return structured UI when appropriate."
    ),
    ui_description=(
        "Use cards for resource summaries, rows and columns for comparisons, "
        "icons for status indicators, and buttons for drill-down actions. "
        "Do NOT use markdown formatting in text values. Use the usageHint "
        "property for heading levels instead. "
        "Respond ONLY with the A2UI JSON array. Do NOT include any text "
        "outside the JSON. Put all explanations into Text components."
    ),
    include_schema=True,
    include_examples=True,
)


def show_raw_json(
    callback_context: CallbackContext,
    llm_response: LlmResponse,
) -> LlmResponse | None:
    """Show the A2UI JSON as text so you can read it, instead of rendering it."""
    if not llm_response.content or not llm_response.content.parts:
        return None
    for part in llm_response.content.parts:
        if part.text:
            part.text = (
                part.text
                .replace("<a2ui-json>", "```json\n")
                .replace("</a2ui-json>", "\n```")
            )
    return llm_response


root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
    after_model_callback=show_raw_json,
)

show_raw_json affiche le JSON A2UI sous forme de texte pour que vous puissiez le lire. Vous le supprimerez plus tard pour voir l'interface utilisateur s'afficher.

La méthode prompt_generator.generate() combine la description de votre rôle avec le schéma JSON A2UI complet et des exemples de type "few-shot". Le LLM sait ainsi exactement comment mettre en forme sa sortie. Vous n'avez pas besoin d'écrire le catalogue de composants à la main.

Cet atelier de programmation utilise la version 0.8 d'A2UI (version="0.8"), qui est la version compatible avec le moteur de rendu A2UI adk web.

6. Tester la sortie JSON

Si l'interface utilisateur de développement de l'ADK est toujours en cours d'exécution, elle devrait recharger automatiquement les modifications que vous avez apportées à votre agent.

Sélectionnez a2ui_agent, démarrez une nouvelle session en cliquant sur + Nouvelle session en haut à droite de l'UI de développement ADK, puis envoyez la même requête qu'avant :

What's running in my project?

Cette fois, l'agent répond avec un JSON A2UI au lieu d'un texte brut. Vous verrez des messages structurés tels que beginRendering et surfaceUpdate (et parfois dataModelUpdate) dans le résultat du chat, dans un bloc de code JSON.

ADK A2UI JSON

Le JSON décrit une interface utilisateur riche avec des cartes, des icônes et des boutons, mais show_raw_json le conserve sous forme de texte pour que vous puissiez le lire. Vous allez ensuite examiner la structure de ce JSON, puis supprimer show_raw_json pour l'afficher sous forme de composants d'interface utilisateur.

7. Comprendre A2UI

Examinez le fichier JSON que votre agent vient de générer. A2UI propose trois types de messages pour créer une UI. Il est possible que la réponse de votre agent n'utilise pas toujours les trois :

1. beginRendering

Crée une surface de rendu et nomme le composant racine :

{"beginRendering": {"surfaceId": "default", "root": "main-column"}}

2. surfaceUpdate

Envoie l'arborescence des composants sous forme de liste plate avec des références d'ID (non imbriquées) :

{"surfaceUpdate": {"surfaceId": "default", "components": [
  {"id": "main-column", "component": {"Column": {"children": {"explicitList": ["title", "card1"]}}}},
  {"id": "title", "component": {"Text": {"text": {"literalString": "My Resources"}, "usageHint": "h1"}}},
  {"id": "card1", "component": {"Card": {"child": "card1-content"}}},
  {"id": "card1-content", "component": {"Text": {"text": {"path": "service_name"}}}}
]}}

3. dataModelUpdate

Envoie les données séparément de la structure :

{"dataModelUpdate": {"surfaceId": "default", "contents": [
  {"key": "service_name", "valueString": "auth-service"},
  {"key": "status", "valueString": "healthy"}
]}}

Les composants sont liés aux données à l'aide de {"path": "key"}. Vous pouvez mettre à jour les données sans renvoyer l'arborescence des composants.

Les 18 primitives

Catégorie

Composants

Disposition

Carte, colonne, ligne, liste, onglets, séparateur, modal

Écran

Texte, Image, Icône, Vidéo, Lecteur audio

Entrée

TextField, DateTimeInput, MultipleChoice, CheckBox, Slider

Action

Bouton

L'agent crée différentes mises en page, comme une vue de navigation, un tableau de bord des priorités ou un formulaire de configuration, à partir de ces mêmes composants. Pour en savoir plus sur chacun d'eux, consultez la documentation de référence sur les composants.

8. Afficher les composants A2UI

Le SDK encapsule A2UI dans des balises standards. adk web les reconnaît et affiche les composants avec son moteur de rendu A2UI intégré. Pour le voir, supprimez show_raw_json.

Mettre à jour l'agent

Remplacez le contenu de a2ui_agent/agent.py par le code suivant : Les seules différences par rapport à l'étape précédente sont que la fonction show_raw_json, son paramètre after_model_callback et les deux importations qu'elle utilisait ont disparu :

from google.adk.agents import Agent
from google.adk.models import Gemini
from google.genai import types
from a2ui.inference_formats.direct_json import DirectJsonFormat
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources

a2ui_format = DirectJsonFormat(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = a2ui_format.prompt_generator.generate(
    role_description=(
        "You are a cloud infrastructure assistant. When users ask about "
        "their cloud resources, use the get_resources tool to fetch the "
        "current state."
    ),
    workflow_description=(
        "Analyze the user's request and return structured UI when appropriate."
    ),
    ui_description=(
        "Use cards for resource summaries, rows and columns for comparisons, "
        "icons for status indicators, and buttons for drill-down actions. "
        "Do NOT use markdown formatting in text values. Use the usageHint "
        "property for heading levels instead. "
        "Respond ONLY with the A2UI JSON array. Do NOT include any text "
        "outside the JSON. Put all explanations into Text components."
    ),
    include_schema=True,
    include_examples=True,
)

root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
)

9. Tester l'UI affichée

Si l'interface utilisateur de développement de l'ADK est toujours en cours d'exécution, elle devrait recharger automatiquement les modifications que vous avez apportées à votre agent.

Actualisez l'onglet du navigateur, sélectionnez a2ui_agent, puis démarrez une nouvelle session en cliquant sur + Nouvelle session en haut à droite de l'UI de développement ADK et envoyez le même prompt qu'avant :

What's running in my project?

Cette fois, adk web affiche les composants A2UI en tant qu'UI réelle : des fiches avec des indicateurs d'état, des détails sur les ressources et des boutons d'action.

Agent A2UI ADK

Essayez un autre prompt pour voir comment l'agent compose une autre UI à partir du même ensemble de primitives :

Does anything need my attention?

Enfin, essayez une autre requête pour générer une autre UI permettant de déployer un nouveau service :

I need to deploy a new service

Les trois requêtes utilisent le même agent, le même outil et les mêmes composants, mais chacune produit une interface utilisateur différente qui correspond à ce que vous avez demandé.

10. Effectuer un nettoyage

Pour éviter de laisser des serveurs locaux en cours d'exécution, nettoyez les ressources :

  • Dans le terminal exécutant adk web, appuyez sur Ctrl+C pour arrêter le serveur de l'agent.

Si vous avez créé un projet spécifiquement pour cet atelier de programmation, vous pouvez le supprimer entièrement :

gcloud projects delete <YOUR_PROJECT_ID>

11. Félicitations

Vous avez créé un agent ADK qui génère une UI riche et interactive à l'aide d'A2UI.

Ce que vous avez appris

  • A2UI est un protocole avec 18 primitives déclaratives et quelques messages simples qui créent une UI.
  • Le SDK A2UI génère des invites système qui enseignent au LLM le catalogue de composants.
  • Le même agent, le même outil et les mêmes primitives composent différentes UI pour différentes intentions.
  • Les composants A2UI peuvent être affichés directement dans adk web pendant le développement.

Créer une interface de production

Dans cet atelier de programmation, vous avez affiché A2UI dans adk web pour le développement et les tests.

Pour la production, vous devez créer un frontend à l'aide de l'un des moteurs de rendu A2UI officiels :

Plate-forme

Moteur de rendu

Installer

Web (React)

@a2ui/react

npm install @a2ui/react

Web (Lit)

@a2ui/lit

npm install @a2ui/lit

Web (Angular)

@a2ui/angular

npm install @a2ui/angular

Mobile/Ordinateur

SDK Flutter GenUI

Premiers pas

Documents de référence

Étape suivante

Découvrez des ressources de formation pour créer et déployer des agents de niveau entreprise avec Gemini Enterprise Agent Ready (GEAR).