AG-UI: Un protocolo ligero para la interacción entre agentes y usuarios

Por qué las aplicaciones agenticas necesitan AG-UI

Antes de ver el código, déjame explicarte por qué necesitábamos un nuevo protocolo en primer lugar. Todo se reduce a la diferencia fundamental entre una función y un agente.

La limitación de la solicitud/respuesta

En el desarrollo web tradicional, las interacciones son transaccionales. Solicitas un perfil de usuario y el servidor te lo envía. Es un intercambio único.

Sin embargo, los agentes son impredecibles y requieren tiempo. Cuando le pides a un agente que «depure por qué tu canalización de CI empezó a fallar repentinamente después de la fusión de un compañero de equipo», no devuelve un objeto JSON de inmediato. En cambio, podría:

1. Obtén los últimos 50 registros de confirmación de GitHub (Acción).
2. Observa que se ha añadido una nueva dependencia sin actualizar el archivo de bloqueo (Observación).
3. Compara la versión del paquete con las CVE conocidas (razonamiento).
4. Pregunta si deseas revertir la fusión o aplicarla (Human-in-the-loop).

Lo explicaré más adelante en la sección «Tipos de eventos», pero por ahora basta con saber que una solicitud HTTP estándar agotaría el tiempo de espera mientras se produce todo esto. Necesitas una forma de transmitir estas actualizaciones parciales para que el usuario no se quede mirando una pantalla congelada.

Las necesidades específicas de los agentes

Los agentes requieren un flujo bidireccional de información que va más allá del texto. Necesitan sincronizar el Estado.

Imagina que un agente te ayuda a redactar un informe. No es solo charlar, es editar un documento. Tanto tú como el agente pueden estar escribiendo al mismo tiempo. AG-UI gestiona esto tratando el «documento» como un estado compartido, utilizando actualizaciones eficientes para mantener tu pantalla y la memoria del agente sincronizadas sin sobrescribir el trabajo de cada uno.

Cómo se comunican los agentes y las interfaces de usuario

AG-UI sustituye el antiguo modelo de llamada a procedimiento remoto (RPC) por un modelo de origen de eventos. En lugar de esperar una respuesta definitiva, el agente envía un flujo constante de eventos que describen lo que está haciendo.

La transmisión del evento

Piensa en la transmisión AG-UI como un teletipo de noticias para el cerebro de tu agente. La aplicación cliente (tu interfaz) se suscribe a este ticker y actualiza la interfaz de usuario en función de lo que ve. Este enfoque desacopla la lógica: tu interfaz React no necesita saber cómo piensa el agente, solo necesita saber qué mostrar.

AG-UI evita el tiempo de espera. Imagen del autor.

Tipos de eventos principales

El protocolo define tipos de eventos estándar que cubren casi todos los escenarios de interacción. Aquí están los más importantes que verás:

1. TEXT_MESSAGE_*: Eventos que transmiten texto generado pieza por pieza. Esto suele implicar eventos _START, _CONTENT (el flujo de tokens) y _END, que juntos crean el conocido efecto de «escritura».

2. TOOL_CALL: Señales de que el agente quiere hacer algo, como consultar el tiempo o realizar una consulta en una base de datos. Fundamentalmente, AG-UI puede transmitir losargumentos de la llamada a la herramienta, lo que permite que la interfaz de usuario rellene previamente los formularios antes incluso de que el agente termine de «hablar».

3.  STATE_DELTA: Este es el gran impulsor de la colaboración. En lugar de reenviar todo el documento cada vez que cambia una letra, el agente envía una pequeña «diferencia» (como «añadir 'hola' en el índice 5»).

4. INTERRUPT: La válvula de seguridad. Si un agente realiza una acción sensible (como «Eliminar base de datos»), emite un evento de interrupción. El flujo se detiene hasta que el usuario envía un evento de aprobación.

Multimodalidad y pasos de razonamiento

El protocolo no se limita al texto. Admite multimodalidad, es decir, transmite imágenes, audio y archivos adjuntos junto con la conversación. También estandariza los pasos de pensamiento, separando los pensamientos internos del agente (rastros de razonamiento) de la respuesta pública final. Es posible que hayas observado un patrón similar al utilizar herramientas como chatGPT, en las que los indicadores de progreso o los pasos intermedios se muestran por separado de la respuesta final. Esto te permite decidir si mostrar a los usuarios el progreso de la ejecución o simplemente el resultado final.

