Herramientas de UI

El adk-ui crate permite a los agentes de IA generar dinámicamente interfaces de usuario enriquecidas a través de llamadas a herramientas. Los Agents pueden renderizar formularios, tarjetas, alertas, tablas, gráficos y más, todo a través de un Rust de tipo seguro API que se serializa a JSON para el consumo del frontend.

Lo que construirás

Conceptos Clave:

• Formularios - Recopila la entrada del usuario con varios tipos de campo
• Tarjetas - Muestra información con botones de acción
• Tablas - Presentan datos estructurados en filas/columnas
• Gráficos - Visualizan datos con gráficos de barras, líneas, áreas, circulares
• Alerts - Muestra notificaciones y mensajes de estado
• Modals - Diálogos de confirmación e interacciones enfocadas
• Toasts - Notificaciones de estado breves
• Interoperabilidad de Protocolo - Emitir UI como A2UI, AG-UI, o cargas útiles de aplicaciones MCP

Ejemplo: Panel de Análisis

Ejemplo: Formulario de Registro

---

Cómo Funciona

┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 1: User requests something                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   User: "I want to register for an account"                                 │
│                                                                             │
│                              ↓                                              │
│                                                                             │
│   ┌──────────────────────────────────────┐                                  │
│   │         AI AGENT (LLM)              │                                  │
│   │  "I should show a registration form" │                                  │
│   └──────────────────────────────────────┘                                  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 2: Agent calls render_form tool                                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   📞 Tool Call: render_form({                                               │
│     title: "Registration",                                                  │
│     fields: [                                                               │
│       {name: "email", type: "email"},                                       │
│       {name: "password", type: "password"}                                  │
│     ]                                                                       │
│   })                                                                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 3: Frontend renders the form                                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌─────────────────────────────────────────────────┐                       │
│   │  📋 Registration                               │                       │
│   │  ────────────────────────────────────────────  │                       │
│   │  Email:    [________________________]          │                       │
│   │  Password: [________________________]          │                       │
│   │                                                │                       │
│   │  [           Register           ]              │                       │
│   └─────────────────────────────────────────────────┘                       │
│                                                                             │
│   ✅ User sees an interactive form, fills it out, clicks Register           │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 4: Form submission sent back to agent                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   📩 Event: {                                                               │
│     type: "form_submit",                                                    │
│     data: { email: "user@example.com", password: "***" }                    │
│   }                                                                         │
│                                                                             │
│   Agent: "Great! I'll process your registration and show a success alert"  │
│                                                                             │
│   📞 Tool Call: render_alert({                                              │
│     title: "Registration Complete!",                                        │
│     variant: "success"                                                      │
│   })                                                                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

Visión General

Las herramientas de UI permiten a los agentes:

• Recopilar la entrada del usuario a través de formularios dinámicos con soporte para textarea
• Mostrar información con tarjetas, alertas y notificaciones
• Presentar datos en tablas y gráficos interactivos (Recharts)
• Mostrar progreso y estados de carga (spinner, skeleton)
• Crear diseños de panel con múltiples componentes
• Solicitar confirmación al usuario mediante modales
• Mostrar notificaciones "toast" para actualizaciones de estado

Inicio Rápido

Añade a tu Cargo.toml:

[dependencies]
adk-ui = { git = "https://github.com/zavora-ai/adk-ui" }
adk-agent = "2.0.0"
adk-model = "2.0.0"

Uso Básico

use adk_rust::prelude::*;
use adk_ui::UiToolset;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let model = Arc::new(GeminiModel::from_env("gemini-2.5-flash")?);

    // Get all 10 UI tools
    let ui_tools = UiToolset::all_tools();

    // Create AI agent with UI tools
    let mut builder = LlmAgentBuilder::new("ui_agent")
        .model(model)
        .instruction(r#"
            You are a helpful assistant that uses UI components to interact with users.
            Use render_form for collecting information.
            Use render_card for displaying results.
            Use render_alert for notifications.
            Use render_modal for confirmation dialogs.
            Use render_toast for brief status messages.
        "#);

    for tool in ui_tools {
        builder = builder.tool(tool);
    }

let agent = builder.build()?;
Ok(())
}

A2UI JSONL (render_screen / render_page / render_kit)

Estas herramientas emiten A2UI v0.9 JSONL para compatibilidad con renderers A2UI.

render_screen (superficie única)

{
  "surface_id": "main",
  "components": [
    { "id": "root", "component": "Column", "children": ["title", "cta"] },
    { "id": "title", "component": "Text", "text": "Welcome", "variant": "h1" },
    { "id": "cta_label", "component": "Text", "text": "Continue", "variant": "body" },
    { "id": "cta", "component": "Button", "child": "cta_label", "action": { "event": { "name": "continue" } } }
  ]
}

render_page (página de múltiples secciones)

