Experiencias de frontend con ADK y A2UI

1. Descripción general

La mayoría de los agentes de IA responden con texto. En este codelab, usarás A2UI para que tu agente responda con una interfaz de usuario. El agente describe tarjetas, listas, botones y formularios en JSON, con un catálogo de componentes estándar, y el cliente los renderiza con sus propios widgets nativos, por lo que los diseños nuevos no necesitan código de frontend nuevo.

Crearás el agente con el Kit de desarrollo de agentes (ADK).

Qué compilarás

Un panel simulado de infraestructura de nube en tres etapas:

  1. Un agente estándar que devuelve datos de recursos como texto sin formato
  2. Un agente de A2UI que devuelve los mismos datos que el JSON estructurado de A2UI
  3. Un agente renderizado que muestra el JSON de A2UI como componentes de la IU interactivos en la IU de desarrollo del ADK

Agente de A2UI del ADK

Qué aprenderás

  • Cómo funciona A2UI: 18 elementos primitivos, los mensajes que compilan una IU y el modelo de componentes planos
  • Cómo usar el SDK de A2UI para solicitar a un agente del ADK que genere JSON de A2UI
  • Cómo renderizar componentes de A2UI en adk web

Requisitos

  • Un proyecto de Google Cloud con la facturación habilitada.
  • Un navegador web, como Chrome
  • Python 3.12 y uv, si ejecutas el código en tu propia máquina en lugar de Cloud Shell

Este codelab está dirigido a desarrolladores intermedios que tienen cierta familiaridad con Python y Google Cloud.

Este codelab tarda aproximadamente 20 minutos en completarse.

Los recursos creados en este codelab deberían costar menos de USD 5.

2. Configura tu entorno

Crea un proyecto de Google Cloud

  1. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
  2. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información para verificar si la facturación está habilitada en un proyecto.

Inicia el editor de Cloud Shell

Para iniciar una sesión de Cloud Shell desde la consola de Google Cloud, haz clic en Activar Cloud Shell en la consola de Google Cloud.

Esto inicia una sesión en el panel inferior de la consola de Google Cloud.

Para iniciar el editor, haz clic en Abrir editor en la barra de herramientas de la ventana de Cloud Shell.

Habilita las APIs

En la barra de herramientas del Editor de Cloud Shell, haz clic en Terminal y Terminal nueva, y, luego, ejecuta el siguiente comando para habilitar las APIs requeridas:

gcloud services enable aiplatform.googleapis.com

Instala dependencias

En la terminal, ejecuta los siguientes comandos para crear una carpeta para este codelab, con una carpeta a2ui_agent dentro para el código del agente, y, luego, instala el Kit de desarrollo de agentes (ADK) y el SDK de A2UI:

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

uv crea un entorno aislado de Python para este codelab, por lo que no necesitas activar nada. Agrega el prefijo uv run a los comandos de Python.

3. Crea el agente

Comienza con un agente estándar del ADK que devuelva texto sin formato. Así se ven la mayoría de las apps de agentes hoy en día.

Configura los parámetros de configuración del proyecto

En la terminal, ejecuta el siguiente comando para crear a2ui_agent/.env con tu proyecto y ubicación, y para que el ADK llame a Gemini a través de tu proyecto de Google Cloud. El ADK carga este archivo automáticamente, por lo que la configuración también funciona en terminales nuevos.

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

Define la herramienta y los datos simulados

Crea a2ui_agent/resources.py con el siguiente contenido. Esta herramienta devuelve una lista de los recursos de la nube con su estado.

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

Define el agente

Crea a2ui_agent/agent.py con el siguiente contenido:

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. Prueba el agente

El ADK incluye una IU de desarrollo que puedes usar para interactuar con tu agente y enviarle instrucciones en un navegador para realizar pruebas.

Inicia la IU de desarrollo del ADK

En la terminal del Editor de Cloud Shell, ejecuta el siguiente comando para iniciar la IU de desarrollo del ADK:

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

Deberías ver un mensaje similar al siguiente:

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

Abre la IU de desarrollo del ADK

Para abrir la IU de desarrollo del ADK en tu navegador, haz clic con Ctrl o Cmd en la URL de prueba local, o bien haz clic en el botón Vista previa en la Web y selecciona Vista previa en el puerto 8080.

Una vez que veas la IU de desarrollo del ADK, selecciona a2ui_agent en el menú desplegable.

Envía instrucciones de ejemplo

Envía una instrucción de muestra al agente:

What's running in my project?

Ahora prueba con otra instrucción de ejemplo y obtendrás más texto como resultado:

Does anything need my attention?

Tu conversación debería ser similar a la siguiente:

Agente de texto del ADK

La respuesta es precisa, pero es un muro de texto.

5. Genera JSON de A2UI

A continuación, cambia el agente de texto sin formato a A2UI.

El SDK de A2UI para Python incluye un generador de instrucciones que escribe instrucciones del sistema por ti. Enseña al LLM el catálogo completo de componentes de A2UI, los nombres y tipos de propiedades correctos, y la estructura JSON.

Actualiza el agente

Reemplaza el contenido de a2ui_agent/agent.py por lo siguiente:

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 muestra el JSON de A2UI como texto para que puedas leerlo. Lo quitarás más adelante para ver la renderización de la IU.

El método prompt_generator.generate() combina la descripción de tu rol con el esquema JSON completo de A2UI y algunos ejemplos, por lo que el LLM sabe exactamente cómo dar formato a su resultado. No es necesario que escribas el catálogo de componentes de forma manual.