Bloques de construcción AG-UI

Ahora que ya entiendes el flujo, veamos las características específicas que hacen que AG-UI sea tan potente para los programadores.

Interfaz de usuario generativa

El texto está muy bien, pero a veces un gráfico es mejor. La interfaz de usuario generativa permite que un agente decida en tiempo de ejecución que debe mostrarte un componente de la interfaz de usuario en lugar de texto.

AG-UI transmite eventos; A2UI define componentes. Imagen del autor.

Hay una distinción aquí que a menudo confunde a la gente (volveré a mencionarla en la sección sobre el marco): AG-UI es el mecanismo de entrega (capa de transporte), y A2UI (interfaz de agente a usuario) es la definición de la interfaz de usuario (carga útil). Un agente puede utilizar un evento AG-UI TOOL_CALL para transportar una carga útil A2UI, un árbol JSON declarativo que describe un componente de la interfaz de usuario (como una «tarjeta de cotización bursátil»). Tu interfaz recibe esto y genera el gráfico real.

Estado compartido con JSON Patch

Manejar el estado compartido es complicado. Si el agente envía un objeto de contexto masivo de 5 MB cada segundo, tu aplicación se ralentizará.

AG-UI resuelveeste problema con JSON Patch (RFC 6902). Comomencioné anteriormente con respecto a la sincronización de estado, cuando el agente cambia un valor en su memoria, calcula la diferencia y envía un eventoSTATE_DELTA.

[
  {
    "op": "replace",
    "path": "/user/status",
    "value": "active"
  }
]

El cliente recibe esta instrucción ligera y la aplica a su estado local. Esta eficiencia es lo que hace posible la colaboración en tiempo real con los agentes.

AG-UI en el panorama protocolario

Es posible que hayas oído hablar de otros protocolos como el MCP (Model Context Protocol). Es importante saber dónde encaja AG-UI en la pila para no utilizar la herramienta equivocada para el trabajo.

La pila agencial

Me gusta pensar en ello como un triángulo de comunicación:

1. MCP (Agente ↔ Herramientas): Esto conecta al agente con el mundo backend: bases de datos, repositorios GitHub y API internas. Se trata de obtener información.
2. A2A (Agente ↔ Agente): Esto permite a los agentes comunicarse entre ustedes y delegar tareas a subagentes.
3. AG-UI (Agente ↔ Usuario): Esta es la «última milla». Conecta la inteligencia del agente con el usuario humano.

El Protocolo Trinity conecta a los agentes. Imagen del autor.

A AG-UI no le importa cómo el agente obtuvo los datos (esa es la tarea de MCP, como mencioné anteriormente); solo le importa cómo mostrarte esos datos.

Implementación de AG-UI

Veamos cómo se ve esto en la práctica. Los programadores suelen interactuar con AG-UI de tres maneras: creando 1) aplicaciones agenticas (conectando una interfaz a un agente), creando 2) integraciones (haciendo que un marco sea compatible) o creando 3) clientes (creando nuevas interfaces). La mayoría de ustedes estarán en la primera categoría.

Explicaré el código en un momento, pero primero debes entender que normalmente no escribirás tú mismo los controladores de protocolo sin procesar. Las bibliotecas se encargan del empaquetado. Pero es necesario comprender el flujo para depurar.

Establecimiento del canal de eventos

La mayoría de las implementaciones utilizan eventos enviados por el servidor (SSE), ya que son sencillos, compatibles con los cortafuegos y perfectos para la transmisión unidireccional del servidor al cliente. Ya lo he insinuado anteriormente, pero SSE es la clave que hace que este protocolo sea tan ligero en comparación con WebSockets.

En una configuración típica (como con Microsoft Agent Framework o CopilotKit), tu servidor expone un punto final que actualiza la conexión a una transmisión.

Suscripción simple a eventos

Aquí tienes un ejemplo conceptual de cómo un cliente frontend escucha la transmisión. Observa cómo gestionamos diferentes tipos de eventos para actualizar la interfaz de usuario.

// Connect to the AG-UI stream
const eventSource = new EventSource('/api/agent/stream');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'TEXT_MESSAGE_CONTENT':
      // Append text to the chat window
      updateChatLog(data.content);
      break;

    case 'TOOL_CALL_START':
      // Show a "Processing..." indicator or the specific tool UI
      showToolIndicator(data.tool_name);
      break;

    case 'STATE_DELTA':
      // Apply the JSON patch to our local state store
      applyPatch(localState, data.patch);
      break;

    case 'INTERRUPT':
      // Prompt the user for permission
      showApprovalModal(data.message);
      break;
  }
};