{
  "title": "Release Notes",
  "description": "Highlights for the latest launch.",
  "sections": [
    {
      "heading": "What’s new",
      "body": "Three big improvements shipped this week.",
      "bullets": ["Faster onboarding", "Better search", "New dashboards"],
      "actions": [{ "label": "View details", "action": "view_details", "variant": "borderless" }]
    }
  ]
}

render_kit (catálogo + tokens + plantillas)

{
  "name": "Fintech Pro",
  "version": "0.1.0",
  "brand": { "vibe": "trustworthy", "industry": "fintech" },
  "colors": { "primary": "#2F6BFF" },
  "typography": { "family": "Source Sans 3" },
  "templates": ["auth_login", "dashboard"]
}

Utilice el React renderer para consumir A2UI JSONL:

import {
  A2uiStore,
  A2uiSurfaceRenderer,
  applyParsedMessages,
  parseJsonl,
} from "@zavora-ai/adk-ui-react";

const store = new A2uiStore();
const parsed = parseJsonl(jsonl);
applyParsedMessages(store, parsed);

export function App() {
  return <A2uiSurfaceRenderer store={store} surfaceId="main" />;
}

Herramientas Disponibles

render_form

Renderizar formularios interactivos para recopilar la entrada del usuario.

{
  "title": "Registration Form",
  "description": "Create your account",
  "fields": [
    {"name": "username", "label": "Username", "type": "text", "required": true},
    {"name": "email", "label": "Email", "type": "email", "required": true},
    {"name": "password", "label": "Password", "type": "password", "required": true},
    {"name": "newsletter", "label": "Subscribe to newsletter", "type": "switch"}
  ],
  "submit_label": "Register"
}

Se renderiza como:

┌─────────────────────────────────────────────────┐
│  📋 Registration Form                          │
│  Create your account                           │
│  ─────────────────────────────────────────────  │
│                                                │
│  Username *                                    │
│  ┌─────────────────────────────────────────┐   │
│  │                                         │   │
│  └─────────────────────────────────────────┘   │
│                                                │
│  Email *                                       │
│  ┌─────────────────────────────────────────┐   │
│  │                                         │   │
│  └─────────────────────────────────────────┘   │
│                                                │
│  Password *                                    │
│  ┌─────────────────────────────────────────┐   │
│  │ ••••••••                                │   │
│  └─────────────────────────────────────────┘   │
│                                                │
│  Subscribe to newsletter  [○]                  │
│                                                │
│  ┌─────────────────────────────────────────┐   │
│  │             Register                    │   │
│  └─────────────────────────────────────────┘   │
│                                                │
└─────────────────────────────────────────────────┘

Tipos de campo: text, email, password, number, date, select, multiselect, switch, slider, textarea

render_card

Mostrar tarjetas de información con botones de acción opcionales.

{
  "title": "Order Confirmed",
  "description": "Order #12345",
  "content": "Your order has been placed successfully. Expected delivery: Dec 15, 2025.",
  "actions": [
    {"label": "Track Order", "action_id": "track", "variant": "primary"},
    {"label": "Cancel", "action_id": "cancel", "variant": "danger"}
  ]
}

Variantes de botón: primary, secondary, danger, ghost, outline

render_alert

Mostrar notificaciones y mensajes de estado.

{
  "title": "Payment Successful",
  "description": "Your payment of $99.00 has been processed.",
  "variant": "success"
}

Variantes: info, success, warning, error

render_confirm

Solicitar confirmación al usuario antes de las acciones.

{
  "title": "Delete Account",
  "message": "Are you sure you want to delete your account? This action cannot be undone.",
  "confirm_label": "Delete",
  "cancel_label": "Keep Account",
  "variant": "danger"
}

render_table

Mostrar datos tabulares.

{
  "title": "Recent Orders",
  "columns": [
    {"header": "Order ID", "accessor_key": "id"},
    {"header": "Date", "accessor_key": "date"},
    {"header": "Amount", "accessor_key": "amount"},
    {"header": "Status", "accessor_key": "status"}
  ],
  "data": [
    {"id": "#12345", "date": "2025-12-10", "amount": "$99.00", "status": "Delivered"},
    {"id": "#12346", "date": "2025-12-11", "amount": "$149.00", "status": "Shipped"}
  ]
}

render_chart

Crear visualizaciones de datos.

{
  "title": "Monthly Sales",
  "chart_type": "bar",
  "x_key": "month",
  "y_keys": ["revenue", "profit"],
  "data": [
    {"month": "Jan", "revenue": 4000, "profit": 2400},
    {"month": "Feb", "revenue": 3000, "profit": 1398},
    {"month": "Mar", "revenue": 5000, "profit": 3800}
  ]
}

Tipos de gráficos: bar, line, area, pie

render_progress

Muestra el progreso de la tarea con pasos opcionales.

