Esperienze frontend con ADK e A2UI

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:

  1. Un agente standard che restituisce i dati delle risorse come testo normale
  2. Un agente A2UI che restituisce gli stessi dati del JSON A2UI strutturato
  3. Un agente sottoposto a rendering che mostra il JSON A2UI come componenti UI interattivi nell'interfaccia utente di sviluppo dell'ADK

Agente ADK A2UI

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

  1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
  2. 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:

Agente di testo ADK

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).

ADK A2UI JSON

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.

Agente ADK A2UI

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 web durante 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)

@a2ui/react

npm install @a2ui/react

Web (Lit)

@a2ui/lit

npm install @a2ui/lit

Web (Angular)

@a2ui/angular

npm install @a2ui/angular

Dispositivi mobili/computer

SDK Flutter GenUI

Come iniziare

Documenti di riferimento

Passaggi successivi

Esplora le risorse di apprendimento per creare ed eseguire il deployment di agenti di livello enterprise con Gemini Enterprise Agent Ready (GEAR).