En este codelab, se usa la versión 0.8 de A2UI (version="0.8"), que es la versión que admite el renderizador de A2UI de adk web.

6. Prueba el resultado de JSON

Si aún tienes en ejecución la IU para desarrolladores del ADK, debería volver a cargar automáticamente los cambios que realizaste en tu agente.

Selecciona a2ui_agent, inicia una nueva sesión haciendo clic en + Nueva sesión en la parte superior derecha de la IU de desarrollo del ADK y, luego, envía la misma instrucción que antes:

What's running in my project?

Esta vez, el agente responde con JSON de A2UI en lugar de texto sin formato. Verás mensajes estructurados, como beginRendering y surfaceUpdate (y, a veces, dataModelUpdate), en el resultado del chat, en un bloque de código JSON.

JSON de A2UI del ADK

El JSON describe una IU enriquecida con tarjetas, íconos y botones, pero show_raw_json lo mantiene como texto para que puedas leerlo. A continuación, verás cómo se estructura este JSON y, luego, quitarás show_raw_json para renderizarlo como componentes de IU reales.

7. Información sobre A2UI

Observa el código JSON que acaba de generar tu agente. La A2UI tiene tres tipos de mensajes para compilar una IU. Es posible que el resultado del agente no use los tres en cada ocasión:

1. beginRendering

Crea una superficie de renderización y nombra el componente raíz:

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

2. surfaceUpdate

Envía el árbol de componentes como una lista plana con referencias de ID (no anidadas):

{"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

Envía los datos por separado de la estructura:

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

Los componentes se vinculan a los datos con {"path": "key"}. Puedes actualizar los datos sin volver a enviar el árbol de componentes.

Las 18 primitivas

Categoría

Componentes

Diseño

Tarjeta, columna, fila, lista, pestañas, divisor y modal

Pantalla

Texto, imagen, ícono, video, reproductor de audio

Entrada

TextField, DateTimeInput, MultipleChoice, CheckBox, Slider

Acción

Botón

El agente crea diferentes diseños, como una vista de exploración, un panel prioritario o un formulario de configuración, a partir de estos mismos componentes. Consulta la referencia de componentes para obtener detalles sobre cada uno.

8. Renderiza componentes de A2UI

El SDK une A2UI en etiquetas estándar. adk web los reconoce y renderiza los componentes con su renderizador A2UI integrado. Para verla, quita show_raw_json.

Actualiza el agente

Reemplaza el contenido de a2ui_agent/agent.py con lo siguiente. Los únicos cambios con respecto al paso anterior son que la función show_raw_json, su parámetro after_model_callback y las dos importaciones que usaba ya no están:

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. Prueba la IU renderizada

Si aún tienes en ejecución la IU para desarrolladores del ADK, debería volver a cargar automáticamente los cambios que realizaste en tu agente.

Actualiza la pestaña del navegador, selecciona a2ui_agent y, luego, haz clic en + Nueva sesión en la parte superior derecha de la IU de desarrollo del ADK para iniciar una nueva sesión y enviar la misma instrucción que antes:

What's running in my project?

Esta vez, adk web renderiza los componentes de la A2UI como una IU real: tarjetas con indicadores de estado, detalles de recursos y botones de acción.

Agente de A2UI del ADK

Prueba con otra instrucción para ver cómo el agente compone una IU diferente a partir del mismo conjunto de elementos primitivos:

Does anything need my attention?

Por último, prueba con otra instrucción para generar una IU diferente para implementar un servicio nuevo:

I need to deploy a new service

Las tres instrucciones usan el mismo agente, la misma herramienta y los mismos componentes, pero cada una produce una IU diferente que se ajusta a lo que pediste.

10. Limpieza

Para evitar que los servidores locales sigan en ejecución, limpia los recursos:

  • En la terminal que ejecuta adk web, presiona Ctrl + C para detener el servidor del agente.

Si creaste un proyecto específicamente para este codelab, puedes borrarlo por completo:

gcloud projects delete <YOUR_PROJECT_ID>

11. Felicitaciones

Creaste un agente del ADK que genera una IU interactiva y enriquecida con A2UI.

Qué aprendiste

  • A2UI es un protocolo con 18 elementos primitivos declarativos y algunos mensajes simples que crean una IU.
  • El SDK de A2UI genera instrucciones del sistema que le enseñan al LLM el catálogo de componentes.
  • El mismo agente, la misma herramienta y las mismas primitivas componen diferentes IU para diferentes intenciones
  • Los componentes de A2UI se pueden renderizar directamente en adk web durante el desarrollo.

Compila un frontend de producción

En este codelab, renderizaste la A2UI dentro de adk web para el desarrollo y las pruebas.

Para la producción, compilarías un frontend con uno de los renderizadores oficiales de A2UI:

Plataforma

Procesador

Instalar

Web (React)

@a2ui/react

npm install @a2ui/react

Web (Lit)

@a2ui/lit

npm install @a2ui/lit

Web (Angular)

@a2ui/angular

npm install @a2ui/angular

Dispositivos móviles o computadoras

SDK de Flutter GenUI

Comienza ahora

Documentos de referencia

Pasos siguientes

Explora los recursos de aprendizaje para crear e implementar agentes de nivel empresarial con Gemini Enterprise Agent Ready (GEAR).