{
  "title": "Installing Dependencies",
  "value": 65,
  "description": "Installing package 13 of 20...",
  "steps": [
    {"label": "Download", "completed": true},
    {"label": "Extract", "completed": true},
    {"label": "Install", "current": true},
    {"label": "Configure", "completed": false}
  ]
}

render_layout

Crear diseños de panel con múltiples secciones.

{
  "title": "System Status",
  "description": "Current system health overview",
  "sections": [
    {
      "title": "Services",
      "type": "stats",
      "stats": [
        {"label": "API Server", "value": "Healthy", "status": "operational"},
        {"label": "Database", "value": "Degraded", "status": "warning"},
        {"label": "Cache", "value": "Down", "status": "error"}
      ]
    },
    {
      "title": "Recent Errors",
      "type": "table",
      "columns": [{"header": "Time", "key": "time"}, {"header": "Error", "key": "error"}],
      "rows": [{"time": "10:30", "error": "Connection timeout"}]
    }
  ]
}

Tipos de sección: stats, table, chart, alert, text

render_modal

Muestra diálogos modales para confirmaciones o interacciones enfocadas.

{
  "title": "Confirm Deletion",
  "message": "Are you sure you want to delete this item? This action cannot be undone.",
  "size": "medium",
  "closable": true,
  "confirm_label": "Delete",
  "cancel_label": "Cancel",
  "confirm_action": "delete_confirmed"
}

Tamaños: small, medium, large, full

render_toast

Mostrar notificaciones toast breves para actualizaciones de estado.

{
  "message": "Settings saved successfully",
  "variant": "success",
  "duration": 5000,
  "dismissible": true
}

Variantes: info, success, warning, error

Herramientas Filtradas

Selecciona solo las herramientas que tu agente necesita:

let toolset = UiToolset::new()
    .without_chart()      // Disable charts
    .without_table()      // Disable tables
    .without_progress()   // Disable progress
    .without_modal()      // Disable modals
    .without_toast();     // Disable toasts

// Or use forms only
let forms_only = UiToolset::forms_only();

Manejo de Eventos de UI

Cuando los usuarios interactúan con la UI renderizada (envían formularios, hacen clic en botones), los eventos se envían de vuelta al agent:

use adk_ui::{UiEvent, UiEventType};

// UiEvent structure
pub struct UiEvent {
    pub event_type: UiEventType,  // FormSubmit, ButtonClick, InputChange
    pub action_id: Option<String>,
    pub data: Option<HashMap<String, Value>>,
}

// Convert to message for agent
let message = ui_event.to_message();

Actualizaciones de UI por streaming

Para actualizaciones de UI en tiempo real, usa UiUpdate para parchear componentes por ID:

use adk_ui::{UiUpdate, UiOperation};

let update = UiUpdate {
    target_id: "progress-bar".to_string(),
    operation: UiOperation::Patch,
    payload: Some(Component::Progress(Progress {
        id: Some("progress-bar".to_string()),
        value: 75,
        label: Some("75%".to_string()),
    })),
};

Operaciones: Replace, Patch, Append, Remove

Esquema de Componentes

Todos los 28 tipos de componentes soportan campos id opcionales para actualizaciones de streaming:

Átomos: Texto, Botón, Icono, Imagen, Insignia Entradas: TextInput, NumberInput, Selector, MultiSelect, Interruptor, DateInput, Deslizador, Área de texto Diseños: Stack, Grid, Card, Container, Divider, Tabs Datos: Table, List, KeyValue, CodeBlock Visualización: Gráfico (barras, líneas, áreas, circular a través de Recharts) Retroalimentación: Alert, Progress, Toast, Modal, Spinner, Skeleton

React Client

Se proporciona una implementación de referencia de React en el repositorio independiente adk-ui:

npm install @zavora-ai/adk-ui-react

El cliente de React incluye:

• TypeScript tipos que coinciden con el esquema de Rust
• Component renderer para los 28 tipos
• Integración de Recharts para gráficos interactivos
• Soporte para renderizado de Markdown
• Soporte para modo oscuro
• Manejo de envío de formularios
• Componentes modales y de notificación (toast)

Arquitectura

Agent ──[render_* tool]──> UiResponse (JSON)
                              │
                              │ SSE
                              ▼
                         Client (React)
                              │
                              └──> UiEvent (user action) ──> Agent

Interoperabilidad de Protocolo

Todas las 13 herramientas de renderizado soportan salida consciente del protocolo a través del protocol argumento:

Cuando protocol se omite, tools usan su formato de salida predeterminado (legado UiResponse JSON para la mayoría de los tools, A2UI para render_screen/render_page/render_kit).

Ejemplo con selección de protocolo:

{
  "protocol": "mcp_apps",
  "mcp_apps": {
    "resource_uri": "ui://demo/surface"
  }
}

