DEV Community: Isaac Ojeda

EF Core: La explosión cartesiana — Hiciste todo bien y aun así el query es un desastre

Isaac Ojeda — Wed, 13 May 2026 00:16:55 +0000

En el artículo anterior vimos el problema N+1: queries dentro de loops que se multiplican con los datos. La solución que aprendiste fue usar Include para cargar las relaciones en una sola query.

Eso es correcto. Hasta que tienes más de una colección relacionada en el mismo nivel.

El escenario: un Include razonable que se vuelve un problema

Tienes pedidos. Cada pedido tiene un cliente, una lista de productos y una lista de pagos. Quieres cargar todo en una sola operación para evitar el N+1:

var pedidos = await context.Pedidos
    .Include(p => p.Cliente)
    .Include(p => p.Productos)
    .Include(p => p.Pagos)
    .Where(p => p.FechaCreacion >= hace30Dias)
    .ToListAsync();

Tres Include. Se ve limpio, se ve correcto. EF Core lo acepta sin quejarse.

Pero el SQL que genera no es lo que imaginas.

Lo que EF Core hace por debajo

El problema aparece específicamente cuando incluyes múltiples colecciones “hermanas” en el mismo nivel del grafo de navegación. Es importante distinguirlo de ThenInclude, que normalmente no genera este problema:

// Caso problemático: dos colecciones en el mismo nivel
.Include(p => p.Productos)
.Include(p => p.Pagos)

// Normalmente no problemático: navegación en profundidad
.Include(p => p.Productos)
    .ThenInclude(pr => pr.Categoria)

Cuando EF Core genera un JOIN para cada colección hermana, el resultado no produce una fila por pedido — produce una fila por cada combinación posible entre los registros relacionados.

Si un pedido tiene 5 productos y 3 pagos, el resultado del JOIN tiene 15 filas para ese pedido. EF Core las lee todas y reconstruye el objeto en memoria, pero la base de datos procesó y transfirió 15 filas donde conceptualmente había 1.

El crecimiento es cartesiano: cada colección multiplica las filas del resultado. Con 100 pedidos, cada uno con 10 productos y 5 pagos, el resultado no son 100 filas — son 5,000 filas que viajan de la base de datos a tu servidor para que EF Core las reduzca de vuelta a 100 objetos.

Eso es la explosión cartesiana.

Cómo detectarlo

El warning de EF Core

Cuando EF Core detecta este patrón, emite un warning en los logs:

Compiling a query which loads related collections for more than
one collection navigation, either via 'Include' or through
projection. Please review the generated SQL and inspect whether
the cartesian explosion might negatively impact performance.

Si ves este mensaje en tus logs y lo ignoraste, es probable que ya tengas este problema en alguna query.

Los tiempos que no tienen proporción

Con los logs habilitados:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(connectionString)
           .LogTo(Console.WriteLine, LogLevel.Information));

Verás algo así:

Executed DbCommand (847ms) [Parameters=[@p0='2025-02-14'], CommandType='Text', CommandTimeout='30']
SELECT p.Id, p.Total, ...
FROM Pedidos p
LEFT JOIN Clientes c ...
LEFT JOIN PedidoProductos pr ...
LEFT JOIN Pagos pa ...
WHERE p.FechaCreacion >= @p0

Una sola query, pero 847ms. Con pocos datos en dev tal vez son 12ms y nadie lo cuestiona. Con datos reales de producción el tiempo empieza a crecer de forma que no tiene proporción con el número de registros que devuelve el endpoint.

A diferencia del N+1, aquí solo hay una query. Si solo cuentas queries, todo parece correcto. Lo que tienes que mirar es cuántas filas devuelve esa query.

La solución: AsSplitQuery

EF Core 5 introdujo AsSplitQuery precisamente para este caso. En lugar de un solo JOIN que produce el producto cartesiano, EF Core ejecuta una query separada por cada Include y ensambla los resultados en memoria:

var pedidos = await context.Pedidos
    .Include(p => p.Cliente)
    .Include(p => p.Productos)
    .Include(p => p.Pagos)
    .Where(p => p.FechaCreacion >= hace30Dias)
    .AsSplitQuery()
    .ToListAsync();

Las queries que se ejecutan ahora:

-- Query 1: los pedidos con el cliente
SELECT p.Id, p.Total, p.FechaCreacion, c.Id, c.Nombre
FROM Pedidos p
LEFT JOIN Clientes c ON p.ClienteId = c.Id
WHERE p.FechaCreacion >= '2025-02-14'

-- Query 2: los productos de esos pedidos
SELECT pr.Id, pr.Nombre, pr.Precio, pr.PedidoId
FROM PedidoProductos pr
WHERE pr.PedidoId IN (1, 2, 3, ...)

-- Query 3: los pagos de esos pedidos
SELECT pa.Id, pa.Monto, pa.FechaPago, pa.PedidoId
FROM Pagos pa
WHERE pa.PedidoId IN (1, 2, 3, ...)

Tres queries en lugar de una, pero cada una devuelve exactamente las filas que necesita. Sin producto cartesiano, sin filas duplicadas.

AsSplitQuery no es siempre la respuesta

Vale la pena entender cuándo usarlo y cuándo no:

Úsalo cuando:

Tienes múltiples Include de colecciones hermanas
Los tiempos de query son desproporcionados respecto al número de registros que devuelves
El warning de EF Core aparece en tus logs

No lo uses cuando:

Solo tienes un Include — el producto cartesiano no ocurre con una sola colección
Necesitas consistencia transaccional estricta — las queries de AsSplitQuery se ejecutan por separado y en teoría otro proceso podría modificar datos entre una y otra
El conjunto de datos es pequeño — el overhead de múltiples queries puede ser mayor que el beneficio

Una advertencia sobre paginación: si usas AsSplitQuery junto con Skip/Take, asegúrate de tener un OrderBy estable y con un campo único. Sin eso, los resultados entre las queries separadas pueden ser inconsistentes.

El Include que no hace nada

Antes de cerrar, vale la pena mencionar un hábito relacionado que ocurre con frecuencia.

Muchos developers agregan Include de forma defensiva — para asegurarse de que las propiedades de navegación no sean null. Tiene sentido cuando materializas la entidad completa. Pero cuando proyectas a un DTO con Select, EF Core ignora completamente los Include:

// ❌ Los Include son ignorados — EF Core no materializa Pedido
var pedidos = await context.Pedidos
    .Include(p => p.Cliente)      // ignorado
    .Include(p => p.Productos)    // ignorado
    .Include(p => p.Pagos)        // ignorado
    .Where(p => p.FechaCreacion >= hace30Dias)
    .Select(p => new PedidoDetalleDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total,
        Productos = p.Productos.Select(pr => pr.Nombre).ToList(),
        TotalPagado = p.Pagos.Sum(pa => pa.Monto)
    })
    .ToListAsync();

EF Core resuelve los JOINs necesarios directamente desde la proyección del Select. Los Include no aportan nada — ni errores, ni beneficios, ni SQL adicional. Lo mismo aplica para AsSplitQuery: si proyectas a un DTO, no hay entidades que materializar, así que tampoco tiene efecto.

El código funciona igual con o sin ellos. El problema es que quien lo lee después asume que son necesarios, y esa confusión se acumula.

La proyección con Select como alternativa

Cuando no necesitas materializar la entidad completa, la proyección con Select puede ser más eficiente que AsSplitQuery. En muchos casos permite a EF Core generar SQL mucho más eficiente y evitar la materialización completa de relaciones:

// ✅ Sin Include, sin AsSplitQuery
var pedidos = await context.Pedidos
    .Where(p => p.FechaCreacion >= hace30Dias)
    .Select(p => new PedidoDetalleDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total,
        Productos = p.Productos.Select(pr => pr.Nombre).ToList(),
        TotalPagado = p.Pagos.Sum(pa => pa.Monto)
    })
    .ToListAsync();

La regla general: usa Include cuando materialices la entidad. Usa Select cuando trabajes con DTOs.

Resumen

Problema	Síntoma	Solución
`ToList()` prematuro	`SELECT *` sin `WHERE`, todo en memoria	Mantener `IQueryable` hasta el final
`SELECT *` silencioso	Proyección ignorada, columnas de más	Expresiones traducibles en `Select`
N+1	Una query por cada registro del loop	`Include` o proyección con `Select`
Explosión cartesiana	Una query lenta con filas multiplicadas	`AsSplitQuery` o proyección con `Select`

Si no ves el SQL que EF Core genera, no sabes lo que está pasando. Los logs son la herramienta más simple y más ignorada para detectar estos problemas antes de que lleguen a producción.

¿Has tenido que resolver una explosión cartesiana en producción? ¿Cómo lo detectaste? Cuéntame en los comentarios.

¿Qué sigue?

En el próximo artículo vamos a hablar de algo que EF Core hace en todas tus consultas sin que lo hayas pedido: rastrear cada entidad que lees para detectar cambios. En pantallas de solo lectura estás pagando ese costo en memoria y CPU sin obtener nada a cambio — y con suficientes datos, se nota.

EF Core: N+1 — Una query en dev, mil queries en producción

Isaac Ojeda — Fri, 08 May 2026 18:33:09 +0000

En el artículo anterior vimos cómo EF Core puede traer más datos de los necesarios sin avisar: un ToList() prematuro que consulta toda la tabla, o un Select con expresiones no traducibles que termina haciendo SELECT * en silencio.

Este problema es diferente. No es que una query traiga demasiado, es que una operación que debería ser una sola query termina convirtiéndose en cientos o miles.

Y lo más difícil: en desarrollo nadie lo nota.

Por qué es el más traicionero de los tres

El ToList() prematuro y el SELECT * silencioso tienen algo en común: el daño es proporcional al tamaño de la tabla. Con pocos datos, el impacto es menor, pero el problema ya existe desde el primer día.

El N+1 es diferente.

Con 10 pedidos en la base de datos, hace 11 queries. Nadie lo siente. Con 10,000 pedidos, hace 10,001 queries por cada carga de pantalla. La base de datos empieza a ahogarse, los tiempos se disparan y el equipo no entiende qué cambió — porque el código lleva meses igual.

Es un problema que crece silenciosamente junto con el negocio.

Y el verdadero costo no es solo “más SQL”. Cada query implica:

un roundtrip a la base de datos
parsing y compilación del comando
ejecución
transferencia de datos
sincronización de conexiones
presión sobre el connection pool

Mil queries pequeñas suelen ser muchísimo más costosas que una sola query grande.

Cómo ocurre en EF Core

Si vienes de EF6 o de otros ORMs con lazy loading habilitado por default, el N+1 clásico era acceder a una propiedad de navegación dentro de un loop y que el ORM disparara una query automáticamente por debajo, sin que el código lo hiciera explícito.

En EF Core el lazy loading está deshabilitado por default. Si intentas acceder a una propiedad de navegación que no fue cargada, obtienes null, no una query silenciosa.

Eso es mejor, pero el problema sigue ocurriendo — ahora de forma explícita.

El N+1 en EF Core se ve así:

var pedidos = await context.Pedidos
    .Where(p => p.FechaCreacion >= hace30Dias)
    .ToListAsync(); // Query 1: trae los pedidos

foreach (var pedido in pedidos)
{
    // Query 2..N: una por cada pedido
    var cliente = await context.Clientes
        .FirstOrDefaultAsync(c => c.Id == pedido.ClienteId);

    Console.WriteLine($"{cliente.Nombre} - {pedido.Total}");
}

El SQL que se ejecuta:

-- Query 1
SELECT p.Id, p.ClienteId, p.Total, p.FechaCreacion
FROM Pedidos
WHERE p.FechaCreacion >= '2025-02-14'

-- Query 2
SELECT TOP(1) * FROM Clientes WHERE Id = 1

-- Query 3
SELECT TOP(1) * FROM Clientes WHERE Id = 2

-- ... y así por cada pedido en el resultado

Con 500 pedidos en el rango de fechas: 501 queries.

Con 5,000 pedidos: 5,001.

La variante que se escapa en code review

El ejemplo anterior es fácil de detectar porque la query adicional es visible dentro del loop.

Pero en proyectos reales el problema suele esconderse detrás de servicios aparentemente inocentes:

var pedidos = await context.Pedidos
    .Where(p => p.FechaCreacion >= hace30Dias)
    .ToListAsync();

foreach (var pedido in pedidos)
{
    // Parece una llamada inocente a un servicio
    var dto = await _pedidoService.EnriquecerAsync(pedido);

    resultado.Add(dto);
}

Y dentro del servicio:

public async Task<PedidoDto> EnriquecerAsync(Pedido pedido)
{
    var cliente = await context.Clientes
        .FirstOrDefaultAsync(c => c.Id == pedido.ClienteId);

    var ultimaFactura = await context.Facturas
        .Where(f => f.ClienteId == pedido.ClienteId)
        .OrderByDescending(f => f.FechaEmision)
        .FirstOrDefaultAsync();

    return new PedidoDto
    {
        Cliente = cliente.Nombre,
        Total = pedido.Total,
        UltimaFactura = ultimaFactura?.Folio
    };
}

Aquí el loop ejecuta 2 queries por pedido en lugar de 1.

Con 500 pedidos: 1,001 queries.

Y el problema es mucho más difícil de detectar porque el foreach se ve completamente razonable. El costo real está escondido en otro archivo, detrás de capas de abstracción.

Este tipo de N+1 suele sobrevivir code reviews durante meses.

Cómo detectarlo

La misma herramienta del artículo anterior: los logs de EF Core.

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(connectionString)
           .LogTo(Console.WriteLine, LogLevel.Information));

Con el N+1 activo, verás algo así en la consola:

Executed DbCommand (2ms) SELECT ... FROM Pedidos WHERE ...
Executed DbCommand (1ms) SELECT TOP(1) ... FROM Clientes WHERE Id = 1
Executed DbCommand (1ms) SELECT TOP(1) ... FROM Clientes WHERE Id = 2
Executed DbCommand (1ms) SELECT TOP(1) ... FROM Clientes WHERE Id = 3
Executed DbCommand (1ms) SELECT TOP(1) ... FROM Clientes WHERE Id = 4
...

Si ves el mismo patrón de query repitiéndose con diferentes parámetros, tienes un N+1.

Una señal todavía más rápida:

si el número de queries crece proporcionalmente al número de registros que devuelve la primera query, casi siempre es N+1.

Las soluciones

`Include` — cuando necesitas la entidad completa

var pedidos = await context.Pedidos
    .Include(p => p.Cliente)
    .Where(p => p.FechaCreacion >= hace30Dias)
    .ToListAsync();

foreach (var pedido in pedidos)
{
    // Cliente ya está cargado, sin queries adicionales
    Console.WriteLine($"{pedido.Cliente.Nombre} - {pedido.Total}");
}

EF Core genera un JOIN y trae todo en una sola query:

SELECT p.Id, p.Total, p.FechaCreacion, c.Id, c.Nombre, c.RFC ...
FROM Pedidos p
LEFT JOIN Clientes c ON p.ClienteId = c.Id
WHERE p.FechaCreacion >= '2025-02-14'

Esto resuelve el N+1 porque elimina las queries repetidas.

Funciona bien cuando realmente necesitas la entidad Cliente completa. Si solo necesitas el nombre, estás trayendo columnas de más.

Y cuidado: usar múltiples Include sobre colecciones puede llevar a otro problema distinto — explosión cartesiana. Lo veremos en el siguiente artículo.

Proyección con `Select` — la más eficiente para DTOs

var pedidos = await context.Pedidos
    .Where(p => p.FechaCreacion >= hace30Dias)
    .Select(p => new PedidoResumenDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total
    })
    .ToListAsync();

EF Core resuelve el JOIN automáticamente a partir de la proyección, sin necesidad de Include.

El SQL resultante solo trae las columnas necesarias:

SELECT c.Nombre, p.Total
FROM Pedidos p
LEFT JOIN Clientes c ON p.ClienteId = c.Id
WHERE p.FechaCreacion >= '2025-02-14'

Esta suele ser la mejor solución cuando trabajas con DTOs:

una sola query
solo las columnas necesarias
sin entidades adicionales en memoria

Cuando el enriquecimiento es inevitable

A veces el servicio que enriquece los datos tiene lógica compleja que no puedes mover fácilmente a una proyección SQL.

En ese caso, la alternativa es cargar todo lo necesario antes del loop:

var pedidos = await context.Pedidos
    .Where(p => p.FechaCreacion >= hace30Dias)
    .ToListAsync();

var clienteIds = pedidos
    .Select(p => p.ClienteId)
    .Distinct()
    .ToList();

// Una sola query para todos los clientes necesarios
var clientes = await context.Clientes
    .Where(c => clienteIds.Contains(c.Id))
    .ToDictionaryAsync(c => c.Id);

foreach (var pedido in pedidos)
{
    var cliente = clientes[pedido.ClienteId];

    Console.WriteLine($"{cliente.Nombre} - {pedido.Total}");
}

Ahora el número de queries es constante:

1 query para pedidos
1 query para clientes

No importa si tienes 10 pedidos o 100,000.

En lugar de N queries de un registro cada una, ahora son 2 queries en total.

Resumen

Situación	Queries ejecutadas	Solución
Query en loop, entidad relacionada	1 + N	`Include` o proyección con `Select`
Servicio con queries dentro del loop	1 + (N × M)	Cargar datos necesarios antes del loop
Proyección con `Select` y JOIN	1	✅ Ya es correcto

La regla general:

Todo lo que necesitas para procesar una lista debería estar cargado antes de iterar sobre ella.

¿Qué sigue?

Hasta ahora vimos tres problemas distintos:

traer más registros de los necesarios
traer más columnas de las necesarias
multiplicar queries accidentalmente

El siguiente problema es el opuesto al N+1:

hacer una sola query… pero generar muchas más filas de las esperadas.

Cuando abusas de Include, EF Core puede terminar produciendo joins gigantescos que duplican datos masivamente — la explosión cartesiana.

Y sí, EF Core incluso tiene herramientas como AsSplitQuery() para intentar balancear ambos extremos.

Lo veremos en el siguiente artículo.

¿Has encontrado un N+1 en producción? ¿Cómo lo detectaste? Cuéntame en los comentarios.

Ports & Adapters: cómo aislar tu núcleo de todo lo que puede cambiar

Isaac Ojeda — Wed, 29 Apr 2026 14:35:11 +0000

Ports & Adapters: cómo aislar tu núcleo de todo lo que puede cambiar

"El núcleo de tu aplicación no debería saber si el correo lo manda SendGrid, Mailgun o un servidor SMTP de Docker levantado a las 2am."

Introducción

Cuando empezamos un proyecto nuevo, el instinto natural es conectar todo rápido: llamamos a SendGrid directamente desde el servicio de negocio, usamos HttpClient con la URL hardcodeada, leemos la configuración en el lugar menos pensado. Funciona. Por un rato.

El problema aparece cuando necesitas correr las pruebas sin mandar correos reales, o cuando el cliente cambia de proveedor de email a mitad del proyecto, o cuando en desarrollo no tienes acceso al servidor SMTP de producción. De repente, lo que "funcionaba" se convierte en un obstáculo.

El patrón Ports & Adapters, introducido por Alistair Cockburn bajo el nombre de Arquitectura Hexagonal, propone una idea elegante y poderosa: el núcleo de tu aplicación define contratos (puertos), y las implementaciones concretas (adaptadores) se enchufan desde afuera. El core no sabe —ni le importa— quién está del otro lado.

Este artículo nace de mi experiencia trabajando con este patrón en proyectos reales con .NET. No como ejercicio académico, sino como herramienta de trabajo que ha simplificado enormemente el mantenimiento, las pruebas y los despliegues en múltiples ambientes.

Desarrollo

El problema concreto: el correo electrónico

Tomemos uno de los casos más comunes: enviar correos electrónicos. En un proyecto típico manejamos al menos tres ambientes:

Ambiente	Proveedor de email
Desarrollo	Servidor SMTP local en Docker (ej. Mailpit)
QA / Staging	Servidor SMTP interno de la empresa
Producción	SaaS como SendGrid, con tracking y analytics

Si el código de negocio sabe con quién está hablando, tienes un problema: cambiar de proveedor implica tocar el núcleo. Eso va en contra de uno de los principios más valiosos en diseño de software: aislar lo que cambia de lo que no cambia.

El port: define el contrato, no la implementación

Un port es simplemente una interfaz. Dice qué se puede hacer, sin decir cómo.

public interface IEmailSender
{
    Task SendAsync(EmailMessage message, CancellationToken cancellationToken = default);
}

public record EmailMessage(
    string To,
    string Subject,
    string HtmlBody,
    string? PlainTextBody = null
);

Tu lógica de negocio depende únicamente de IEmailSender. No sabe nada de SMTP, ni de SendGrid, ni de credenciales. Solo conoce el contrato.

public class UserRegistrationService
{
    private readonly IEmailSender _emailSender;

    public UserRegistrationService(IEmailSender emailSender)
    {
        _emailSender = emailSender;
    }

    public async Task RegisterAsync(RegisterUserCommand command)
    {
        // ... lógica de registro ...

        await _emailSender.SendAsync(new EmailMessage(
            To: command.Email,
            Subject: "¡Bienvenido!",
            HtmlBody: $"<h1>Hola, {command.Name}</h1><p>Tu cuenta ha sido creada.</p>"
        ));
    }
}

El núcleo queda limpio. Nada de dependencias externas, nada que cambie cuando cambias de proveedor.

Los adapters: implementaciones intercambiables

Cada ambiente tiene su propio adapter, que implementa el mismo port.

Adapter SMTP (para desarrollo con Docker):

public class SmtpEmailSender : IEmailSender
{
    private readonly SmtpOptions _options;

    public SmtpEmailSender(IOptions<SmtpOptions> options)
    {
        _options = options.Value;
    }

    public async Task SendAsync(EmailMessage message, CancellationToken cancellationToken = default)
    {
        using var client = new SmtpClient();
        await client.ConnectAsync(_options.Host, _options.Port, SecureSocketOptions.None, cancellationToken);

        var mail = new MimeMessage();
        mail.To.Add(MailboxAddress.Parse(message.To));
        mail.Subject = message.Subject;
        mail.Body = new TextPart(TextFormat.Html) { Text = message.HtmlBody };

        await client.SendAsync(mail, cancellationToken);
        await client.DisconnectAsync(true, cancellationToken);
    }
}

Adapter SendGrid (para producción):

public class SendGridEmailSender : IEmailSender
{
    private readonly SendGridClient _client;
    private readonly SendGridOptions _options;

    public SendGridEmailSender(IOptions<SendGridOptions> options)
    {
        _options = options.Value;
        _client = new SendGridClient(_options.ApiKey);
    }

    public async Task SendAsync(EmailMessage message, CancellationToken cancellationToken = default)
    {
        var msg = MailHelper.CreateSingleEmail(
            from: new EmailAddress(_options.FromEmail, _options.FromName),
            to: new EmailAddress(message.To),
            subject: message.Subject,
            plainTextContent: message.PlainTextBody,
            htmlContent: message.HtmlBody
        );

        await _client.SendEmailAsync(msg, cancellationToken);
    }
}

Cada adapter es independiente. Si mañana migras de SendGrid a Mailgun, creas un nuevo adaptador y listo. El núcleo no se toca.

El Factory: construir el adapter correcto según la configuración

Aquí es donde el patrón cobra su mayor fuerza en la práctica. En lugar de registrar manualmente el adaptador en Program.cs y cambiarlo por ambiente, uso un factory que lee la configuración y devuelve la implementación adecuada.

Configuración en appsettings.json:

{
  "Email": {
    "Provider": "SendGrid",
    "SendGrid": {
      "ApiKey": "SG.xxx",
      "FromEmail": "noreply@miapp.com",
      "FromName": "Mi Aplicación"
    },
    "Smtp": {
      "Host": "localhost",
      "Port": 1025
    }
  }
}

Factory para el registro:

public static class EmailServiceExtensions
{
    public static IServiceCollection AddEmailSender(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        var provider = configuration["Email:Provider"] ?? "Smtp";

        services.AddTransient<IEmailSender>(sp =>
        {
            return provider switch
            {
                "SendGrid" => new SendGridEmailSender(
                    sp.GetRequiredService<IOptions<SendGridOptions>>()),

                "Smtp" => new SmtpEmailSender(
                    sp.GetRequiredService<IOptions<SmtpOptions>>()),

                _ => throw new InvalidOperationException($"Proveedor de email no soportado: {provider}")
            };
        });

        services.Configure<SendGridOptions>(configuration.GetSection("Email:SendGrid"));
        services.Configure<SmtpOptions>(configuration.GetSection("Email:Smtp"));

        return services;
    }
}

