1. Panoramica
La maggior parte degli agenti AI risponde con un testo. In questo codelab, utilizzerai A2UI per consentire al tuo agente di rispondere con un'interfaccia utente. L'agente descrive schede, elenchi, pulsanti e moduli in formato JSON, utilizzando un catalogo di componenti standard, e il client li esegue il rendering con i propri widget nativi, in modo che i nuovi layout non richiedano nuovo codice frontend.
Creerai l'agente con Agent Development Kit (ADK).
Cosa creerai
Una dashboard dell'infrastruttura cloud simulata in tre fasi:
- Un agente standard che restituisce i dati delle risorse come testo normale
- Un agente A2UI che restituisce gli stessi dati del JSON A2UI strutturato
- Un agente sottoposto a rendering che mostra il JSON A2UI come componenti UI interattivi nell'interfaccia utente di sviluppo dell'ADK

Obiettivi didattici
- Come funziona A2UI: 18 primitive, i messaggi che creano un'interfaccia utente e il modello di componenti piatto
- Come utilizzare l'SDK A2UI per chiedere a un agente ADK di generare JSON A2UI
- Come eseguire il rendering dei componenti A2UI in
adk web
Che cosa ti serve
- Un progetto cloud Google Cloud con la fatturazione abilitata
- Un browser web come Chrome
- Python 3.12+ e uv, se esegui il codice sulla tua macchina anziché su Cloud Shell
Questo codelab è destinato a sviluppatori di livello intermedio che hanno una certa familiarità con Python e Google Cloud.
Il completamento di questo codelab richiede circa 20 minuti.
Le risorse create in questo codelab dovrebbero costare meno di 5 $.
2. Configura l'ambiente
Crea un progetto Google Cloud
- Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
- Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.
Avvia l'editor di Cloud Shell
Per avviare una sessione Cloud Shell dalla console Google Cloud, fai clic su Attiva Cloud Shell nella console Google Cloud.
Viene avviata una sessione nel riquadro inferiore della console Google Cloud.
Per avviare l'editor, fai clic su Apri editor sulla barra degli strumenti della finestra di Cloud Shell.
Abilita API
Nella barra degli strumenti dell'editor di Cloud Shell, fai clic su Terminale e Nuovo terminale, quindi esegui questo comando per abilitare le API richieste:
gcloud services enable aiplatform.googleapis.com
Installa le dipendenze
Nel terminale, esegui i seguenti comandi per creare una cartella per questo codelab, con una cartella a2ui_agent al suo interno per il codice dell'agente, e installa Agent Development Kit (ADK) e l'SDK A2UI:
mkdir -p ~/adk-a2ui/a2ui_agent cd ~/adk-a2ui uv init --bare uv add google-adk a2ui-agent-sdk
uv crea un ambiente Python isolato per questo codelab, quindi non devi attivare nulla. Aggiungi il prefisso uv run ai comandi Python.
3. Crea l'agente
Inizia con un agente ADK standard che restituisce testo normale. Ecco come si presenta la maggior parte delle app di agenti oggi.
Configurare le impostazioni progetto
Nel terminale, esegui questo comando per creare a2ui_agent/.env con il tuo progetto e la tua posizione e per fare in modo che ADK chiami Gemini tramite il tuo progetto Google Cloud. ADK carica automaticamente questo file, quindi le impostazioni funzionano anche nei nuovi terminali.
cat > ~/adk-a2ui/a2ui_agent/.env <<EOF GOOGLE_CLOUD_PROJECT=$(gcloud config get project) GOOGLE_CLOUD_LOCATION=global GOOGLE_GENAI_USE_ENTERPRISE=True EOF
Definisci lo strumento e i dati simulati
Crea a2ui_agent/resources.py con il seguente contenuto. Questo strumento restituisce un elenco di risorse cloud con il relativo stato.
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
Definisci l'agente
Crea a2ui_agent/agent.py con i seguenti contenuti:
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. Testare l'agente
L'ADK include una UI per sviluppatori che puoi utilizzare per interagire con il tuo agente e inviargli prompt in un browser per i test.
Avvia l'interfaccia utente di sviluppo ADK
Nel terminale dell'editor di Cloud Shell, esegui questo comando per avviare l'interfaccia utente di sviluppo dell'ADK:
uv run adk web --port 8080 --allow_origins "*" --reload_agents
Dovresti visualizzare un messaggio simile al seguente:
+-----------------------------------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://127.0.0.1:8080. | +-----------------------------------------------------------------------------+
Apri la UI di sviluppo di ADK
Puoi aprire l'interfaccia utente di sviluppo dell'ADK nel browser facendo clic con Ctrl o Cmd sull'URL di test locale oppure facendo clic sul pulsante Anteprima web e selezionando Anteprima sulla porta 8080.
Una volta visualizzata l'interfaccia utente di sviluppo dell'ADK, seleziona a2ui_agent dal menu a discesa.
Inviare prompt di esempio
Invia un prompt di esempio all'agente:
What's running in my project?
Ora prova un altro prompt di esempio e otterrai più testo:
Does anything need my attention?
La conversazione dovrebbe essere simile alla seguente:

La risposta è precisa, ma è un lungo blocco di testo.
5. Generare JSON A2UI
Poi, passa dall'agente da testo normale ad A2UI.
L'SDK Python A2UI include un generatore di prompt che scrive prompt di sistema per te. Insegna all'LLM il catalogo completo dei componenti A2UI, i nomi e i tipi di proprietà corretti e la struttura JSON.
Aggiornare l'agente
Sostituisci i contenuti di a2ui_agent/agent.py come segue:
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 mostra il JSON A2UI come testo, in modo che tu possa leggerlo. Lo rimuoverai in un secondo momento per visualizzare il rendering della UI.
Il metodo prompt_generator.generate() combina la descrizione del ruolo con lo schema JSON A2UI completo e alcuni esempi few-shot, in modo che l'LLM sappia esattamente come formattare l'output. Non è necessario scrivere manualmente il catalogo dei componenti.
Questo codelab utilizza A2UI versione 0.8 (version="0.8"), ovvero la versione supportata dal renderer A2UI adk web.
6. Testare l'output JSON
Se la UI di sviluppo dell'ADK è ancora in esecuzione, ricaricherà automaticamente le modifiche apportate all'agente.
Seleziona a2ui_agent, avvia una nuova sessione facendo clic su +Nuova sessione in alto a destra nell'interfaccia utente per sviluppatori dell'ADK, quindi invia lo stesso prompt di prima:
What's running in my project?
Questa volta, l'agente risponde con JSON A2UI anziché testo normale. Nell'output della chat, in un blocco di codice JSON, vedrai messaggi strutturati come beginRendering e surfaceUpdate (e a volte dataModelUpdate).

