AG-UI 1.0 a examen: 31 tipos de evento, 68 secuencias de conformidad y dos SDK oficiales que el corpus nunca alcanza

AG-UI 1.0 publica un esquema de 94.359 bytes y 68 secuencias de prueba. Su cliente TypeScript aprueba las 68; el .NET se desvía en 38 y Python no tiene cliente.

Casi todos los “protocolos abiertos” para agentes de IA son un README, un logo y un paquete de TypeScript que, por casualidad, habla con su propio servidor. AG-UI no es eso. Publica un esquema JSON de 94.359 bytes como contrato normativo, 219 documentos de prueba, 68 secuencias de eventos grabadas con expectativas legibles por máquina y un arnés que impide que el corpus encoja en silencio.

Eso lo vuelve auditable de una forma que casi nada en este espacio lo es. Así que lo audité: cloné el repositorio en main, instalé los paquetes publicados de npm y PyPI (no el código del monorepo) y pasé el corpus de conformidad del propio protocolo por un arnés de repetición que escribí contra el cliente distribuido. Después revisé justo las partes que el corpus dice no cubrir.

El resultado no es una demolición. El cliente de TypeScript aprobó las 68 secuencias. Lo interesante está en los bordes que el proyecto documenta en sus propios archivos — y uno de ellos es una violación de un MUST en un SDK que la especificación llama oficial.

Lo que AG-UI 1.0 trae de verdad

DatoValor
Repositorioag-ui-protocol/ag-ui, MIT, creado el 2025-05-07
Estrellas / watchers / forks18.970 / 102 (0,54%) / 1.964 (10,4%)
Issues abiertas591
Tipos de evento en el esquema 1.031, en ocho familias
Esquema94.359 bytes, 98 definiciones, $id = https://ag-ui.com/spec/1.0/schema.json
Secuencias de conformidad (1.0 / borrador)68 / 71
Documentos de prueba219 — 135 válidos, 84 inválidos
Código del arnés3.314 líneas en spec/harness/
Paquetes publicados@ag-ui/core 1.0.4 (2026-11-05), ag-ui-protocol 1.0.0 (17-09-2026, 18:31 UTC)
SDK que la especificación declara oficiales3 — TypeScript, Python y .NET
Carriles que el corpus ejecuta realmente2 — TypeScript y .NET

El esquema no es decorativo. https://ag-ui.com/spec/1.0/schema.json responde 200 con un prefijo sha256 de 4b5c93226838a0e7 y 94.359 bytes: idéntico byte a byte a spec/1.0/schema.json del repositorio. Su propia descripción fija la postura de diseño sin ambigüedad:

Objects are exact: this file defines what exists in this version of the protocol, so a property it does not declare fails validation.

Y la parte en prosa del documento dice cuál manda en cada terreno:

The schema is authoritative for structure. […] This document is authoritative for behaviour. Ordering, lifecycle, attribution, error handling, compatibility. The schema cannot express any of it. If an implementation disagrees with a rule here, the implementation has a bug.

Un protocolo que escribe esa frase invita exactamente a la prueba que hice.

Prueba uno: el cliente publicado contra su propio corpus

El carril de TypeScript del repositorio sirve cada secuencia grabada por HTTP real como tramas SSE dentro de un HttpAgent y luego evalúa el bloque de expectativas. Reconstruí ese bucle en Node puro contra @ag-ui/client@1.0.4 de npm — no contra el código del espacio de trabajo — con un http.createServer de cuarenta líneas sustituyendo al servidor simulado del proyecto:

const server = http.createServer((req, res) => {
  let raw = "";
  req.on("data", (c) => (raw += c));
  req.on("end", () => {
    requestBody = JSON.parse(raw);
    res.writeHead(200, { "content-type": "text/event-stream" });
    for (const ev of fixture.stream) res.write(`data: ${JSON.stringify(ev)}\n\n`);
    res.end();
  });
});
// los pares fijados instalan los shims de era; para eso está fixture.client.maxProtocolVersion
class FixtureAgent extends HttpAgent {
  get maxProtocolVersion() { return pinned ?? super.maxProtocolVersion; }
}