Y en Program.cs, limpio y simple:

builder.Services.AddEmailSender(builder.Configuration);

Cambiar de proveedor es ahora una línea en el appsettings del ambiente correspondiente. Sin recompilar, sin tocar el núcleo.

El decorador: comportamiento sin contaminar los adaptadores

Un patrón que combina perfectamente con esto es el Decorator. Imagina que quieres agregar logging a todos los envíos de email, independientemente del proveedor:

💡 Ya he hablado sobre este patrón en este artículo.

public class LoggingEmailSenderDecorator : IEmailSender
{
    private readonly IEmailSender _inner;
    private readonly ILogger<LoggingEmailSenderDecorator> _logger;

    public LoggingEmailSenderDecorator(
        IEmailSender inner,
        ILogger<LoggingEmailSenderDecorator> logger)
    {
        _inner = inner;
        _logger = logger;
    }

    public async Task SendAsync(EmailMessage message, CancellationToken cancellationToken = default)
    {
        _logger.LogInformation("Enviando correo a {To} con asunto '{Subject}'", message.To, message.Subject);

        try
        {
            await _inner.SendAsync(message, cancellationToken);
            _logger.LogInformation("Correo enviado correctamente a {To}", message.To);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error al enviar correo a {To}", message.To);
            throw;
        }
    }
}

Para enchufar el decorador, puedes usar Scrutor (librería NuGet de Dependency Injection avanzado) o hacerlo manualmente:

// Con Scrutor
services.Decorate<IEmailSender, LoggingEmailSenderDecorator>();

// O manualmente
services.AddTransient<IEmailSender>(sp =>
{
    var inner = /* tu factory aquí */;
    var logger = sp.GetRequiredService<ILogger<LoggingEmailSenderDecorator>>();
    return new LoggingEmailSenderDecorator(inner, logger);
});

💡 También utilizar Keyed Services del DI es útil cuando queremos tener varios decoradores, en mi artículo mencionado anteriormente hablo sobre ello.

El logging aplica a cualquier adaptador. Si mañana agregas un adaptador nuevo, el decorador lo cubre automáticamente. Sin duplicar código.

El adaptador `Null`: tu mejor aliado en pruebas

Para pruebas unitarias o escenarios donde no quieres efectos secundarios reales, el Null Object Pattern aplicado como adaptador es invaluable:

public class NullEmailSender : IEmailSender
{
    public Task SendAsync(EmailMessage message, CancellationToken cancellationToken = default)
        => Task.CompletedTask; // No hace nada. Y está bien.
}

También puedes tener una versión que almacena los mensajes en memoria para hacer aserciones en las pruebas:

public class InMemoryEmailSender : IEmailSender
{
    public List<EmailMessage> SentMessages { get; } = new();

    public Task SendAsync(EmailMessage message, CancellationToken cancellationToken = default)
    {
        SentMessages.Add(message);
        return Task.CompletedTask;
    }
}

// En tus pruebas
var emailSender = new InMemoryEmailSender();
var service = new UserRegistrationService(emailSender);

await service.RegisterAsync(new RegisterUserCommand("test@example.com", "Isaac"));

Assert.Single(emailSender.SentMessages);
Assert.Equal("test@example.com", emailSender.SentMessages[0].To);

Pruebas rápidas, sin dependencias externas, sin configuración extra.

Este patrón escala a todo

Este mismo enfoque aplica a cualquier dependencia de infraestructura:

Almacenamiento de archivos: IFileStorage con adaptadores para AzureBlobStorage, LocalFileSystem, S3
Notificaciones push: IPushNotificationSender con adaptadores para Firebase, APNS, etc.
SMS: ISmsSender con Twilio en producción, log en desarrollo
Caché: ICacheProvider sobre IMemoryCache o IDistributedCache
Pagos: IPaymentGateway con Stripe, Conekta, o un mock para pruebas

El patrón es el mismo: define el contrato en el núcleo, implementa fuera, conecta con un factory.

Conclusión

Ports & Adapters no es un patrón complicado. Su fuerza está en una idea simple: el núcleo de tu aplicación debería poder existir sin importarle nada del mundo exterior. No le importa si el correo va por SMTP o SendGrid. No le importa si los archivos están en Azure Blob o en disco local. No le importa si estás en desarrollo, QA o producción.

Lo que me ha resultado más valioso en la práctica es la combinación Factory + Decorador:

El Factory decide qué adaptador construir según la configuración del ambiente.
El Decorador agrega comportamiento transversal (logging, reintentos, métricas) sin contaminar ningún adaptador.
El Null/InMemory adapter hace que las pruebas sean rápidas y deterministas.

Cuando alguien en el equipo dice "hay que cambiar de proveedor de email", la respuesta es: creamos un adaptador nuevo, actualizamos el appsetting, listo. Sin miedo, sin regresiones inesperadas, sin refactors dolorosos.

Ese es el tipo de arquitectura que te deja dormir tranquilo en producción.

Referencias y recursos para aprender más

Alistair Cockburn — Hexagonal Architecture (artículo original, 2005)

https://alistair.cockburn.us/hexagonal-architecture/
Microsoft Docs — Dependency Injection en ASP.NET Core

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection
Scrutor — Decorator support for Microsoft DI

https://github.com/khellang/Scrutor
MailKit — Cliente SMTP para .NET

https://github.com/jstedfast/MailKit
Mailpit — Servidor SMTP para desarrollo con Docker

https://mailpit.axllent.org/
Mark Seemann — Dependency Injection in .NET (libro recomendado)

https://www.manning.com/books/dependency-injection-principles-practices-patterns
Clean Architecture — Robert C. Martin (el contexto más amplio de este patrón)

https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html

¿Usas este patrón en tus proyectos? ¿Con qué combinaciones de adaptadores has trabajado? Déjame tu experiencia en los comentarios.

Cómo manejar fallos transitorios en .NET con Polly y ResiliencePipelineBuilder

Isaac Ojeda — Mon, 27 Apr 2026 13:30:06 +0000

Introducción

Hay una idea que tarde o temprano aparece en cualquier sistema distribuido: no todo error significa que algo esté roto de verdad.

A veces una API tarda más de lo normal. A veces un servicio está reiniciándose. A veces la red falla durante un instante. Y a veces simplemente pegaste justo en el peor momento posible.

Ese tipo de errores existen, pasan seguido y, lo más importante, muchas veces se resuelven solos si reintentas correctamente.

Ahí entra Polly.

Con Polly v8 cambió bastante la forma de definir resiliencia en .NET. La API ahora gira alrededor de ResiliencePipeline y ResiliencePipelineBuilder, que permiten componer estrategias como retry, timeout o circuit breaker de una forma mucho más clara que en versiones anteriores.

Si ya vienes usando Microsoft.Extensions.Http.Resilience con HttpClient, probablemente ya viste una parte de esta idea. Pero Polly no sirve solo para HTTP. También aplica para operaciones como:

subir archivos a Blob Storage
consultar una base de datos
invocar un servicio gRPC
procesar mensajes de una cola
ejecutar cualquier operación async que pueda fallar por causas temporales

En este artículo vamos a usar un ejemplo simple para mostrar cómo aplicar ResiliencePipelineBuilder, pero también quiero aprovechar para cubrir mejor el concepto detrás de todo esto: Retry Pattern, transient fault handling y algunos criterios prácticos para no caer en reintentos ciegos.

El problema real

Cuando estamos empezando, es común tratar todos los errores igual: si falló, falló. Se lanza la excepción, se loguea algo y listo.

El problema es que en producción eso suele ser demasiado ingenuo.

Imagina este flujo:

Usuario -> Tu app -> Servicio externo -> falla momentáneamente -> error

Ahora imagina este otro:

Usuario -> Tu app -> Servicio externo -> falla momentáneamente -> retry -> éxito

La diferencia entre ambos no es menor. En el primer caso devuelves un error por algo que tal vez duró 300 milisegundos. En el segundo, absorbiste una falla esperable del entorno y la operación terminó bien.

Eso es resiliencia: no asumir que el mundo es estable, sino diseñar para que el sistema siga funcionando razonablemente bien cuando aparecen fallos normales.

¿Qué es transient fault handling?

Transient fault handling es la práctica de detectar errores temporales y responder de forma inteligente, en lugar de tratar esos errores como fallos definitivos.

No significa "reintentar todo".

Significa:

identificar qué errores son temporales
decidir si vale la pena reintentar
espaciar esos intentos de forma razonable
cortar cuando ya no tiene sentido seguir intentando

Ejemplos comunes de fallos transitorios:

TimeoutException
errores de transporte representados por HttpRequestException
respuestas 429 Too Many Requests
respuestas 408 Request Timeout
errores 5xx
problemas breves de conectividad
servicios que están arrancando o recuperándose

Ejemplos de fallos que normalmente no conviene reintentar:

401 Unauthorized
403 Forbidden
404 Not Found cuando el recurso realmente no existe
validaciones de negocio fallidas
errores de formato o datos inválidos

Esta distinción es la base del Retry Pattern. Si no la haces bien, el retry deja de ser una estrategia de resiliencia y pasa a ser una forma elegante de insistir inútilmente.

En HTTP no basta con capturar `HttpRequestException`

Aquí hay un matiz importante. En operaciones HTTP, no siempre decides reintentar por la excepción que recibes. Muy a menudo lo que realmente importa es el status code de la respuesta.

HttpRequestException suele representar errores de transporte o conectividad:

fallo DNS
conexión rechazada
corte de red
handshake TLS fallido
socket cerrado de forma inesperada

Eso sí suele ser un buen candidato para retry.

Pero en HTTP también existe otro caso: la petición llega al servidor, el servidor responde, y aun así la respuesta indica que conviene reintentar. Ahí el criterio ya no está en la excepción, sino en el código de estado.

En otras palabras:

si no hay respuesta, normalmente evalúas la excepción
si sí hay respuesta, normalmente evalúas el status code

Además, con HttpClient una respuesta 404, 429 o 503 no lanza excepción por sí sola. Solo obtienes una excepción si tú llamas a EnsureSuccessStatusCode() o si el fallo ocurre antes de recibir la respuesta. Por eso, cuando haces retry en HTTP, muchas veces necesitas manejar ambas cosas: excepciones de transporte y resultados HTTP no exitosos.

¿Cuándo tiene sentido reintentar según el status code?

Como regla general, tiene sentido considerar retry en estos códigos:

408 Request Timeout: el servidor no completó la petición a tiempo
429 Too Many Requests: te están limitando; idealmente debes respetar Retry-After
500 Internal Server Error: puede ser transitorio, aunque depende del sistema
502 Bad Gateway: fallo temporal de gateway o upstream
503 Service Unavailable: servicio saturado, caído o en mantenimiento
504 Gateway Timeout: el gateway no recibió respuesta a tiempo del upstream

Hay otros códigos que a veces pueden ser reintentables, pero dependen mucho del dominio:

409 Conflict: puede tener sentido si el conflicto es temporal o si hay concurrencia optimista
423 Locked: puede ser temporal si el recurso está bloqueado brevemente
425 Too Early: en algunos escenarios conviene reintentar más tarde

En cambio, normalmente no tiene sentido reintentar estos códigos:

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found cuando el recurso realmente no existe
405 Method Not Allowed
422 Unprocessable Entity

La idea de fondo es simple: si el problema está en tu request, reintentar no arregla nada. Si el problema está en el servidor, en la red o en una condición temporal del entorno, entonces retry sí puede tener sentido.

Retry Pattern

El Retry Pattern consiste en volver a ejecutar una operación que falló, asumiendo que el error pudo haber sido temporal.

La clave no está en el hecho de reintentar. La clave está en cómo reintentas.

Un retry bien hecho:

solo reintenta errores transitorios
pone un límite claro de intentos
espera entre intentos
idealmente usa backoff y jitter
deja trazabilidad con logs o métricas

Un retry mal hecho:

reintenta cualquier excepción
dispara intentos de forma inmediata
multiplica la carga sobre un servicio ya degradado
empeora la latencia total
puede generar operaciones duplicadas si no hay idempotencia

Si te quedas con una sola idea del artículo, que sea esta: retry no es un parche; es una decisión de diseño.

Un punto importante: idempotencia

Antes de agregar reintentos a cualquier operación, hay una pregunta que conviene hacer siempre:

Si esta operación se ejecuta dos veces, ¿el resultado sigue siendo correcto?

Eso es idempotencia.

Por ejemplo:

consultar datos suele ser seguro para reintentar
actualizar un estado a un valor fijo puede ser seguro
cobrar una tarjeta dos veces claramente no es seguro

Si una operación no es idempotente, agregar retry sin más puede introducir errores peores que el fallo original.

No quiere decir que no puedas reintentar nunca, pero sí que probablemente necesites una estrategia adicional: claves idempotentes, deduplicación, control transaccional o algún mecanismo parecido.

Instalación

dotnet add package Polly

El servicio inestable del ejemplo

Para mostrar el comportamiento de Polly, el proyecto usa un servicio que falla de forma aleatoria. No es sofisticado, pero alcanza para representar bastante bien lo que pasa cuando dependes de infraestructura o servicios externos.

public class UnreliableService
{
    private readonly Random _random = new();
    private int _attemptCount = 0;

    public double FailureRate { get; set; } = 0.7;

    public async Task<string> ProcessDataAsync(string data, CancellationToken cancellationToken = default)
    {
        _attemptCount++;
        var currentAttempt = _attemptCount;

        Console.WriteLine($"  [Intento {currentAttempt}] Procesando: \"{data}\"...");

        await Task.Delay(TimeSpan.FromMilliseconds(_random.Next(100, 500)), cancellationToken);

        if (_random.NextDouble() < FailureRate)
        {
            var exception = GetRandomException();
            Console.WriteLine($"  [Intento {currentAttempt}] ❌ Falló con: {exception.GetType().Name}");
            throw exception;
        }

        Console.WriteLine($"  [Intento {currentAttempt}] ✅ Éxito!");
        return $"Procesado: {data} (intento #{currentAttempt})";
    }
}

Las excepciones simuladas son justamente de las que suelen entrar en la categoría de fallos transitorios:

HttpRequestException
TimeoutException
IOException
InvalidOperationException con mensaje temporal

En este ejemplo usamos excepciones porque no estamos simulando respuestas HTTP reales. Pero si esta misma idea se aplicara a HttpClient, además de las excepciones convendría evaluar el status code devuelto por el servidor.

Creando el pipeline de retry

Aquí es donde Polly v8 muestra su enfoque. En este caso el ejemplo es genérico y por eso decide reintentar según excepciones:

using Polly;
using Polly.Retry;

var retryPipeline = new ResiliencePipelineBuilder<string>()
    .AddRetry(new RetryStrategyOptions<string>
    {
        MaxRetryAttempts = 3,
        BackoffType = DelayBackoffType.Exponential,
        Delay = TimeSpan.FromSeconds(1),
        UseJitter = true,
        ShouldHandle = new PredicateBuilder<string>()
            .Handle<HttpRequestException>()
            .Handle<TimeoutException>()
            .Handle<IOException>()
            .Handle<InvalidOperationException>(ex =>
                ex.Message.Contains("temporarily unavailable")),
        OnRetry = args =>
        {
            Console.WriteLine($"  ⏳ Reintento #{args.AttemptNumber} en {args.RetryDelay.TotalSeconds:F1}s");
            return ValueTask.CompletedTask;
        }
    })
    .Build();

Qué hace cada opción

Propiedad	Qué significa en la práctica
`MaxRetryAttempts`	Cuántas veces más vas a intentar después del primer fallo
`BackoffType`	Cómo crece la espera entre reintentos
`Delay`	El delay base
`UseJitter`	Agrega un pequeño factor aleatorio para que todos los clientes no reintenten al mismo tiempo
`ShouldHandle`	Define exactamente qué errores o resultados sí merecen retry
`OnRetry`	Te permite registrar eventos, medir, agregar observabilidad o contexto

¿Por qué usar backoff exponencial?

Porque reintentar demasiado rápido suele ser una mala idea.

Si un servicio está saturado o recién se está recuperando, pegarle tres veces seguidas en 50 milisegundos no ayuda. Lo más probable es que solo agraves el problema.

Con backoff exponencial, el intervalo entre intentos crece progresivamente:

Exponential (base 1s): 1s -> 2s -> 4s -> 8s
Linear (base 1s):      1s -> 2s -> 3s -> 4s
Constant (base 1s):    1s -> 1s -> 1s -> 1s

En la mayoría de integraciones con servicios externos, exponencial suele ser el punto de partida razonable.

¿Y el jitter para qué sirve?

Supongamos que tienes diez instancias de tu app. Todas llaman al mismo servicio. Todas fallan al mismo tiempo. Todas reintentan exactamente un segundo después.

Acabas de crear una mini estampida coordinada.

Eso se conoce como thundering herd. El jitter rompe ese patrón agregando una pequeña variación aleatoria en el delay. No parece gran cosa, pero en escenarios con volumen real hace bastante diferencia.

Ejecutando la operación con resiliencia

Una vez construido el pipeline, ejecutas la operación dentro de él:

var result = await retryPipeline.ExecuteAsync(
    async ct => await unreliableService.ProcessDataAsync("Datos importantes", ct),
    CancellationToken.None);

Console.WriteLine($"Resultado: {result}");

Una salida típica puede verse así:

[Intento 1] Procesando: "Datos importantes"...
[Intento 1] ❌ Falló con: HttpRequestException
⏳ Reintento #1 en 1.2s
[Intento 2] Procesando: "Datos importantes"...
[Intento 2] ❌ Falló con: TimeoutException
⏳ Reintento #2 en 2.1s
[Intento 3] Procesando: "Datos importantes"...
[Intento 3] ✅ Éxito!

Resultado: Procesado: Datos importantes (intento #3)

Lo interesante no es solo que eventualmente funcione. Lo importante es que el código de negocio queda limpio, y la política de resiliencia queda definida en un lugar explícito.

Centralizando pipelines reutilizables

Si vas a usar la misma idea en varios lugares, tiene sentido encapsular la configuración en un factory. El proyecto ya hace algo de eso en ResiliencePipelines:

public static class ResiliencePipelines
{
    public static ResiliencePipeline<T> CreateRetryPipeline<T>(int maxRetries = 3)
    {
        return new ResiliencePipelineBuilder<T>()
            .AddRetry(new RetryStrategyOptions<T>
            {
                MaxRetryAttempts = maxRetries,
                BackoffType = DelayBackoffType.Exponential,
                Delay = TimeSpan.FromSeconds(1),
                UseJitter = true,
                ShouldHandle = new PredicateBuilder<T>()
                    .Handle<HttpRequestException>()
                    .Handle<TimeoutException>()
                    .Handle<IOException>()
            })
            .Build();
    }
}

Esto tiene varias ventajas:

evitas repetir configuración
mantienes consistencia entre operaciones similares
puedes cambiar la estrategia en un solo punto
es más simple testear y evolucionar la política con el tiempo

También existe el pipeline sin tipo genérico

Si tu operación no devuelve valor, puedes usar ResiliencePipelineBuilder sin T:

var pipeline = new ResiliencePipelineBuilder()
    .AddRetry(new RetryStrategyOptions
    {
        MaxRetryAttempts = 3,
        BackoffType = DelayBackoffType.Exponential,
        Delay = TimeSpan.FromSeconds(1)
    })
    .Build();

await pipeline.ExecuteAsync(async ct =>
{
    await SubirArchivoAsync(ct);
}, cancellationToken);

Retry no vive solo

Aunque el foco de este artículo sea retry, la resiliencia real rara vez se resuelve con una sola estrategia.

Por ejemplo, este tipo de composición suele tener bastante sentido:

var advancedPipeline = new ResiliencePipelineBuilder<string>()
    .AddTimeout(TimeSpan.FromSeconds(10))
    .AddRetry(new RetryStrategyOptions<string>
    {
        MaxRetryAttempts = 3,
        BackoffType = DelayBackoffType.Exponential,
        Delay = TimeSpan.FromSeconds(1)
    })
    .Build();

Aquí hay una idea importante: el retry te protege de fallos transitorios, pero el timeout te protege de operaciones que quedan colgadas demasiado tiempo.

Con el tiempo, es común sumar otras estrategias según el caso:

Circuit Breaker para dejar de insistir cuando un servicio claramente está caído
Timeout para no esperar indefinidamente
Rate Limiter para proteger recursos internos o externos
Fallback para responder de forma degradada cuando no puedes completar la operación principal

Cuándo NO usar retry

Este punto muchas veces queda corto, pero es de los más importantes.

No deberías aplicar retry de forma automática cuando:

el error es permanente
la operación no es segura para repetir (no es idempotente)
cada intento adicional empeora la congestión
el costo de esperar más supera el beneficio
el usuario necesita una respuesta rápida y explícita, no varios segundos de insistencia

En HTTP, eso también significa que no deberías decir "voy a reintentar cualquier HttpRequestException o cualquier respuesta no exitosa". Hay que distinguir entre errores de transporte y respuestas con significado funcional.

En otras palabras: resiliencia no significa esconder todos los errores. Significa tratar mejor los errores que sí vale la pena absorber.

Qué conviene observar en producción

Si agregas retry pero no mides nada, te pierdes la mitad del valor.

Como mínimo, conviene tener visibilidad sobre esto:

cuántos reintentos se están ejecutando
qué excepciones están disparando esos retries
cuánto aumenta la latencia total por los reintentos
qué operaciones terminan fallando incluso después de agotar el pipeline

Eso te ayuda a responder preguntas concretas:

¿estoy absorbiendo fallos ocasionales o tapando un problema más serio?
¿mi política de retry está bien definida o está agregando demasiada espera?
¿hay un servicio externo que se está degradando más de lo que pensábamos?

Polly te deja enganchar callbacks como OnRetry, y desde ahí puedes registrar eventos, emitir métricas o enriquecer trazas distribuidas. En local alcanza con un Console.WriteLine, pero en producción lo ideal es que esos eventos terminen en tu stack de observabilidad.

Ejemplo más cercano a un caso real

Si en vez de un servicio simulado estuvieras subiendo un archivo a Azure Blob Storage, la idea sería muy parecida:

public class ResilientBlobUploader
{
    private readonly BlobContainerClient _container;
    private readonly ResiliencePipeline _uploadPipeline;

    public ResilientBlobUploader(BlobContainerClient container)
    {
        _container = container;
        _uploadPipeline = new ResiliencePipelineBuilder()
            .AddRetry(new RetryStrategyOptions
            {
                MaxRetryAttempts = 3,
                BackoffType = DelayBackoffType.Exponential,
                Delay = TimeSpan.FromSeconds(2),
                ShouldHandle = new PredicateBuilder()
                    .Handle<RequestFailedException>(ex =>
                        ex.Status is 408 or 429 or 500 or 502 or 503 or 504)
                    .Handle<IOException>()
            })
            .Build();
    }

    public async Task UploadAsync(string blobName, Stream content, CancellationToken ct)
    {
        await _uploadPipeline.ExecuteAsync(async token =>
        {
            var blob = _container.GetBlobClient(blobName);
            await blob.UploadAsync(content, overwrite: true, token);
        }, ct);
    }
}

Observa algo importante: no se manejan todos los códigos de error, solo los que realmente sugieren una condición temporal o recuperable.

Ejecutar el ejemplo

dotnet run

El programa compara operaciones con y sin resiliencia, y además muestra un pipeline inline para que se vea la diferencia entre centralizar la configuración o definirla localmente.

Conviene ejecutarlo varias veces, porque al haber fallos aleatorios vas a ver escenarios distintos en cada corrida.

Conclusión

Lo más valioso de Polly no es que "agrega retries". Lo valioso es que te obliga a pensar mejor cómo responde tu sistema frente a fallos normales del entorno.

Si tuviera que resumir el mensaje del artículo, sería este:

No todos los errores son iguales.
Algunos errores son transitorios y merecen un retry.
Un retry bien configurado necesita criterio, límites, backoff y observabilidad.
Si la operación no es idempotente, reintentar puede ser peligroso.
Retry es solo una pieza dentro de una estrategia de resiliencia más amplia.

Polly v8 hace que modelar todo esto sea bastante más cómodo que antes. Y eso está bueno, porque en aplicaciones reales la resiliencia no suele ser un lujo: suele ser parte de hacer software que se comporte bien fuera de tu máquina.

Referencias

EF Core: tu query funciona, tus pruebas pasan… y estás leyendo 50,000 filas para devolver 3

Isaac Ojeda — Sat, 14 Mar 2026 22:44:46 +0000

El código lleva meses en producción. Nadie se ha quejado. Todas las pruebas pasan.

Luego llega un cliente grande, con años de historial acumulado, y esa pantalla que siempre cargó “bien” empieza a tardar varios segundos. A veces ni siquiera falla: simplemente se vuelve torpe, pesada, impredecible.

Empiezas a revisar y descubres algo incómodo: el problema siempre estuvo ahí. Solo necesitaba suficientes datos para hacerse visible.

Ese es uno de los patrones más traicioneros cuando trabajas con EF Core. No porque el código esté roto, sino porque funciona. Devuelve los datos correctos. Pasa QA. Sobrevive en producción durante meses. Y aun así, por debajo, puede estar ejecutando consultas mucho más caras de lo que parecen.

En este artículo quiero mostrar dos trampas comunes:

cuando materializas demasiado pronto con ToList() y el filtro termina ocurriendo en memoria;
cuando dejas lógica no traducible dentro de la proyección y la consulta deja de ser tan eficiente como parece.

La idea no es memorizar reglas raras de EF Core. La idea es desarrollar un reflejo: siempre revisar el SQL real que se genera.

Por qué casi nadie lo detecta a tiempo

Este problema rara vez aparece de golpe.

En local, todo corre sobre una base pequeña, con datos de prueba y una máquina rápida. Las consultas tardan milisegundos y nadie siente la necesidad de inspeccionar el SQL.

En QA o staging, la infraestructura puede parecerse a producción, pero el volumen de datos sigue sin representar el mundo real. El problema ya existe, solo que todavía no pesa.

En producción, con clientes pequeños, los tiempos siguen siendo aceptables. No hay alertas. No hay tickets. No hay razón aparente para abrir el capó.

Y entonces llega el cliente con años de historial, decenas de miles de registros y patrones reales de uso. Ahí, por primera vez, la consulta muestra su costo verdadero.

Lo más difícil de este escenario no es corregirlo. Lo más difícil es que cuando por fin se vuelve visible, el código ya lleva tanto tiempo vivo que nadie recuerda con claridad por qué se escribió así.

En EF Core, el peligro no siempre es que algo falle. A veces el peligro es que funcione… pero de la forma más cara posible.

Problema 1: el `ToList()` que mueve el filtro fuera de SQL

El origen: una excepción legítima

Todo empieza con algo bastante normal: quieres usar lógica de negocio propia dentro de un Where.

var pedidos = await context.Pedidos
    .Where(p => EsDelUltimoMes(p.FechaCreacion))
    .Select(p => new PedidoResumenDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total
    })
    .ToListAsync();

