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 :
- Un agent standard qui renvoie les données de ressources sous forme de texte brut
- Un agent A2UI qui renvoie les mêmes données que le JSON A2UI structuré
- Un agent rendu qui affiche le JSON A2UI sous forme de composants d'UI interactifs dans l'UI de développement 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
- Dans la console Google Cloud, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.
- 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 :

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.

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.

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 webpendant 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) |
|
|
Web (Lit) |
|
|
Web (Angular) |
|
|
Mobile/Ordinateur | SDK Flutter GenUI |
Documents de référence
- Spécifications et documentation A2UI
- Dépôt GitHub A2UI
- Moteurs de rendu A2UI
- Documentation ADK
- Intégration ADK A2UI
É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).