</> LBE Tech
← Todos los artículos
.NETAG-UIMicrosoft Agent FrameworkASP.NET CoreSeguridadBackend

AG-UI llega a .NET: guía de migración al protocolo 1.0

Migra un backend .NET a AG-UI 1.0: paquetes estables, hosting de Agent Framework aún prerelease, cambios de API y controles de seguridad.

28 de septiembre de 2026 · · 8 min de lectura
Puente luminoso que conecta un servidor .NET con una interfaz de agente mediante flujos de eventos y una ruta de migración

El anuncio de Microsoft sobre el SDK de AG-UI para .NET está fechado el 25 de septiembre de 2026. La publicación presenta la contribución del SDK, su integración con Microsoft.Extensions.AI y el camino de hosting para Microsoft Agent Framework.

La otra fecha clave es el 17 de septiembre de 2026. Ese día, la release oficial de AG-UI publicó en NuGet los cinco paquetes .NET en la versión 1.0.0, a las 18:54:29 UTC: AGUI.Abstractions, AGUI.Formatting, AGUI.Protobuf, AGUI.Client y AGUI.Server. La página de releases muestra después una entrada del 23 de septiembre, con paquetes de otros lenguajes. Por eso esta guía trata el protocolo y el hosting como dos ciclos de estabilidad distintos.

Protocolo estable, hosting en vista previa

Los paquetes AGUI.* son el SDK de protocolo. AGUI.Abstractions contiene los modelos, eventos, herramientas, interrupciones, estado y el serializador generado; AGUI.Formatting proporciona la abstracción de formato y SSE; AGUI.Protobuf es un codec opcional; AGUI.Client consume un endpoint y AGUI.Server produce eventos a partir de un IChatClient. La documentación de Microsoft señala que SSE es el transporte predeterminado y cubre todos los eventos, mientras protobuf es opt-in y cubre un subconjunto.

La release 1.0 congeló el esquema y cambió detalles que sí afectan a una migración: PROTOCOL_VERSION pasa a "1.0", los modelos adoptan los nombres del esquema 1.0, los nulos opcionales se omiten al serializar y los nulos de payload se conservan. AGUI.Client incluye la versión 1.0 en cada RunAgentInput y valida la versión anunciada por el productor. Que el flujo SSE siga conectando no demuestra que los modelos, snapshots o serializadores sean compatibles.

La integración de Agent Framework es otra capa. Microsoft.Agents.AI.Hosting.AGUI.AspNetCore conserva el pegamento de ASP.NET Core que convierte un AIAgent en un endpoint, pero la ficha de NuGet mantiene la versión 1.22.0-preview.260918.1 y la etiqueta prerelease. Microsoft Learn también muestra la instalación con --prerelease. Un proyecto puede usar el protocolo estable 1.0.0 y, por separado, evaluar el hosting de Agent Framework como preview.

Inventario de una migración

Antes de cambiar código, localiza referencias a Microsoft.Agents.AI.AGUI, los namespaces antiguos, AddAGUI, MapAGUI, constructores posicionales de AGUIChatClient y comparaciones manuales de la versión del protocolo. La nota de migración del repositorio de Agent Framework confirma que el paquete en árbol fue retirado; el repositorio conserva la integración de hosting y el protocolo vive en el SDK oficial.

El mapa de paquetes es deliberadamente granular:

  • Microsoft.Agents.AI.AGUI (cliente) pasa a AGUI.Client.
  • Sus adaptadores de servidor pasan a AGUI.Server.
  • Eventos, mensajes y herramientas pasan a AGUI.Abstractions.
  • AGUI.Protobuf solo se agrega si el transporte protobuf forma parte del diseño.
  • AGUI.Formatting contiene las ayudas de formato cuando se trabaja fuera del adaptador habitual.

Fija 1.0.0 en el proyecto o en Directory.Packages.props. Para el hosting prerelease, fija explícitamente la versión preview aprobada por tu equipo y conserva un rollback; no mezcles una actualización flotante del framework de agentes con el cambio del protocolo.

Servidor directo con IChatClient

El ejemplo publicado por Microsoft muestra que AGUI.Server puede exponer un IChatClient sin usar Agent Framework. Este fragmento sigue el quickstart oficial para una aplicación ASP.NET Core con TargetFramework net10.0 y una referencia a Microsoft.AspNetCore.App; no es un proyecto mínimo compilable por sí solo. Requiere AGUI.Server 1.0.0, las dependencias de Microsoft.Extensions.AI, un proveedor de modelo y una implementación propia de CreateChatClient() que devuelva un IChatClient configurado. La versión del paquete queda fijada en el proyecto:

dotnet add package AGUI.Server --version 1.0.0
using AGUI.Abstractions;
using AGUI.Server;
using Microsoft.AspNetCore.Http.Json;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.Options;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton(CreateChatClient());
builder.Services.Configure<JsonOptions>(options =>
    options.SerializerOptions.TypeInfoResolverChain.Insert(
        0, AGUIJsonUtilities.DefaultTypeInfoResolver));

var app = builder.Build();

app.MapPost("/", (
    RunAgentInput input,
    IChatClient chatClient,
    IOptions<JsonOptions> jsonOptions,
    CancellationToken cancellationToken) =>
{
    var context = input.ToChatRequestContext(
        jsonOptions.Value.SerializerOptions);

    var events = chatClient.GetStreamingResponseAsync(
        context.Messages,
        context.ChatOptions,
        cancellationToken).AsAGUIEventStreamAsync(context, cancellationToken);

    return TypedResults.ServerSentEvents(events);
});

await app.RunAsync();