private static bool EsDelUltimoMes(DateTime fecha) =>
    fecha >= DateTime.Now.AddMonths(-1);

Ese código no es traducible tal como está. EsDelUltimoMes es un método local de C#, y EF Core no sabe convertirlo a SQL. En EF Core moderno, eso normalmente termina en una excepción de traducción.

Algo como esto:

InvalidOperationException: The LINQ expression could not be translated.
Either rewrite the query in a form that can be translated, or switch to
client evaluation explicitly by inserting a call to 'AsEnumerable',
'AsAsyncEnumerable', 'ToList', or 'ToListAsync'.

La excepción no miente. Pero es muy fácil leerla de forma peligrosa.

La “solución” que parece arreglar todo

Alguien ve que el mensaje menciona ToList(), lo agrega, y el problema desaparece:

var pedidos = context.Pedidos
    .ToList()
    .Where(p => EsDelUltimoMes(p.FechaCreacion))
    .Select(p => new PedidoResumenDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total
    })
    .ToList();

Y sí: ahora funciona. Compila, devuelve resultados correctos y pasa las pruebas.

Pero ya no estás filtrando en la base de datos. Estás trayendo todos los registros primero, y luego aplicando la lógica en memoria.

En otras palabras, el SQL que sale ya no se parece a la intención original. Se parece más a esto:

SELECT p.Id, p.ClienteId, p.Total, p.Activo, p.FechaCreacion, ...
FROM Pedidos

Sin WHERE. Sin proyección útil. Sin límite.

Si la tabla tiene 50,000 filas, esas 50,000 filas viajan completas desde la base de datos hasta tu aplicación. Solo después haces el filtro en C# para devolver quizá 3 resultados al usuario.

Ese es el tipo de problema que no se nota con 200 registros, pero sí con años de operación acumulada.

La forma correcta

La solución real es expresar el filtro usando operadores que EF Core sí conozca y pueda traducir.

var fechaLimite = DateTime.Now.AddMonths(-1);

var pedidos = await context.Pedidos
    .Where(p => p.FechaCreacion >= fechaLimite)
    .Select(p => new PedidoResumenDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total
    })
    .ToListAsync();

Ahora sí el filtro vive donde debe vivir: en SQL.

SELECT c.Nombre, p.Total
FROM Pedidos p
LEFT JOIN Clientes c ON p.ClienteId = c.Id
WHERE p.FechaCreacion >= '2025-02-14'

La regla práctica aquí no es “nunca uses métodos”. Es esta: mientras la lógica se exprese con operadores y funciones que EF Core conoce, podrá empujarla a SQL. Cuando no pueda, corres el riesgo de que la evaluación ocurra fuera de la base de datos o de que EF directamente falle al traducir.

Si necesitas lógica de negocio más compleja, aplícala después de materializar, pero solo sobre un conjunto de datos que ya filtraste correctamente en la base.

Nota: en algunos escenarios complejos, usar Raw SQL es perfectamente válido. No es una derrota; es una herramienta más.

Problema 2: la proyección parece pequeña, pero la consulta deja de ser eficiente

El segundo problema es más silencioso.

Aquí el Where sí se traduce. La consulta sí filtra en la base de datos. Los resultados son correctos. El detalle está en la proyección.

El escenario

var pedidos = await context.Pedidos
    .Where(p => p.FechaCreacion >= fechaLimite)
    .Select(p => new PedidoResumenDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total,
        Estatus = ObtenerEtiqueta(p.Activo)
    })
    .ToListAsync();

private static string ObtenerEtiqueta(bool activo) =>
    activo ? "Activo" : "Inactivo";

A simple vista, parece una proyección pequeña. Solo quieres tres campos.

El problema es que ObtenerEtiqueta sigue siendo lógica local de C#. EF Core no puede traducir ese método directamente. En la proyección final, eso puede hacer que parte del trabajo termine resolviéndose del lado del cliente.

Y cuando eso pasa, la consulta puede traer más información de la necesaria para completar esa proyección en memoria.

La parte peligrosa no es solo “que funcione”. Es que desde el código parece una consulta mínima, cuando en realidad el SQL puede estar cargando más columnas de las que tú creías.

No siempre será literalmente un SELECT *, pero sí puede ocurrir que EF traiga suficiente información como para volver la proyección más costosa de lo que aparenta en C#.

La forma correcta

Si el formateo no necesita vivir en SQL, sepáralo de la consulta:

var pedidos = await context.Pedidos
    .Where(p => p.FechaCreacion >= fechaLimite)
    .Select(p => new PedidoResumenDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total,
        EsActivo = p.Activo
    })
    .ToListAsync();

// Dejar que la capa presentación muestre los datos
// o
// 👇🏼
foreach (var pedido in pedidos)
    pedido.Estatus = ObtenerEtiqueta(pedido.EsActivo);

Así la base de datos solo devuelve lo necesario, y el formateo ocurre después, en memoria, pero ya sobre un conjunto pequeño y bien proyectado.

Si la lógica sí puede expresarse con algo traducible, entonces mejor dejarla en la consulta:

var pedidos = await context.Pedidos
    .Where(p => p.FechaCreacion >= fechaLimite)
    .Select(p => new PedidoResumenDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total,
        Estatus = p.Activo ? "Activo" : "Inactivo"
    })
    .ToListAsync();

Una expresión ternaria simple como esa normalmente sí se traduce a CASE WHEN en SQL.

Cómo inspeccionar lo que EF Core realmente está haciendo

Si no ves el SQL, estás adivinando.

Y adivinar con consultas que hoy corren sobre 500 filas y mañana correrán sobre 5 millones suele salir caro.

Opción 1: logs en desarrollo

Puedes habilitar logs del contexto para ver el SQL ejecutado:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(connectionString)
           .LogTo(Console.WriteLine, LogLevel.Information)
           .EnableSensitiveDataLogging());

EnableSensitiveDataLogging() conviene dejarlo solo en desarrollo.

En la salida, busca entradas como esta:

Executed DbCommand (X ms) [Parameters=[...], CommandType='Text', CommandTimeout='30']

Ahí está la consulta real.

Opción 2: `ToQueryString()`

Cuando quieres revisar una consulta específica, esta suele ser la forma más directa:

var query = context.Pedidos
    .Where(p => p.FechaCreacion >= fechaLimite)
    .Select(p => new PedidoResumenDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total,
        Estatus = p.Activo ? "Activo" : "Inactivo"
    });

Console.WriteLine(query.ToQueryString());
var pedidos = await query.ToListAsync();

ToQueryString() funciona sobre cualquier IQueryable antes de materializarlo. Si tienes dudas sobre traducción, úsalo. Te ahorra suposiciones.

Un detalle extra en consultas de lectura

Si esa consulta solo existe para mostrar datos y no vas a modificar las entidades después, vale la pena considerar AsNoTracking():

var pedidos = await context.Pedidos
    .AsNoTracking()
    .Where(p => p.FechaCreacion >= fechaLimite)
    .Select(p => new PedidoResumenDto
    {
        Cliente = p.Cliente.Nombre,
        Total = p.Total
    })
    .ToListAsync();

No arregla problemas de traducción ni evita consultas mal diseñadas. Pero sí reduce trabajo del change tracker en escenarios de solo lectura, y eso puede sumar bastante cuando la pantalla consulta muchos registros.

Sobre asistentes de código y queries “que funcionan”

Los asistentes de código suelen optimizar para darte algo que compile, que se vea razonable y que devuelva el resultado esperado.

Eso está bien. Pero una consulta correcta funcionalmente no siempre es una consulta sana desde el punto de vista de traducción o performance.

El asistente no ve el volumen real de tu tabla. No está mirando el plan de ejecución. No sabe si ese query hoy devuelve 20 registros o si mañana va a inspeccionar medio millón para construir una pantalla.

Por eso esta revisión sigue siendo responsabilidad del developer: no basta con que la consulta compile y pase pruebas. Hay que confirmar qué SQL genera y dónde se está ejecutando realmente cada parte de la lógica.

Resumen

Situación	Qué ocurre	Cómo detectarlo
Método local no traducible dentro de `Where`	EF Core normalmente falla al traducir o te obliga a mover la evaluación fuera de SQL	Excepción de traducción
`ToList()` antes del filtro	La consulta se materializa completa y el filtrado ocurre en memoria	Revisando el código y el SQL generado
Lógica no traducible en la proyección final	Parte de la proyección puede resolverse en cliente y traer más datos de los necesarios	`ToQueryString()`, logs y revisión de columnas consultadas

La idea central de todo esto es simple: no confíes en que una query está bien solo porque funciona.

En EF Core, una consulta puede ser correcta en resultados y aun así ser innecesariamente cara. Y la forma más confiable de descubrirlo no es mirando el LINQ: es mirando el SQL.

¿Qué sigue?

Este es el primero de una serie sobre cosas que EF Core hace de forma poco obvia y que solo se vuelven dolorosas cuando los datos son reales.

El siguiente artículo va sobre el problema N+1: esa consulta que en desarrollo parece hacer unas pocas llamadas a la base, pero en producción termina haciendo cientos o miles.

Si alguna vez te pasó algo parecido, seguramente no fue porque el código estuviera “mal” en apariencia. Fue porque el costo real estaba escondido en un lugar que casi nadie revisa a tiempo.

Primeros pasos con Microsoft Agent Framework: construyendo un chatbot de soporte con C#

Isaac Ojeda — Tue, 24 Feb 2026 03:33:14 +0000

Introducción

Microsoft lleva años apostando por herramientas para construir aplicaciones con IA: primero llegó Semantic Kernel, después AutoGen, y ahora ambos convergen en su sucesor directo: Microsoft Agent Framework (MAF). Creado por los mismos equipos, MAF unifica lo mejor de ambos mundos — la estabilidad y características enterprise de Semantic Kernel con las abstracciones simples para agentes multi-turno de AutoGen — y agrega nuevas capacidades como workflows basados en grafos y un sistema robusto de manejo de estado.

Al momento de escribir este artículo, MAF está en public preview, disponible para .NET y Python bajo licencia MIT.

En este artículo vamos a aprender los conceptos fundamentales del framework y a construir algo concreto: una API con ASP.NET Core 10 que expone un chatbot de soporte técnico capaz de responder preguntas basándose en documentación Markdown interna, manteniendo el contexto de la conversación entre mensajes.

El código completo está disponible en GitHub.

Desarrollo

¿Qué es Microsoft Agent Framework?

MAF gira en torno a dos conceptos centrales que vale la pena entender antes de escribir código:

Agents son sistemas que usan un LLM para procesar entradas, tomar decisiones, llamar herramientas y generar respuestas. Son ideales cuando la tarea es dinámica y no puedes predecir de antemano exactamente qué pasos se van a necesitar — como una conversación de soporte donde el usuario puede preguntar cualquier cosa.

Workflows son secuencias de pasos definidas explícitamente, conectadas en un grafo. Son la elección correcta cuando el flujo es predecible y necesitas control determinista sobre la ejecución — como un pipeline de procesamiento de datos o un flujo de aprobaciones.

La documentación oficial tiene una regla de oro que me parece honesta y útil: "If you can write a function to handle the task, do that instead of using an AI agent." No todo necesita un agente. En este artículo construimos un agente porque la naturaleza conversacional e impredecible del soporte técnico es exactamente el caso de uso para el que están diseñados.

Los 5 conceptos clave

El tutorial oficial de Microsoft Learn organiza el aprendizaje en 5 pasos progresivos. Aquí los resumo en mis propias palabras antes de ver el código:

1. Tu primer agente. Un AIAgent se crea a partir de un cliente de chat (Azure OpenAI, OpenAI, etc.) con instrucciones y un nombre. Es stateless por diseño — el mismo agente puede atender múltiples conversaciones en paralelo. Correrlo es tan simple como await agent.RunAsync("pregunta").

2. Tools. Cualquier método C# decorado con [Description] se puede convertir en una herramienta que el agente puede llamar cuando lo necesite, usando AIFunctionFactory.Create(). El LLM decide autónomamente cuándo y con qué argumentos invocarla. Esto es lo que le da al agente la capacidad de actuar sobre el mundo real.

3. Multi-turn conversations. Como el agente es stateless, el historial de la conversación vive en un AgentSession. Se crea con agent.CreateSessionAsync() y se pasa en cada llamada. El agente recuerda todo lo que ocurrió en esa sesión.

4. Memory y Persistencia. La sesión es serializable a JsonElement. Esto permite guardarla en cualquier almacenamiento (memoria, base de datos, Redis) y reconstruirla después con agent.DeserializeSessionAsync(). Para un chat de soporte, esto significa que el usuario puede retomar una conversación donde la dejó, incluso si el servidor se reinició.

5. Workflows. Para orquestar múltiples agentes o pasos en secuencias definidas, se usa WorkflowBuilder. Se definen Executors (unidades de procesamiento) y se conectan con Edges. En este artículo no los implementamos porque no añaden valor real al caso de uso — pero al final menciono cuándo sí tendría sentido usarlos.

El ejemplo: SupportBot

El escenario es simple: una empresa tiene documentación interna en archivos .md — guías de usuario, FAQs, manuales de módulos. En lugar de que los empleados busquen manualmente en esos archivos, un chatbot lee la documentación y responde en lenguaje natural, manteniendo el hilo de la conversación.

Deliberadamente dejé fuera RAG y embeddings. La búsqueda por keywords en archivos planos es suficiente para demostrar cómo funciona MAF, y mantiene el ejemplo enfocado en el framework, no en infraestructura de búsqueda vectorial.

La estructura del proyecto es la siguiente:

SupportBot/
├── Program.cs
├── appsettings.json
├── Docs/
│   ├── accesos.md
│   ├── facturacion.md
│   └── reportes.md
├── Agents/
│   └── SupportAgentFactory.cs
├── Tools/
│   └── DocumentationTool.cs
├── Models/
│   ├── ChatRequest.cs
│   └── ChatResponse.cs
└── Sessions/
    └── InMemorySessionStore.cs

Instalación

dotnet new webapi -n SupportBot
cd SupportBot

dotnet add package Azure.AI.OpenAI --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI --prerelease
dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
dotnet add package Microsoft.Extensions.AI --prerelease

Todos los paquetes de Microsoft.Agents.AI están en prerelease — el flag es necesario.

La Tool: DocumentationTool

Aquí está el corazón del ejemplo. DocumentationTool es la herramienta que el agente llamará cuando necesite buscar información para responder al usuario.

using System.ComponentModel;

namespace SupportBot.Tools;

public class DocumentationTool
{
    private readonly string _docsPath;

    public DocumentationTool(string docsPath)
    {
        _docsPath = docsPath;
    }

    [Description("Busca en la documentación interna del sistema información sobre un tema específico. Úsala siempre antes de responder una pregunta del usuario.")]
    public string GetDocumentation(
        [Description("El tema o concepto sobre el que buscar. Por ejemplo: 'accesos', 'facturación', 'reportes', 'contraseña', etc.")]
        string topic)
    {
        if (!Directory.Exists(_docsPath))
            return "No hay documentación disponible en este momento.";

        var files = Directory.GetFiles(_docsPath, "*.md");

        if (files.Length == 0)
            return "No hay documentación disponible en este momento.";

        var keywords = topic.ToLowerInvariant()
            .Split(' ', StringSplitOptions.RemoveEmptyEntries);

        var matchingFiles = files.Where(file =>
        {
            var fileName = Path.GetFileNameWithoutExtension(file).ToLowerInvariant();
            var content = File.ReadAllText(file).ToLowerInvariant();
            return keywords.Any(k => fileName.Contains(k) || content.Contains(k));
        }).ToList();

        var filesToRead = matchingFiles.Count > 0 ? matchingFiles : files.ToList();

        var builder = new System.Text.StringBuilder();
        foreach (var file in filesToRead)
        {
            var fileName = Path.GetFileNameWithoutExtension(file);
            var content = File.ReadAllText(file);
            builder.AppendLine($"=== {fileName.ToUpperInvariant()} ===");
            builder.AppendLine(content);
            builder.AppendLine();
        }

        return builder.ToString();
    }
}

Hay dos detalles importantes aquí. El primero es que los atributos [Description] no son decorativos — MAF los usa para construir el schema que el LLM recibe, y de su calidad depende que el modelo entienda bien cuándo y cómo llamar la herramienta. El segundo es la estrategia de fallback: si no encuentra archivos que hagan match con el tema, retorna todos los documentos. Es una decisión pragmática — preferimos que el agente tenga demasiado contexto a que se quede sin información para responder.

El Agente: SupportAgentFactory

using Azure.AI.OpenAI;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using SupportBot.Tools;

namespace SupportBot.Agents;

public class SupportAgentFactory
{
    private readonly AIAgent _agent;

    public SupportAgentFactory(IConfiguration configuration, IWebHostEnvironment env)
    {
        var endpoint = configuration["AzureOpenAI:Endpoint"]
            ?? throw new InvalidOperationException("AzureOpenAI:Endpoint no configurado");
        var deploymentName = configuration["AzureOpenAI:DeploymentName"] ?? "gpt-4o-mini";
        var apiKey = configuration["AzureOpenAI:ApiKey"]
            ?? throw new InvalidOperationException("AzureOpenAI:ApiKey no configurado");

        var docsPath = Path.Combine(env.ContentRootPath, "Docs");
        var docTool = new DocumentationTool(docsPath);

        var instructions = """
            Eres un asistente de soporte técnico interno. Tu única fuente de información
            es la documentación del sistema que puedes consultar con la herramienta GetDocumentation.

            Reglas:
            - SIEMPRE consulta la documentación antes de responder cualquier pregunta.
            - Responde de forma clara, concisa y en el mismo idioma que el usuario.
            - Si la documentación no contiene la respuesta, dilo claramente.
            - No inventes información que no esté en la documentación.
            - Si el usuario saluda o hace preguntas generales, responde amablemente y pregunta en qué puedes ayudar.
            - No respondas preguntas fuera del contexto del sistema.
            """;

        _agent = new AzureOpenAIClient(
                new Uri(endpoint),
                new System.ClientModel.ApiKeyCredential(apiKey))
            .GetChatClient(deploymentName)
            .AsIChatClient()
            .AsAIAgent(
                instructions: instructions,
                name: "SupportAgent",
                tools: [AIFunctionFactory.Create(docTool.GetDocumentation)]
            );
    }

    public AIAgent Agent => _agent;
}

El flujo de construcción es una cadena: AzureOpenAIClient → GetChatClient() → AsIChatClient() → AsAIAgent(). El último paso es donde se convierten las tools registradas y las instrucciones en la configuración que el agente usará en cada conversación.

Nótese que el agente se construye una sola vez y se registra como singleton. Como es stateless, puede atender todas las conversaciones concurrentes sin problema — el estado de cada conversación vive en su propia AgentSession.

Manejo de Sesiones: InMemorySessionStore

using System.Collections.Concurrent;
using System.Text.Json;

namespace SupportBot.Sessions;

public class InMemorySessionStore
{
    private readonly ConcurrentDictionary<string, JsonElement> _sessions = new();

    public bool TryGetSession(string sessionId, out JsonElement session)
        => _sessions.TryGetValue(sessionId, out session);

    public void SaveSession(string sessionId, JsonElement session)
        => _sessions[sessionId] = session;

    public bool DeleteSession(string sessionId)
        => _sessions.TryRemove(sessionId, out _);
}

El store guarda sesiones como JsonElement — el formato en que MAF las serializa nativamente. ConcurrentDictionary garantiza thread-safety sin necesidad de locks manuales. Para producción, esto se reemplazaría por Redis o una base de datos, pero la interfaz del store no cambiaría.

Los Endpoints: Program.cs

using System.Text.Json;
using Microsoft.Agents.AI;
using SupportBot.Agents;
using SupportBot.Models;
using SupportBot.Sessions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<SupportAgentFactory>();
builder.Services.AddSingleton<InMemorySessionStore>();

var app = builder.Build();

app.MapPost("/chat", async (
    ChatRequest request,
    SupportAgentFactory agentFactory,
    InMemorySessionStore sessionStore) =>
{
    if (string.IsNullOrWhiteSpace(request.SessionId))
        return Results.BadRequest("SessionId es requerido.");

    if (string.IsNullOrWhiteSpace(request.Message))
        return Results.BadRequest("Message es requerido.");

    var agent = agentFactory.Agent;

    AgentSession session;
    if (sessionStore.TryGetSession(request.SessionId, out var serializedSession))
    {
        session = await agent.DeserializeSessionAsync(serializedSession);
    }
    else
    {
        session = await agent.CreateSessionAsync();
    }

    var response = await agent.RunAsync(request.Message, session);

    var updatedSession = await agent.SerializeSessionAsync(session);
    sessionStore.SaveSession(request.SessionId, updatedSession);

    return Results.Ok(new ChatResponse(request.SessionId, response.Text));
});

app.MapDelete("/chat/{sessionId}", (
    string sessionId,
    InMemorySessionStore sessionStore) =>
{
    sessionStore.DeleteSession(sessionId);
    return Results.NoContent();
});

app.Run();

El endpoint POST /chat sigue un patrón claro: cargar o crear sesión → ejecutar el agente → serializar y guardar la sesión actualizada → retornar la respuesta. El sessionId lo genera el cliente (puede ser un GUID) y lo manda en cada request para mantener el hilo de la conversación.

Un detalle de la versión RC1: SerializeSessionAsync es async, a diferencia de lo que indica la documentación inicial del framework.

El agente en acción

Con la API corriendo, así se ve una conversación multi-turn real:

Primer mensaje:

POST /chat
{
  "sessionId": "usr-42",
  "message": "Hola, no puedo entrar al sistema, olvidé mi contraseña"
}

{
  "sessionId": "usr-42",
  "reply": "¡Hola! Para resetear tu contraseña sigue estos pasos: ve a la pantalla de login y haz clic en '¿Olvidaste tu contraseña?', ingresa tu correo corporativo y recibirás un enlace válido por 24 horas. Si no recibes el correo en 10 minutos, revisa tu carpeta de spam o contacta a TI."
}

Mensaje de seguimiento (mismo sessionId):

