Arquitectura de Agentes de IA en C# con Semantic Kernel: Guía Práctica

El auge de los agentes de IA autónomos está transformando la ingeniería de software corporativa. Sin embargo, cuando las empresas intentan mover sus pruebas de concepto (PoCs) en Python a sistemas .NET de misión crítica, se enfrentan a un muro de inestabilidad: falta de determinismo, pérdida de estado, alucinaciones no controladas y un acoplamiento extremo a las APIs de los proveedores (OpenAI, Anthropic, etc.).

Escribir un wrapper sobre un LLM es trivial. Orquestar un ecosistema de agentes que tome decisiones de negocio, ejecute herramientas (tools) y acceda a bases de datos en producción sin comprometer la arquitectura del sistema, es un reto de ingeniería pura.

En este artículo, exploramos cómo orquestar arquitecturas agénticas en .NET / C# utilizando Semantic Kernel bajo los principios de Clean Architecture.

Desafíos de los Agentes en Producción

Los modelos de lenguaje grande (LLMs) son inherentemente probabilísticos. Los sistemas empresariales exigen determinismo. Esta fricción genera tres desafíos fundamentales:

1. Gestión de Estado (Statefulness): Un agente debe recordar el contexto de una operación compleja que puede durar minutos u horas. Si el servidor se reinicia, ¿el agente pierde la memoria?
2. Orquestación y “Tool Calling”: Cuando un agente necesita consultar una base de datos de clientes o disparar un correo, debe hacerlo a través de interfaces controladas (sandbox), nunca inyectando SQL o realizando llamadas HTTP directas sin validación.
3. Manejo de Fallos (Resiliencia): Los proveedores de IA imponen límites de cuota (Rate Limiting) y sufren latencias impredecibles.

La Arquitectura Propuesta: Semantic Kernel + Clean Architecture

Microsoft Semantic Kernel es el SDK ideal para .NET porque trata a la IA como un componente más de la infraestructura, no como el centro del universo.

En un contexto de Clean Architecture, la IA reside estrictamente en la capa de Infrastructure. El “Cerebro” de tu aplicación (la capa de Domain y Application) dicta las reglas, valida las propuestas del agente y mantiene el control absoluto.

Ejemplo Práctico: Agente Extractor de Metadatos

Vamos a implementar un agente que analiza un documento no estructurado, extrae metadatos clave y los persiste, utilizando inyección de dependencias y aislamiento de estado.

1. Definición del Plugin (Tool Calling Confinado)

En Semantic Kernel, las herramientas que el agente puede usar se definen como Plugins. Estos plugins son clases C# nativas decoradas con atributos.

// Capa: Application (Use Cases / Plugins)
using Microsoft.SemanticKernel;
using System.ComponentModel;

public class DatabasePlugin
{
    private readonly IMetadataRepository _repository;

    public DatabasePlugin(IMetadataRepository repository)
    {
        _repository = repository; // Inyectado de forma segura
    }

    [KernelFunction, Description("Guarda los metadatos extraídos de un modelo 3D en la base de datos.")]
    public async Task<string> SaveMetadataAsync(
        [Description("ID único del modelo")] string modelId,
        [Description("Número de polígonos detectados")] int polygons,
        [Description("Formato del archivo")] string format)
    {
        // 🛡️ El dominio C# valida los datos antes de hacer nada
        if (polygons < 0) return "Error: Los polígonos no pueden ser negativos.";

        await _repository.SaveAsync(modelId, polygons, format);
        return "Metadata guardada con éxito en SQL Server.";
    }
}

2. Orquestación del Agente con Redis y Azure OpenAI

Construimos el agente instanciando el Kernel y conectándolo a nuestros proveedores.

// Capa: Infrastructure (Agent Orchestrator)
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.ChatCompletion;

public class MetadataAgentService : IMetadataAgentService
{
    private readonly Kernel _kernel;
    private readonly IChatCompletionService _chatService;
    
    public MetadataAgentService(Kernel kernel, DatabasePlugin dbPlugin)
    {
        _kernel = kernel;
        // Inyectamos el plugin C# de forma nativa
        _kernel.Plugins.AddFromObject(dbPlugin, "DatabaseTools"); 
        _chatService = _kernel.GetRequiredService<IChatCompletionService>();
    }

    public async Task ProcessDocumentAsync(string userPrompt)
    {
        var history = new ChatHistory("Eres un agente experto en extracción de datos. Extrae polígonos y formatos. Usa la herramienta DatabaseTools para guardar tus hallazgos.");
        history.AddUserMessage(userPrompt);

        // Habilitamos que el agente decida llamar automáticamente a nuestras funciones C#
        var executionSettings = new OpenAIPromptExecutionSettings 
        {
            ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions
        };

        // El SDK orquesta el bucle de "Razonamiento -> Llamada a Herramienta C# -> Respuesta"
        var result = await _chatService.GetChatMessageContentAsync(
            history, 
            executionSettings, 
            _kernel
        );
    }
}

3. Integración con Servicios (Persistencia y Desacoplamiento)

Para lograr verdadera escalabilidad, tu agente no puede vivir aislado en memoria RAM.

1. Redis para ChatHistory: Utilizamos Redis para persistir el ChatHistory. Si el contenedor Docker se reinicia, el agente recupera su contexto exacto y continúa la operación.
2. Azure OpenAI + Polly: Envolvemos el IChatCompletionService con políticas de Exponential Backoff (Polly). Si Azure devuelve un error HTTP 429 (Too Many Requests), el backend reintenta inteligentemente sin fallar la petición del usuario.
3. RabbitMQ para Worker Agents: Las peticiones al agente se encolan. La API web solo devuelve un 202 Accepted, mientras un Worker Service procesa la IA en background.

Resultados y Métricas en Producción

Al aplicar esta arquitectura en clientes reales, los resultados son contundentes:

• Reducción de Timeouts (504): Del 8% al 0.01% al aislar el procesamiento de IA en Workers.
• Fiabilidad del Dato: Al confinar el Tool Calling a clases de C# con tipado fuerte, se eliminaron los errores de inyección SQL (SQLi) causados por JSONs mal formados del LLM.
• Flexibilidad (Vendor-Agnostic): Cambiar de AzureOpenAI a un modelo Ollama local tomó 2 líneas de código en Program.cs, sin tocar la lógica de negocio ni los plugins.

Conclusión

La IA generativa no reemplaza a la ingeniería de software; la hace más necesaria que nunca. Un agente es tan fuerte como los rieles arquitectónicos sobre los que opera. Semantic Kernel, acoplado a los principios de Clean Architecture en .NET, proporciona esos rieles.