Después evalué las expectativas tal como las declara cada archivo: outcome, eventTypes en orden, eventPaths, eventAbsentPaths, avisos, messageCount, y messages/state/request con coincidencia por subconjunto.

Resultado: 68 de 68. No “casi todas”: todas, incluidas las que exigen que el cliente rechace una secuencia (first-tool-chunk-missing-name-fatal, run-finished-with-active-subagent-fatal), las que exigen que no se queje de una secuencia conforme (conformant-run-is-quiet) y las que fijan las rutas de degradación 0.0.39 y 0.0.57.

Dos detalles útiles para quien integre:

  • El cliente estampa protocolVersion: "1.0" en cada RunAgentInput. Capturé el cuerpo saliente: {"threadId":"…","runId":"…","protocolVersion":"1.0","state":{},"messages":[],"tools":[],"context":[],"forwardedProps":{}}. La página de versionado exige esa declaración, así que esta regla sí se cumple en la práctica.
  • @ag-ui/core@1.0.4 exporta 12 símbolos en tiempo de ejecución y no tiene dependencias. Son tipos, el enum EventType, PROTOCOL_VERSION y un par de ayudas: no trae validador. La validación vive en @ag-ui/client (zod). Si instalas “el core” esperando validar un documento contra el protocolo, no obtienes nada; el comportamiento de conformidad está en el paquete cliente.

Ese es el estado de la implementación de referencia hoy, y es mejor que la media. El resto del artículo trata de lo que el corpus no puede ver.

El corpus no tiene carril de Python, y lo dice

spec/1.0/conformance/README.md abre describiendo qué es la suite:

It is a regression suite for the first-party clients, and it asserts two different kinds of thing.

Y unas secciones más abajo, bajo «What does not belong here»:

Python. There is no Python client to hold to this.

La posición honesta dentro del repositorio es que el corpus cubre dos clientes. La posición pública es otra. La especificación publicada afirma:

AG-UI is maintained with three first-party SDKs — TypeScript, Python and .NET — and every rule here applies to all of them equally.

Ambas frases son ciertas en sus propios términos — Python no recibe carril porque no hay un cliente de Python que probar — pero no pueden ser toda la historia, porque un backend de agente en Python es la forma más común de usar este protocolo. pip install ag-ui-protocol es la vía documentada del lado servidor. Si el lado Python queda exento de conformidad de comportamiento por construcción, “every rule applies to all of them equally” habla de una ambición, no de una verificación.

Así que probé lo que el corpus no prueba: si los modelos del SDK de Python coinciden con el esquema en los 219 documentos que el esquema publica.

Veintidós documentos que el esquema rechaza, y qué hace Python con ellos