Adaptadores de interoperabilidad

adk-ui incluye primitivas de adaptador para conversión de protocolo:

• A2uiAdapter — Convierte superficies canónicas a A2UI JSONL
• AgUiAdapter — Convierte a cargas útiles de eventos AG-UI McpAppsAdapter — Convierte a MCP cargas útiles de recursos de aplicaciones

Estos implementan un trait UiProtocolAdapter compartido para una conversión consistente en todas las herramientas.

Cronograma de Desaprobación

El perfil de tiempo de ejecución heredado adk_ui contiene metadatos de desaprobación:

Sustitutos: a2ui, ag_ui, mcp_apps

Estos metadatos se exponen mediante las constantes UI_PROTOCOL_CAPABILITIES, y adk-server los publica en /api/ui/capabilities. La respuesta de capacidad también informa implementationTier, specTrack, summary, y limitations para que los clientes puedan distinguir subconjuntos híbridos o de compatibilidad de soporte de protocolo totalmente nativo.

Cuando adk-server es el límite orientado al host, también expone ayudantes de puente aditivos de MCP Apps en /api/ui/initialize, /api/ui/message, /api/ui/update-model-context, /api/ui/notifications/poll, /api/ui/notifications/resources-list-changed, y /api/ui/notifications/tools-list-changed. Estos puntos finales preservan los contratos de tiempo de ejecución existentes de ADK y aceptan cuerpos de solicitud directos o Envoltorios tipo JSON-RPC con métodos ui/....

Para consumidores en tiempo de ejecución, adk-server también soporta:

• x-adk-ui-transport: protocol_native o uiTransport: "protocol_native" para AG-UI-native SSE serialization
• AG-UI dual-path request inputs a través de input / agUiInput junto al existente newMessage
• MCP Las aplicaciones conectan envoltorios dentro de /api/run_sse a través de mcpAppsInitialize, mcpAppsRequest, y mcpAppsInitialized

Estas adiciones son opcionales. Los consumidores existentes de /api/run y /api/run_sse continúan recibiendo el wrapper genérico ADK a menos que soliciten explícitamente un modo de transporte nativo de AG-UI.

Para las respuestas de herramientas de Apps MCP propiedad del framework, adk-server::ui_types ahora expone:

• McpUiBridgeSnapshot para el estado de puente host/app tipado
• McpUiToolResult para la envolvente de respuesta aditiva
• McpUiToolResultBridge para el puente metadata (protocolVersion, structuredContent, hostInfo, hostCapabilities, hostContext, appInfo, appCapabilities, initialized)

Prefiera McpUiBridgeSnapshot::build_tool_result(...) al promover el estado del puente/sesión en una respuesta de herramienta. Esto estandariza la forma del resultado de la herramienta mientras se preserva resourceUri y en línea html mecanismos de reserva para hosts orientados a la compatibilidad.

Para mapeos incrustados o de host de navegador, el puente aditivo HTTP corresponde a los flujos de host/aplicación de la siguiente manera:

• ui/initialize -> /api/ui/initialize
• ui/message -> /api/ui/message
• ui/update-model-context -> /api/ui/update-model-context
• notifications/resources/list_changed -> /api/ui/notifications/resources-list-changed
• notifications/tools/list_changed -> /api/ui/notifications/tools-list-changed
• notificaciones de host en cola -> /api/ui/notifications/poll

Los puntos finales de puente directos /api/ui/* son la ruta de ciclo de vida preferida para los hosts de Apps MCP. Los campos de solicitud de Apps MCP del lado del tiempo de ejecución permanecen disponibles como una ruta de compatibilidad aditiva para clientes mixtos o heredados.

Ejemplos

El repositorio independiente adk-ui contiene los ejemplos de interfaz de usuario ejecutables:

Ejecuta estos ejemplos desde el repositorio adk-ui para mantener los paquetes de Rust y React en la misma línea de versiones.

Sample Prompts

Prueba las herramientas de UI con estas indicaciones:

# Forms
"I want to register for an account"
"Create a contact form"
"Create a feedback form with a comments textarea"

# Cards
"Show me my profile"
"Display a product card for a laptop"

# Alerts
"Show a success message"
"Display a warning about expiring session"

# Modals
"I want to delete my account" (shows confirmation modal)
"Show a confirmation dialog before submitting"

# Toasts
"Show a success toast notification"
"Display an error toast"

# Tables
"Show my recent orders"
"List all users"

# Charts
"Show monthly sales chart"
"Display traffic trends as a line chart"
"Show revenue breakdown as a pie chart"

# Progress & Loading
"Show upload progress at 75%"
"Display a loading spinner"
"Show skeleton loading state"

# Dashboards
"Show system status dashboard"

---

Anterior: ← Herramientas de Navegador | Siguiente: MCP Herramientas →