Este patrón oculta la complejidad de la lógica interna del agente. Tu interfaz es solo un «reproductor» de los eventos que envía el agente.

Integraciones y compatibilidad con el ecosistema

No tienes que construir todo esto desde cero. El ecosistema está madurando rápidamente, y las principales plataformas y marcos convergen en patrones de interacción similares impulsados por eventos.

El «triángulo dorado» de las herramientas

Microsoft describe un «triángulo dorado» para el desarrollo de agentes:

1. DevUI: Para visualizar el proceso de pensamiento del agente (depuración).
2. OpenTelemetry: Para medir el rendimiento y el coste.
3. AG-UI: Para conectarse con el usuario.

Marcos compatibles

El ecosistema se está expandiendo rápidamente. Más allá de los principales actores, el apoyo está creciendo en todos los ámbitos:

1. Microsoft Agent Framework: Cuenta con middleware nativo para ASP.NET Core (Microsoft.Agents.AI.Hosting.AGUI).

2. CopilotKit: Actúa como el «navegador» para AG-UI, proporcionando una interfaz React completa que sabe cómo representar estos eventos de forma inmediata.

3. Ecosistema Python: Los marcoscomo LangGraph, CrewAI, Mastra, Pydantic AI, Agno y LlamaIndex pueden exponerse como puntos finales AG-UI.

4. SDKs: A pesar de quee TypeScript y Python son los lenguajes dominantes, hay SDK activos o en desarrollo para Kotlin, Go, Dart, Java yRust.

Fiabilidad, depuración y seguridad

Abrir una línea directa de comunicación entre una IA y un navegador conlleva riesgos. A continuación te explicamos cómo mantener tu aplicación segura.

El servidor frontend de confianza

Nunca permitas que un cliente se conecte directamente al tiempo de ejecución del agente sin procesar. Como he destacado en la sección «Por qué las aplicaciones agenticas necesitan AG-UI», utiliza siempre un servidor frontend de confianza (patrón BFF). Este servidor actúa como guardián. Añade autenticación, limitación de velocidad y validación de entradas antes de pasar el mensaje del usuario al agente.

Consideraciones de seguridad

Inyección inmediata

Los usuarios malintencionados podrían intentar anular las instrucciones de tu agentemediante ataques de inyección de comandos. Como mencionéanteriormente, tu middleware debe sanitizar las entradas.

Llamadas a herramientas no autorizadas

El hecho de que un agente pueda eliminar un archivo no significa que el usuario actual deba poder hacerlo. Tu servidor de confianza debe filtrar las herramientas disponibles para el agente en función de los permisos del usuario.

Seguridad del Estado

Dado que el estado se comparte a través de parches JSON, ten cuidado con la contaminación de prototipos. Asegúrate de que tu biblioteca de parches prohíba las modificaciones de propiedades protegidas como __proto__.

Depuración con Dojo

Si tu agente se comporta de forma extraña, utiliza AG-UI Dojo. Es un sitio de pruebaque te permite visualizar el flujo de eventos sin procesar. Te ayuda a detectar problemas como parches JSON malformados o llamadas a herramientas que se activan pero no devuelven resultados.

Conclusión

Hemos tratado la arquitectura, los tipos de eventos y los patrones de implementación de AG-UI.

Ahora bien, soy consciente de que, siendo realistas, el programador independiente medio o alguien que trabaje en una pequeña empresa no va a «adoptar AG-UI» y, de repente, «desacoplar tu frontend de tu backend». Todo esto requeriría importantes decisiones arquitectónicas, la aceptación de varios equipos y recursos que la mayoría de la gente no tiene.

Pero comprender AG-UI es importante incluso si no lo estás implementando. A la hora de evaluar marcos de trabajo para agentes o decidir si desarrollar una solución interna o utilizar una plataforma, saber cómo es una «buena» comunicación entre el agente y la interfaz de usuario te permite tomar una decisión más acertada. Reconocerás cuándo una herramienta te está obligando a seguir patrones rígidos.

Si deseas profundizar en la creación de estos sistemas, consulta nuestros cursos Introducción a los agentes de IA y Creación de sistemas agenticos escalables para llevar tus habilidades al siguiente nivel.