Il JSON descrive una UI avanzata con schede, icone e pulsanti, ma show_raw_json lo mantiene come testo in modo che tu possa leggerlo. Successivamente, esaminerai la struttura di questo JSON e poi rimuoverai show_raw_json per eseguirne il rendering come componenti UI effettivi.
7. Informazioni su A2UI
Guarda il file JSON appena generato dall'agente. A2UI dispone di tre tipi di messaggi per la creazione di un'interfaccia utente. L'output dell'agente potrebbe non utilizzare tutte e tre le opzioni ogni volta:
1. beginRendering
Crea una superficie di rendering e assegna un nome al componente radice:
{"beginRendering": {"surfaceId": "default", "root": "main-column"}}
2. surfaceUpdate
Invia l'albero dei componenti come un elenco piatto con riferimenti agli ID (non nidificati):
{"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
Invia i dati separatamente dalla struttura:
{"dataModelUpdate": {"surfaceId": "default", "contents": [
{"key": "service_name", "valueString": "auth-service"},
{"key": "status", "valueString": "healthy"}
]}}
I componenti vengono associati ai dati utilizzando {"path": "key"}. Puoi aggiornare i dati senza inviare nuovamente l'albero dei componenti.
I 18 primitivi
Categoria | Componenti |
Layout | Scheda, Colonna, Riga, Elenco, Schede, Divisore, Modale |
Display | Testo, immagine, icona, video, AudioPlayer |
Ingresso | TextField, DateTimeInput, MultipleChoice, CheckBox, Slider |
Azione | Pulsante |
L'agente crea layout diversi, come una visualizzazione di navigazione, una dashboard delle priorità o un modulo di configurazione, a partire da questi stessi componenti. Per informazioni dettagliate su ciascun componente, consulta le informazioni di riferimento sui componenti.
8. Esegui il rendering dei componenti A2UI
L'SDK racchiude A2UI in tag standard. adk web li riconosce e esegue il rendering dei componenti con il renderer A2UI integrato. Per visualizzarlo, rimuovi show_raw_json.
Aggiornare l'agente
Sostituisci i contenuti di a2ui_agent/agent.py con quanto segue. Le uniche modifiche rispetto al passaggio precedente sono che la funzione show_raw_json, il relativo parametro after_model_callback e le due importazioni utilizzate non sono più presenti:
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. Testa la UI sottoposta a rendering
Se la UI di sviluppo dell'ADK è ancora in esecuzione, ricaricherà automaticamente le modifiche apportate all'agente.
Aggiorna la scheda del browser, seleziona a2ui_agent, quindi avvia una nuova sessione facendo clic su +Nuova sessione in alto a destra nell'interfaccia utente di sviluppo dell'ADK e invia lo stesso prompt di prima:
What's running in my project?
Questa volta, adk web esegue il rendering dei componenti A2UI come UI effettiva: schede con indicatori di stato, dettagli delle risorse e pulsanti di azione.

Prova un prompt diverso per vedere come l'agente compone una UI diversa dallo stesso insieme di primitive:
Does anything need my attention?
Infine, prova un altro prompt per generare un'altra UI per il deployment di un nuovo servizio:
I need to deploy a new service
Tutti e tre i prompt utilizzano lo stesso agente, lo stesso strumento e gli stessi componenti, ma ognuno produce un'interfaccia utente diversa che si adatta a ciò che hai chiesto.
10. Elimina
Per evitare che i server locali rimangano in esecuzione, libera spazio dalle risorse:
- Nel terminale in cui è in esecuzione
adk web, premi Ctrl+C per arrestare il server dell'agente.
Se hai creato un progetto specifico per questo codelab, puoi eliminarlo completamente:
gcloud projects delete <YOUR_PROJECT_ID>
11. Complimenti
Hai creato un agente ADK che genera un'interfaccia utente interattiva e avanzata utilizzando A2UI.
Che cosa hai imparato
- A2UI è un protocollo con 18 primitive dichiarative e alcuni semplici messaggi che creano una UI
- L'SDK A2UI genera prompt di sistema che insegnano all'LLM il catalogo dei componenti
- Lo stesso agente, strumento e primitive compongono UI diverse per intent diversi
- I componenti A2UI possono essere visualizzati direttamente in
adk webdurante lo sviluppo
Crea un frontend di produzione
In questo codelab, hai eseguito il rendering di A2UI all'interno di adk web per lo sviluppo e il test.
Per la produzione, devi creare un frontend utilizzando uno dei renderer A2UI ufficiali:
Piattaforma | Renderer | Installa |
Web (React) |
|
|
Web (Lit) |
|
|
Web (Angular) |
|
|
Dispositivi mobili/computer | SDK Flutter GenUI |
Documenti di riferimento
- Specifiche e documentazione di A2UI
- Repository GitHub di A2UI
- Renderer A2UI
- Documentazione ADK
- Integrazione dell'ADK A2UI
Passaggi successivi
Esplora le risorse di apprendimento per creare ed eseguire il deployment di agenti di livello enterprise con Gemini Enterprise Agent Ready (GEAR).