POST /chat
{
  "sessionId": "usr-42",
  "message": "¿Y si tampoco recuerdo mi correo corporativo?"
}

{
  "sessionId": "usr-42",
  "reply": "En ese caso, la cuenta puede quedar bloqueada tras 5 intentos fallidos. Te recomiendo contactar directamente al equipo de soporte en soporte@empresa.com o llamar al ext. 100 para que puedan verificar tu identidad y ayudarte a recuperar el acceso."
}

El agente recuerda que estamos hablando de un problema de acceso y responde en contexto, sin necesidad de que el usuario repita la situación.

¿Cuándo agregarías Workflows aquí?

En este ejemplo los Workflows no añaden valor — el flujo conversacional es impredecible por naturaleza y el agente lo maneja bien solo. Pero hay escenarios donde sí tendría sentido introducirlos:

Si quisieras clasificar automáticamente la intención antes de responder (¿es una pregunta de accesos, facturación o reportes?) y enrutar a agentes especializados según el tema, un Workflow con un executor de clasificación seguido de ejecutores especializados sería la arquitectura correcta.

Si quisieras escalar a un humano cuando el agente no encuentra respuesta, un Workflow con un paso de "human-in-the-loop" integrado en el grafo lo haría de forma limpia y auditable.

La regla es simple: si puedes predecir los pasos, usa un Workflow. Si la conversación es abierta e impredecible, deja que el agente decida.

Conclusión

Microsoft Agent Framework simplifica genuinamente la construcción de agentes conversacionales en .NET. La abstracción de AIAgent, el manejo de sesiones serializable y el sistema de tools via atributos [Description] permiten tener algo funcional con muy poco código de infraestructura — lo que queda es lógica de negocio real.

El hecho de que aún esté en preview se nota en algunos detalles: la API cambia entre versiones (como el caso de SerializeSessionAsync que en RC1 es async), y la documentación a veces no refleja el estado actual del código. Dicho esto, para proyectos nuevos donde el timeline lo permite, ya vale la pena apostar por él en lugar de Semantic Kernel — es el camino hacia adelante según el propio equipo de Microsoft.

Los siguientes pasos naturales para este proyecto serían reemplazar el InMemorySessionStore por Redis o SQL Server para persistencia real, agregar autenticación al endpoint, e integrar un frontend — pero eso es material para otro artículo.

Referencias

Microsoft Agent Framework Overview — Microsoft Learn
Get Started: Steps 1–5 — Microsoft Learn
Repositorio oficial con samples — GitHub
Anuncio oficial: Semantic Kernel y Microsoft Agent Framework — Microsoft Dev Blog
Migration Guide from Semantic Kernel — Microsoft Learn

Sistema de Control de Jobs en Tiempo Real con Channels y Background Services en .NET

Isaac Ojeda — Sat, 01 Nov 2025 22:42:58 +0000

Introducción

En el desarrollo moderno de aplicaciones, es común necesitar ejecutar procesos en segundo plano que se comuniquen con nuestra API de forma eficiente y segura. Tradicionalmente, esto se resolvía con implementaciones complejas usando locks, colas manuales o infraestructura externa como RabbitMQ. Sin embargo, .NET ofrece una solución simple pero elegante: System.Threading.Channels.

En este artículo, exploraremos cómo construir un sistema de control de jobs en tiempo real utilizando:

🔧 Channels para comunicación thread-safe entre componentes
🔄 Background Services para tareas recurrentes
🚀 Minimal APIs para endpoints modernos y limpios
⚡ TaskCompletionSource para comunicación bidireccional

Al finalizar, tendrás un proyecto funcional que puedes adaptar para casos de uso reales como procesamiento de emails, análisis de imágenes, generación de reportes, y más.

Nota: El código fuente siempre lo encontrarás en mi github -> DevToPosts/ApiBackgroundChannels at main · isaacOjeda/DevToPosts

¿Qué son los Channels?

Los Channels en .NET son estructuras de datos thread-safe diseñadas para escenarios productor-consumidor. Piensa en ellos como una "tubería" donde un lado escribe datos y el otro los lee, sin preocuparte por locks o sincronización manual.

¿Por qué usarlos?

✅ Thread-safe por diseño
✅ Alta performance con bajo overhead
✅ Backpressure integrado (control de flujo)
✅ Ideal para comunicación entre hilos/tareas
✅ Alternativa simple a colas externas (RabbitMQ, Redis) para escenarios internos
✅ Optimizado para async/await (usa ValueTask internamente)

Arquitectura del Proyecto

Este proyecto demuestra cómo controlar un Background Job desde una API usando Channels para comunicación bidireccional:

┌──────────────┐         ┌─────────┐         ┌──────────────────┐
│  API Request │ ──────> │ Channel │ ──────> │ Background Job   │
│  (Productor) │         │ (Cola)  │         │ (Consumidor)     │
└──────────────┘         └─────────┘         └──────────────────┘
      ↑                                             │
      └────── TaskCompletionSource ─────────────────┘
                     (Respuesta)

Paso 1: Definir el Modelo de Comunicación

Primero, necesitamos estructuras para enviar comandos y recibir respuestas:

public enum CommandType { Start, Stop, GetStatus }

public class JobCommand
{
    public CommandType Type { get; set; }
    public TaskCompletionSource<JobStatus>? ResponseTask { get; set; }
}

public class JobStatus
{
    public bool IsRunning { get; set; }
    public int ExecutionCount { get; set; }
    public DateTime? LastExecutionTime { get; set; }
    public string Message { get; set; } = string.Empty;
}

💡 Clave: TaskCompletionSource nos permite crear una Task que completaremos manualmente cuando tengamos la respuesta, haciendo posible la comunicación bidireccional.

Paso 2: Crear el Background Service (Consumidor)

public class JobProcessor : BackgroundService
{
    private readonly Channel<JobCommand> _channel;
    private bool _isJobRunning = false;
    private int _executionCount = 0;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        _logger.LogInformation("JobProcessor iniciado. Esperando comandos...");

        // ✅ Patrón recomendado por Microsoft: WaitToReadAsync + TryRead
        // Más eficiente que ReadAllAsync para alta concurrencia
        while (await _channel.Reader.WaitToReadAsync(stoppingToken))
        {
            while (_channel.Reader.TryRead(out var command))
            {
                try
                {
                    await ProcessCommandAsync(command, stoppingToken);
                }
                catch (Exception ex)
                {
                    _logger.LogError(ex, "Error procesando comando");
                    // ✅ Notificar errores al productor
                    command.ResponseTask?.TrySetException(ex);
                }
            }
        }
    }

    private async Task ProcessCommandAsync(JobCommand command, CancellationToken token)
    {
        switch (command.Type)
        {
            case CommandType.Start:
                _isJobRunning = true;
                _ = Task.Run(async () => await RunRecurringJobAsync(token));

                // Enviar respuesta al productor
                command.ResponseTask?.SetResult(new JobStatus 
                { 
                    IsRunning = true, 
                    Message = "Job iniciado" 
                });
                break;

            case CommandType.Stop:
                _isJobRunning = false;
                command.ResponseTask?.SetResult(new JobStatus 
                { 
                    IsRunning = false, 
                    Message = "Job detenido" 
                });
                break;

            case CommandType.GetStatus:
                command.ResponseTask?.SetResult(new JobStatus
                {
                    IsRunning = _isJobRunning,
                    ExecutionCount = _executionCount
                });
                break;
        }
    }
}

WaitToReadAsync() + TryRead(): Patrón recomendado por Microsoft para mejor performance
TrySetException(): Propaga errores al productor de forma segura
Bucle anidado: Procesa múltiples comandos en batch cuando están disponibles

Paso 3: Configurar el Channel y el Servicio

En Program.cs:

// ✅ Bounded Channel con opciones optimizadas (recomendado por Microsoft)
builder.Services.AddSingleton(Channel.CreateBounded<JobCommand>(
    new BoundedChannelOptions(100)
    {
        FullMode = BoundedChannelFullMode.Wait, // Backpressure automático
        SingleWriter = false, // Múltiples endpoints pueden escribir
        SingleReader = true   // Solo un BackgroundService consume
    }));

// Registrar el Background Service
builder.Services.AddHostedService<JobProcessor>();

💡 ¿Bounded vs Unbounded?

Característica	Unbounded	Bounded
Capacidad	Ilimitada	Limitada (configurable)
Memoria	Puede crecer sin control	Controlada
Backpressure	No	Sí (automático)
Uso recomendado	Productores lentos	Productores rápidos
Performance	Writes síncronos	Writes pueden ser async

Modos de Bounded Channel (FullMode):

Wait (recomendado): Espera hasta que haya espacio (backpressure)
DropWrite: Descarta el nuevo elemento
DropOldest: Descarta el elemento más antiguo
DropNewest: Descarta el elemento más reciente

Opciones de optimización:

SingleWriter: true = mejor performance si solo un productor escribe
SingleReader: true = mejor performance si solo un consumidor lee
AllowSynchronousContinuations: false (default) para evitar bloqueos

Paso 4: Crear los Endpoints (Productores)

public static IEndpointRouteBuilder MapJobEndpoints(this IEndpointRouteBuilder app)
{
    var jobGroup = app.MapGroup("api/job");

    jobGroup.MapPost("start", async (Channel<JobCommand> channel) =>
    {
        // Crear TaskCompletionSource para esperar la respuesta
        var tcs = new TaskCompletionSource<JobStatus>();

        var command = new JobCommand
        {
            Type = CommandType.Start,
            ResponseTask = tcs
        };

        // ✅ WriteAsync maneja backpressure automáticamente
        await channel.Writer.WriteAsync(command);

        // Esperar respuesta del consumidor
        var status = await tcs.Task;
        return Results.Ok(status);
    });

    // Endpoints similares para stop y status...

    return app;
}

💡 Flujo:

API recibe request → Crea TaskCompletionSource
Escribe comando en el Channel con WriteAsync() (maneja backpressure)
Espera que el consumidor complete la Task
Retorna la respuesta al cliente

¿Por qué este patrón?

Sin Channels:

// ❌ Locks manuales, propenso a errores
private static readonly object _lock = new();
private static Queue<Command> _queue = new();

public void AddCommand(Command cmd)
{
    lock(_lock) { _queue.Enqueue(cmd); }
}

Con Channels:

// ✅ Thread-safe automático, limpio, con backpressure
await channel.Writer.WriteAsync(command);

Casos de Uso Reales con Channels

1. Cola de Emails/Notificaciones

// Microsoft recomienda Bounded para prevenir OutOfMemory
var emailChannel = Channel.CreateBounded<EmailMessage>(
    new BoundedChannelOptions(1000)
    {
        FullMode = BoundedChannelFullMode.Wait
    });
// API recibe requests → Encola en Channel → Background envía emails en lotes

2. Procesamiento de Imágenes

Channel<ImageProcessingJob> imageChannel;
// Upload de imágenes → Channel → Worker redimensiona/optimiza en background

3. Logs Centralizados

// DropOldest para logs: si está lleno, descarta los más antiguos
var logChannel = Channel.CreateBounded<LogEntry>(
    new BoundedChannelOptions(5000)
    {
        FullMode = BoundedChannelFullMode.DropOldest
    });

4. Rate Limiting / Throttling

var boundedChannel = Channel.CreateBounded<Request>(100);
// Limita a 100 requests concurrentes, el resto espera (backpressure)

5. Event Sourcing Interno

Channel<DomainEvent> eventChannel;
// Eventos de dominio → Channel → Múltiples handlers procesan en paralelo

6. Pipeline de Datos (ejemplo oficial de Microsoft)

// Patrón de processing pipeline con múltiples stages
Channel<RawData> inputChannel;
Channel<ProcessedData> outputChannel;
// Stage 1: Raw → Validated → Stage 2: Validated → Enriched

Usa Channels cuando:

✅ Comunicación dentro de la misma aplicación
✅ Necesitas alta performance y bajo latency
✅ Quieres simplicidad sin infraestructura externa
✅ Trabajas con async/await
✅ Necesitas backpressure automático

Usa Queue externo (RabbitMQ/Azure Service Bus) cuando:

❌ Necesitas comunicación entre múltiples aplicaciones/servicios
❌ Requieres persistencia de mensajes
❌ Necesitas escalabilidad horizontal
❌ Requieres garantías de entrega (at-least-once, exactly-once)

¿Por qué usar Channels?

A lo largo de este tutorial, hemos visto cómo Channels ofrece ventajas significativas:

Simplicidad: No necesitas infraestructura externa para empezar
Performance: Diseñados desde cero para async/await con ValueTask
Seguridad: Thread-safe por diseño, sin preocupaciones por race conditions
Control: Backpressure automático previene sobrecarga del sistema
Flexibilidad: Configuración granular según tus necesidades específicas

Impacto en tu arquitectura

Este patrón es especialmente valioso cuando:

Estás construyendo aplicaciones monolíticas modernas que necesitan procesamiento asíncrono
Quieres reducir costos de infraestructura eliminando dependencias de message brokers
Necesitas optimizar performance con procesamiento en memoria
Buscas simplicidad operacional sin sacrificar escalabilidad vertical

Los Channels de .NET demuestran que no siempre necesitas herramientas complejas para resolver problemas complejos. A veces, la solución más elegante es la que viene incorporada en tu framework.

Próximos Pasos

¿Listo para llevar este conocimiento al siguiente nivel? Aquí tienes algunas ideas para expandir este proyecto:

1. Implementar Múltiples Consumidores

// Escalar procesamiento con múltiples workers
builder.Services.AddHostedService<JobProcessor>(); // Worker 1
builder.Services.AddHostedService<JobProcessor>(); // Worker 2
builder.Services.AddHostedService<JobProcessor>(); // Worker 3

Aprenderás: Paralelización, distribución de carga, sincronización entre workers

2. Integrar Observabilidad

// Métricas con System.Diagnostics.Metrics
var meter = new Meter("BackgroundJobs");
var jobsProcessed = meter.CreateCounter<long>("jobs_processed");
var queueDepth = meter.CreateObservableGauge("queue_depth", 
    () => channel.Reader.Count);

Aprenderás: OpenTelemetry, métricas personalizadas, dashboards con Grafana/Prometheus

3. Implementar Persistencia

// Guardar estado en caso de restart
public class PersistentJobProcessor : BackgroundService
{
    private readonly IJobStateRepository _repository;

    protected override async Task ExecuteAsync(CancellationToken token)
    {
        // Recuperar jobs pendientes al iniciar
        await _repository.RestorePendingJobsAsync(token);
        // ... continuar procesamiento normal
    }
}

Aprenderás: State management, recovery strategies, durabilidad

4. Agregar Pipeline de Procesamiento

// Pipeline multi-etapa
var rawChannel = Channel.CreateBounded<RawData>(100);
var validatedChannel = Channel.CreateBounded<ValidatedData>(100);
var enrichedChannel = Channel.CreateBounded<EnrichedData>(100);

// Stage 1: Validación
builder.Services.AddHostedService<ValidationProcessor>();
// Stage 2: Enriquecimiento
builder.Services.AddHostedService<EnrichmentProcessor>();
// Stage 3: Persistencia
builder.Services.AddHostedService<PersistenceProcessor>();

Aprenderás: Pipeline pattern, ETL processes, data transformation

5. Implementar Rate Limiting Avanzado

// Rate limiter con ventanas deslizantes
public class RateLimitedJobProcessor : BackgroundService
{
    private readonly RateLimiter _rateLimiter;

    protected override async Task ExecuteAsync(CancellationToken token)
    {
        while (await _channel.Reader.WaitToReadAsync(token))
        {
            using var lease = await _rateLimiter.AcquireAsync(1, token);
            if (lease.IsAcquired)
            {
                // Procesar job
            }
        }
    }
}

Aprenderás: Rate limiting patterns, token bucket, leaky bucket

6. Crear Dashboard de Monitoreo

// SignalR para updates en tiempo real
builder.Services.AddSignalR();

// Notificar estado a clientes conectados
await _hubContext.Clients.All.SendAsync("JobStatusUpdate", new {
    QueueDepth = channel.Reader.Count,
    ProcessingRate = jobsPerSecond,
    ActiveJobs = activeJobCount
});

Aprenderás: Real-time updates, SignalR, live dashboards

7. Añadir Resiliencia

// Polly para retry policies
var retryPolicy = Policy
    .Handle<Exception>()
    .WaitAndRetryAsync(3, retryAttempt => 
        TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)));

await retryPolicy.ExecuteAsync(async () => 
{
    await ProcessJobAsync(command);
});

Aprenderás: Retry patterns, circuit breakers, fallback strategies

8. Implementar Health Checks

// Health check para el channel
builder.Services.AddHealthChecks()
    .AddCheck<ChannelHealthCheck>("channel_health")
    .AddCheck<JobProcessorHealthCheck>("job_processor_health");

public class ChannelHealthCheck : IHealthCheck
{
    public Task<HealthCheckResult> CheckHealthAsync()
    {
        var queueDepth = _channel.Reader.Count;
        return queueDepth < 1000 
            ? HealthCheckResult.Healthy() 
            : HealthCheckResult.Degraded("Queue depth high");
    }
}

Aprenderás: Health monitoring, readiness/liveness probes, Kubernetes integration

9. Migrar a Arquitectura Distribuida

// Cuando crezcas más allá de un solo servidor
// Considera migrar a:
// - Azure Service Bus para messaging distribuido
// - Azure Queue Storage para simplicidad y bajo costo
// - RabbitMQ para control total
// - Redis Streams para alta performance

// Mantén la misma interfaz, cambia la implementación
public interface IJobQueue
{
    Task EnqueueAsync(JobCommand command);
    Task<JobCommand> DequeueAsync(CancellationToken token);
}

// Implementación con Channels (actual)
public class InMemoryJobQueue : IJobQueue { }

// Implementación con Azure Service Bus (futuro)
public class ServiceBusJobQueue : IJobQueue { }

Aprenderás: Estrategias de migración, abstracciones, arquitectura evolutiva

Recursos para Continuar Aprendiendo

Documentación Oficial:

Artículos Avanzados:

[Parte 4] Construyendo un Agente Conversacional con el Agent Framework de Semantic Kernel

Isaac Ojeda — Sat, 19 Jul 2025 18:56:35 +0000

🧠 Crea tu propio agente conversacional con Semantic Kernel

¿Te imaginas construir un asistente conversacional que entienda lenguaje natural y, además, sea capaz de ejecutar funciones reales de tu sistema? Con el Agent Framework de Semantic Kernel, eso ya no es solo posible, sino sorprendentemente sencillo.

En este tutorial te voy a mostrar cómo crear un agente inteligente especializado en gestión de facturas, diseñado para ayudar a abogados en una notaría pública. Este agente no solo entiende lo que le pides, sino que también puede:

Consultar el estado de una factura.
Crear prefacturas automáticamente.
Ver facturas vencidas.
Marcar facturas como pagadas.
Obtener información detallada de un cliente.

Todo esto lo logra invocando funciones reales en C#, conectadas a una base de datos real y expuestas mediante un plugin personalizado.

Durante el artículo veremos paso a paso:

Cómo configurar Semantic Kernel con Azure OpenAI.
Cómo definir tus propias funciones con [KernelFunction].
Cómo crear un ChatCompletionAgent con instrucciones personalizadas.
Cómo ejecutar al agente dentro de una API HTTP.
Y cómo mantener conversaciones con historial persistente.

Además, el proyecto incluye un cliente web de ejemplo (tipo chat) para que puedas probarlo todo en vivo y adaptar la solución a tus propios casos de uso.

🔗 Todo el código está disponible en este repositorio:

github.com/isaacOjeda/DevToPosts/tree/main/SemanticKernelSeries/SemanticKernelLearning04

🧠 ¿Qué es el Agent Framework en Semantic Kernel?

El Agent Framework es una de las capacidades más potentes introducidas en las versiones recientes de Semantic Kernel: un sistema que permite crear agentes conversacionales inteligentes con la capacidad de razonar, planificar e invocar funciones definidas por el desarrollador para lograr un objetivo.

A diferencia de un chatbot tradicional basado en reglas, un agente en Semantic Kernel:

Comprende instrucciones en lenguaje natural.
Decide qué acciones tomar en base al contexto disponible.
Invoca funciones (también llamadas “skills” o “plugins”) que tú defines en código.
Puede encadenar múltiples pasos de razonamiento para llegar a un resultado.

Este modelo es ideal para construir asistentes especializados con conocimientos de negocio y herramientas personalizadas.

🎯 Caso de uso: un asistente de facturación

En este tutorial vamos a construir un ejemplo real usando el Agent Framework: un asistente conversacional para abogados en una notaría pública, cuya función es gestionar facturas mediante lenguaje natural.

El asistente será capaz de:

Verificar si una factura está pagada o vencida.
Crear prefacturas para clientes nuevos.
Consultar el listado de facturas pendientes de pago.
Marcar una factura como pagada.
Obtener información detallada de un cliente y su historial de facturación.

Todo esto será posible gracias a una capa de funciones en C# expuestas al agente mediante anotaciones [KernelFunction], y alimentadas por un servicio de backend que accede a la base de datos.

🧬 ¿Por qué usar agentes en lugar de comandos o controladores tradicionales?

Con el Agent Framework:

El usuario no necesita conocer los comandos disponibles.
El agente elige por sí mismo la función que debe usar.
Puedes cambiar o extender el comportamiento del sistema sin modificar el frontend.
La experiencia es más natural, fluida y adaptable a distintos usuarios.

Esto hace que construir asistentes LLM especializados con Semantic Kernel sea una excelente opción para interfaces inteligentes sobre sistemas de negocio existentes, especialmente en entornos con operaciones rutinarias, como la gestión de facturas.

⚙️ Requisitos previos y setup del entorno

Antes de construir nuestro asistente de facturación, necesitamos preparar nuestro proyecto con las dependencias necesarias y configurar el acceso a un modelo de lenguaje compatible (en este caso, Azure OpenAI).

Este ejemplo está construido sobre .NET 9, con soporte para SQLite como base de datos local, y aprovecha la integración entre Semantic Kernel y Azure OpenAI.

🗂️ Puedes consultar el código completo y funcional de este proyecto en el repositorio:

🔗 github.com/isaacOjeda/DevToPosts/tree/main/SemanticKernelSeries/SemanticKernelLearning04

Allí encontrarás todos los archivos de configuración, modelos, servicios y ejemplos necesarios para correr este asistente de forma local o integrarlo en tu aplicación.

📦 Paquetes necesarios

El Agent Framework se encuentra dentro del paquete Microsoft.SemanticKernel.Agents.Core, por lo que debes incluir explícitamente las dependencias en tu archivo .csproj.

<ItemGroup>
  <PackageReference Include="Microsoft.SemanticKernel" Version="1.60.0" />
  <PackageReference Include="Microsoft.SemanticKernel.Agents.Core" Version="1.60.0" />
  <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.7" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="9.0.0" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="9.0.0" />
  <PackageReference Include="Microsoft.VisualStudio.Azure.Containers.Tools.Targets" Version="1.22.1" />
</ItemGroup>

Esto nos da acceso al núcleo de Semantic Kernel, las capacidades de agentes, así como herramientas necesarias para la persistencia y desarrollo web.

🧪 Configurando el Kernel

El kernel es el núcleo que conecta el modelo de lenguaje con tus plugins. En este ejemplo, usamos Azure OpenAI para procesar instrucciones en lenguaje natural. A continuación se muestra cómo configurar el kernel con los valores de appsettings.json:

public static IServiceCollection AddSemanticKernel(this IServiceCollection services, IConfiguration configuration)
{
    var azureOpenAIConfig = configuration.GetSection("AzureOpenAI");

    services.AddAzureOpenAIChatCompletion(
        deploymentName: azureOpenAIConfig["DeploymentName"]!,
        apiKey: azureOpenAIConfig["ApiKey"]!,
        endpoint: azureOpenAIConfig["Endpoint"]!,
        modelId: azureOpenAIConfig["ModelId"]!
    );

    services.AddTransient(serviceProvider => new Kernel(serviceProvider));

    return services;
}

La configuración en appsettings.json se vería algo así:

"AzureOpenAI": {
  "DeploymentName": "notaria-assistant",
  "ApiKey": "TU_API_KEY",
  "Endpoint": "https://tuservicio.openai.azure.com/",
  "ModelId": "gpt-35-turbo"
}

Con esto, el Kernel queda disponible vía inyección de dependencias y listo para clonar, personalizar o conectar a nuestros agentes.

🧱 Servicios base y modelos de dominio

Nuestro agente necesita acceder a datos del mundo real, por lo que construimos un servicio InvoiceService con métodos como:

GetInvoiceByNumberAsync
CreateInvoiceAsync
MarkInvoiceAsPaidAsync
GetUnpaidInvoicesAsync
GetCustomerByEmailAsync

Este servicio será inyectado en el plugin que veremos en la próxima sección, y expone la lógica de negocio que el agente puede usar para resolver instrucciones. Si ya tienes una capa de servicios en tu aplicación, puedes integrarla directamente.

🧩 Definir tus funciones (skills/plugins)

Una de las capacidades más poderosas del Agent Framework es permitir que tus agentes ejecuten funciones reales escritas en C#. Estas funciones se registran como "plugins" usando decoradores especiales, y luego el agente las puede invocar cuando detecta que son necesarias para cumplir una instrucción del usuario.

En este caso, hemos creado un plugin llamado InvoicesPlugin, que expone cinco funciones relacionadas con facturación. Cada una está decorada con el atributo [KernelFunction], lo que la hace visible para Semantic Kernel.

🧠 ¿Qué es un plugin?

Un plugin en Semantic Kernel es simplemente una clase con métodos públicos asincrónicos decorados con [KernelFunction]. Además, puedes usar [Description] en los parámetros y métodos para mejorar la comprensión del agente sobre lo que hace cada función.

🗂️ El código completo del plugin puede consultarse en el repositorio:

Ver InvoicesPlugin.cs en GitHub

🧾 Ejemplo 1: Verificar el estado de una factura

[KernelFunction]
[Description("Verifica el estado de pago de una factura específica usando su número de factura.")]
public async Task<string> VerifyPaymentAsync(
    [Description("Número de la factura a verificar (ej: INV-202412-0001)")] string numeroFactura)
{
    var invoice = await invoiceService.GetInvoiceByNumberAsync(numeroFactura);

    if (invoice == null)
        return $"❌ No se encontró ninguna factura con el número: {numeroFactura}";

    var result = new StringBuilder();
    result.AppendLine($"📋 **Factura: {invoice.InvoiceNumber}**");
    result.AppendLine($"🔸 Estado: {GetStatusText(invoice.Status)}");
    // ...otros campos visuales

    return result.ToString();
}

💡 Nota:

En este ejemplo, todas las funciones del plugin reciben y retornan datos en formato string, ya que el enfoque está en mantener el ejemplo simple y fácil de seguir.

Sin embargo, el Agent Framework de Semantic Kernel soporta objetos complejos como parámetros de entrada y salida. Puedes retornar clases personalizadas, listas u objetos anidados, y el agente será capaz de interpretarlos, formatearlos o incluso razonar sobre ellos en sus respuestas.

En un escenario real, podrías devolver una InvoiceDetail con propiedades estructuradas en lugar de una cadena formateada, lo que abre la puerta a integraciones más ricas o adaptadas al canal (por ejemplo, APIs, UIs o chatbots).

Este método se encarga de buscar una factura por número y devolver su estado, fecha de vencimiento, monto y otra información útil. Como puedes ver, el resultado se formatea para ser legible y amigable, incluyendo emojis para mejorar la experiencia.

✍️ Ejemplo 2: Crear una prefactura

[KernelFunction]
[Description("Realiza una prefactura para un cliente usando email, descripción, monto y días hasta el vencimiento.")]
public async Task<string> CreateInvoiceDraftAsync(
    string clienteEmail,
    string descripcion,
    decimal monto,
    int diasVencimiento = 30)
{
    var customer = await invoiceService.GetCustomerByEmailAsync(clienteEmail);
    if (customer == null)
        return $"❌ No se encontró ningún cliente con el email: {clienteEmail}";

    var dueDate = DateTime.UtcNow.AddDays(diasVencimiento);
    var invoice = await invoiceService.CreateInvoiceAsync(
        customer.Id, descripcion, monto, dueDate, "Factura generada automáticamente");

    return $"✅ Prefactura creada: {invoice.InvoiceNumber} para {customer.Name}";
}

Este método genera una factura en estado "borrador", útil para cuando un abogado quiere adelantar una facturación para un cliente específico.

🧠 ¿Por qué usar `[KernelFunction]`?

Al decorar tus funciones con este atributo, estás dando al agente la capacidad de:

Descubrir qué herramientas tiene disponibles.
Seleccionar de forma automática la función correcta en base a la intención del usuario.
Combinar funciones si es necesario (por ejemplo, buscar cliente → generar factura).

Gracias a esto, no necesitas escribir prompts complejos ni reglas condicionales. El agente decide qué hacer en tiempo de ejecución.

🤖 Crear un agente y asignarle objetivos

Una vez que tenemos definido nuestro plugin con las funciones necesarias, es hora de crear un agente que lo utilice. Un agente es una instancia del tipo ChatCompletionAgent que sabe cómo interactuar con un modelo de lenguaje, tiene acceso a un conjunto de funciones y puede operar con base en instrucciones personalizadas.

En este paso lo conectamos todo: el kernel, el plugin, y la intención del asistente.

🧠 ¿Qué es un `ChatCompletionAgent`?

El ChatCompletionAgent es una implementación del Agent Framework de Semantic Kernel que permite interactuar con modelos de lenguaje compatibles (como GPT-4 o GPT-3.5) de forma conversacional. Este tipo de agente:

Usa un kernel preconfigurado con modelos y funciones.
Puede tener instrucciones personalizadas (“persona” o “rol”).
Decide automáticamente qué función usar, si corresponde.
Mantiene un contexto conversacional.

🏗️ Registrando el agente con DI

En este ejemplo, configuramos el agente como un servicio usando la extensión AddAgents. Esto permite que el agente se cree con acceso al kernel y al InvoicesPlugin:

services.AddKeyedTransient<ChatCompletionAgent>("AssistantAgent", (sp, _) =>
{
    var kernel = sp.GetRequiredService<Kernel>();
    var agentKernel = kernel.Clone();

    // Registramos el plugin de facturas
    var invoiceService = sp.GetRequiredService<InvoiceService>();
    agentKernel.ImportPluginFromObject(new InvoicesPlugin(invoiceService));

    var agent = new ChatCompletionAgent()
    {
        Name = "Asistente",
        Instructions = """
            Eres un asistente de abogados en una notaría pública. 
            Tu tarea es ayudar a los abogados a gestionar y verificar el estado de las facturas.

            Funciones disponibles:
            - Verificar el estado de pago de facturas específicas
            - Crear prefacturas para clientes
            - Consultar facturas pendientes de pago
            - Marcar facturas como pagadas
            - Consultar información de clientes

            Siempre proporciona información clara y detallada sobre el estado de las facturas.
            Usa emojis para hacer las respuestas más visuales y fáciles de entender.
        """,
        Kernel = agentKernel,
        Arguments = new KernelArguments(
            new OpenAIPromptExecutionSettings()
            {
                FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
            })
    };

    return agent;
});

🧩 Este agente se construye a partir de un Kernel clonado. Así puedes tener múltiples agentes con diferentes plugins, instrucciones o configuraciones sin interferencias entre ellos.

🗣️ Instrucciones: cómo le decimos al agente quién es

La propiedad Instructions permite definir la personalidad, contexto y objetivos del agente. Aquí estamos usando un sistema de "prompt largo" al estilo system message:

Instructions = """
    Eres un asistente de abogados en una notaría pública. 
    Tu tarea es ayudar a los abogados a gestionar y verificar el estado de las facturas.
    ...
"""

Este mensaje guía al modelo para que entienda el contexto en el que opera, el lenguaje que debe usar y el tipo de resultados esperados.

⚙️ Control de funciones automáticas

El fragmento clave para habilitar la selección automática de funciones es:

Arguments = new KernelArguments(
    new OpenAIPromptExecutionSettings()
    {
        FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
    })

Esto permite que el modelo analice la intención del usuario y decida si debe invocar alguna función del plugin registrado. No es necesario indicarle explícitamente el nombre de la función: el agente elige por sí mismo en función del mensaje recibido.

Con este paso, ya tenemos un asistente especializado corriendo sobre Semantic Kernel, con acceso completo a las funciones del plugin de facturación y configurado para operar en el contexto de una notaría pública.

🚀 Ejecutar el agente y manejar conversaciones

Una vez que nuestro agente está registrado y conectado a sus funciones, llega el momento de ponerlo en acción. En este ejemplo, creamos una API HTTP que permite a cualquier cliente (como una app web o móvil) interactuar con el asistente de forma conversacional.

Todo el ciclo se orquesta desde un conjunto de endpoints dentro de AgentEndpoints.cs.

🌐 Endpoint para iniciar una conversación

El primer paso en cualquier interacción es crear un hilo de conversación. Esto permite almacenar el historial y mantener contexto entre múltiples mensajes.

group.MapPost("/start", async (ConversationService conversationService) =>
{
    var conversationId = await conversationService.CreateConversationAsync();
    return Results.Ok(new { ConversationId = conversationId });
});

Este endpoint genera un ConversationId único que luego será utilizado en cada mensaje posterior. La conversación se almacena en la base de datos con su historial asociado.

💬 Enviar una pregunta al agente

El segundo endpoint es el más importante: recibe un mensaje del usuario y devuelve la respuesta del agente. Lo interesante es que reconstruye el historial completo antes de invocar el modelo, lo que permite mantener coherencia y continuidad.

group.MapPost("/", async (AskQuestionRequest request,
    [FromKeyedServices("AssistantAgent")] ChatCompletionAgent agent,
    ConversationService conversationService) =>
{
    // ... Obtener historial desde base de datos
    // ... Agregar mensaje del usuario actual
    // ... Crear ChatHistoryAgentThread y lanzar la invocación
});

📜 Cómo se construye el historial

El historial de conversación se crea a partir de los mensajes previos almacenados en la base de datos:

var chatHistory = new ChatHistory();
foreach (var dbMessage in conversation.Messages)
{
    if (dbMessage.Role == "user")
        chatHistory.AddUserMessage(dbMessage.Content);
    else if (dbMessage.Role == "assistant")
        chatHistory.AddAssistantMessage(dbMessage.Content);
}

Después se añade el nuevo mensaje del usuario, y se encapsula todo en un ChatHistoryAgentThread, que es el tipo de contexto que entiende el agente:

chatHistory.AddUserMessage(request.Question);
var thread = new ChatHistoryAgentThread(chatHistory, request.ThreadId);

🧠 Ejecutar al agente y procesar respuestas

El agente se invoca de forma asíncrona usando InvokeAsync, lo que permite recibir múltiples respuestas si el modelo decide dividir su salida (especialmente útil cuando hay invocación de funciones):

var responses = agent.InvokeAsync(request.Question, thread);

var allResponses = new List<string>();
await foreach (var agentResponse in responses)
{
    var content = agentResponse.Message.Content ?? string.Empty;
    if (!string.IsNullOrWhiteSpace(content))
    {
        allResponses.Add(content);
    }
}

Luego se combinan todas las respuestas en un solo mensaje y se guarda nuevamente en la base de datos:

var finalResponse = string.Join("\n\n", allResponses);
await conversationService.AddMessageAsync(request.ThreadId, finalResponse, "assistant");

✅ Respuesta final

El resultado es una experiencia completamente conversacional, persistente y con funciones automatizadas. El cliente (por ejemplo, una SPA en Blazor o React) solo necesita enviar preguntas con un ConversationId y mostrar las respuestas generadas.

📌 ¿Por qué usar historial y contexto?

Esto es clave para que el agente pueda entender preguntas como:

“¿Y esa factura de Juan ya se pagó?”

Sin historial, el modelo no sabría a qué se refiere “esa factura”. Al mantener contexto, el agente puede hacer inferencias y ejecutar funciones con mayor precisión.

Con esto, tenemos todo lo necesario para una experiencia de agente conversacional real, persistente, funcional y extensible.

📁 Nota:

Recuerda que el código completo está disponible en el repositorio, incluyendo el contexto de la base de datos y la implementación completa de ConversationService, que se encarga de crear conversaciones, almacenar mensajes y reconstruir el historial.

🔗 Ver el proyecto en GitHub

🧰 Extras, buenas prácticas y posibles extensiones

Hasta este punto ya tienes un agente conversacional funcional, conectado a un modelo de lenguaje, con un plugin personalizado, y persistencia completa de las conversaciones. Sin embargo, el Agent Framework de Semantic Kernel ofrece muchas oportunidades para llevar tu solución al siguiente nivel.

A continuación, te comparto algunas ideas para extender o mejorar tu asistente.

🔗 Agentes con múltiples plugins

El Kernel puede importar múltiples plugins, no solo uno. Por ejemplo, podrías tener:

InvoicesPlugin: para gestión de facturas.
CalendarPlugin: para gestionar eventos o vencimientos.
EmailPlugin: para enviar notificaciones automáticas.

agentKernel.ImportPluginFromObject(new CalendarPlugin(...));
agentKernel.ImportPluginFromObject(new EmailPlugin(...));

Esto permite que el mismo agente decida qué herramienta usar dependiendo del mensaje del usuario, sin que tengas que escribir lógica adicional.

🧠 Agentes que planifican múltiples pasos

El Agent Framework incluye soporte experimental para planificación automática, donde el modelo puede decidir ejecutar múltiples funciones encadenadas para lograr un objetivo complejo.

Por ejemplo:

“Crea una prefactura para Carlos y márcala como pagada.”

Esto podría generar un plan con dos pasos: CreateInvoiceDraftAsync → MarkInvoiceAsPaidAsync.

El agente puede manejar estas secuencias si se configura con FunctionCalling en modo Auto() y si las funciones están bien descritas.

🧪 Testing y depuración

Cuando construyes agentes que llaman funciones reales, es importante:

Probar con mensajes ambiguos o incompletos para ver cómo reacciona el agente.
Monitorear los logs de funciones invocadas.
Verificar qué parámetros está eligiendo el modelo.
Utilizar FunctionResult para obtener metadata sobre las llamadas.

También puedes capturar los mensajes generados por el modelo para analizarlos más adelante, por ejemplo, almacenando las decisiones o planes generados en una tabla de auditoría.

⚠️ Cuida la experiencia conversacional

Algunos consejos prácticos para que el asistente se sienta más natural:

Usa emojis y lenguaje cercano si el público lo permite (como hicimos aquí).
Asegúrate de que las respuestas siempre incluyan lo esencial, incluso si no hay datos (ej: “no hay facturas vencidas”).
Controla el tamaño del historial para evitar prompts excesivamente largos.
Maneja errores con mensajes claros: si una factura no existe, si el email es inválido, etc.

🧩 Integración con interfaces visuales

Aunque este ejemplo se enfoca en la API HTTP y el backend del agente, la interacción no termina ahí. Puedes conectar este agente conversacional a diferentes interfaces gráficas según tu contexto:

Una aplicación web (por ejemplo, Blazor, React, Angular).
Un chatbot embebido en tu intranet o sitio público.
Clientes móviles nativos.
Canales como Microsoft Teams, Telegram o WhatsApp.

💬 Importante:

El repositorio del proyecto incluye un chat funcional ya implementado que se comunica con esta API y permite mantener conversaciones con el agente.

Este cliente está disponible como referencia y punto de exploración: puedes ver cómo se estructuran los hilos, cómo se muestra el historial y cómo se consume el endpoint /api/agent.

🔗 Ver el repositorio en GitHub

Este ejemplo es ideal para experimentar con el flujo completo: desde el frontend que envía preguntas, hasta el agente que responde y persiste el historial.

🌱 ¿Qué más podrías construir con este enfoque?

El Agent Framework es ideal para automatizar tareas repetitivas en sistemas internos. Algunos ejemplos reales donde este enfoque encaja:

Asistentes de soporte técnico interno (consultar errores, reiniciar servicios).
Asistentes legales que redactan contratos o extraen cláusulas.
Agentes que combinan datos de distintas fuentes (facturas + clientes + CRM).
Robots de backoffice que ayudan a generar informes o consolidar información.

📌 Consejo final:

Piensa en tu agente como un colega digital: cuantas más herramientas le des, más tareas podrá resolver sin que tú tengas que intervenir manualmente.

✅ Conclusión

El Agent Framework de Semantic Kernel abre una puerta poderosa para construir aplicaciones inteligentes que combinan lenguaje natural con lógica de negocio real. En este artículo, creamos un agente conversacional especializado en facturación, capaz de razonar sobre peticiones del usuario e invocar funciones de una aplicación en .NET.

Hemos visto cómo:

Configurar un Kernel con Azure OpenAI.
Exponer funciones reales como plugins usando [KernelFunction].
Construir y personalizar un agente con instrucciones específicas.
Mantener conversaciones persistentes con historial contextual.
Integrar todo en una API funcional, lista para usarse desde un cliente.

Este enfoque es aplicable a muchísimos casos reales: desde automatización interna hasta asistentes legales, técnicos o administrativos.

💡 Lo mejor de todo es que puedes extender esta base fácilmente: agregar nuevos plugins, integrar fuentes de datos adicionales, o escalar hacia canales como webchat, Teams o bots en producción.

Si te interesa explorar más sobre cómo usar Semantic Kernel en escenarios del mundo real, o quieres construir asistentes más sofisticados, este es apenas el comienzo.

🔗 Recuerda que el código completo está disponible aquí:

github.com/isaacOjeda/DevToPosts/tree/main/SemanticKernelSeries/SemanticKernelLearning04

📚 Referencias

Si quieres seguir explorando el Agent Framework de Semantic Kernel y todas sus posibilidades en C#, aquí tienes enlaces oficiales de documentación que complementan lo visto en este artículo:

Semantic Kernel – Parte 03: Embeddings y Retrieval-Augmented Generation (RAG)

Isaac Ojeda — Sun, 16 Feb 2025 17:00:31 +0000

Introducción

En esta tercera parte de nuestra serie sobre Semantic Kernel, nos adentramos en la integración de Embeddings y Retrieval-Augmented Generation (RAG) para mejorar la generación de contenido y la recuperación de información. Utilizando herramientas como Ollama para la creación de embeddings y Qdrant como vector store, podemos construir sistemas más inteligentes capaces de generar respuestas más precisas basadas en datos externos y actualizados, en lugar de depender únicamente de los datos con los que fue entrenado el modelo. A través de esta configuración, aprovechamos la sinergia entre el poder de los modelos de lenguaje y la capacidad de búsqueda semántica para proporcionar soluciones más efectivas a las consultas de los usuarios. En este artículo, exploraremos cómo implementar estas tecnologías en Semantic Kernel, con ejemplos prácticos para configurar los servicios y gestionar los embeddings de manera eficiente.

¿Qué son los Embeddings?

Los embeddings son representaciones numéricas de texto en un espacio vectorial de alta dimensión. Estas representaciones permiten medir la similitud semántica entre palabras, frases o documentos completos. En el contexto de Semantic Kernel, los embeddings se utilizan para mejorar la búsqueda de información y la generación de respuestas basadas en conocimiento almacenado.

Características clave de los Embeddings:

Capturan el significado semántico del texto.
Permiten encontrar contenido relacionado aunque no se utilicen exactamente las mismas palabras.
Se almacenan en bases de datos especializadas llamadas vector stores (como Qdrant).
Se generan con modelos de lenguaje avanzados, como los proporcionados por Ollama u Open AI.

¿Qué es RAG (Retrieval-Augmented Generation)?

Retrieval-Augmented Generation (RAG) es una técnica que combina la recuperación de información con la generación de respuestas mediante un modelo de lenguaje. En lugar de confiar solo en los datos con los que fue entrenado el modelo, RAG permite buscar información relevante en bases de conocimiento externas y utilizarla para generar respuestas más precisas y actualizadas.

Funcionamiento de RAG en Semantic Kernel:

Consulta del usuario: Un usuario hace una pregunta o solicitud.
Búsqueda semántica:
- Se generan embeddings de la consulta.
- Se comparan con los embeddings almacenados en el vector store (Qdrant) para recuperar información relevante.
Generación de respuesta:
- La información recuperada se pasa como contexto al modelo de lenguaje.
- Se genera una respuesta más precisa y fundamentada en los datos encontrados.

Beneficios de RAG en Semantic Kernel:

Mejor comprensión de consultas: Permite obtener respuestas relevantes incluso si el usuario no usa palabras exactas.
Conocimiento actualizado: Se pueden agregar nuevos datos al sistema sin necesidad de reentrenar el modelo de IA.
Optimización del procesamiento: Reduce el costo computacional al recuperar solo la información relevante en lugar de analizar todo el corpus de datos.

Configurando Semantic Kernel con Embeddings y un Vector Store

En esta sección, configuraremos Semantic Kernel para trabajar con Embeddings y un Vector Store, utilizando Aspire para orquestar los servicios.

Los servicios principales que vamos a configurar son:

llama3.2: Modelo generador de texto.
nomic-embed-text: Modelo generador de embeddings.
Qdrant: Almacenamiento y recuperación de embeddings.
Aspire: Orquestación y despliegue de los servicios.

Configuración de Aspire

Aspire nos permite definir y gestionar los servicios necesarios en un solo archivo de configuración. En este caso, configuramos Qdrant como nuestro vector store y llama3.2 y nomic-embed-text como proveedor de embeddings.

Nota 💡: Esto ya lo hemos visto en los otros posts, siempre usa como referencia el código fuente (DevToPosts/SemanticKernelSeries/SemanticKernelLearning03 at main · isaacOjeda/DevToPosts) para más información.

var builder = DistributedApplication.CreateBuilder(args);

// Configuración de Qdrant
var qdrant = builder.AddQdrant("qdrant")
    .WithLifetime(ContainerLifetime.Persistent);

// Configuración de Ollama
var ollama =
    builder.AddOllama("ollama")
        .WithDataVolume()
        .WithOpenWebUI();

// Modelos de Ollama
var llamaModel = ollama.AddModel("llama", "llama3.2");
var embedding = ollama.AddModel("embed-text", "nomic-embed-text");

// Configuración del API Service con referencias a los modelos y Qdrant
var apiService = builder.AddProject<Projects.SemanticKernelLearning03_ApiService>("apiservice")
    .WithReference(llamaModel)
    .WithReference(embedding)
    .WithReference(qdrant);

// Construcción y ejecución de Aspire
builder.Build().Run();

Qdrant se configura como un servicio persistente.
- Se hace de esta forma para que no sea tan lento de inicializar en cada inicio de Aspire.
Ollama se configura con almacenamiento de datos y una interfaz web.
- Se añaden los modelos "llama3.2" para generación de texto y "nomic-embed-text" para embeddings.
Por último se agrega nuestra API en ASP.NET Core.
Configuración de Semantic Kernel con Aspire

Aspire se encargará de inyectar las cadenas de conexión en la API, según los nombres definidos en la configuración.

Para hacer que Semantic Kernel utilice correctamente los servicios orquestados por Aspire, debemos procesar estas cadenas de conexión. Como lo hemos hecho en ejemplos anteriores, parsearemos la información recibida y estructuraremos mejor nuestra configuración.

Para lograr esto, separaremos la configuración de dependencias en un archivo específico, lo que nos permitirá mantener un código más limpio y modular.

Creando `DependencyConfig.cs` para gestionar las dependencias

En este archivo, crearemos el método de extensión AddSemanticKernel, el cual:

Obtiene las cadenas de conexión inyectadas por Aspire.
Extrae los detalles necesarios de Ollama (para generación de texto y embeddings).
Extrae la información de conexión a Qdrant (Vector Store).
Registra los servicios de Semantic Kernel con las dependencias configuradas.
Agrega un servicio de búsqueda semántica (ITextSearch) que permite realizar búsquedas en una colección de vectores, el cual usaremos más adelante.

Aquí está el código en DependencyConfig.cs:

public static class DependencyConfig
{
    public static void AddSemanticKernel(this WebApplicationBuilder builder)
    {
        var (endpoint, completionModel) =
            GetModelDetailsFromConnectionString(builder.Configuration.GetConnectionString("llama")!);
        var (_, embeddingModel) =
            GetModelDetailsFromConnectionString(builder.Configuration.GetConnectionString("embed-text")!);
        var (host, port, apiKey) =
            GetQdrantDetailsFromConnectionString(builder.Configuration.GetConnectionString("qdrant")!);

        builder.Services.AddKernel()
            .AddOllamaChatCompletion(completionModel, endpoint)
            .AddOllamaTextEmbeddingGeneration(embeddingModel, endpoint)
            .AddQdrantVectorStore(host: host, port: port, apiKey: apiKey);

        builder.Services.AddKeyedTransient<ITextSearch>(BlogPost.VectorName, (sp, _) =>
        {
            var vectorStore = sp.GetRequiredService<IVectorStore>();
            var embeddingGenerationService = sp.GetRequiredService<ITextEmbeddingGenerationService>();

            var blogposts = vectorStore.GetCollection<Guid, BlogPost>(BlogPost.VectorName);

            blogposts.CreateCollectionIfNotExistsAsync().ConfigureAwait(true);

            var textSearch = new VectorStoreTextSearch<BlogPost>(blogposts, embeddingGenerationService);

            return textSearch;
        });
    }
}

