En este tutorial, construimos toda la pila de Agentic UI desde cero utilizando Python simple, sin depender de marcos externos para abstraer las ideas centrales. Implementamos el flujo de eventos AG-UI para que el comportamiento del agente sea observable en tiempo real e incorporamos A2UI como una capa declarativa que permite definir interfaces como JSON estructurado en lugar de código ejecutable. A medida que avanzamos, permitimos que un LLM genere interfaces de usuario completas a partir de lenguaje natural, sincronice el agente y el estado de la interfaz de usuario a través de actualizaciones de parches JSON y aplique la seguridad humana en el circuito para acciones críticas. Además, obtenemos una comprensión clara y completa de cómo el razonamiento de los agentes se transforma en interfaces de usuario interactivas y compatibles con el protocolo.
importar subproceso, sys para pkg en ["openai", "rich", "pydantic"]: subprocess.check_call([sys.executable, "-m", "pip", "install", "-q", pkg]) importar os, getpass if os.environ.get("OPENAI_API_KEY"): API_KEY = os.environ["OPENAI_API_KEY"] print(" Usando OPENAI_API_KEY del entorno.") más: intente: desde google.colab importar datos de usuario API_KEY = userdata.get("OPENAI_API_KEY") print(" Usando OPENAI_API_KEY de Colab Secrets.") excepto excepción: API_KEY = getpass.getpass("
Ingrese su clave API de OpenAI (oculta): ") print("
Clave API recibida.") BASE_URL = os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1") MODEL = os.environ.get("OPENAI_MODEL", "gpt-4o-mini") importar json, re, time, uuid, copiar, textwrap de enum importar Enum de clases de datos importar clase de datos, campo, asdict de escribir importar Cualquiera, Opcional, Generador de pydantic import BaseModel, campo de openai import OpenAI de rich.console import Consola de rich.panel import Panel de rich.table import Tabla de rich.tree import Árbol de rich.text import Texto de rich.markdown import Markdown de rich import box console = Console(width=105) client = OpenAI(api_key=API_KEY, base_url=BASE_URL) def llm(messages, **kw): try: return client.chat.completions.create(modelo=MODELO, mensajes=mensajes, temperatura=0.2, **kw) excepto Excepción como e: console.print(f"[red]LLM error: {e}[/]") return Ninguno def hdr(n, title, sub=""): console.print() console.rule(f"[bold cian]SECTION {n}", style="cyan") body = f"[bold white]{title}[/]n[dim]{sub}[/]" if sub else f"[bold white]{title}[/]" console.print(Panel(body, border_style="cyan", padding=(1, 2))) hdr(1, "Protocolo AG-UI – Sistema de eventos", "El protocolo AG-UI real utiliza ~16 tipos de eventos transmitidos a través de SSE.n" "Implementamos todos los tipos de eventos principales y un emisor de streaming en Python puro.") clase AGUIEventType(str, Enum): RUN_STARTED = "RUN_STARTED" RUN_FINISHED = "RUN_FINISHED" RUN_ERROR = "RUN_ERROR" TEXT_MESSAGE_START = "TEXT_MESSAGE_START" TEXT_MESSAGE_CONTENT = "TEXT_MESSAGE_CONTENT" TEXT_MESSAGE_END = "TEXT_MESSAGE_END" TOOL_CALL_START = "TOOL_CALL_START" TOOL_CALL_ARGS = "TOOL_CALL_ARGS" TOOL_CALL_RESULT = "TOOL_CALL_RESULT" TOOL_CALL_END = "TOOL_CALL_END" STATE_SNAPSHOT = "STATE_SNAPSHOT" STATE_DELTA = "STATE_DELTA" INTERRUPT = "INTERRUPT" PERSONALIZADO = "PERSONALIZADO" STEP_STARTED = "STEP_STARTED" STEP_FINISHED = "STEP_FINISHED" @dataclass clase AGUIEvent: tipo: AGUIEventType datos: dict = campo(default_factory=dict) event_id: str = campo(default_factory=lambda: str(uuid.uuid4())[:8]) marca de tiempo: float = campo(default_factory=time.time) def to_sse(self) -> str: payload = {"type": self.type.value, "id": self.event_id, **self.data} return f"event: ag-uindata: {json.dumps(payload)}nn" def to_json(self) -> dict: return {"type": self.type.value, "id": self.event_id, "ts": self.timestamp, **self.data} clase AGUIEventStream: def __init__(self): self.events: lista[AGUIEvent] =[]self.oyentes: lista =[]def emit(self, evento: AGUIEvent): self.events.append(event) para oyente en self.listeners: oyente(evento) def on(self, callback): self.listeners.append(callback) def replay(self) -> list[dict]: return [e.to_json() for e en self.events] def demo_agui_lifecycle(): stream = AGUIEventStream() event_colors = { "RUN_": "negrita verde", "TEXT_": "cian", "TOOL_": "magenta", "STATE_": "amarillo", "INTERRUPT": "negrita roja", "STEP_": "tenue", } def frontend_listener(evento: AGUIEvent): color = "blanco" para prefijo, c en event_colors.items(): if event.type.value.startswith(prefijo): color = c romper detalle = json.dumps(event.data)[:80] si event.data else "" console.print(f" [{color}]
{event.type.value:.<28}[/] {detail}") stream.on(frontend_listener) run_id = str(uuid.uuid4())[:8] console.print("[bold]Simulando la ejecución completa del agente AG-UI…[/]n") stream.emit(AGUIEvent(AGUIEventType.RUN_STARTED, {"run_id": run_id})) stream.emit(AGUIEvent(AGUIEventType.STEP_STARTED, {"step": "analyzing_query", "label": "Comprensión de la solicitud"})) stream.emit(AGUIEvent(AGUIEventType.STEP_FINISHED, {"step": "analyzing_query"})) msg_id = str(uuid.uuid4())[:8] stream.emit(AGUIEvent(AGUIEventType.TEXT_MESSAGE_START, {"message_id": msg_id, "role": "assistant"})) para el fragmento en ["Buscaré", "los datos", "y crearé", "un panel", "para usted."]: stream.emit(AGUIEvent(AGUIEventType.TEXT_MESSAGE_CONTENT, {"message_id": msg_id, "delta": chunk})) stream.emit(AGUIEvent(AGUIEventType.TEXT_MESSAGE_END, {"message_id": msg_id})) tool_id = str(uuid.uuid4())[:8] stream.emit(AGUIEvent(AGUIEventType.TOOL_CALL_START, {"tool_call_id": tool_id, "name": "query_database"})) stream.emit(AGUIEvent(AGUIEventType.TOOL_CALL_ARGS, {"tool_call_id": tool_id, "args_delta": '{"query": "SELECCIONAR ingresos DE las ventas"}'})) stream.emit(AGUIEvent(AGUIEventType.TOOL_CALL_RESULT, {"tool_call_id": tool_id, "result": [{"mes": "enero", "ingresos": 42000}, {"mes": "febrero", "ingresos": 58000}]})) stream.emit(AGUIEvent(AGUIEventType.TOOL_CALL_END, {"tool_call_id": tool_id})) stream.emit(AGUIEvent(AGUIEventType.STATE_SNAPSHOT, { "estado": {"active_agent": "DataAnalyst", "stage": "rendering", "progress": 0.75} })) stream.emit(AGUIEvent(AGUIEventType.STATE_DELTA, { "delta": [{"op": "replace", "path": "/progress", "value": 1.0}] })) stream.emit(AGUIEvent(AGUIEventType.INTERRUPT, { "reason": "high_risk_action", "description": "El agente quiere enviar un correo electrónico a los 5000 clientes.", "options": ["aprobar", "rechazar", "modificar"], })) stream.emit(AGUIEvent(AGUIEventType.RUN_FINISHED, {"run_id": run_id, "status": "completed"})) console.print(Panel( stream.events[3].to_sse(), title="[bold]Ejemplo de formato de cable SSE (cómo se ve en la red)", border_style="dim", )) table = Table(title="AG-UI Event Stream Summary", box=box.ROUNDED) table.add_column("Category", style="cyan", width=15) table.add_column("Events", justify="center", style="green") counts = {} para e in flujo.eventos: gato = e.type.value.rsplit("_", 1)[0]if "_" en e.type.value else e.type.value counts[cat] = counts.get(cat, 0) + 1 para cat, n en counts.items(): table.add_row(cat, str(n)) table.add_row("[bold]TOTAL", f"[bold]{len(stream.events)}") console.print(table) demo_agui_lifecycle()
Comenzamos construyendo la columna vertebral de cada interfaz agente: el flujo de eventos AG-UI. Implementamos los 16 tipos de eventos de la especificación AG-UI real, eventos de ciclo de vida, transmisión de texto token por token, llamadas de herramientas transmitidas, instantáneas de estado, deltas y señales de interrupción, y los serializamos en el formato de cable SSE que los sistemas de producción utilizan a través de HTTP. Luego, conectamos un oyente frontal que reacciona a cada evento a medida que llega, simulando la experiencia exacta que tendría una aplicación React o Flutter al consumir esta transmisión.
hdr(2, "A2UI — Árboles de componentes declarativos", "Especificación A2UI de Google: los agentes emiten listas de componentes JSON planos con referencias de ID.n" "El registro de widgets del cliente asigna tipos → widgets nativos.n" "Datos similares a seguros, código expresivo. No se envía código ejecutable.") class A2UIMessageType(str, Enum): CREATE_SURFACE = "createSurface" UPDATE_COMPONENTS = "updateComponents" UPDATE_DATA_MODEL = "updateDataModel" DELETE_SURFACE = "deleteSurface" @dataclass clase A2UIComponent: id: str tipo: str propiedades: dict = campo(default_factory=dict) niños: lista[str] = campo(default_factory=list) def to_dict(self) -> dict: d = {"id": self.id, "type": self.type, **self.properties} if self.children: d["children"] = self.children return d @dataclass clase A2UIDataModel: data: dict = field(default_factory=dict) def get_binding(self, path: str) -> Any: parts = [p for p in path.split("/") if p] val = self.data for p en partes: if isinstance(val, dict): val = val.get(p) elif isinstance(val, list) y p.isdigit(): val = val[int(p)] else: return Ninguno return val @dataclass clase A2UISurface: Surface_id: str componentes: lista[A2UIComponent] = campo(default_factory=list) data_model: A2UIDataModel = campo(default_factory=A2UIDataModel) def to_messages(self) -> lista[dict]: mensajes =[]msgs.append({ "tipo": A2UIMessageType.CREATE_SURFACE.value, "surfaceId": self.surface_id, }) msgs.append({ "tipo": A2UIMessageType.UPDATE_COMPONENTS.value, "surfaceId": self.surface_id, "components": [c.to_dict() para c en self.components], }) if self.data_model.data: msgs.append({ "type": A2UIMessageType.UPDATE_DATA_MODEL.value, "surfaceId": self.surface_id, "dataModel": self.data_model.data, }) devuelve clase de mensajes WidgetRegistry: def __init__(self): self._renderers = {} def registro(self, componente_tipo: str, render_fn): self._renderers[component_type] = render_fn def render(self, componente: A2UIComponent, superficie: A2UISurface, sangría: int = 0): fn = self._renderers.get(component.type) if fn: fn(componente, superficie, sangría) else: pad = " " * sangría console.print(f"{pad}[dim]⟨{component.type} id={component.id}⟩ (sin renderizador)[/]") def render_tree(self, superficie: A2UISurface): comp_map = {c.id: c para c en superficie.components} all_children = set() para c en superficie.components: all_children.update(c.children) raíces = [c para c en Surface.components si c.id no está en all_children] def _render(comp_id: str, sangría: int): comp = comp_map.get(comp_id) si no comp: devuelve self.render(comp, superficie, sangría) para child_id en comp.children: _render(child_id, sangría + 1) para raíz en raíces: _render(root.id, 0) registro = WidgetRegistry() def _resolve(comp, superficie, clave, predeterminado=None): val = comp.properties.get(clave, predeterminado) vinculante = comp.properties.get("dataBinding") si vinculante e isinstance(binding, str) y vinculante.startswith("/"): resuelto = superficie.data_model.get_binding(binding) si resuelto no es Ninguno: devuelve resuelto si isinstance(val, str) y val.startswith("/") y "/" en val[1:]: resuelto = superficie.data_model.get_binding(val) si resuelto no es Ninguno: devolver resuelto devolver val def _to_float(val, default=0.0): if isinstance(val, (int, float)): return float(val) if isinstance(val, str): clean = val.strip().rstrip("%") intente: f = float(cleaned) if "%" in val of > 1: return f / 100.0 return f excepto ValueError: return default return default def render_card(comp, superficie, sangría): pad = " " * sangría título = str(_resolve(comp, superficie, "título", "Tarjeta")) console.print(f"{pad}┌─{'─' * 50}─┐") console.print(f"{pad}│ [bold]{title:^50}[/] │") console.print(f"{pad}├─{'─' * 50}─┤") si no comp.children: subtitle = str(_resolve(comp, Surface, "subtitle", "")) if subtitle: console.print(f"{pad}│ {subtitle:<49}│") console.print(f"{pad}└─{'─' * 50}─┘") def render_text(comp, superficie, sangría): pad = " " * sangría texto = _resolve(comp, superficie, "text", "") estilo = comp.properties.get("estilo", "cuerpo") estilos = {"headline": "negrita blanca", "cuerpo": "blanco", "caption": "dim", "label": "negrita cian"} console.print(f"{pad}[{styles.get(style, 'blanco')}]{text}[/]") def render_button(comp, superficie, sangría): pad = " " * sangría etiqueta = str(_resolve(comp, superficie, "etiqueta", "Botón")) variante = comp.properties.get("variante", "primario") colores = {"primario": "negrita blanca sobre azul", "secundario": "blanco sobre gris30", "peligro": "negrita blanca sobre rojo"} console.print(f"{pad} [{colors.get(variant, 'white')}] {label} [/]") def render_text_field(comp, superficie, sangría): pad = " " * etiqueta de sangría = comp.properties.get("label", "Input") placeholder = comp.properties.get("placeholder", "") console.print(f"{pad} {label}: [tenue]┌──────────────────────────┐[/]") console.print(f"{pad} [tenue]│ {placeholder:<25}│[/]") console.print(f"{pad} [dim]└──────────────────────────┘[/]") def render_row(comp, superficie, sangría): pase def render_column(comp, superficie, sangría): pase def render_image(comp, superficie, sangría): pad = " " * sangría alt = comp.properties.get("alt", "image") console.print(f"{pad} [dim] [{alt}][/]") def render_divider(comp, superficie, sangría): pad = " " * sangría console.print(f"{pad} {'─' * 50}") def render_chip(comp, superficie, sangría): pad = " " * sangría etiqueta = str(_resolve(comp, superficie, "label", "")) console.print(f"{pad} [on grey23] {label} [/]") def render_progress(comp, superficie, sangría): pad = " " * sangría valor_bruto = _resolve(comp, superficie, "valor", 0) valor = max(0.0, min(1.0, _to_float(valor_bruto, 0.0))) etiqueta = str(_resolve(comp, superficie, "etiqueta", "")) bar_len = int(valor * 40) bar = f"[verde]{'█' * bar_len}[/][dim]{'░' * (40 – bar_len)}[/]" console.print(f"{pad} {label}: {bar} {value*100:.0f}%") para nombre, fn en [ ("card", render_card), ("text", render_text), ("button", render_button), ("text-field", render_text_field), ("row", render_row), ("column", render_column), ("image", render_image), ("divider", render_divider), ("chip", render_chip), ("progress-bar", render_progress), ]: registro.register(nombre, fn) console.print("n[bold]Demostración: formulario de reserva A2UI: el agente genera una interfaz de usuario de reserva de restaurante[/]n") booking_surface = A2UISurface(surface_id="booking-form-1", componentes=[ A2UIComponent("raíz", "tarjeta", {"título": "
Reservar una mesa"}, niños=["c1", "c2", "c3", "c4", "c5", "c6"]), A2UIComponent("c1", "text", {"text": "", "dataBinding": "/restaurant/name", "style": "headline"}), A2UIComponent("c2", "text", {"text": "", "dataBinding": "/restaurant/cuisine", "style": "caption"}), A2UIComponent("c3", "divisor", {}), A2UIComponent("c4", "campo de texto", {"label": "Fecha", "placeholder": "AAAA-MM-DD"}), A2UIComponent("c5", "text-field", {"label": "Invitados", "placeholder": "1-12"}), A2UIComponent("c6", "button", {"label": "Reserve Now", "variant": "primary", "action": "submit_booking"}), ], data_model=A2UIDataModel({"restaurant": {"name": "Chez Laurent", "cocina": "Contemporánea francesa • $$$$"}}) ) console.print(Panel( "n".join(json.dumps(m, indent=2)[:200] for m in booking_surface.to_messages()), title="[bold]Secuencia JSONL de A2UI (lo que pasa por el cable)", border_style="amarillo", )) console.print("[bold]Renderizado por el registro del widget del cliente:[/]n") registro.render_tree(booking_surface) console.print() t = Table(title="Lista de componentes planos A2UI (modelo de adyacencia)", box=box.ROUNDED) t.add_column("ID", estilo="cian", ancho=8) t.add_column("Tipo", estilo="verde", ancho=14) t.add_column("Niños", estilo="amarillo", ancho=20) t.add_column("Enlaces", estilo="magenta", ancho=25) para c en booking_surface.components: enlace = c.properties.get("dataBinding", "") t.add_row(c.id, c.type, ", ".join(c.children) if c.children else "—", vinculante o "—") console.print
Implementamos la especificación A2UI de Google: un modelo de lista de adyacencia plana donde los componentes hacen referencia a los niños por ID en lugar de anidarlos, lo que hace que el formato sea trivialmente transmitible y fácil de generar incrementalmente para los LLM. Creamos un Registro de widgets del lado del cliente que asigna cadenas de tipos abstractos como "tarjeta", "campo de texto" y "barra de progreso" a renderizadores de terminal concretos, reflejando cómo una aplicación de producción los asigna a componentes de React o widgets de Flutter. Demostramos el ciclo completo con un formulario de reserva de restaurante, completo con enlaces de modelos de datos que desacoplan los valores dinámicos de la estructura de la interfaz de usuario, exactamente como lo prescribe la especificación A2UI.
hdr(3, "UI generativa: LLM produce interfaces en vivo", "El agente genera árboles de componentes A2UI dinámicamente en función de la consulta.n" "Este es el núcleo de la 'UI generativa': interfaces adaptativas al contexton" "que van mucho más allá de las respuestas de chat de solo texto.") A2UI_GENERATION_PROMPT = """ Usted es un agente de UI generativa A2UI. Dada una consulta de usuario, genera una interfaz rica e interactiva — NO texto. Genera un árbol de componentes A2UI como JSON: 1. Genera una lista plana de componentes usando el modelo de adyacencia (hijos = lista de ID). 2. Tipos de componentes disponibles: tarjeta, texto, botón, campo de texto, fila, columna, divisor, imagen, barra de progreso, selección, selector de fecha, tabla de datos. 3. Incluya un objeto "modelo de datos" separado para los valores dinámicos. El componente ROOT debe ser una "tarjeta" con todos los demás como descendientes 5. Piense en qué UI sirve MEJOR al usuario: formularios para entrada, tablas para datos, barras de progreso para estado, chips para etiquetas, botones para FORMATO DE SALIDA (JSON estricto, nada más): { "surfaceId": "unique-id", "components": [ {"id": "root", "type": "card", "title": "…", "children": ["c1",. "c2"]}, {"id": "c1", "type": "text", "text": "…", "style": "headline"}, … ], "dataModel": { … } } """ def generate_ui(user_query: str) -> Opcional[A2UISurface]: console.print(f" [dim]Generando UI para:[/] [bold]{user_query}[/]") respuesta = llm([ {"role": "system", "content": A2UI_GENERATION_PROMPT}, {"role": "user", "content": user_query}, ], max_tokens=1200) si no es respuesta: devolver Ninguno raw = respuesta.choices[0].message.content try: clean = re.sub(r'“`jsons*|s*“`', '', raw).strip() spec = json.loads(cleaned) excepto json.JSONDecodeError: console.print(f"[red]Error al analizar la interfaz de usuario generada: {raw[:200]}[/]") return Ninguno componentes =[]para c en spec.get("componentes",[]): componentes.append(A2UIComponent( id=c.get("id", str(uuid.uuid4())[:6]), tipo=c.get("tipo", "texto"), propiedades={k: v para k, v en c.items() si k no está en ("id", "tipo", "niños")}, niños=c.get("niños",[]), )) superficie = A2UISurface( superficie_id=spec.get("surfaceId", f"gen-{uuid.uuid4().hex[:6]}"), componentes=componentes, data_model=A2UIDataModel(spec.get("dataModel", {})), ) devuelve superficie def demo_generative_ui(consulta: str): superficie = generate_ui(consulta) si superficie: console.print(f"n[negrita verde]Componentes {len(surface.components)} generados:[/]") registro.render_tree(surface) console.print() tipos = {} para c en Surface.components: tipos[c.type] = tipos.get(c.type, 0) + 1 console.print(" [dim]Tipos de componentes utilizados:[/] " + ", ".join(f"[cian]{t}[/]×{n}" para t, n en tipos.items())) if Surface.data_model.data: console.print(f" [dim]Claves del modelo de datos:[/] {list(surface.data_model.data.keys())}") console.print() console.print("n[bold]Demostración 1: el agente genera un formulario de incorporación[/]") demo_generative_ui( "Crear un flujo de incorporación de usuario: recopilar nombre, correo electrónico, rol (menú desplegable), " "método de notificación preferido (chips) y un botón 'Comenzar'." ) console.print("n[bold]Demostración 2: el agente genera un panel de datos[/]") demo_generative_ui( "Mostrar un panel de estado del proyecto con: nombre del proyecto 'Atlas v2', " "4 miembros del equipo, progreso del sprint al 68%, 3 bloqueadores marcados como " "críticos, y botones de acción para 'Ver trabajos pendientes' y 'Programar standup'." ) console.print("n[bold]Demostración 3: El agente genera un diálogo de confirmación[/]") demo_generative_ui( "Mostrar una confirmación de pago: cargo de $2,450 a Visa que termina en 4242, " "orden #ORD-8891, con los botones Aprobar y Rechazar." )
Le entregamos las claves al LLM y le permitimos generar árboles completos de componentes A2UI en tiempo de ejecución a partir de descripciones en inglés sencillo; esta es la UI generativa en su forma más pura. Solicitamos al modelo el esquema A2UI y el catálogo de componentes, y produce superficies completamente estructuradas con tarjetas, formularios, chips, barras de progreso y enlaces de datos, eligiendo el mejor patrón de UI para cada consulta. Realizamos tres demostraciones, un flujo de incorporación, un panel de proyecto y una confirmación de pago, mostrando cómo el mismo agente adapta su interfaz a contextos tremendamente diferentes sin un único diseño codificado.
hdr(4, "Sincronización de estado: estado compartido entre el agente y la interfaz de usuario", "AG-UI sincroniza el estado bidireccionalmente usando STATE_SNAPSHOT y STATE_DELTA.n" "El agente ES la máquina de estado; la interfaz de usuario ES el renderizador.n" "Las diferencias del parche JSON mantienen las actualizaciones mínimas y eficientes.") class SharedState: def __init__(self, inicial: dict = Ninguno): self.state: dict = inicial o {} self.history: lista[dict] =[]self.version: int = 0 def snapshot(self) -> AGUIEvent: return AGUIEvent(AGUIEventType.STATE_SNAPSHOT, {"state": copy.deepcopy(self.state), "version": self.version}) def apply_delta(self, operaciones: lista[dict]) -> AGUIEvent: para op en operaciones: path_parts = [p para p en op["path"].split("/") if p] target = self.state for part in path_parts[:-1]: if isinstance(target, dict): target = target.setdefault(part, {}) elif isinstance(target, list) y part.isdigit(): target = target[int(part)] key = path_parts[-1] if path_parts else Ninguno si la clave es Ninguna: continuar si op["op"] == "replace": target[key] = op["valor"] elif op["op"] == "agregar": if isinstance(destino, lista) y key.isdigit(): target.insert(int(key), op["value"]) else: target[key] = op["value"] elif op["op"] == "eliminar": if isinstance(destino, dict): target.pop(key, Ninguno) self.version += 1 self.history.append({"version": self.version, "ops": operaciones}) return AGUIEvent(AGUIEventType.STATE_DELTA, {"delta": operaciones, "version": self.version}) console.print("n[bold]Demostración: proceso de revisión de documentos: 3 agentes, estado compartido[/]n") stream = AGUIEventStream() state = SharedState({ "document": {"title": "Informe de estrategia del cuarto trimestre", "status": "borrador", "word_count": 2840}, "pipeline": {"stage": "research", "progress": 0.0}, "agents": {"active": "Investigador", "queue": ["Editor", "Revisor"]}, "feedback":[], }) def log_event(event: AGUIEvent): if event.type in (AGUIEventType.STATE_SNAPSHOT, AGUIEventType.STATE_DELTA): if event.type == AGUIEventType.STATE_DELTA: ops = event.data.get("delta",[]) para op en operaciones: console.print(f" [amarillo]STATE_DELTA[/] v{event.data.get('version')}: " f"[cian]{op['op']}[/] {op['path']} → {op.get('value', '∅')}") else: console.print(f" [amarillo]STATE_SNAPSHOT[/] v{event.data.get('version')}: {list(event.data['state'].keys())}") stream.on(log_event) stream.emit(state.snapshot()) console.print("n[negrita verde]▸ Agente investigador trabajando…[/]") stream.emit(state.apply_delta([ {"op": "replace", "path": "/pipeline/stage", "value": "research_complete"}, {"op": "replace", "path": "/pipeline/progress", "value": 0.33}, {"op": "add", "path": "/feedback/0", "value": {"agent": "Investigador", "note": "Se agregaron 4 nuevas fuentes de datos"}}, ])) console.print("n[negrita verde]▸ Agente del editor funcionando…[/]") stream.emit(state.apply_delta([ {"op": "replace", "path": "/agents/active", "value": "Editor"}, {"op": "replace", "path": "/pipeline/stage", "value": "editing"}, {"op": "replace", "path": "/pipeline/progress", "value": 0.66}, {"op": "replace", "path": "/document/word_count", "value": 3150}, ])) console.print("n[negrita verde]▸ Agente revisor trabajando…[/]") stream.emit(state.apply_delta([ {"op": "replace", "path": "/agents/active", "value": "Reviewer"}, {"op": "replace", "path": "/pipeline/stage", "value": "review_complete"}, {"op": "replace", "path": "/pipeline/progress", "value": 1.0}, {"op": "replace", "path": "/document/status", "value": "approved"}, ])) console.print(Panel( json.dumps(state.state, indent=2), title="[bold]Estado final compartido después de la canalización", border_style="green", )) t = Table(title="Historial del estado (versiones)", box=box.ROUNDED) t.add_column("Version", style="cyan", justify="center") t.add_column("Operaciones", estilo="amarillo") para h en state.history: ops_summary = "; ".join(f"{o['op']} {o['path']}" para o en h["ops"]) t.add_row(str(h["version"]), ops_summary[:70]) console.print hdr(5, "Human-in-the-Loop — AG-UI INTERRUPT Events", "Cuando un agente realiza una acción de alto riesgo, emite un evento INTERRUPT.n" "La interfaz genera una interfaz de usuario de aprobación. La ejecución se detiene hasta que el humanon" "aprueba, rechaza o modifica. El estado es preservado en todo.") @dataclass clase InterruptRequest: id_interrupción: str acción_descripción: str nivel_riesgo: str recursos_afectados: lista[str] cambios_propuestos: dict opciones: lista[str] = campo(default_factory=lambda: ["aprobar", "rechazar", "modificar"]) @dataclass clase InterruptResponse: interrupción_id: str decisión: str modificaciones: Opcional[dict] = Ninguna clase InterruptableAgent: RISK_RULES = { "delete": "crítico", "pago": "crítico", "email_all": "alto", "publish": "alto", "update": "medio", "read": "bajo", } def __init__(self): self.stream = AGUIEventStream() self.pending_interrupts: dict[str, InterruptRequest] = {} def evalua_and_maybe_interrupt(self, action: str, detalles: dict) -> Opcional[InterruptRequest]: riesgo = "bajo" para palabra clave, nivel en self.RISK_RULES.items(): si palabra clave en acción.lower(): riesgo = salto de nivel si riesgo en ("crítico", "alto"): interrupción = InterruptRequest( interrupción_id=str(uuid.uuid4())[:8], acción_descripción=acción, nivel_riesgo=riesgo, recursos_afectados=detalles.get("recursos",[]), cambios_propuestos=detalles.get("cambios", {}), ) self.pending_interrupts[interrupt.interrupt_id] = interrupción self.stream.emit(AGUIEvent(AGUIEventType.INTERRUPT, { "interrupt_id": interrupción.interrupt_id, "razón": riesgo, "descripción": interrupción.acción_descripción, "recursos_afectados": interrupción.recursos_affectados, "cambios_propuestos": interrupción.cambios_propuestos, "opciones": interrupción.opciones, })) devolver interrupción devolver Ninguno def resolve_interrupt(self, respuesta: InterruptResponse) -> str: interrupción = self.pending_interrupts.pop(response.interrupt_id, Ninguno) si no interrumpe: devuelve "No se encontró ninguna interrupción pendiente". si respuesta.decisión == "aprobar": devolver f" APROBADO: '{interrupt.action_description}' ejecutándose ahora." elif respuesta.decisión == "rechazar": devolver f"
RECHAZADO: '{interrupt.action_description}' cancelado." elif respuesta.decisión == "modificar": devolver f"
MODIFICADO: '{interrupt.action_description}' actualizado con: {response.modifications}" return f"Decisión desconocida: {response.decision}" console.print("n[bold]Demostración: el agente encuentra acciones de distintos niveles de riesgo[/]n") agente = InterruptableAgent() acciones = [ ("Leer perfil de usuario", {"recursos": ["usuario:123"]}), ("Actualizar preferencias de usuario", {"resources": ["user:123"], "changes": {"theme": "dark"}}), ("Eliminar cuenta de usuario", {"resources": ["user:123", "data:all"], "changes": {"action": "permanent_delete"}}), ("Enviar correo electrónico a los 12.000 usuarios", {"resources": ["email:newsletter"], "changes": {"subject": "Gran anuncio"}}), ("Publicar publicación de blog", {"resources": ["post:draft-42"], "changes": {"status": "public"}}), ] def event_logger(event): if event.type == AGUIEventType.INTERRUPT: d = event.data Risk_style = {"critical": "bold red", "high": "bold yellow"}.get(d["reason"], "blanco") console.print(f"n [negrita]
INTERRUMPIR EVENTO[/]") console.print(f" Riesgo: [{risk_style}]{d['reason'].upper()}[/]") console.print(f" Acción: {d['description']}") console.print(f" Afectado: {d['affected_resources']}") console.print(f" Opciones: {d['options']}") agent.stream.on(event_logger) resultados =[]para action_desc, detalles en acciones: interrupción = agente.assess_and_maybe_interrupt(action_desc, detalles) si interrupción: decisión = "rechazar" si interrupción.riesgo_nivel == "crítico" de lo contrario "aprobar" resultado = agente.resolve_interrupt(InterruptResponse(interrupt.interrupt_id, decisión)) más: resultado = f"
EJECUTADO AUTOMÁTICAMENTE: '{action_desc}' (bajo riesgo, no se necesita aprobación)" results.append((action_desc, result)) console.print() t = Table(title="Execution Results", box=box.ROUNDED, show_lines=True) t.add_column("Action", style="white", width=28) t.add_column("Outcome", style="dim", width=55) para action_desc, resultado en resultados: t.add_row(action_desc, resultado) console.print
Construimos un motor SharedState que emite eventos AG-UI STATE_SNAPSHOT y STATE_DELTA utilizando operaciones de parche JSON, manteniendo el backend del agente y la UI del frontend perfectamente sincronizados a través de cada mutación. Demostramos esto con un proceso de revisión de documentos de tres agentes en el que un investigador, un editor y un revisor modifican el estado compartido en secuencia, y la interfaz ve cada cambio en el instante en que ocurre. Luego implementamos el patrón AG-UI INTERRUPT, en el que el agente evalúa los niveles de riesgo para las acciones propuestas, emite eventos de interrupción para cualquier acción peligrosa y pausa la ejecución hasta que un humano apruebe, rechace o modifique el plan.
hdr(6, "Full Pipeline — UI adaptable impulsada por LLM", "La arquitectura completa de UI Agentic en un solo pipeline:n" " Consulta de usuario → Análisis de intención → Selección de patrón de UI →n" " Generación de A2UI → Transmisión de eventos AG-UI → Sincronización de estado → Renderizado") UI_ROUTER_PROMPT = """ Usted es un agente de enrutamiento de UI. Dada una consulta de usuario, decida qué tipo de UI generar. RESPONDA SOLO EN JSON: { "intent": "form | tablero | confirmación | lista | detalle | asistente | error", "reasoning": "por qué encaja este patrón de interfaz de usuario", "ui_complexity": "simple | moderado | complex", "needs_approval": true/false, "data_requirements": ["qué datos necesita la interfaz de usuario"] } """ class AgenticUIPipeline: def __init__(self): self.stream = AGUIEventStream() self.state = SharedState({"pipeline": {"stage": "idle"}, "renders": 0}) self.interrupt_agent = InterruptableAgent() def route(self, query: str) -> dict: resp = llm([ {"role": "system", "content": UI_ROUTER_PROMPT}, {"role": "user", "content": query}, ], max_tokens=300) si no, resp: return {"intent": "dashboard", "reasoning": "fallback", "ui_complexity": "simple", "needs_approval": Falso, "requisitos_de_datos":[]} raw = resp.elecciones[0].message.content intente: devuelva json.loads(re.sub(r'“`jsons*|s*“`', '', raw).strip()) excepto json.JSONDecodeError: devuelva {"intent": "dashboard", "reasoning": "parse_fallback", "ui_complexity": "simple", "needs_approval": False, "data_requirements":[]} def ejecutar(self, user_query: str): run_id = str(uuid.uuid4())[:8] console.print(Panel(f"[bold]{user_query}[/]", title=" Consulta de usuario", border_style="white")) self.stream.emit(AGUIEvent(AGUIEventType.RUN_STARTED, {"run_id": run_id})) self.stream.emit(AGUIEvent(AGUIEventType.STEP_STARTED, {"step": "routing"})) enrutamiento = self.route(user_query) console.print(f"n [negrita cian]
Decisión del enrutador:[/]") console.print(f" Intención: [green]{routing.get('intent')}[/] | " f"Complejidad: [amarillo]{routing.get('ui_complexity')}[/] | " f"Aprobación: {'
'si enrutamiento.get('necesita_aprobación') más '
'}") console.print(f" Razonamiento: [dim]{routing.get('razoning', '')}[/]") self.stream.emit(AGUIEvent(AGUIEventType.STEP_FINISHED, {"step": "routing", "result": enrutamiento})) self.state.apply_delta([ {"op": "replace", "path": "/pipeline/stage", "value": "generating"}, ]) self.stream.emit(AGUIEvent(AGUIEventType.STEP_STARTED, {"step": "generating_ui"})) msg_id = str(uuid.uuid4())[:8] self.stream.emit(AGUIEvent(AGUIEventType.TEXT_MESSAGE_START, {"message_id": msg_id})) self.stream.emit(AGUIEvent(AGUIEventType.TEXT_MESSAGE_CONTENT, { "message_id": msg_id, "delta": f"Construyendo una interfaz {routing.get('intent')} para usted…" })) self.stream.emit(AGUIEvent(AGUIEventType.TEXT_MESSAGE_END, {"message_id": msg_id})) superficie = generate_ui(user_query) self.stream.emit(AGUIEvent(AGUIEventType.STEP_FINISHED, {"step": "generating_ui"})) si enrutamiento.get("needs_approval") y superficie: self.stream.emit(AGUIEvent(AGUIEventType.INTERRUPT, { "reason": "ui_confirmation", "description": f"Generated {len(surface.components)} interfaz de usuario del componente. ¿Renderizarlo?", "opciones": ["renderizar", "regenerar", "cancelar"], })) console.print("n [negrita amarilla]
INTERRUPT:[/] UI generada, esperando aprobación humana…") console.print(" [verde]→ Aprobación automática para demostración…[/]") if superficie: self.state.apply_delta([ {"op": "replace", "path": "/pipeline/stage", "value": "rendering"}, {"op": "replace", "path": "/renders", "value": self.state.state.get("renders", 0) + 1}, ]) console.print(f"n[negrita verde]
Interfaz renderizada ({len(surface.components)} componentes):[/]n") registro.render_tree(surface) self.stream.emit(AGUIEvent(AGUIEventType.CUSTOM, { "subtype": "a2ui_surface", "surface": Surface.to_messages(), })) self.state.apply_delta([{"op": "replace", "path": "/pipeline/stage", "value": "complete"}]) self.stream.emit(AGUIEvent(AGUIEventType.RUN_FINISHED, {"run_id": run_id, "status": "success"})) console.print() event_counts = {} para e en self.stream.events: event_counts[e.type.value] = event_counts.get(e.type.value, 0) + 1 t = Table(title="Resumen de eventos de canalización", box=box.ROUNDED) t.add_column("Tipo de evento", style="cyan") t.add_column("Count", justify="center", style="green") para etype, cuenta en sorted(event_counts.items()): t.add_row(etype, str(count)) console.print pipeline = AgenticUIPipeline() console.print("n[bold]Demo 1: El agente crea un formulario de configuración[/]") pipeline.run( "Crear un panel de configuración de notificaciones donde puedo alternar correo electrónico/SMS/push, " "establecer horas de silencio y elegir un sonido de notificación." ) pipeline.stream = AGUIEventStream() pipeline.state = SharedState({"pipeline": {"stage": "idle"}, "renders": 0}) console.print("n[bold]Demostración 2: El agente crea un panel de seguimiento de pedidos[/]") pipeline.run( "Mostrar estado del pedido n.° ORD-7742: enviado a través de FedEx, seguimiento 789456123, " "entrega estimada el 24 de marzo, 2 de 3 artículos entregados. Muestra una " "barra de progreso y botones de acción para 'Contactar con soporte técnico' y 'Solicitar reembolso'." ) hdr(7, "Actualizaciones incrementales de la interfaz de usuario — Live Surface Modification", "Las superficies A2UI se pueden actualizar de forma incremental. El agente puede agregar, eliminarn" "o modificar componentes y enlaces de datos en una superficie activa sinn" "regenerar todo el árbol. Esencial para la colaboración en tiempo real.") class LiveSurface: def __init__(self, superficie: A2UISurface): self.surface = superficie self.update_log: list[str] =[]def add_component(self, componente: A2UIComponent, parent_id: Opcional[str] = Ninguno): self.surface.components.append(component) if parent_id: for c in self.surface.components: if c.id == parent_id: c.children.append(component.id) break self.update_log.append(f"ADD {component.type}#{component.id} → padre:{parent_id o 'root'}") def update_component(self, componente_id: str, new_props: dict): para c en self.surface.components: si c.id == componente_id: c.properties.update(new_props) self.update_log.append(f"UPD #{component_id} accesorios: {list(new_props.keys())}") return self.update_log.append(f"ERR #{component_id} not found") def remove_component(self, componente_id: str): self.surface.components = [c para c en self.surface.components si c.id != componente_id] para c en self.surface.components: si componente_id en c.children: d: dict, ruta: str, valor: Cualquiera) -> dict: parts = [p for p in path.split("/") if p] d = copy.deepcopy(d) current = d for p in parts[:-1]: current = current.setdefault(p, {}) if parts: current[parts[-1]] = value return d console.print("n[bold]Demostración: edición colaborativa en vivo: el agente modifica la interfaz de usuario en tiempo real[/]n") inicial = A2UISurface( superficie_id="tablero de tareas", componentes=[ A2UIComponent("tablero", "tarjeta", {"título": "
Sprint Board"}, niños=["t1", "t2", "t3"]), A2UIComponent("t1", "chip", {"label": "AUTH-101: flujo de inicio de sesión", "variant": "in_progress"}), A2UIComponent("t2", "chip", {"label": "AUTH-102: configuración de OAuth", "variant": "todo"}), A2UIComponent("t3", "chip", {"label": "AUTH-103: 2FA", "variant": "todo"}), ], data_model=A2UIDataModel({"sprint": {"name": "Sprint 14", "velocity": 21}}), ) live = LiveSurface(initial) console.print("[bold]Placa inicial:[/]") registro.render_tree(live.surface) console.print("n[negrita amarilla]Tablero de actualización del agente en tiempo real…[/]n") live.update_component("t1", {"variant": "done", "label": "
AUTH-101: Flujo de inicio de sesión"}) live.update_component("t2", {"variant": "in_progress", "label": "
AUTH-102: configuración de OAuth"}) live.add_component( A2UIComponent("t4", "chip", {"label": "AUTH-104: restablecimiento de contraseña", "variant": "todo"}), parent_id="board" ) live.update_data("/sprint/velocity", 25) live.remove_component("t3") console.print("[bold]Tablero actualizado:[/]") registro.render_tree(live.surface) console.print() t = Table(title="Registro de actualización incremental", box=box.ROUNDED) t.add_column("#", style="cyan", width=4, justify="center") t.add_column("Operation", style="amarillo") para i, entrada en enumerate(live.update_log, 1): t.add_row(str(i), entrada) console.print
Conectamos cada pieza en una única clase AgenticUIPipeline
hdr(8, "Referencia: La pila de protocolos de UI de Agentic", "Cómo encajan AG-UI, A2UI, MCP y A2A en la arquitectura de agente moderna"). ┌─────────────────────────── ───────────────────────────┐ │ [negrita cian] INTERFAZ DE USUARIO [/] (React, Flutter, SwiftUI, Terminal) │ │ Representa widgets nativos a partir de las especificaciones de los componentes │ └────────────────────────┬── ───────────────────────────┘ │ Árboles de componentes A2UI (JSON) │ Eventos AG-UI (SSE/WebSocket) ┌────────────────────────┴── ───────────────────────────┐ │ [negrita amarilla]PROTOCOLO AG-UI[/] (Agente Interacción del usuario) │ │ • Transmisión de eventos (TEXTO, TOOL_CALL, ESTADO, INTERRUPCIÓN)│ │ • Sincronización de estado bidireccional (INSTANTÁNEA + DELTA) │ │ • Humano en el circuito (INTERRUPCIÓN → flujo de aprobación) │ └────────────────────────┬── ───────────────────────────┘ │ ┌────────────────────────┴── ───────────────────────────┐ │ [bold magenta]AGENT RUNTIME[/] (LangGraph, CrewAI, personalizado, etc.) │ │ • Genera superficies A2UI (UI generativa) │ │ • Administra el estado compartido │ │ • Orquesta subagentes a través del protocolo A2A │ │ • Accede a herramientas a través del protocolo MCP │ └────────────────────────┬── ───────────────────────────┘ │ ┌────────────────────────┴── ───────────────────────────┐ │ [negrita verde]LLM BACKBONE[/] (GPT, Claude, Gemini, etc.) │ │ • Genera árboles de componentes como salida estructurada │ │ • Razones sobre los patrones de UI por contexto │ │ • Transmite tokens para renderizado en tiempo real │ └─────────────────────────── ───────────────────────────┘ [dim]Roles de protocolo: AG-UI = Agente
Usuario (transmisión de eventos, estado, HITL) A2UI = Agente → UI (especificaciones de componentes declarativos) A2A = Agente → Agente (delegación, subagentes) MCP = Agente → Herramientas (llamada a funciones, contexto)[/] """, title="[bold]Referencia de arquitectura", border_style="cyan")) ref = Table(title="Conceptos de UI de Agent — Referencia rápida", box=box.DOUBLE_EDGE, show_lines=True) ref.add_column("Concepto", estilo="bold cian", ancho=22) ref.add_column("Qué hace", estilo="blanco", ancho=35) ref.add_column("Mecanismo clave", estilo="amarillo", ancho=28) ref.add_row("Eventos AG-UI", "Transmitir acciones del agente al frontend en tiempo real", "SSE/WebSocket + ~16 tipos de eventos") ref.add_row("Componentes A2UI", "Árboles de UI declarativos: seguros, portátiles, nativos", "JSON plano + registro de widgets") ref.add_row("Sincronización de estado", "Mantener el estado del agente y de la UI al mismo tiempo", "STATE_SNAPSHOT + STATE_DELTA") ref.add_row("UI generativa", "LLM genera UI en tiempo de ejecución, no solo texto", "A2UI JSON como salida estructurada") ref.add_row("INTERRUPT (HITL)", "Pausar la ejecución para aprobación humana", "Evento INTERRUPT → flujo de aprobación") ref.add_row("Actualización incremental","Modificar superficies activas sin regeneración completa", "Mensaje A2UI updateComponents") ref.add_row("Enlace de datos", "Lecturas de UI desde un modelo de datos compartido", "Rutas de puntero JSON (/path/to/val)") ref.add_row("Widget Registro", "El cliente asigna tipos abstractos a widgets nativos", "Catálogo de componentes confiables") console.print(ref) console.print(Panel( "[bold green]¡Tutorial completo![/]nn" "[dim]Lo que creaste:[/]n" " • Un sistema de eventos AG-UI completo con los 16 tipos de eventosn" " • Un renderizador A2UI con componentes de lista de adyacencia plana + enlace de datosn" " • Basado en LLM UI generativa que crea interfaces a partir de lenguaje naturaln" " • Sincronización de estado bidireccional con deltas de parches JSONn" " • Flujos de aprobación e interrupción humana en el buclen" " • Actualizaciones incrementales de superficie en vivonn" "[dim]Para ir más allá:[/]n" " • Sirve eventos AG-UI a través de SSE real con FastAPIn" " • Conéctate a los componentes CopilotKit React para una interfaz realn" " • Utiliza AGUIAdapter de Pydantic AI para alojamiento de agentes de producciónn" " • Agregue el protocolo A2A para delegación de múltiples agentesn" " • Implemente en AWS Bedrock AgentCore con soporte nativo AG-UI", title="[bold]
¿Qué sigue?", border_style="verde", padding=(1, 2), ))
Cerramos con un diagrama de pila de protocolos visual que muestra exactamente cómo AG-UI, A2UI, A2A y MCP encajan en la arquitectura agente moderna, desde la columna vertebral de LLM en la parte inferior hasta la interfaz de usuario nativa en la parte superior. Proporcionamos una tabla de referencia rápida que asigna cada concepto que creamos, transmisión de eventos, árboles de componentes, sincronización de estado, interfaz de usuario generativa, interrupciones, actualizaciones incrementales, enlace de datos y registros de widgets, con sus mecanismos principales. Señalamos el camino a seguir hacia la producción: servir eventos AG-UI a través de SSE real con FastAPI, conectarnos a los componentes CopilotKit React, usar AGUIAdapter de Pydantic AI e implementar en AWS Bedrock AgentCore.
En conclusión, tenemos un canal de UI Agentic completamente funcional que toma una consulta simple en lenguaje natural y la transforma en una interfaz estructurada e interactiva impulsada por un agente inteligente. No nos limitamos a ensamblar componentes; entendemos cómo opera y se conecta cada capa, desde la transmisión de eventos AG-UI en tiempo real y las definiciones de interfaz declarativa A2UI hasta la sincronización de estados a través de JSON Patch y mecanismos de seguridad humanos en el circuito aplicados. Esta claridad nos permite razonar sobre el comportamiento del sistema, depurar eficazmente y ampliar la funcionalidad sin depender de abstracciones de caja negra. Además, tenemos la capacidad de diseñar nuestros propios sistemas de interfaz de usuario controlados por agentes, adaptarlos a diferentes casos de uso y crear con confianza experiencias listas para producción donde los agentes y las interfaces evolucionan juntos de manera controlada, transparente y escalable.
Consulte los códigos completos con Notebook aquí. Además, no dude en seguirnos en Twitter y no olvide unirse a nuestro SubReddit de más de 130.000 ML y suscribirse a nuestro boletín. ¡Esperar! estas en telegrama? Ahora también puedes unirte a nosotros en Telegram.
¿Necesita asociarse con nosotros para promocionar su repositorio de GitHub O su página principal de Hugging O su lanzamiento de producto O seminario web, etc.? Conéctate con nosotros
La publicación Una inmersión profunda en la codificación de la interfaz de usuario agente, la interfaz de usuario generativa, la sincronización de estados y los flujos de aprobación basados en interrupciones apareció por primera vez en MarkTechPost.