Método: para cada una de las 42 definiciones con pruebas, cargar fixtures/<Def>/{valid,invalid}/*.json, validar contra el ancla de esa definición en schema.json con un validador JSON Schema estándar para fijar la línea base, y luego alimentar el mismo documento al modelo pydantic correspondiente de ag-ui-protocol==1.0.0.

Primero la base: los 135 documentos válidos validan, los 84 inválidos se rechazan. El corpus es coherente consigo mismo.

Después el SDK:

ResultadoDocumentosProporción
Rechazado al parsear (coincide con el esquema)6274%
Aceptado y luego normalizado a un documento válido1417%
Aceptado y reemitido todavía inválido810%
Documentos que el esquema rechaza y el SDK acepta2226%

Cero falsos rechazos: todo documento que el esquema acepta, Python lo acepta. La brecha va en una sola dirección — Python es más permisivo que el contrato — en cuatro formas recurrentes:

  1. Un campo descrito que lleva null. metadata: null en TEXT_MESSAGE_CONTENT, rawEvent: null en TEXT_MESSAGE_END, code: null en SUBAGENT_ERROR, parentMessageId: null en TOOL_CALL_START. El esquema los declara string u objeto; un valor presente pero nulo lo falla. Pydantic lee str | None = None y elimina la clave al reemitir.
  2. Un discriminador requerido ausente. REASONING_MESSAGE_START sin role es rechazado por el esquema y aceptado por el SDK, que rellena el valor por defecto del Literal.
  3. Un miembro de unión con una clave de otro miembro. {"type":"interrupt","interrupts":[…],"pendingToolCallIds":[…]} en RUN_FINISHED. Los objetos del esquema están cerrados por miembro; extra="allow" conserva la clave intrusa y la vuelve a poner en el cable.
  4. Propiedades desconocidas. {"type":"TEXT_MESSAGE_END","messageId":"msg_1","somethingNewer":true} se reemite intacto, igual que la clave retirada subAgents y un campo FileSource.reference que el esquema no define.

Las formas 3 y 4 son las que salen del proceso. Mete un documento inválido, vuelca el modelo, valida otra vez: ocho documentos salen todavía inválidos.

El MUST que esto rompe, en palabras de la especificación

La página del modelo de procesamiento es inusualmente directa para un documento de protocolo:

Unrecognised material is not an error. A malformed known value is.

  • A property that is not described on an event MUST NOT abort the run.
  • A field the protocol DOES describe, carrying a value the schema rejects, MUST be fatal: the consumer MUST fail the run rather than repair, coerce or ignore the value.

Las formas 1 y 2 son exactamente la segunda regla: metadata: null es un campo descrito con un valor que el esquema rechaza, y el trabajo de pydantic es coercionar e ignorar. El propio modelo base generado del SDK de Python lo admite:

Coercion is pydantic’s default: the strict contract is the specification’s validation corpus, not this class.

Esa frase es honesta y, leída contra el MUST de arriba, también es una confesión. Se genera desde spec/generator/python.ts, así que es una decisión de nivel de protocolo y no un descuido: los modelos son deliberadamente una superficie de parseo permisiva y el corpus se declara el contrato estricto. En TypeScript esa división funciona — el cliente aplica y el corpus lo demuestra. En Python el corpus no está conectado al SDK, así que la mitad estricta existe como archivos JSON que nadie ejecuta contra el paquete que se instala desde PyPI.

Mientras tanto, el material desconocido sí sobrevive en Python, sin ningún aviso: busqué cualquier mecanismo de advertencia en el paquete instalado y no encontré ninguno fuera de capabilities.py. Es la otra mitad de una incoherencia interna en la prosa del protocolo:

  • El README del propio spec/1.0/schema.json: un límite de SDK tolera campos que no reconoce — stripping them with a warning en lugar de rechazar la secuencia.
  • La página del modelo de procesamiento: unrecognised material survives.

Descartar con aviso y sobrevivir en silencio son comportamientos distintos. El cliente de TypeScript hace lo primero (unknown-property-stripped y open-metadata-preserved pasan). Los modelos de Python hacen lo segundo. Los dos pueden citar una frase de la especificación.

Prueba dos: el carril .NET existe, pero no con las mismas reglas

.NET es el tercer SDK oficial y el único segundo carril del corpus. No aprueba el corpus como TypeScript: aprueba su propia versión del corpus.

38 de las 68 secuencias — 56% — llevan un bloque expectOverrides.dotnet que sustituye la aserción de ese carril. Las claves sobrescritas, contadas:

Expectativa sobrescritaSecuencias
messages19
messageCount15
errorContains11
outcome10
warnings9
eventTypes9
noWarnings8
eventPaths5
request4
eventAbsentPaths2
eventTypesAbsent1
requestAbsentPaths1

El formato de sobrescritura exige un motivo escrito, y esos motivos son la documentación más útil del repositorio. Muchos son diferencias legítimas de plataforma: .NET arma el historial con Microsoft.Extensions.AI, no guarda estado y no tiene reductor de actividad. Pero nueve no son diferencias. Están etiquetados, en palabras del proyecto:

GAP, not a design difference: EventStreamConverter has no case for TEXT_MESSAGE_CHUNK or TOOL_CALL_CHUNK, so a chunk stream falls through to the pass-through branch. Nothing is expanded into a message and none of the chunk-stream rules are enforced. Pinned here so the gap cannot widen or close unnoticed; alignment tracked separately.

Nueve secuencias — toda la familia de streams por trozos — afirman lo contrario de la regla en el carril .NET, porque el conversor de .NET nunca implementó la expansión de trozos. Las consecuencias están escritas prueba por prueba: first-chunk-missing-id-fatal dice “the stream is accepted instead of rejected”; chunk-expansion-assembles dice “the two chunks assemble into nothing at all”.

Hay una segunda versión estructural del mismo problema en el generador. spec/generator/dotnet-models.ts escribe clases C# desde el esquema, pero la lista de clases se mantiene a mano, y el archivo dice qué cuesta eso:

the class list below is written by hand, so a definition the schema gains and nobody adds to it is simply absent from .NET — while TypeScript and Python emit it, and the drift gate, which compares the generator only against its own output, stays green.

La protección contra eso es un conjunto NOT_IN_DOTNET escrito a mano con siete entradas, todas operaciones JSON Patch, cada una con su motivo. La deriva se detecta solo donde alguien se acordó de enumerarla, y la puerta que debería detectar el resto compara el generador consigo mismo, no con el esquema.

Tres documentos, dos respuestas sobre quién mantiene .NET

Esta es la parte que importa más que cualquier detalle de ingeniería, porque decide qué puedes esperar que se arregle.

DocumentoQué dice de .NET
Especificación publicadaUno de “three first-party SDKs”, donde “every rule here applies to all of them equally”
Tabla de SDK en docs/introduction.mdxEstado: Supported. Integraciones: Community
CONTRIBUTING.md“All community integrations (ie, .NET, Golang SDK, etc.) will need to be maintained by the community member who made the contribution.”
Estructura de carpetassdks/dotnet — no sdks/community/dotnet
Corpus de conformidadUn carril propio, descrito como de “the first-party clients”

El mismo paquete es oficial cuando la especificación necesita reclamar uniformidad y comunitario cuando alguien pregunta quién lo arregla. No es una conspiración: es lo que pasa cuando un proyecto hace crecer una especificación formal más rápido que su gobernanza. Pero para quien adopta tiene una consecuencia concreta: el SDK con el 56% de sus aserciones sobrescritas es el que no tiene obligación de mantenimiento declarada. Si construyes sobre .NET, tú eres el mantenedor de tu conformidad.

La afirmación que esperaba romper, y no rompí

spec/RECONCILIATION.md abre con un número que parece una errata:

0 fields where TypeScript and Python disagree with the schema about required-ness.

Intenté falsificarlo. Comparar el array required de cada definición con is_required() de pydantic en 75 definiciones da 53 desacuerdos, que parece un hallazgo limpio hasta leer la advertencia del propio documento: un discriminador fijo escrito Literal[X] = X siempre se serializa, así que llamarlo opcional “sería la misma afirmación falsa”. Aplicando esa regla desaparecen 51 de los 53; los dos que quedan están en RunAgentInput, y el documento los nombra él mismo (tools y context figuran como opcionales porque el esquema les da valores por defecto).

Recalculado con el método declarado: 0. El número se sostiene. Un proyecto que publica una tabla de reconciliación y acierta merece el crédito, y es la razón por la que me creí el resto de sus huecos autoinformados.

Qué se movió de verdad entre 1.0 y el borrador

El esquema se describe como “stable, frozen” en 1.0, con un borrador por delante. Comparando spec/1.0/schema.json con el spec/draft/schema.json servido:

  • 98 definiciones en ambos; ninguna añadida ni eliminada.
  • 6 definiciones cambiadas, y cada cambio es una propiedad opcional añadida.
  • Nuevas: encryptedValueType en BaseMessage, ReasoningMessage, ToolCall, ToolMessage, ReasoningEncryptedValueEvent; y error en ToolCallResultEvent.
  • Unión de eventos: 31 en ambos.

Es una velocidad de evolución genuinamente conservadora para una ventana de dos meses, y el mejor argumento a favor del protocolo: la superficie contra la que integras hoy no se reescribe debajo de ti. El corpus creció de 68 a 71 secuencias en el mismo periodo.

Salud del repositorio, sin adornos

18.970 estrellas con 102 watchers es una tasa de seguimiento del 0,54%: la gente lo guarda en marcadores, no lo sigue. El “Show HN” que lo lanzó el 2025-05-13 sumó 36 puntos y 5 comentarios. Los forks son el 10,4% de las estrellas, normal para algo que se integra en lugar de bifurcarse.

La concentración de commits es la otra señal. GitHub informa 182 contribuidores; entre los cien primeros, ranst91 acumula 1.282 de 5.077 commits (25,3%), con contextablemark en 735 y mme en 724. ranst91 es Atai Barkai, CEO de CopilotKit, y mme es el autor del SDK de Python. El protocolo es MIT y vive en su propia organización de GitHub, pero su centro de gravedad es una empresa, cuyo producto además es el cliente de producción recomendado. No es una crítica: es la misma estructura que React y Meta, y es lo que hay que descontar al decidir cuánta arquitectura cuelgas de él.

Lo que el protocolo hace bien, y merece copiarse

Tres cosas aquí son mejores que la media y no cuestan nada de imitar:

  1. El esquema responde en su propio $id. https://ag-ui.com/spec/1.0/schema.json sirve exactamente los bytes que el repositorio confirma, así que un validador puede apuntar a la especificación y no a una copia que se desfasa.
  2. El corpus está fijado dos veces. streams/MANIFEST.txt contrasta el listado del directorio en ambas direcciones, y cada prueba debe declarar un kill: “the single-line change to the implementation that must make this fail.” Una prueba que no puede fallar es peor que ninguna, y esta es la única suite que lo dice en el propio formato.
  3. Las deprecaciones tienen fecha de caducidad y registro. DEPRECATIONS.md anota cada forma retirada, su reemplazo, el shim que la atiende y una fecha a doce meses. Verifiqué la afirmación del lanzamiento: npm publicó 1.0.0 el 17-09-2026 a las 18:27:36 UTC y PyPI a las 18:31:18 — cuatro minutos de diferencia, que es como debe verse un “publicado a la vez”.

Preguntas frecuentes

¿AG-UI es un protocolo real o un envoltorio de proveedor? Real, en el sentido que importa: un JSON Schema normativo servido en su $id, 68 secuencias grabadas con expectativas escritas y un cliente que las pasa. También es un proyecto centrado en CopilotKit: la sección de alcance de la especificación, el cliente de producción recomendado y el 25% de los commits del top-100 apuntan ahí. Los dos hechos son ciertos y ninguno anula al otro.

¿El cliente de TypeScript cumple de verdad? En mi repetición de las 68 secuencias contra @ag-ui/client@1.0.4 de npm, sí: todas las aserciones, incluidos los descartes, los avisos y los casos fatales. No compilé ni ejecuté el carril .NET (no hay dotnet en este entorno), así que sus 38 sobrescrituras se leen de las pruebas, no se observan.

¿Por qué Python acepta 22 documentos que el esquema rechaza? Porque el modelo base pydantic generado usa extra="allow" y confía en la coerción de pydantic — de forma deliberada, y declarada en el docstring generado. El contrato estricto es el corpus JSON, que no se ejecuta contra el paquete de Python. Si necesitas rigor del lado productor en Python, valida con el esquema antes de codificar.

¿pip install ag-ui-protocol me da un cliente? No. El paquete 1.0.0 contiene core, encoder y _generated: modelos de evento, un codificador y tipos. No hay runtime de agente ni cliente, y el README del corpus dice sin rodeos que no hay cliente de Python al que exigirle. El agente de 30 líneas del README es FastAPI más este codificador.

¿Dónde fijo las versiones? @ag-ui/client y @ag-ui/core en 1.0.4, ag-ui-protocol en 1.0.0, y trata 1.0.1–1.0.4 como parches del protocolo: maxProtocolVersion del cliente devuelve 1.0.4 mientras la declaración del cable es 1.0. Consume protocolVersion de la secuencia y no infieras capacidades del número de parche.

¿Debería adoptarlo? Si vas a construir una interfaz de agente y pensabas inventar tu propia secuencia de eventos, usa esta: 31 tipos de evento, un esquema contra el que validar y un cliente de referencia real. Si construyes un backend solo en Python que habla con un frontend JS, úsalo y mantén el esquema en tu suite de pruebas, porque nada más en la pila va a detectar un evento no conforme antes que tus usuarios.

Qué verificar por tu cuenta antes de adoptarlo

  1. Valida tus propios productores contra el esquema, en CI, no contra el SDK. jsonschema o zod, el archivo de 94.359 bytes y un trabajo que falle al rechazo. Los modelos de Python no lo harán por ti.
  2. Pasa el corpus por el cliente que vayas a distribuir. Las pruebas son JSON plano con expectativas declarativas; el arnés son cien líneas, como el de arriba. El repositorio dice que nada hace esto por clientes de terceros.
  3. Si distribuyes .NET, lee primero las 38 sobrescrituras. Son la especificación de lo que ese cliente no hace — sobre todo la expansión de trozos.
  4. Fija un protocolVersion y comprueba lo que recibes. El cliente envía 1.0; haz que tu agente lo verifique en vez de suponerlo.
  5. Trata las llamadas a herramientas como entrada no confiable dos veces. La especificación dice que el protocolo “cannot enforce” el consentimiento, la validación y el aislamiento del renderizado, y tiene razón: son obligaciones tuyas, y son las que deciden si una inyección de prompt se convierte en una acción.
  6. Lee RECONCILIATION.md antes de escribir tu propia capa de compatibilidad. Es el único lugar que admite dónde se desfasan los SDK y el esquema, y es exacto.

Conclusión

AG-UI 1.0 es el protocolo de agentes más verificable publicado hasta ahora, y su verificabilidad no es marketing: el esquema es idéntico byte a byte a lo que confirma el repositorio, el cliente de TypeScript publicado pasa las 68 secuencias del propio proyecto y la tabla de reconciliación resiste un intento de falsificación.

Las brechas son igual de concretas. El corpus prueba dos clientes de los tres que la especificación llama oficiales, y ningún verificador en este espacio puede ver la secuencia de un productor Python antes de que salga del proceso. El cliente .NET se desvía en el 56% del corpus — nueve por admisión propia de una función ausente — y tres documentos distintos no se ponen de acuerdo sobre si ese cliente es oficial. Si este año eliges un protocolo de eventos, elige este, con el esquema en tu suite de pruebas y con una respuesta clara a la pregunta de quién mantiene el SDK que no estás usando.

Lecturas relacionadas: la auditoría del SDK de MCP para TypeScript aplica el mismo método de medir el paquete a otro protocolo, la guía del protocolo A2A explica cómo se compara la capa agente-a-agente, y el stack de agentes de frontend de CopilotKit — el proveedor detrás de AG-UI — muestra qué hay encima de esta capa.