Explicación del código

Obtenemos los detalles de conexión
- GetModelDetailsFromConnectionString extrae el modelo y endpoint desde las cadenas de conexión de Ollama (chat y embeddings).
- GetQdrantDetailsFromConnectionString extrae el host, puerto y API key de Qdrant.
Registramos los servicios de Semantic Kernel
- AddOllamaChatCompletion para generación de texto con Ollama.
- AddOllamaTextEmbeddingGeneration para generación de embeddings.
- AddQdrantVectorStore para almacenar y recuperar datos desde Qdrant.
Configuramos un servicio de búsqueda semántica (ITextSearch)
- Se obtiene la colección de vectores asociada a BlogPost.
- Si la colección no existe, se crea automáticamente en Qdrant.
- Se inicializa un objeto VectorStoreTextSearch<BlogPost>, permitiendo realizar búsquedas semánticas en la colección.

Almacenando Embeddings en Qdrant

Para almacenar datos en Qdrant, primero debemos definir nuestro modelo de datos que será indexado en la base de datos vectorial.

En este ejemplo, queremos guardar una serie de posts y realizar búsquedas semánticas sobre su contenido.

Advertencia ⚠️: Las búsquedas vectoriales que estamos viendo aquí están en Preview (Alpha), por lo que podrían cambiar en el futuro. Actualmente, no se recomienda su uso en producción, a menos que estés dispuesto a evolucionar junto con el framework.
Anteriormente, se utilizaban los Memory de Semantic Kernel para búsquedas similares, pero estos están en proceso de ser considerados "Legacy", por lo que su uso a largo plazo podría no ser viable.

Definición del modelo `BlogPost`

El modelo BlogPost representará las entradas del blog en nuestra base de datos vectorial.

public class BlogPost
{
    public const string VectorName = "blogposts";

    [VectorStoreRecordKey]
    [TextSearchResultLink]
    public Guid BlogPostId { get; set; }

    [VectorStoreRecordData(IsFilterable = true)]
    [TextSearchResultName]
    public string Title { get; set; }

    [VectorStoreRecordData(IsFullTextSearchable = true)]
    [TextSearchResultValue]
    public string Description { get; set; }

    [VectorStoreRecordVector(768, DistanceFunction.DotProductSimilarity, IndexKind.Hnsw)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }

    [VectorStoreRecordData(IsFilterable = true)]
    public string[] Tags { get; set; }
}

Atributos de BlogPost:

BlogPostId: Identificador único del post. Se marca como clave primaria con [VectorStoreRecordKey] y como enlace de resultados de búsqueda con [TextSearchResultLink].
Title: Almacena el título del post. Usado como filtro con [VectorStoreRecordData(IsFilterable = true)] y como nombre principal en los resultados de búsqueda con [TextSearchResultName].
Description: Contiene el contenido del post. Es indexado para búsquedas de texto completo con [VectorStoreRecordData(IsFullTextSearchable = true)] y su valor es mostrado en los resultados con [TextSearchResultValue].
DescriptionEmbedding: Representación vectorial de Description. Almacenado como un vector de 768 dimensiones usando [VectorStoreRecordVector], con DotProductSimilarity como función de distancia y Hnsw para indexación eficiente.
Tags: Etiquetas relacionadas con el post. Pueden ser usadas como filtros en consultas con [VectorStoreRecordData(IsFilterable = true)]. ### Creando un endpoint para almacenar BlogPost en Qdrant

Para guardar nuevos BlogPost, crearemos un endpoint que recibirá los datos del post, generará su embedding y lo almacenará en la base de datos vectorial.

Nuestro servicio ya tiene configurados ITextEmbeddingGenerationService (para generar embeddings) e IVectorStore (para interactuar con Qdrant).

public static class CreateBlogPost
{
    public record Request(string Title, string Description, string[] Tags);

    public record Response(Guid BlogPostId);

    public class Handler
    {
        private readonly ITextEmbeddingGenerationService _embeddingService;
        private readonly IVectorStore _vectorStore;

        public Handler(ITextEmbeddingGenerationService embeddingService, IVectorStore vectorStore)
        {
            _embeddingService = embeddingService;
            _vectorStore = vectorStore;
        }

        public async Task<Response> Handle(Request request, CancellationToken ct)
        {
            var blogposts = _vectorStore.GetCollection<Guid, BlogPost>(BlogPost.VectorName);

            await blogposts.CreateCollectionIfNotExistsAsync(ct);

            var embeddingContents =
                await _embeddingService.GenerateEmbeddingAsync(request.Description, cancellationToken: ct);

            var newBlogPost = new BlogPost
            {
                BlogPostId = Guid.NewGuid(),
                Title = request.Title,
                Description = request.Description,
                DescriptionEmbedding = embeddingContents,
                Tags = request.Tags
            };

            await blogposts.UpsertAsync(newBlogPost, cancellationToken: ct);

            return new Response(newBlogPost.BlogPostId);
        }
    }
}

Explicación del código

Manejador (Handler)
- Recibe los servicios ITextEmbeddingGenerationService y IVectorStore a través del constructor.
Lógica del método Handle
- Obtiene la colección blogposts de Qdrant.
- Si la colección no existe, la crea con CreateCollectionIfNotExistsAsync().
- Genera el embedding del Description usando _embeddingService.GenerateEmbeddingAsync().
- Crea un BlogPost con los datos proporcionados y el embedding generado.
- Guarda el post en Qdrant con UpsertAsync(), que inserta o actualiza el registro.

Nota 💡: Para ver cómo este handler se integra con Minimal APIs, revisa el código fuente del proyecto. Para mantener este artículo conciso, omitiremos detalles específicos.

Probando el endpoint con `api.http`

Para poblar la base de datos vectorial, podemos hacer una solicitud HTTP de prueba.

Ejemplo en SemanticKernelLearning03.ApiService.http:

@SemanticKernelLearning03.ApiService_HostAddress = https://localhost:7391

POST {{SemanticKernelLearning03.ApiService_HostAddress}}/api/blog-posts
Content-Type: application/json

{
  "Title": "Introducción a ASP.NET Core",
  "Description": "Una guía completa sobre cómo comenzar con ASP.NET Core y sus características principales.",
  "Tags": ["ASP.NET Core", "C#", "Web Development"]
}

Verificando los datos en Qdrant

Si ejecutamos nuestra solución con Aspire y realizamos la solicitud anterior, podemos inspeccionar los datos en el dashboard de Qdrant y verificar que la colección y los registros existen.

Consideraciones sobre el tamaño de los vectores

Este ejemplo usa nomic-embed-text, que genera vectores de 768 dimensiones.
Qdrant debe estar configurado para aceptar este tamaño de vector.
Si usas modelos de OpenAI u otros proveedores, verifica el tamaño del vector antes de insertarlo en Qdrant.

Recuperando Información desde Qdrant

Para demostrar cómo realizar búsquedas semánticas en los vectores almacenados en Qdrant, podemos hacerlo de distintas maneras: usando el vector directamente o utilizando una abstracción que Semantic Kernel nos proporciona, llamada ITextSearch.

ITextSearch tiene distintas implementaciones, como BingTextSearch (que realiza búsquedas en Bing), pero en nuestro caso usaremos VectorStoreTextSearch, que está diseñado específicamente para realizar búsquedas en bases de datos vectoriales.

Esta clase necesita conocer:

El modelo de embeddings que estamos usando.
El nombre de la colección en Qdrant donde haremos la búsqueda.

El proceso realmente es sencillo y podríamos hacerlo manualmente construyendo consultas directamente contra la base de datos vectorial. Sin embargo, en este caso, aprovecharemos ITextSearch para simplificar el proceso.

Nota 💡: Para más información sobre búsquedas vectoriales en Semantic Kernel, consulta la documentación oficial de Microsoft:

Vector search using Semantic Kernel Vector Store connectors (Preview) | Microsoft Learn

Implementación del Endpoint `SearchBlogPost`

Para realizar la búsqueda semántica, crearemos un nuevo endpoint llamado SearchBlogPost, que permitirá encontrar los posts más relevantes basados en una consulta en lenguaje natural.

public static class SearchBlogPost
{
    public record Request(string Query);

    public record Response(Guid BlogPostId, string Title, string Description);

    public class Handler([FromKeyedServices(BlogPost.VectorName)] ITextSearch textSearch)
    {
        public async Task<List<Response>> Handle(Request request, CancellationToken ct)
        {
            KernelSearchResults<TextSearchResult> textResults =
                await textSearch.GetTextSearchResultsAsync(request.Query, new()
                {
                    Top = 2,
                    Skip = 0,
                }, ct);

            List<Response> responses = new();
            await foreach (TextSearchResult result in textResults.Results.WithCancellation(ct))
            {
                responses.Add(new(
                    Guid.Parse(result.Link),
                    result.Name,
                    result.Value));
            }

            return responses;
        }
    }
}

Explicación del Código

Uso de ITextSearch
- Lo recibimos en el constructor con [FromKeyedServices(BlogPost.VectorName)]. Esto asegura que estamos inyectando la instancia correcta configurada para nuestra colección de blog posts en Qdrant.
  - Esto lo hemos configurado en DependencyConfig anteriormente.
Realizamos la búsqueda semántica
- Llamamos a GetTextSearchResultsAsync(...);, donde:
  - request.Query es el término de búsqueda ingresado.
  - Top = 2 indica que queremos los dos resultados más relevantes.
  - Skip = 0 significa que no saltaremos ningún resultado.
Procesamos los resultados
- Iteramos sobre textResults.Results para extraer:
  - result.Link: Contiene el BlogPostId almacenado como string, lo convertimos a Guid.
  - result.Name: Corresponde al título del blog post.
  - result.Value: Contiene la descripción del blog post.
Devolvemos la lista de resultados
- Cada Response representa un blog post relevante basado en la búsqueda semántica.

Una vez que el endpoint SearchBlogPost está registrado, podemos comenzar a realizar búsquedas semánticas para encontrar los posts más relevantes según el texto ingresado.

Ejemplo de Consulta

Podemos hacer una búsqueda con la siguiente solicitud:

### Busquedas Semanticas
@Query=arquitectura de software
GET {{SemanticKernelLearning03.ApiService_HostAddress}}/api/blog-posts?Query={{Query}}

Respuesta Esperada

Si hay blog posts relevantes en la base de datos, la API devolverá un listado de los más coincidentes. Un ejemplo de respuesta podría ser:

[
  {
    "blogPostId": "949b7164-2021-4fcc-b58e-9887fdd00d0e",
    "title": "Clean Architecture: Diseño de Software Modular y Escalable",
    "description": "Clean Architecture es un enfoque de diseño de software ..."
  },
  {
    "blogPostId": "2340f1ac-e810-4067-90f5-a71899c6d42a",
    "title": "Principios SOLID en el Desarrollo de Software",
    "description": "Los principios SOLID son un conjunto de cinco principios de..."
  }
]

Si revisamos el repositorio, podemos notar que hay posts de distintos temas (por ejemplo, Machine Learning, Bases de Datos, DevOps), pero la búsqueda regresó los más relevantes según el texto ingresado. Esto demuestra que el motor de búsqueda semántico está funcionando correctamente.

Personalizando la Búsqueda

Podemos ajustar la consulta cambiando:

La cantidad de resultados (Top): Actualmente devuelve dos posts, pero podríamos aumentar este valor si queremos más opciones.
El modelo de embeddings: Si cambiamos el modelo de embeddings usado para almacenar los vectores, los resultados pueden variar en precisión y relevancia.

Integración con RAG (Retrieval-Augmented Generation)

En esta sección, vamos a implementar un nuevo endpoint que va más allá de una búsqueda semántica. En lugar de solo buscar contenido relevante, vamos a generar texto de manera dinámica a partir de una consulta proporcionada por el usuario. Lo interesante aquí es que el contexto para la generación de la respuesta será el contenido de los Posts del Blog que coincidan con la consulta del usuario.

¿Cómo funciona?

Si el usuario hace una pregunta como:

cuál es el objetivo principal de clean architecture?

En lugar de simplemente devolver una lista de posts relacionados, el modelo de Semantic Kernel buscará los posts más relevantes relacionados con la consulta, y usará esos resultados como contexto para generar una respuesta detallada. El modelo no solo devolverá contenido estático, sino que también incorporará la información más relevante y actualizada disponible en los posts, permitiendo una respuesta más precisa y contextualizada.

Esta técnica es útil porque, por lo general, los modelos de lenguaje (LLMs) se entrenan con datos estáticos que no contienen información actualizada o específica del dominio. Al integrar la Recuperación de Información (RAG), aprovechamos los datos disponibles en tiempo real para mejorar la relevancia y exactitud de las respuestas generadas.

¿Cómo lo implementamos?

En el post anterior, vimos cómo crear Plugins o Funciones Semánticas, y cómo Semantic Kernel se encarga de invocar automáticamente esos plugins cuando es necesario. Ahora, vamos a utilizar un plugin de búsqueda vectorial para recuperar los posts relevantes y luego construir un prompt personalizado que permita al modelo generar una respuesta coherente utilizando esos posts como contexto.

El Endpoint y el Código

El endpoint que vamos a implementar es el siguiente:

public static class QuestionsBlogPost
{
    public record Request(string Query);

    public record Response(string Content);

    public class Handler(Kernel kernel, [FromKeyedServices(BlogPost.VectorName)] ITextSearch textSearch)
    {
        public async Task<Response> Handle(Request request, CancellationToken ct)
        {
            var searchPlugin = textSearch.CreateWithGetTextSearchResults("SearchPlugin");
            kernel.Plugins.Add(searchPlugin);

            string promptTemplate = """
                                    Utiliza solamente los siguientes contenidos para contestar las preguntas realizadas. 
                                    Si no sabes la respuesta, hazle saber al usuario que no se encontró información relevante.

                                    Al final de tu respuesta, incluye el nombre del contenido utilizado como referencia.

                                    {{#with (SearchPlugin-GetTextSearchResults query)}}  
                                        {{#each this}}  
                                        Name: {{Name}}
                                        Value: {{Value}}
                                        -----------------
                                        {{/each}}  
                                    {{/with}}  

                                    Pregunta:

                                    {{query}}
                                    """;

            KernelArguments arguments = new() { { "query", request.Query } };

            HandlebarsPromptTemplateFactory promptTemplateFactory = new();
            var response = await kernel.InvokePromptAsync(
                promptTemplate,
                arguments,
                templateFormat: HandlebarsPromptTemplateFactory.HandlebarsTemplateFormat,
                promptTemplateFactory: promptTemplateFactory,
                cancellationToken: ct);

            return new Response(response.ToString());
        }
    }
}

Explicación del Código

Handler: Esta clase maneja la lógica de la consulta, invoca el plugin de búsqueda, crea el prompt con el contexto adecuado y genera la respuesta. Recibe un objeto Kernel y una instancia de ITextSearch que se utiliza para realizar la búsqueda de contenido relevante en los posts del blog.
searchPlugin: Este es el plugin de búsqueda que se crea utilizando el método CreateWithGetTextSearchResults. Este plugin se encarga de realizar la búsqueda semántica en los posts y recuperar los resultados más relevantes. El plugin se añade al Kernel para que pueda ser invocado cuando sea necesario.
promptTemplate: Es el template que se utilizará para generar el texto. En este caso, se utiliza Handlebars para permitir la inserción de los resultados de la búsqueda dentro del prompt. La idea es que el modelo genere una respuesta usando solamente los contenidos encontrados en la búsqueda. El template también incluye instrucciones para que el modelo devuelva el nombre y el valor de los posts utilizados como referencia.

