Interfaz de usuario generativa con ADK Agents mediante el protocolo A2UI: Mensajes y ejemplos
Aprenda cómo A2UI permite a un agente devolver una interfaz de usuario interactiva en formato JSON, cómo difiere de AG-UI, y cómo ejecutar localmente el ejemplo del buscador de restaurantes de Google ADK.
Fuentes: Agent to UI Protocol (A2UI) with Agent Development Kit (ADK)
Cuatro protocolos surgen repetidamente cuando los agentes se integran en aplicaciones reales: MCP, A2A, A2UI y AG-UI. AG-UI conecta una aplicación de front-end con el back-end del agente, y funciona bien junto con el Google Agent Development Kit (ADK). El foco aquí es A2UI, un protocolo con un nombre sorprendentemente similar, y cómo utilizarlo desde un agente ADK.
Qué es A2UI
A2UI es un protocolo de interfaz generativa de Google. Permite a los agentes de IA crear interfaces interactivas y enriquecidas que pueden mostrarse en web, móviles y ordenadores. Supongamos que un usuario pregunta: “¿Cuáles son algunos buenos restaurantes en Nueva York?”. El agente puede hacer más que devolver una lista de texto; también puede proporcionar una descripción de la interfaz, y un renderizador en el lado del cliente convierte esa descripción en una visualización interactiva de los restaurantes.
Los conceptos básicos están documentados en a2ui.org, y lo esencial se puede resumir en unos pocos párrafos.
Cuatro tipos de mensajes
Todo lo que envía un agente está en formato JSON, y existen solo cuatro tipos de mensajes:
createSurfacecrea una superficie nueva e indica qué catálogo de componentes utiliza.updateComponentsagrega o modifica componentes de interfaz dentro de una superficie.updateDataModelcambia el estado de la aplicación.deleteSurfaceelimina una superficie.
Juntos describen tanto la interfaz como los datos que la sustentan:
{
"version": "v0.9",
"createSurface": {
"surfaceId": "main",
"catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json"
}
}
{
"version": "v0.9",
"updateComponents": {
"surfaceId": "main",
"components": [...]
}
}
{
"version": "v0.9",
"updateDataModel": {
"surfaceId": "main",
"path": "/user",
"value": { "name": "Alice" }
}
}
El catálogo de componentes
A2UI incluye un catálogo estándar, agrupado por función:
- Layout: Fila, Columna y Lista, que organizan otros componentes
- Display: Texto, Imagen, Icono, Video y Divisor, que muestran información
- Interactivo: Botón, Campo de texto, Casilla de verificación, Campo de fecha y hora y Deslizador, que reciben entrada
- Contenedor: Tarjeta, Pestañas y Modal, que agrupan contenido
La referencia de componentes en la documentación contiene toda la galería con ejemplos.
Una conversación de reserva, mensaje por mensaje
El ejemplo de reserva en un restaurante de la documentación ilustra bien el ciclo de vida.
Primero, el agente crea una superficie:
{
"version": "v0.9",
"createSurface": {
"surfaceId": "booking",
"catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json"
}
}
En segundo lugar, define la estructura de la interfaz de usuario:
{
"version": "v0.9",
"updateComponents": {
"surfaceId": "booking",
"components": [
{
"id": "root",
"component": "Column",
"children": ["header", "guests-field", "submit-btn"]
},
{
"id": "header",
"component": "Text",
"text": "Confirm Reservation",
"variant": "h1"
},
{
"id": "guests-field",
"component": "TextField",
"label": "Guests",
"value": { "path": "/reservation/guests" }
},
{
"id": "submit-btn",
"component": "Button",
"child": "submit-text",
"variant": "primary",
"action": {
"event": {
"name": "confirm",
"context": {
"details": { "path": "/reservation" }
}
}
}
}
]
}
}
Tercero, completa los datos:
{
"version": "v0.9",
"updateDataModel": {
"surfaceId": "booking",
"path": "/reservation",
"value": {
"datetime": "2025-12-16T19:00:00Z",
"guests": "2"
}
}
}
Cuarto, el usuario cambia la cantidad de invitados a 3, y el cliente actualiza automáticamente /reservation/guests. Quinto, el usuario pulsa Confirmar, y el cliente envía una respuesta con la acción realizada:
{
"version": "v0.9",
"action": {
"name": "confirm",
"surfaceId": "booking",
"context": {
"details": {
"datetime": "2025-12-16T19:00:00Z",
"guests": "3"
}
}
}
}
Sexto, responde el agente, ya sea actualizando nuevamente la interfaz de usuario o cerrando la superficie:
{
"version": "v0.9",
"deleteSurface": { "surfaceId": "booking" }
}
Transporte y renderizado
A2UI no se preocupa por cómo viajan los mensajes, ya que funciona cualquier cosa capaz de transportar JSON. Actualmente se admiten como transportes A2A y AG-UI, mientras que REST, WebSockets y SSE están planeados o propuestos. La página de transportes de la documentación enumera lo que está disponible en la actualidad.
Una vez que el agente ha generado el JSON, un renderizador lo convierte en componentes nativos. En la web, existen renderizadores como Lit y Angular, y el SDK GenUI de Flutter abarca dispositivos móviles, de escritorio y web. La página de renderizadores mantiene la lista actualizada.
A2UI y AG-UI lado a lado
Los nombres son similares, y las funciones son diferentes pero complementarias. AG-UI es la conexión entre una aplicación orientada al usuario y el backend de agentes. A2UI es una especificación declarativa que los agentes utilizan para incluir widgets de interfaz de usuario en sus respuestas.
Probando las muestras
El repositorio A2UI incluye ejemplos de agentes ADK que se pueden generar y renderizar localmente. Clónelo primero:
git clone https://github.com/google/a2ui.git
cd a2ui
Establecer una clave de la API Gemini:
export GEMINI_API_KEY="your_gemini_api_key_here"
Cada muestra cuenta con una parte de servidor (el agente) y una parte de cliente (el renderizador), y ambas deben estar en ejecución. Las muestras del agente ADK se encuentran en la carpeta adk, dentro de samples/agent, mientras que los renderizadores del cliente están en samples/client.
Búsqueda de restaurantes
Desde la carpeta samples/client/lit, un único comando inicia la demostración:
npm run demo:restaurant
Abra http://localhost:5173/?app=restaurant y comience a hacer preguntas, por ejemplo “Los 5 mejores restaurantes chinos en Nueva York”. El agente genera la interfaz de usuario y el cliente la renderiza:
Los registros muestran el JSON A2UI en bruto que envió el agente:
[REST] LiteLLM completion() model= gemini-2.5-flash; provider = gemini
[REST] INFO:agent:Event from runner: model_version='gemini-2.5-flash' content=Content(
[REST] parts=[
[REST] Part(
[REST] text="""<a2ui-json>
[REST] [
[REST] {
[REST] "beginRendering": {
[REST] "surfaceId": "default",
[REST] "root": "root-column",
[REST] "styles": {
[REST] "primaryColor": "#FF0000",
[REST] "font": "Roboto"
[REST] }
[REST] }
[REST] },
[REST] {
[REST] "surfaceUpdate": {
[REST] "surfaceId": "default",
[REST] "components": [
[REST] {
[REST] "id": "root-column",
[REST] "component": {
[REST] "Column": {
[REST] "children": {
[REST] "explicitList": [
[REST] "title-heading",
[REST] "item-list"
[REST] ]
[REST] }
[REST] }
[REST] }
[REST] },
...
Qué ocurre en el interior
El código del agente se encuentra en samples/agent/adk/restaurant_finder. prompt_builder.py muestra cómo se construye la instrucción para que el agente responda en formato A2UI. La descripción del rol comienza con una instrucción clara de que la salida final debe ser una respuesta JSON en formato A2UI:
ROLE_DESCRIPTION = (
"You are a helpful restaurant finding assistant. Your final output MUST be a a2ui"
" UI JSON response."
)
UI_DESCRIPTION = """
- If the query is for a list of restaurants, use the restaurant data you have already received from the `get_restaurants` tool to populate the `dataModelUpdate.contents` array (e.g., as a `valueMap` for the "items" key).
- If the number of restaurants is 5 or fewer, you MUST use the `SINGLE_COLUMN_LIST_EXAMPLE` template.
- If the number of restaurants is more than 5, you MUST use the `TWO_COLUMN_LIST_EXAMPLE` template.
- If the query is to book a restaurant (e.g., "USER_WANTS_TO_BOOK..."), you MUST use the `BOOKING_FORM_EXAMPLE` template.
- If the query is a booking submission (e.g., "User submitted a booking..."), you MUST use the `CONFIRMATION_EXAMPLE` template.
"""
La clase A2uiSchemaManager carga los catálogos de componentes y genera indicaciones del sistema que guían al modelo sobre el formato válido para JSON A2UI. Al llamar a generate_system_prompt se combina la descripción del rol del agente con el esquema y algunos ejemplos prácticos, lo que proporciona al modelo indicaciones precisas sobre el formato:
version = VERSION_0_9
restaurant_prompt = A2uiSchemaManager(
version,
catalogs=[
BasicCatalog.get_config(
version=version,
examples_path=f"examples/{version}",
)
],
schema_modifiers=[remove_strict_validation],
).generate_system_prompt(
role_description=ROLE_DESCRIPTION,
ui_description=UI_DESCRIPTION,
include_schema=True,
include_examples=True,
validate_examples=True,
)
agent.py crea luego el agente con esa instrucción del sistema:
return LlmAgent(
model=LiteLlm(model=LITELLM_MODEL),
name="restaurant_agent",
description="An agent that finds restaurants and helps book tables.",
instruction=instruction,
tools=[get_restaurants],
)
Después de que el agente emita JSON, debe validarse contra el esquema A2UI antes de transmitirlo al cliente:
# --- Validation Steps ---
# Check if it validates against the A2UI_SCHEMA
# This will raise jsonschema.exceptions.ValidationError if it fails
logger.info(
"--- RestaurantAgent.stream: Validating against A2UI_SCHEMA... ---"
)
selected_catalog.validator.validate(parsed_json_data)
La documentación de ADK cuenta con una página de integración A2UI que ofrece más detalles. En el lado del cliente, renderers/lit alberga la implementación de Lit que toma el JSON generado y lo renderiza.
Herramientas para comenzar
CopilotKit publica una plantilla inicial A2UI, además de un A2UI Composer para experimentar con componentes.
Lugares útiles para seguir leyendo son la documentación y especificaciones del protocolo A2UI, el repositorio de GitHub, la publicación de Google sobre interfaces controladas por agentes, la página de integración de ADK, el Composer e iniciador de CopilotKit, y un par de videos de YouTube sobre agentes que crean interfaces en tiempo real.
Lecturas relacionadas
- Notas prácticas: El SDLC agente: Cómo la IA está transformando el desarrollo de software — Guía detallada de las Notas prácticas: El SDLC agente: Cómo la IA está transformando el desarrollo de software: contratos, verificaciones y espacios para código listo para usar para los equipos que implementan este patrón.
- Elegir un socio para el desarrollo de agentes de IA: Preguntas más allá de la demostración — Cómo evaluar a los proveedores de agentes en 2026: definición del flujo de trabajo, integraciones, permisos, conocimientos, pruebas de fallos, visibilidad en el despliegue, revisión humana y responsabilidad posterior al lanzamiento.