El adaptador transforma RunAgentInput en mensajes y opciones de chat y vuelve a convertir el streaming en eventos AG-UI. En una aplicación real, sustituye la ruta raíz por una ruta específica, añade autenticación y autorización, y configura límites y observabilidad antes de exponerla.

Hosting con Agent Framework

Si el backend ya usa un AIAgent, la capa de hosting reduce el código de integración, pero mantiene el estado prerelease. En el fragmento siguiente, chatClient es una variable ya creada; el proyecto necesita además Microsoft.Agents.AI, un proveedor de modelo y la configuración de credenciales. El bloque es parcial y no constituye un proyecto compilable por sí solo:

dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore --version 1.22.0-preview.260918.1 --prerelease
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
using Microsoft.Extensions.AI;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAGUIServer();

var app = builder.Build();
var agent = chatClient.AsAIAgent(
    name: "AGUIAssistant",
    instructions: "You are a helpful assistant.");

app.MapAGUIServer("/ag-ui", agent);
await app.RunAsync();

El nombre AddAGUIServer()/MapAGUIServer() es parte de la migración; AddAGUI() y MapAGUI() ya no son los puntos de entrada documentados.

El .nuspec comprobado de Microsoft.Agents.AI.Hosting.AGUI.AspNetCore declara, para sus grupos net8.0, net9.0 y net10.0, mínimos AGUI.Abstractions >= 0.0.6 y AGUI.Server >= 0.0.6; no fija 1.0.0. Esos límites inferiores no permiten inferir que el preview sea compatible o incompatible con AGUI.* 1.0.0. Un restore exitoso tampoco demuestra compatibilidad wire o binaria con 1.0.0: hay que revisar conflictos y probar la matriz real. Si necesitas el protocolo estable 1.0.0, prueba el servidor directo AGUI.Server 1.0.0; si necesitas MapAGUIServer, fija el preview y documenta sus dependencias efectivas.

Para un cliente .NET, el constructor también cambia a opciones:

dotnet add package AGUI.Client --version 1.0.0
using AGUI.Client;

using var httpClient = new HttpClient();
var chatClient = new AGUIChatClient(
    new(httpClient, "http://localhost:5001"));

El endpoint remoto sigue siendo responsabilidad de quien lo hospeda. Configura HttpClient con el ciclo de vida y la autenticación de tu aplicación; no incrustes tokens en la URL ni los incluyas en eventos.

Compatibilidad que conviene probar

Una migración de 0.x a 1.0 debe probarse como cambio de contrato, no solo como restore exitoso. Conserva un caso sintético y compara cliente y servidor con las mismas versiones fijadas.

  1. Negociación: confirma que cada RunAgentInput declara 1.0 y que el cliente rechaza una versión de productor que no entiende.
  2. Texto y ciclo de vida: verifica RUN_STARTED, deltas de texto y RUN_FINISHED, incluido el cierre de bloques antes de pasar a una herramienta.
  3. Herramientas e interrupciones: prueba argumentos parciales, resultado de herramienta, aprobación humana, cancelación y error terminal.
  4. Estado y snapshots: compara deltas, snapshots y threadId en dos ejecuciones consecutivas; revisa especialmente campos opcionales ausentes frente a nulos de payload.
  5. Transporte: ejercita SSE con desconexión del cliente y, solo si se usa, protobuf; no asumas que ambos cubren el mismo conjunto de eventos.
  6. Interoperabilidad: añade al menos un cliente TypeScript o Python si el endpoint se consumirá fuera de .NET.

Guarda la versión de SDK, el commit del servicio, el payload mínimo y la salida de cada escenario para poder revertir una actualización.

Seguridad antes de publicar el endpoint

AG-UI normaliza eventos; no sustituye una frontera de confianza. El endpoint debe estar detrás de la autenticación y autorización de tu aplicación, con políticas de origen y protección contra abuso acordes con el cliente. Aplica límites de tamaño al cuerpo, duración y concurrencia de cada ejecución, y cancela el trabajo cuando el cliente abandone el stream. Los límites deben ser del servicio, no una suposición del codec SSE.

Trata threadId, mensajes, estado y argumentos de herramientas como entradas no confiables. Valida que el usuario autenticado puede leer y continuar ese hilo; no uses el identificador como autorización ni lo interpolas en rutas de almacenamiento sin validación. El estado que llega del cliente debe pasar por un esquema y una política de tamaño antes de combinarse con instrucciones del agente.

Las herramientas requieren una política aparte. Permite por defecto solo las necesarias, separa herramientas de lectura y de escritura, y exige aprobación humana para acciones irreversibles. No emitas secretos, tokens, mensajes de sistema, trazas internas ni datos de otros usuarios como eventos de texto o estado. Redacta logs y telemetría, y evita registrar el contenido completo de una conversación por defecto.

Por último, conserva la diferencia entre compatibilidad de wire y compatibilidad de API fuente. Un cliente puede seguir recibiendo SSE aunque un cambio de nombres, nulos o snapshots rompa una deserialización posterior. Versionar paquetes, validar PROTOCOL_VERSION, limitar el endpoint y probar la matriz de eventos son controles complementarios.

Decisión de despliegue

El resultado práctico es una migración en dos carriles. El primero es el SDK AG-UI 1.0.0, estable en NuGet y con cambios de esquema que deben revisarse. El segundo es el hosting de Agent Framework, todavía prerelease en la ficha consultada. Puedes adoptar el protocolo estable con un servidor propio basado en IChatClient y aplazar el hosting, o evaluar el preview de forma controlada, fijar su versión y mantener un rollback.

Fuentes primarias

También puede interesarte

Comentarios

Cargando…