{{#with (SearchPlugin-GetTextSearchResults query)}}  
    {{#each this}}  
    Name: {{Name}}  
    Value: {{Value}}  
    -----------------
    {{/each}}  
{{/with}}

Al final, se agrega la pregunta del usuario para que el modelo la utilice como parte de la respuesta:

Pregunta:
{{query}}

KernelArguments: Este objeto contiene los argumentos que se pasan al modelo, en este caso, la consulta realizada por el usuario.
InvokePromptAsync: Este método invoca el modelo utilizando el template y los argumentos proporcionados, lo que genera una respuesta basada en los contenidos recuperados.

Flujo Completo

El usuario hace una consulta (por ejemplo, "¿Qué es Clean Architecture?").
El Kernel busca los posts relevantes utilizando el plugin de búsqueda vectorial.
El prompt personalizado es generado e incluye los resultados de la búsqueda.
El modelo LLM genera una respuesta utilizando los posts recuperados como contexto.
La respuesta generada se devuelve al usuario, incluyendo la referencia a los contenidos utilizados.

Este enfoque permite mejorar la calidad de las respuestas generadas por el modelo, ya que se aprovecha la información más actualizada y relevante disponible en el dominio. Además, al usar el contenido de los posts, el modelo tiene un contexto más específico y adaptado a las necesidades del usuario, lo que mejora la relevancia y precisión de la respuesta.

Probando el Endpoint

Una vez que hemos configurado y creado nuestro endpoint, es hora de probarlo. Para ello, podemos hacer una solicitud HTTP como la siguiente, que ilustrará cómo interactuar con el servicio de generación de texto mediante la integración de RAG.

Ejemplo de solicitud HTTP:

###
@Question=cuál es el objetivo principal de clean architecture?
GET {{SemanticKernelLearning03.ApiService_HostAddress}}/api/blog-posts/qa?Query={{Question}}

Cuando se ejecuta esta solicitud, obtendremos una respuesta estructurada que incluye no solo la respuesta generada por el modelo, sino también la referencia al contenido utilizado para generar esa respuesta.

Respuesta esperada:

El objetivo principal de Clean Architecture es promover la separación de preocupaciones y la modularidad en el diseño de software, lo que permite a las aplicaciones ser más mantenibles y escalables a lo largo del tiempo.

Reference: Clean Architecture: Diseño de Software Modular y Escalable.

En este caso, la respuesta del endpoint es completamente dinámica y se genera utilizando los resultados de búsqueda obtenidos de los posts del blog relacionados con la pregunta. Como puedes observar, no solo obtenemos un resultado que responde a la consulta, sino que también proporcionamos el nombre del contenido utilizado como referencia, lo cual permite al usuario conocer la fuente de la información generada.

En el ejemplo, configuramos el promptTemplate para que el modelo de lenguaje solo utilizara los contenidos relevantes encontrados a través de la búsqueda de texto vectorial. De esta forma, garantizamos que la generación del modelo sea específica y relevante para el contexto proporcionado por los posts del blog.

Este template establece claramente la regla para que el modelo solo use los resultados de búsqueda como contexto, lo cual optimiza la relevancia de las respuestas generadas.

Escalabilidad y Flexibilidad del Prompt

El prompt puede ser adaptado para ser más específico y mejorar la calidad de las respuestas generadas, por ejemplo, agregando instrucciones más detalladas sobre el formato de la respuesta o proporcionando una estructura más precisa para guiar al modelo. La flexibilidad del sistema permite ajustar el nivel de detalle según la necesidad del caso de uso.

Ejemplo de otro Prompt:

Enlista los puntos más importantes al querer optimizar consultas SQL

Resultado generado:

¡Claro! A continuación, te presento los puntos más importantes para optimizar consultas SQL:

1. **Índices**: Los índices ayudan a acelerar la búsqueda de datos en una base de datos. Deben ser creados en las columnas que se utilizan en la cláusula WHERE o en la cláusula ORDER BY.
2. **Normalización y desnormalización de datos**: La normalización ayuda a reducir la cantidad de datos duplicados en una base de datos, mientras que la desnormalización puede mejorar el rendimiento en ciertas situaciones.
.
.
.

Referencia: Optimización de Consultas SQL en Aplicaciones .NET

Como vemos, el modelo genera una lista de los puntos más importantes y proporciona la referencia adecuada para la información. Este tipo de integración con Semantic Kernel y RAG hace que sea posible tener respuestas altamente relevantes y específicas basadas en contenido actual y relacionado.

Conclusión

A lo largo de este post, hemos aprendido a configurar y utilizar Semantic Kernel para aprovechar el poder de los embeddings y la técnica de Retrieval-Augmented Generation (RAG). Desde la generación y almacenamiento de vectores en Qdrant, hasta la realización de búsquedas semánticas y la generación de respuestas contextualizadas mediante prompts personalizados, hemos visto cómo combinar distintas tecnologías para crear soluciones de IA avanzadas y especializadas.

Esta integración no solo mejora la precisión y relevancia de las respuestas, sino que también demuestra el potencial de unir funciones semánticas, RAG y bases de datos vectoriales para abordar desafíos reales en el manejo de información. Con estas herramientas, podrás desarrollar aplicaciones que se adaptan al contexto de tus datos, ofreciendo respuestas dinámicas y actualizadas.

¡El camino hacia aplicaciones inteligentes y contextualmente precisas está abierto! Sigue experimentando y optimizando estas técnicas para llevar tus proyectos al siguiente nivel.

Referencias

Extendiendo Semantic Kernel: Creando Plugins para Consultas Dinámicas

Isaac Ojeda — Thu, 16 Jan 2025 17:34:53 +0000

1. Introducción

En el tutorial anterior, exploramos cómo configurar y utilizar Semantic Kernel junto con Aspire y Ollama para crear un API básico que generaba resúmenes de texto. Ahora, vamos a dar un paso más y enfocarnos en una de las características más potentes de Semantic Kernel: los plugins.

En este tutorial, aprenderás a crear y utilizar plugins en Semantic Kernel. Los plugins son clases o componentes que encapsulan funciones específicas, permitiendo extender las capacidades del kernel con nuevas habilidades personalizadas.

Para ejemplificarlo, desarrollaremos dos plugins:

Un plugin que retorna la hora actual en formato UTC.
Un plugin que utiliza datos de geolocalización y clima para proporcionar información meteorológica de una ciudad específica.

Los plugins en Semantic Kernel permiten agregar habilidades modulares y reutilizables. Esto no solo facilita la escalabilidad del proyecto, sino que también abre las puertas para integrar servicios externos o lógica personalizada de manera sencilla y eficiente.

Nota 💡: Aquí podrás encontrar el código fuente de este tutorial: DevToPosts/SemanticKernelSeries/SemanticKernelLearning02 at main · isaacOjeda/DevToPosts

2. Qué son los Plugins en Semantic Kernel

¿Qué es un Plugin en Semantic Kernel?

Un plugin en Semantic Kernel es una clase que contiene métodos decorados con atributos especiales, como [KernelFunction], para exponer su funcionalidad al kernel. Esto permite que esas funciones sean llamadas por el kernel como si fueran partes integradas de su sistema.

¿Por qué usar Plugins?

Modularidad: Los plugins encapsulan lógica específica, lo que los hace fáciles de mantener y reutilizar.
Flexibilidad: Puedes crear plugins para realizar tareas como interactuar con APIs externas, procesar datos o realizar cálculos.
Integración sencilla: Los plugins se registran fácilmente en el kernel, haciéndolos disponibles para su uso en el API o dentro de flujos más complejos.

Componentes clave de un Plugin

Métodos decorados con [KernelFunction]: Esto marca las funciones que el kernel puede invocar.
Descripción: Los métodos pueden incluir descripciones para documentar su propósito, facilitando su descubrimiento.
Dependencias externas: Los plugins pueden interactuar con servicios externos, como APIs, utilizando patrones conocidos como IHttpClientFactory.

Plugins que construiremos en este tutorial

TimeInformationService: Un plugin que proporciona la hora actual en UTC.
WeatherInformationService: Un plugin que utiliza una API externa para obtener información de geolocalización y clima.

Ambos plugins serán integrados en nuestro kernel y expuestos a través del API que desarrollamos en el tutorial anterior.

¿Cómo funcionan los Plugins en Semantic Kernel?

Los plugins registrados en el kernel pueden ser invocados en tiempo de ejecución mediante prompts o directamente desde el código. El kernel gestiona automáticamente la ejecución de estos métodos, permitiendo integrarlos en flujos de procesamiento complejos.

3. Desarrollo del Ejemplo

Ahora que entendemos qué son los plugins en Semantic Kernel, vamos a desarrollar e integrar dos plugins personalizados en nuestro proyecto:

TimeInformationService: Un plugin simple que devuelve la hora actual en UTC.
WeatherInformationService: Un plugin más avanzado que utiliza una API externa para obtener información sobre el clima en una ciudad.

Paso 1: Crear los Plugins

TimeInformationService

El siguiente plugin proporciona la hora actual en formato UTC. Es un ejemplo sencillo para entender cómo funcionan los plugins básicos en Semantic Kernel.

/// <summary>
/// A plugin that returns the current time.
/// </summary>
public class TimeInformationService
{
    [KernelFunction]
    [Description("Retrieves the current time in UTC.")]
    public string GetCurrentUtcTime() => DateTime.UtcNow.ToString("R");
}

Aquí destacamos:

El atributo [KernelFunction] expone el método al kernel.
El método devuelve la hora en formato "R" (RFC1123), que es legible y estándar.

WeatherInformationService

Este plugin es más complejo. Obtiene información sobre una ciudad (coordenadas, país, etc.) y también el clima actual utilizando servicios externos.

public class WeatherInformationService(IHttpClientFactory httpClientFactory)
{
    [KernelFunction]
    [Description("Get weather information for a city.")]
    public async Task<WeatherInfo> GetWeatherByCity(string cityName)
    {
        if (string.IsNullOrWhiteSpace(cityName))
            throw new ArgumentException("City name cannot be null or empty.", nameof(cityName));

        // Step 1: Get city coordinates
        var city = await GetCityCoordinatesAsync(cityName);

        // Step 2: Get weather data
        var weatherResult = await GetWeatherDataAsync(city.Latitude, city.Longitude);

        return new WeatherInfo
        {
            City = city.Name,
            Country = city.Country,
            Temperature = weatherResult.CurrentWeather.Temperature,
            WindSpeed = weatherResult.CurrentWeather.Windspeed,
            WeatherCode = weatherResult.CurrentWeather.Weathercode
        };
    }

    private async Task<GeocodingResult> GetCityCoordinatesAsync(string cityName)
    {
        // ...For more info, check the source code
    }

    private async Task<WeatherApiResponse> GetWeatherDataAsync(double latitude, double longitude)
    {
        // ...For more info, check the source code
    }
}

Puntos clave:

Este plugin utiliza IHttpClientFactory para realizar llamadas HTTP a APIs externas.
- Como puedes ver, la inyección de dependencias funciona sin problema, por lo que aquí podríamos inyectar lo que se necesite que el plugin realice
El Kernel utiliza los nombres de los métodos y los parámetros para darles significado y así usarlo según el prompt solicitado.

Paso 2: Registrar los Plugins en el Kernel

Para que el kernel pueda usar estos plugins, debemos registrarlos en la configuración del servicio:

var kernel = builder.Services.AddKernel();

// Registrar el servicio de hora
kernel.ImportPlugin<TimeInformationService>();

// Registrar el servicio de clima
kernel.ImportPlugin<WeatherInformationService>();

Paso 3: Exponer los Plugins Utilizando el Kernel

En lugar de llamar directamente a los métodos de los servicios, utilizaremos el Kernel de Semantic Kernel para invocar los plugins mediante prompts. Esto nos permitirá combinar capacidades y hacer el uso más dinámico de los plugins.

Haremos la prueba con un simple endpoint que invoque el prompt

app.MapPost("/api/chat", async (ChatRequest request, Kernel kernel) =>
{
    var settings = new OpenAIPromptExecutionSettings()
    {
        FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
    };

    // Aquí podríamos hacer un Prompt más explícito para el modelo si nuestra intención fuera
    // solo contestar preguntas sobre el clima.

    var response = await kernel.InvokePromptAsync(request.Question, new(settings));

    return Results.Ok(new
    {
        Result = response.ToString()
    });
});

Explicación del Código

Uso del Kernel:
- El método InvokePromptAsync utiliza el kernel para procesar el prompt y determinar qué función de los plugins debe ejecutarse.
- En este caso, el Kernel automáticamente seleccionará el método correcto (GetCurrentUtcTime o GetWeatherByCity) basado en el texto del prompt.
Integración Flexible:
- La estructura permite enviar cualquier pregunta o texto, dejando que el Kernel interprete y seleccione el método adecuado.
  - También podemos hacer prompts donde seamos explícitos de que Plugin queremos que el modelo utilice, pero por ahora lo dejamos en automático y que el modelo decida.

4. Probar los Endpoints

Con los endpoints configurados y los plugins integrados en el Kernel, es momento de validarlos y observar cómo funcionan.

Ejemplo 1: Consultar el Clima

Utilizando Postman, envía la siguiente solicitud al endpoint configurado:

{
  "question": "Cuál es el clima actual en Londres"
}

Al depurar la aplicación, notarás que el modelo entiende la intención del prompt, lo asocia con nuestro plugin y determina que queremos el clima actual de Londres. Esto sucede porque hemos registrado una función específica que devuelve esta información:

La respuesta sería algo similar a:

{
    "result": "El clima actual en Londres es frío y nublado, con una temperatura de 8.6°C y un viento que sopla a 6.8 km/h. La codificación del tiempo es 3, lo que indica condiciones climáticas mezcladas, con algunas nubes y posibles lluvias."
}

Ejemplo 2: Consultar Información de una Ciudad

Ahora, realiza una consulta diferente, como esta:

{
  "question": "Cuál es la población actual de Madrid?"
}

En este caso, el modelo invocará automáticamente otra función registrada en el plugin que se encarga de obtener información sobre una ciudad:

La respuesta será algo como:

{
    "result": "La población actual de Madrid es de aproximadamente 3,255,594 personas, según la información proporcionada por el servicio de información geográfica."
}

¿Notas el poder detrás de esta integración? Con esta configuración, el Kernel puede realizar tareas que antes requerían múltiples servicios separados. Todo se reduce a cómo estructuramos los prompts y las funciones de nuestros plugins.

¡Y esto es solo el principio! Aún no hemos explorado características avanzadas como memoria semántica y RAG (Retrieval-Augmented Generation), pero con lo que ya tenemos, podemos construir soluciones extremadamente flexibles y personalizadas para cualquier dominio o industria.

Con prompts más específicos, puedes resolver problemas complejos y automatizar procesos avanzados. La única limitación es tu creatividad y las necesidades de tu proyecto.

5. Extender Funcionalidades y Consideraciones Finales

Ahora que hemos visto cómo registrar plugins y probarlos con el Kernel, reflexionemos sobre cómo podemos extender estas funcionalidades para adaptarlas a necesidades más complejas. Aquí algunas ideas y recomendaciones para el siguiente nivel:

Incorporar Más Plugins

La flexibilidad de Semantic Kernel nos permite agregar más funciones a nuestros plugins o crear nuevos plugins para cubrir otras áreas de interés, como:

Análisis de texto: Procesar grandes volúmenes de datos textuales para obtener resúmenes, extraer palabras clave o identificar entidades.
Integraciones externas: Conectar con APIs de terceros para realizar tareas como manejo de correos electrónicos, acceso a sistemas empresariales o realizar transacciones.
Procesamiento de imágenes: Usar servicios como OCR para reconocer texto en imágenes o realizar análisis visual.

Usar Memoria Semántica

La memoria semántica de Semantic Kernel puede almacenar y recuperar información contextualmente relevante. Por ejemplo:

Recordar interacciones previas para mejorar la experiencia del usuario.
Contextualizar consultas complejas basándose en datos históricos.
Implementar personalización profunda en aplicaciones que requieran un historial de acciones o preferencias.

Optimización de Prompts

Un diseño adecuado de prompts es clave para mejorar la precisión de los resultados. Algunas recomendaciones:

Sea específico: Prompts detallados producen resultados más enfocados.
Use ejemplos: Proporcionar ejemplos en el prompt puede ayudar al modelo a entender la intención de manera más clara.
Evalúe y ajuste: Experimente con diferentes configuraciones para obtener mejores resultados en diferentes escenarios.

Escalabilidad y Producción

Si bien en estos ejemplos usamos Ollama localmente para evitar problemas de infraestructura, en un entorno de producción puedes cambiar sin modificar tu código base y usar servicios como OpenAI o Azure OpenAI para aprovechar su escalabilidad y confiabilidad. Esto implica:

Definir claves API para entornos seguros.
Configurar políticas de acceso según las necesidades de tu organización.
Monitorear el uso y los costos para optimizar el rendimiento.

Casos de Uso Empresariales

Con los elementos ya implementados, podemos visualizar algunos casos prácticos donde estas capacidades sean útiles:

Asistentes de soporte: Resolver consultas comunes en tiempo real con información siempre actualizada.
Automatización de tareas repetitivas: Por ejemplo, generar reportes basados en datos o notificaciones programadas.
Sistemas personalizados: Aplicaciones inteligentes que se adapten dinámicamente a las necesidades de los usuarios, como dashboards interactivos o chatbots avanzados. ### Conclusión

Con Semantic Kernel, hemos transformado lo que tradicionalmente sería una combinación de servicios aislados en una solución unificada y potente. Desde entender intenciones en lenguaje natural hasta ejecutar acciones basadas en plugins específicos, el Kernel nos proporciona una plataforma flexible y extensible para la creación de aplicaciones inteligentes.

La verdadera ventaja de esta tecnología radica en su capacidad de evolución. Puedes comenzar con casos de uso simples, como los ejemplos de este tutorial, y escalar hacia soluciones más complejas que integren múltiples fuentes de datos, memoria semántica y funcionalidades avanzadas.

Tu creatividad y las necesidades de tu proyecto dictarán el camino. Ahora que tienes las bases, ¿qué construirás con Semantic Kernel?

Semantic Kernel: Crea un API para Generación de Texto con Ollama y Aspire

Isaac Ojeda — Tue, 14 Jan 2025 20:18:42 +0000

1. Introducción

En este tutorial, aprenderás cómo usar Semantic Kernel para integrar Large Language Models (LLM) y construir un servicio REST que resuma texto. Utilizaremos Ollama como motor local de modelos de lenguaje, lo que nos permitirá evitar el uso de servicios en la nube en esta fase de desarrollo.

El objetivo principal es configurar un entorno de trabajo funcional en C# que permita a los desarrolladores:

Conectar un modelo de lenguaje local (llama3.2).
Crear un kernel para manejar tareas personalizadas.
Exponer la funcionalidad como un endpoint REST en una API ASP.NET Core.

Al finalizar, tendrás un servicio de API que podrá recibir texto como entrada y devolver un resumen en una sola oración. Esto no solo te ayudará a entender cómo usar Semantic Kernel, sino que también te dará una base sólida para construir aplicaciones prácticas basadas en IA generativa.

2. Introducción a Semantic Kernel

2.1. ¿Qué es Semantic Kernel?

Semantic Kernel es un SDK de código abierto que permite a los desarrolladores crear sus propios agentes personalizados de inteligencia artificial (IA). Al combinar modelos de lenguaje de gran escala (LLMs) con código nativo, los desarrolladores pueden crear agentes de IA que entiendan y respondan a solicitudes en lenguaje natural para realizar una variedad de tareas.

2.2 ¿Qué es un agente de IA?

Un agente de IA es un programa diseñado para alcanzar objetivos predeterminados. Los agentes de IA están impulsados por modelos de lenguaje de gran escala (LLMs) entrenados con cantidades masivas de datos. Estos agentes pueden completar una amplia variedad de tareas con mínima o ninguna intervención humana. Algunos ejemplos de lo que pueden hacer los agentes de IA incluyen:

Escribir código.
Redactar correos electrónicos.
Resumir reuniones.
Proporcionar recomendaciones.
¡Y mucho más!

Semantic Kernel integra modelos de lenguaje como OpenAI, Azure OpenAI y Hugging Face con lenguajes de programación convencionales como C#, Python y Java. Los desarrolladores pueden crear "plugins" para interactuar con los LLMs y realizar diversas tareas. Además, el SDK de Semantic Kernel incluye plugins predefinidos que pueden mejorar rápidamente una aplicación. Esto permite que los desarrolladores utilicen LLMs en sus propias aplicaciones sin necesidad de aprender los detalles específicos de la API del modelo.

2.3 Componentes clave del SDK de Semantic Kernel

Capa de orquestación de IA

El núcleo del stack de Semantic Kernel es una capa de orquestación de IA que permite la integración fluida de modelos de IA y plugins. Esta capa combina estos componentes para crear interacciones innovadoras con los usuarios.

Conectores

El SDK ofrece un conjunto de conectores que permiten a los desarrolladores integrar LLMs en sus aplicaciones existentes. Estos conectores actúan como un puente entre el código de la aplicación y los modelos de IA.

Plugins

El SDK opera con plugins, que funcionan como el "cuerpo" de la aplicación de IA. Los plugins incluyen solicitudes (prompts) que el modelo de IA debe responder y funciones para realizar tareas especializadas. Los desarrolladores pueden usar plugins predefinidos o crear los suyos propios.

3. Desarrollo del Ejemplo

En esta sección, construiremos un API REST que utiliza Semantic Kernel y el modelo de lenguaje llama3.2 de Ollama para resumir texto en una sola oración. El objetivo es entender cómo configurar el entorno y crear una habilidad básica que pueda ser utilizada desde cualquier aplicación a través de un endpoint.

3.1. Configuración con Aspire

Antes de entrar en los detalles del API, configuramos el entorno utilizando Aspire. Este framework facilita la construcción de aplicaciones distribuidas, simplificando la gestión de dependencias y servicios.

Lo que he hecho para simplificar la configuración, es utilizar Visual Studio para crear la solución ejemplo de Aspire con .NET 9:

Esta plantilla, también incluye un proyecto de Blazor, en este tutorial no lo utilizaremos, pero al finalizar, puedes utilizar ese proyecto para consumir los endpoints realizados y ya tener una aplicación funcional.

El código de Aspire tiene los siguientes propósitos:

Configurar Ollama: Define el modelo llama3.2 como el motor de lenguaje. Esto nos permite trabajar con un modelo local, eliminando la necesidad de infraestructura compleja en desarrollo.
Modularidad: Cada proyecto (como SemanticKernelLearning01_ApiService) se configura como un módulo independiente, permitiendo una estructura clara y extensible.

Nota: Usar Ollama local es ideal para pruebas y desarrollo, ya que no requiere configurar una infraestructura en la nube. Sin embargo, en producción puedes cambiar a OpenAI o Azure OpenAI sin modificar el código, aprovechando la flexibilidad de Semantic Kernel.

Código de Aspire:

Primero necesitamos los siguientes paquetes:

  <ItemGroup>
    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.0.0" />
    <PackageReference Include="CommunityToolkit.Aspire.Hosting.Ollama" Version="9.1.0" />
  </ItemGroup>

var builder = DistributedApplication.CreateBuilder(args);

var ollama =
    builder
        .AddOllama("ollama")// <-- Utilizará docker para usar ollama y sus modelos 
        .WithDataVolume()   // <-- Volumen de Docker para persistir modelos descargados
        .WithOpenWebUI();   // <-- UI Estilo ChatGPT

// Descarga el modelo llama3.2 con nombre "llama"
var llamaModel = ollama.AddModel("llama", "llama3.2");

// Nuestra API depende de Ollama, por lo que se referencia y espera a que esté listo
builder.AddProject<Projects.SemanticKernelLearning01_ApiService>("apiservice")
    .WithReference(llamaModel)
    .WaitFor(llamaModel);

builder.Build().Run();

Aquí configuramos Ollama como motor de generación de texto y vinculamos el modelo llama3.2. También iniciamos el servicio API como un módulo dentro del proyecto.

3.2. Configuración del API REST

En el siguiente bloque de código, configuramos un API REST utilizando ASP.NET Core y Semantic Kernel. Aquí se define un endpoint que acepta texto como entrada y devuelve su resumen generado por el modelo de lenguaje.

Puntos clave del código:

Kernel y Ollama: Se inicializa el kernel de Semantic Kernel y se conecta con Ollama usando la configuración definida en Aspire.
Habilidad de Resumen: La lógica para resumir texto se encapsula en un prompt que el modelo interpreta para generar respuestas.
Exposición del Endpoint: Se define un endpoint /api/summarizer que recibe un objeto JSON con el texto a resumir y devuelve el resultado.

Código del API REST:

Paquetes necesarios:

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.0" />
    <PackageReference Include="Microsoft.SemanticKernel" Version="1.33.0" />
    <PackageReference Include="Microsoft.SemanticKernel.Connectors.Ollama" Version="1.33.0-alpha" />
  </ItemGroup>

Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.AddServiceDefaults();
builder.Services.AddProblemDetails();
builder.Services.AddOpenApi();

var kernel = builder.Services.AddKernel();

var (endpoint, modelId) = GetOllamaConnectionString();

#pragma warning disable SKEXP0070
kernel.AddOllamaTextGeneration(modelId, endpoint); // Está en alpha, puede cambiar.
#pragma warning restore SKEXP0070

var app = builder.Build();

app.UseExceptionHandler();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.MapDefaultEndpoints();

app.MapPost("/api/summarizer", async (
    TextCompletionRequest request,
    ITextGenerationService textGenerationService) =>
{
    var prompt = $"""
                 Summarize the following text in one sentence:  

                 {request.Text}
                 """;

    var response = await textGenerationService.GetTextContentsAsync(prompt);

    return response;
});

app.Run();

3.3. Explicación General del Flujo

Creación del Kernel: Se configura el kernel para usar Ollama como motor de generación de texto con el modelo llama3.2.
Definición del Endpoint: El endpoint /api/summarizer recibe un JSON con una propiedad Text.
Generación del Resumen: El texto recibido se envía al modelo junto con un prompt que instruye al modelo para resumirlo en una oración.
Devolución del Resultado: El resumen generado se devuelve como respuesta al cliente que llamó al API.

Código restante:

(Uri endpoint, string modelId) GetOllamaConnectionString()
{
    // Este ConnectionString es establecida por Aspire
    var connectionString = builder.Configuration.GetConnectionString("llama");

    var connectionBuilder = new DbConnectionStringBuilder
    {
        ConnectionString = connectionString
    };

    Uri endpoint = new Uri(connectionBuilder["Endpoint"].ToString());
    string modelId = connectionBuilder["Model"].ToString();

    return (endpoint, modelId);
}

// Simple DTO
public record TextCompletionRequest(string Text);

Nota 💡: Recuerda que siempre puedes descargar el código desde desde este Repositorio

3.4 Probando la solución

Si corremos el proyecto de Aspire, automáticamente orquestará lo necesario para que la API pueda comunicarse con ollama:

Su primera ejecución será lenta, ya que tendrá que descargar el modelo llama3.2.

Existen muchos modelos que podemos ejecutar, tanto para Text Generation y para Embeddings (revisado en próxmos post), puedes revisar más aquí: Ollama.

Probemos el endpoint (utilizando Visual Studio y un archivo .http):

@host = https://localhost:7384

### Text Generation
POST {{host}}/api/summarizer
Content-Type: application/json

{
    "text": "Mariana found an ancient book in her grandfather’s library, with a bookmark pointing to a page that read, “Recite these words and your destiny will change.” Intrigued, she read it out loud, and in an instant, she found herself in a bustling market in a medieval town. \rNo one seemed surprised by her modern clothing; in fact, one merchant greeted her as if he knew her. As she searched for answers, an old man explained that she was the heir to a lost legacy and had to make a choice: stay and lead a kingdom on the brink of chaos, or return to her everyday life. \rWith the book in her hands, Mariana took a deep breath and closed her eyes, choosing the challenge she had secretly always wanted."
}

Respuesta:

[
  {
    "text": "Mariana discovers an ancient book that transports her to a medieval town, where she learns she is the heir to a lost legacy and must make a choice between returning to her ordinary life or leading a kingdom on the brink of chaos.",
    "modelId": "llama3.2"
  }
]

La ejecución de modelos con ollama claro que suele ser más lento, para acelerar su ejecución debemos de contar con una GPU y de preferencia Nvidia.

Para operaciones sencillas, me ha funcionado bien y como vemos, la respuesta ha funcionado, todo ejecutandose en nuestra computadora.

4. Conclusión

En este tutorial, exploramos los fundamentos de Semantic Kernel y cómo integrarlo con Ollama para construir un servicio funcional capaz de generar resúmenes de texto. A través de este ejercicio:

Aprendiste a configurar un entorno básico utilizando Aspire, simplificando la administración de servicios distribuidos.
Descubriste cómo conectar Semantic Kernel con un motor de lenguaje local, como llama3.2 de Ollama, para evitar complicaciones de infraestructura en desarrollo.
Implementaste un API REST con un endpoint práctico que utiliza generación de texto como una habilidad central.

Este ejercicio muestra lo versátil que puede ser Semantic Kernel para crear aplicaciones inteligentes que aprovechan los modelos de lenguaje. Además, la flexibilidad de la arquitectura permite cambiar fácilmente entre diferentes proveedores de modelos, como OpenAI o Azure, sin necesidad de modificar el código base.

Este tutorial es solo el inicio. A partir de aquí, puedes explorar y agregar nuevas habilidades, integrar bases de datos vectoriales para contextualizar las respuestas o expandir el API con capacidades adicionales.

5. Próximos Pasos

Ahora que ya tienes una base sólida para trabajar con Semantic Kernel y Ollama, considera avanzar con los siguientes temas para expandir tus conocimientos:

Ampliar tus habilidades en Semantic Kernel:
- Aprende a crear habilidades más complejas con múltiples pasos y dependencias.
- Explora cómo usar conectores para integrar datos externos, como archivos, APIs, o bases de datos.
Incorporar contexto mediante bases de datos vectoriales:
- Experimenta con herramientas como Qdrant o Pinecone para agregar contexto a las respuestas basadas en vectores.
- Usa embeddings para conectar preguntas con datos relevantes en tiempo real.
Migrar a un entorno de producción:
- Configura la misma API para usar OpenAI o Azure OpenAI como motores de generación de texto.
- Aprende a manejar credenciales y seguridad en aplicaciones en producción.
Construir una interfaz gráfica:
- Usa Blazor para crear una interfaz interactiva donde los usuarios puedan interactuar con tus habilidades de Semantic Kernel.
Desarrollar tutoriales más avanzados:
- Enseña a otros cómo resolver problemas reales, como análisis de sentimientos, clasificación de texto o generación de contenido adaptado al contexto.

Integration Tests en .NET con TestContainers: Pruebas de Base de Datos Aisladas

Isaac Ojeda — Thu, 07 Nov 2024 21:23:19 +0000

Introducción a las Pruebas de Integración

En el desarrollo de software, las pruebas de integración son esenciales para verificar que los distintos módulos de una aplicación trabajen correctamente en conjunto. A diferencia de las pruebas unitarias, que se centran en unidades individuales de código, las pruebas de integración se enfocan en asegurarse de que los componentes del sistema interactúan adecuadamente entre sí y, en muchos casos, dependen de servicios externos, como bases de datos, servicios de autenticación o APIs de terceros.

En este artículo, vamos a trabajar con una Web API de ejemplo que utiliza SQL Server como base de datos. La idea es configurar un entorno de pruebas de integración utilizando TestContainers, una librería que permite levantar contenedores Docker de forma programática y en tiempo de ejecución, facilitando así la creación de entornos de prueba aislados y controlados.

Para ejecutar nuestras pruebas, usaremos xUnit como framework de testing y Respawn para resetear la base de datos entre pruebas, lo que ayuda a garantizar que cada prueba comience con un estado limpio y consistente. Gracias a TestContainers, podemos levantar un contenedor de SQL Server específicamente para nuestras pruebas, eliminando la dependencia de una base de datos local o compartida y asegurando que el entorno sea reproducible en cualquier máquina.

El código fuente completo de esta configuración y las pruebas está disponible en este repositorio de GitHub. Si quieres seguir este tutorial, puedes clonar el repositorio y ajustar los pasos según sea necesario para tu propio proyecto.

Herramientas y Librerías Utilizadas

Para implementar pruebas de integración con un entorno aislado y controlado, usaremos las siguientes librerías:

xUnit: Un framework de pruebas en .NET, ideal para organizar y ejecutar nuestras pruebas de integración.
Testcontainers.MsSql: Permite levantar un contenedor de SQL Server en Docker exclusivamente para nuestras pruebas, evitando dependencias locales y asegurando un entorno consistente.
Respawn: Resetea la base de datos entre pruebas, manteniendo un estado limpio y libre de datos residuales para cada ejecución.
FluentAssertions: Simplifica la escritura de aserciones, haciéndolas más legibles y expresivas.
Microsoft.AspNetCore.Mvc.Testing: Utilizada para crear un servidor web en memoria para poder exponer los endpoints y poder ejecutar las pruebas de inicio a fin.

Creación de un Contenedor SQL Server con TestContainers

En esta sección, configuraremos un contenedor de SQL Server para nuestras pruebas de integración usando TestContainers y un ICollectionFixture en xUnit. Esto permitirá que todas las pruebas dentro de una misma colección compartan una instancia de contenedor SQL Server, evitando configuraciones repetitivas y asegurando un entorno consistente.

Uso de ICollectionFixture y CollectionDefinition en xUnit

xUnit proporciona el concepto de ICollectionFixture para compartir configuraciones entre pruebas en una misma colección. Con ICollectionFixture, podemos crear una configuración compartida que solo se inicializa una vez y está disponible para todas las pruebas que pertenecen a una colección específica. Esto es ideal cuando tenemos configuraciones costosas o que queremos evitar inicializar en cada prueba, como en este caso, un contenedor Docker para SQL Server.

La configuración se organiza en dos partes:

ICollectionFixture: Define una clase de configuración compartida, en este caso SqlServerContainerFixture, que contiene toda la lógica para levantar y detener el contenedor SQL Server.
CollectionDefinition: Agrupa las pruebas que comparten la misma configuración. Asociamos las pruebas a esta colección usando el nombre de la colección (en este caso, "SqlServerContainerFixture").

Creación del Contenedor SQL Server

A continuación, se muestra el código de SqlServerContainerFixture, que configura y administra el ciclo de vida de un contenedor SQL Server. Este fixture implementa IAsyncLifetime, que permite ejecutar lógica de inicialización y limpieza de recursos de forma asincrónica.

public class SqlServerContainerFixture : IAsyncLifetime
{
    public const string FixtureName = "SqlServerContainerFixture";
    public MsSqlContainer SqlServerContainer { get; private set; }
    public string ConnectionString => SqlServerContainer.GetConnectionString();

    public SqlServerContainerFixture()
    {
        // Configuramos el contenedor SQL Server usando TestContainers
        SqlServerContainer = new MsSqlBuilder()
            .WithImage("mcr.microsoft.com/mssql/server:2022-latest") // Imagen de SQL Server
            .WithPassword("Passw0rd!") // Contraseña obligatoria para SQL Server
            .Build();
    }

    // Inicializa el contenedor de forma asincrónica antes de que las pruebas comiencen a ejecutarse
    public async Task InitializeAsync()
    {
        await SqlServerContainer.StartAsync();
    }

    // Detiene y limpia el contenedor después de que todas las pruebas hayan finalizado
    public async Task DisposeAsync()
    {
        await SqlServerContainer.StopAsync();
    }
}

Propiedades y Constructor:
- SqlServerContainer: Es el contenedor de SQL Server configurado a través de la clase MsSqlBuilder de TestContainers, donde especificamos la imagen docker, la contraseña y el puerto para el contenedor.
- ConnectionString: Proporciona una cadena de conexión a SQL Server, obtenida directamente del contenedor para que las pruebas puedan conectarse a esta base de datos.
Async Lifecycle con IAsyncLifetime:
- InitializeAsync(): Este método se ejecuta antes de que cualquier prueba en la colección se ejecute. Llama a StartAsync() para levantar el contenedor de SQL Server.
- DisposeAsync(): Este método se ejecuta una vez que todas las pruebas de la colección han finalizado, liberando recursos al detener el contenedor con StopAsync().

Definición de la Colección de Pruebas

A continuación, definimos la colección de pruebas asociada al fixture SqlServerContainerFixture. Esto se hace con [CollectionDefinition], que simplemente establece un nombre para la colección y vincula el fixture a todas las pruebas de la misma colección:

[CollectionDefinition(SqlServerContainerFixture.FixtureName)]
public class DatabaseCollection : ICollectionFixture<SqlServerContainerFixture>
{
    // Esta clase no necesita código. Su único propósito es asociar
    // el CollectionDefinition con ICollectionFixture.
}

[CollectionDefinition]: Asocia un nombre de colección, en este caso "SqlServerContainerFixture", con el fixture SqlServerContainerFixture.
ICollectionFixture<SqlServerContainerFixture>: Define la dependencia del fixture en todas las pruebas que pertenezcan a la colección.

Al agrupar nuestras pruebas en esta colección, cada una podrá acceder al contenedor de SQL Server compartido, eliminando la necesidad de inicializar un nuevo contenedor para cada prueba individualmente. Esto hace que las pruebas sean más eficientes y garantiza un entorno de datos consistente.

Configuración de Reseteo de Base de Datos con Respawn y WebApplicationFactory

Uso de `WebApplicationFactory`

WebApplicationFactory es una clase proporcionada por Microsoft que permite crear un servidor de pruebas en memoria basado en la configuración de la aplicación real. Esto es útil cuando necesitas probar la integración de tu Web API, ya que te permite simular el comportamiento de la aplicación sin necesidad de un servidor físico o configuración externa.

En este caso, estamos creando un WebApplicationFixture que extiende WebApplicationFactory<Program>. Esta clase personalizada actúa como un "wrapper" para iniciar la aplicación en un entorno de pruebas, y también maneja la configuración de la base de datos y su reseteo entre pruebas utilizando Respawn.

Configuración de Respawn para el Reseteo de la Base de Datos

Respawn es una librería que facilita el reseteo rápido y eficiente de la base de datos, lo cual es especialmente útil en pruebas de integración. Lo que hace Respawn es eliminar los datos de las tablas entre pruebas, asegurando que cada prueba tenga un entorno limpio y consistente sin la necesidad de restaurar toda la base de datos.

En nuestro WebApplicationFixture, estamos utilizando IAsyncLifetime para manejar la inicialización y limpieza asincrónica de los recursos antes y después de que se ejecuten las pruebas. En particular, se usa para la configuración de Respawn:

public class WebApplicationFixture(SqlServerContainerFixture sqlServerContainerFixture)
    : WebApplicationFactory<Program>, IAsyncLifetime
{
    private Respawner? _respawner;

    // Inicialización de Respawn y base de datos
    async Task IAsyncLifetime.InitializeAsync()
    {
        using var scope = Services.CreateScope();
        var dbSeed = scope.ServiceProvider.GetRequiredService<AppDbContextSeed>();

        // Inicializar Respawn
        _respawner = await Respawner.CreateAsync(sqlServerContainerFixture.ConnectionString, new RespawnerOptions
        {
            TablesToIgnore = ["__EFMigrationsHistory"]
        });

        // Asegurar que la base de datos esté creada y con datos de prueba
        await dbSeed.EnsureCreatedAsync();
        await dbSeed.SeedAsync();
    }

    // Reseteo de la base de datos después de las pruebas
    async Task IAsyncLifetime.DisposeAsync()
    {
        if (_respawner is null)
        {
            return;
        }

        // Reseteamos la base de datos a su estado inicial
        await _respawner.ResetAsync(sqlServerContainerFixture.ConnectionString);
    }
}

InitializeAsync():
- Respawner.CreateAsync(): Configuramos Respawn con la cadena de conexión del contenedor SQL Server para reiniciar las tablas relevantes antes de cada clase de pruebas. Las tablas especificadas en TablesToIgnore no se resetean.
- dbSeed.EnsureCreatedAsync() y dbSeed.SeedAsync(): Aseguran que la base de datos esté creada y se tengan datos iniciales para las pruebas.
DisposeAsync():
- Cuando las pruebas de una clase han finalizado, DisposeAsync() es responsable de ejecutar el método ResetAsync() de Respawn, que limpia la base de datos, dejando las tablas listas para la siguiente clase de pruebas.

Configuración de la Base de Datos con `ConfigureWebHost`

Dentro de la clase WebApplicationFixture, también estamos utilizando el método ConfigureWebHost para ajustar la configuración de la aplicación de pruebas, especialmente la conexión a la base de datos. Esto es necesario porque la aplicación por defecto podría estar configurada para usar una base de datos local o un entorno diferente, por lo que tenemos que "reconfigurar" la cadena de conexión para que apunte al contenedor SQL Server levantado con TestContainers:

protected override void ConfigureWebHost(IWebHostBuilder builder)
{
    builder.UseEnvironment("IntegrationTests");
    builder.ConfigureTestServices(services =>
    {
        // Eliminar configuraciones anteriores de la base de datos
        var descriptor = services.SingleOrDefault(
            d => d.ServiceType == typeof(DbContextOptions<AppDbContext>));

        services.Remove(descriptor!);

        var descriptorAppDbContext = services.SingleOrDefault(
            d => d.ServiceType == typeof(AppDbContext));

        services.Remove(descriptorAppDbContext!);

        // Configurar la base de datos para que utilice el contenedor SQL Server
        services.AddDbContext<AppDbContext>(options =>
        {
            options.UseSqlServer(sqlServerContainerFixture.ConnectionString);
        });
    });
}

UseEnvironment("IntegrationTests"): Establece el entorno de pruebas para que la aplicación cargue las configuraciones específicas para pruebas de integración (de ser necesario, podríamos tener un appsettings.IntegrationTests.json).
ConfigureTestServices(): Reconfigura los servicios de la aplicación para que la conexión de la base de datos apunte al contenedor SQL Server. Primero, eliminamos cualquier configuración previa de DbContext y luego agregamos la nueva configuración que utiliza la cadena de conexión proporcionada por el contenedor.

Con esta configuración, WebApplicationFixture:

Levanta la aplicación en memoria utilizando WebApplicationFactory para simular el servidor real.
Utiliza Respawn para reiniciar la base de datos antes de cada clase de pruebas, asegurando un entorno limpio.
Configura la conexión a la base de datos para que apunte al contenedor SQL Server levantado con TestContainers.

Escribir una Prueba de Integración Básica

Las pruebas de integración en este contexto validan la comunicación entre nuestra aplicación y la base de datos SQL Server. Usando WebApplicationFixture y SqlServerContainerFixture, simulamos el entorno de la aplicación y reiniciamos el estado de la base de datos para cada clase de pruebas, asegurando que cada prueba comience desde un estado limpio.

Estructura de la Clase de Prueba `CreateProductTests`

La clase CreateProductTests contiene dos pruebas básicas para el endpoint de creación de productos:

Una prueba para validar que la creación de un producto es exitosa.
Una prueba para verificar el comportamiento cuando se intenta crear un producto con una categoría inexistente.

namespace TestContainers.Integration.Tests.Endpoints.ProductTests;

[Collection(SqlServerContainerFixture.FixtureName)]
public class CreateProductTests : IClassFixture<WebApplicationFixture>
{
    private readonly WebApplicationFixture _factory;
    private readonly AppDbContext _dbContext;
    private readonly HttpClient _client;

    public CreateProductTests(WebApplicationFixture factory)
    {
        _factory = factory;
        _dbContext = factory.DbContext;
        _client = factory.HttpClient;
    }

[Collection]: Esta anotación asegura que SqlServerContainerFixture se utilice para todas las pruebas dentro de esta clase, compartiendo la misma configuración de base de datos.
IClassFixture<WebApplicationFixture>: WebApplicationFixture proporciona acceso a un cliente HTTP en memoria (HttpClient) para simular llamadas HTTP y a AppDbContext para realizar operaciones directas en la base de datos durante la configuración de pruebas.

Primera Prueba: Creación Exitosa de un Producto

La prueba CreateProduct_ReturnsProduct verifica que la creación de un producto con una categoría válida sea exitosa y que los datos devueltos sean correctos.

[Fact]
public async Task CreateProduct_ReturnsProduct()
{
    // Arrange
    var category = await GetFirstCategory();
    var product = new Product
    {
        Name = "Test Product",
        Description = "Test Description",
        Price = 10.0m,
        CategoryId = category.Id
    };

    // Act
    var response = await _client.PostAsJsonAsync("/products", product);

    // Assert
    response.EnsureSuccessStatusCode();

    var createdProduct = await response.Content.ReadFromJsonAsync<Product>();

    createdProduct.ShouldNotBeNull();
    createdProduct.Name.ShouldBeEqualTo(product.Name);
    createdProduct.Price.ShouldBeEqualTo(product.Price);
}

Arrange: Se obtiene una categoría válida desde la base de datos (GetFirstCategory) y se crea un objeto Product con propiedades válidas.
Act: Se envía una solicitud HTTP POST al endpoint /products con los datos del producto. Esto simula una creación de producto en el sistema.
Assert: Se verifica que la respuesta sea exitosa y que los datos del producto creado coincidan con los esperados.

Segunda Prueba: Creación Fallida de un Producto con Categoría Inexistente

La prueba CreateProduct_Fails_WhenCategoryDoesNotExist verifica que la creación de un producto falle cuando se especifica una categoría inválida.

[Fact]
public async Task CreateProduct_Fails_WhenCategoryDoesNotExist()
{
    // Arrange
    var product = new Product
    {
        Name = "Test Product",
        Description = "Test Description",
        Price = 10.0m,
        CategoryId = 0 // Categoría inválida
    };

    // Act
    var response = await _client.PostAsJsonAsync("/products", product);

    // Assert
    response.StatusCode.ShouldBeEqualTo(HttpStatusCode.BadRequest);
}

Arrange: Se crea un objeto Product con una categoría inexistente (CategoryId = 0).
Act: Se envía una solicitud HTTP POST al endpoint /products con el producto, esperando un fallo.
Assert: Se verifica que el servidor responde con un estado BadRequest (400), indicando que la categoría especificada no existe.

Método Auxiliar `GetFirstCategory`

El método GetFirstCategory es una función auxiliar que facilita la recuperación de la primera categoría disponible en la base de datos. Este método permite a las pruebas obtener un CategoryId válido para productos.

private async Task<Category> GetFirstCategory()
{
    return await _dbContext.Categories.FirstAsync();
}

Este enfoque de pruebas ayuda a mantener las pruebas de integración eficientes y confiables, verificando los comportamientos principales del endpoint de creación de productos y manejando casos tanto exitosos como de error.

Cuando Usar Integration Tests o Unit Tests

Las pruebas de software se dividen principalmente en pruebas unitarias e integración, y cada tipo tiene su propósito y contexto de uso. La elección entre uno u otro depende del objetivo de la prueba y del nivel de aislamiento necesario. A continuación, te explicamos cuándo es adecuado utilizar cada tipo de prueba.

Unit Tests: Aislando el Comportamiento de una Funcionalidad Específica

Las pruebas unitarias son el tipo más básico de pruebas. Están diseñadas para verificar el comportamiento de una unidad de código de manera aislada, sin depender de recursos externos como bases de datos, servicios web o sistemas de archivos. Este tipo de pruebas se centran en una pequeña parte del sistema, como un método o función individual, asegurando que se ejecute correctamente bajo diferentes condiciones.

Cuándo usar Unit Tests:

Cuando deseas comprobar el comportamiento de una función o método específico en aislamiento.
Cuando necesitas verificar que una lógica de negocio interna funciona correctamente.
Para asegurar que el código cumple con los requisitos del comportamiento esperado.
Cuando los cambios realizados no deberían afectar otras partes del sistema (por ejemplo, al refactorizar código o agregar nuevas características pequeñas).

Ventajas:

Rápidos de ejecutar: debido a que son pequeños y no requieren recursos externos.
Aislamiento: puedes asegurarte de que las dependencias externas no interfieran.
Fáciles de automatizar: las pruebas unitarias suelen ser fáciles de configurar y ejecutar en una suite de pruebas automatizadas.

Integration Tests: Validando la Interacción entre Componentes

Las pruebas de integración van un paso más allá, probando cómo diferentes unidades de código interactúan entre sí y con sistemas externos, como bases de datos, API, o sistemas de mensajería. Se aseguran de que los componentes del sistema funcionen juntos de la forma esperada.

Cuándo usar Integration Tests:

Cuando necesitas verificar cómo los módulos o servicios interactúan entre sí.
Si deseas probar la integración con sistemas externos como bases de datos, servicios web, o colas de mensajes.
Para validar que los cambios no afecten negativamente la interacción de diferentes capas del sistema.
Para garantizar que la configuración de infraestructura y las dependencias externas (como bases de datos) estén correctamente conectadas y funcionando.

Ventajas:

Cobertura completa de flujo: Validan el flujo real de datos a través de los diferentes componentes del sistema, lo que aumenta la confianza en la funcionalidad de alto nivel.
Identificación de problemas de integración: Detectan problemas en la forma en que los componentes interactúan entre sí, lo cual no se podría verificar con pruebas unitarias.
Reducción de errores en producción: Aseguran que el sistema se comporte correctamente en un entorno más cercano al real.

¿Unit Tests o Integration Tests? ¿Cuándo usar cada uno?

A menudo, la clave está en la combinación adecuada de ambos tipos de pruebas:

Unit Tests: Son el primer paso en el ciclo de vida del desarrollo, permitiendo detectar errores rápidamente y de forma aislada.
Integration Tests: Deben complementarse con las pruebas unitarias para garantizar que todos los componentes funcionen correctamente cuando se ensamblen.

Es decir:

Si estás desarrollando una pequeña funcionalidad que no interactúa con sistemas externos, prioriza las pruebas unitarias.
Si estás trabajando con interacción entre sistemas, bases de datos o servicios externos, añade pruebas de integración para validar estos comportamientos más complejos.

Ambos tipos de pruebas son fundamentales para una estrategia de pruebas completa, y saber cuándo usar cada uno te ayudará a mantener una buena cobertura de pruebas y mejorar la calidad de tu software.

Consideraciones para Escenarios Complejos

Cuando trabajamos con escenarios más allá de las simples operaciones CRUD, es crucial que nuestras pruebas de integración sean flexibles y realistas. A continuación, algunos puntos a considerar:

Datos de Configuración Inicial (Seed Data)

En escenarios complejos, es probable que necesites un conjunto de datos predefinido para representar un estado inicial específico de la base de datos. Utilizar datos de configuración inicial (o "seed data") permite que las pruebas se ejecuten en condiciones que simulan situaciones de negocio más avanzadas.

Estrategia de Configuración: Puedes agregar datos de configuración en la fase de inicialización del WebApplicationFixture. Esto permite que los datos de prueba específicos estén listos cada vez que se ejecuten las pruebas.
Uso de Factories o Builders: Para configurar datos complejos, considera el uso de patrones como Factory o Builder que ayuden a crear objetos con propiedades adecuadas para el escenario, manteniendo el código de prueba más limpio y reutilizable.

Simulación de Estados de la Aplicación

Algunas pruebas pueden requerir que la aplicación esté en un estado específico antes de ejecutar el test (como el "estado de procesamiento" o "finalizado" de una orden). Para simular estos estados:

Configuración de Estados con Estados Mock o Flags: Configura los estados directamente en las entidades de prueba, o utiliza servicios mock (como mocks de notificaciones, correos electrónicos o servicios externos) para simular estados sin requerir que la aplicación ejecute todos los pasos.
Test Doubles: Para escenarios que dependen de servicios externos, considera el uso de "doubles" (dummies, mocks, etc.) que representen estos servicios sin necesidad de hacer llamadas reales. Esto ayuda a centrar la prueba en la lógica de negocio sin complicaciones adicionales.

Verificación de Efectos Colaterales

Cuando las pruebas de integración implican actualizaciones de datos o envío de eventos a otros sistemas, es importante verificar que los efectos colaterales ocurren como se espera.

Simulación de Eventos: Para los sistemas basados en eventos, puedes verificar que los eventos se envíen correctamente o incluso simular la recepción de eventos que la aplicación debe procesar.
Validación de Estados Finales: Después de realizar una operación, verifica que las tablas relevantes y los estados de las entidades reflejen los cambios esperados.

Los escenarios complejos pueden agregar valor significativo a las pruebas de integración, ayudando a identificar problemas difíciles de reproducir en condiciones normales. Aplicar una configuración cuidadosa, incluyendo datos de configuración inicial, control de transacciones, y mocks de estados y dependencias, permitirá manejar estos escenarios de forma efectiva y aumentar la robustez de las pruebas de integración.

Conclusión

Las pruebas de integración son esenciales para garantizar que los componentes de una aplicación funcionen de manera coherente y sin problemas cuando se combinan. A lo largo de este tutorial, hemos visto cómo configurar un entorno de pruebas sólido y flexible utilizando herramientas como xUnit, Testcontainers, Respawn, y WebApplicationFactory en .NET, permitiendo realizar pruebas con una base de datos SQL Server en contenedor y manteniendo un servidor de pruebas en memoria.

Al seguir las prácticas descritas, desde el uso de contenedores hasta la optimización de la infraestructura de pruebas, puedes asegurar que tu aplicación se mantenga estable a lo largo del ciclo de desarrollo. Este enfoque no solo minimiza errores que solo podrían detectarse en producción, sino que también facilita la identificación y resolución de problemas antes de que escalen.

Recuerda que, aunque estas pruebas pueden ser más costosas en términos de tiempo de ejecución y configuración que las pruebas unitarias, la inversión en pruebas de integración robustas proporciona un valor significativo. Estas pruebas ayudan a prevenir fallos graves y aseguran una experiencia de usuario final consistente. Adoptar buenas prácticas de optimización y aprovechar herramientas modernas para la gestión de entornos de prueba te permitirá mantener una suite de pruebas rápida y eficiente, fortaleciendo la confiabilidad de tus aplicaciones en el tiempo.

DEV Community: Isaac Ojeda

EF Core: La explosión cartesiana — Hiciste todo bien y aun así el query es un desastre

El escenario: un Include razonable que se vuelve un problema

Lo que EF Core hace por debajo

Cómo detectarlo

El warning de EF Core

Los tiempos que no tienen proporción

La solución: AsSplitQuery

AsSplitQuery no es siempre la respuesta

El Include que no hace nada

La proyección con Select como alternativa

Resumen

¿Qué sigue?

EF Core: N+1 — Una query en dev, mil queries en producción

Por qué es el más traicionero de los tres

Cómo ocurre en EF Core

La variante que se escapa en code review

Cómo detectarlo

Las soluciones

Include — cuando necesitas la entidad completa

Proyección con Select — la más eficiente para DTOs

Cuando el enriquecimiento es inevitable

Resumen

¿Qué sigue?

Ports & Adapters: cómo aislar tu núcleo de todo lo que puede cambiar

Ports & Adapters: cómo aislar tu núcleo de todo lo que puede cambiar

Introducción

Desarrollo

El problema concreto: el correo electrónico

El port: define el contrato, no la implementación

Los adapters: implementaciones intercambiables

El Factory: construir el adapter correcto según la configuración

El decorador: comportamiento sin contaminar los adaptadores

El adaptador Null: tu mejor aliado en pruebas

Este patrón escala a todo

Conclusión

Referencias y recursos para aprender más

Cómo manejar fallos transitorios en .NET con Polly y ResiliencePipelineBuilder

Introducción

El problema real

¿Qué es transient fault handling?

En HTTP no basta con capturar HttpRequestException

¿Cuándo tiene sentido reintentar según el status code?

Retry Pattern

Un punto importante: idempotencia

Instalación

El servicio inestable del ejemplo

Creando el pipeline de retry

Qué hace cada opción

¿Por qué usar backoff exponencial?

¿Y el jitter para qué sirve?

Ejecutando la operación con resiliencia

Centralizando pipelines reutilizables

También existe el pipeline sin tipo genérico

Retry no vive solo

Cuándo NO usar retry

Qué conviene observar en producción

Ejemplo más cercano a un caso real

Ejecutar el ejemplo

Conclusión

Referencias

EF Core: tu query funciona, tus pruebas pasan… y estás leyendo 50,000 filas para devolver 3

Por qué casi nadie lo detecta a tiempo

Problema 1: el ToList() que mueve el filtro fuera de SQL

El origen: una excepción legítima

La “solución” que parece arreglar todo

La forma correcta

Problema 2: la proyección parece pequeña, pero la consulta deja de ser eficiente

El escenario

La forma correcta

Cómo inspeccionar lo que EF Core realmente está haciendo

Opción 1: logs en desarrollo

Opción 2: ToQueryString()

Un detalle extra en consultas de lectura

Sobre asistentes de código y queries “que funcionan”

Resumen

¿Qué sigue?

Primeros pasos con Microsoft Agent Framework: construyendo un chatbot de soporte con C#

Introducción

Desarrollo

`Include` — cuando necesitas la entidad completa

Proyección con `Select` — la más eficiente para DTOs

El adaptador `Null`: tu mejor aliado en pruebas

En HTTP no basta con capturar `HttpRequestException`

Problema 1: el `ToList()` que mueve el filtro fuera de SQL

Opción 2: `ToQueryString()`

🧠 ¿Por qué usar `[KernelFunction]`?

🧠 ¿Qué es un `ChatCompletionAgent`?