Router conversacional: arquitectura, estado e intenciones para bots

Introducción

Los routers conversacionales son el cerebro de un chatbot: deciden cómo manejar cada mensaje del usuario. En este tutorial aprenderás a implementar un router conversacional robusto que gestiona estados, intenciones, y flujos complejos.

Arquitectura de un Router

Un router conversacional efectivo necesita:

Gestión de Estado: Recordar el contexto de la conversación
Resolución de Intenciones: Determinar qué quiere hacer el usuario
Enrutamiento: Dirigir a los handlers apropiados
Comandos Globales: Manejar comandos prioritarios (menú, ayuda)
Fallbacks: Respuestas cuando no se entiende el mensaje

Modelo de Estado de Conversación

public class ConversationState
{
    public required string UserId { get; init; }
    public string? CurrentFlow { get; set; }
    public Dictionary<string, object> Context { get; set; } = new();
    public DateTime LastInteraction { get; set; } = DateTime.UtcNow;
    public string? PendingAction { get; set; }
    public int MessageCount { get; set; }
}

public interface IConversationStateStore
{
    Task<ConversationState> GetAsync(string userId, CancellationToken cancellationToken = default);
    Task SaveAsync(ConversationState state, CancellationToken cancellationToken = default);
    Task ClearAsync(string userId, CancellationToken cancellationToken = default);
}

Implementación del Router

using Microsoft.Extensions.Logging;

public class ConversationRouter
{
    private readonly IConversationStateStore _stateStore;
    private readonly IIntentClassificationService _intentClassifier;
    private readonly ILogger<ConversationRouter> _logger;
    private readonly Dictionary<string, Func<RouteContext, Task<string>>> _handlers;
    
    public ConversationRouter(
        IConversationStateStore stateStore,
        IIntentClassificationService intentClassifier,
        ILogger<ConversationRouter> logger)
    {
        _stateStore = stateStore;
        _intentClassifier = intentClassifier;
        _logger = logger;
        
        // Registrar handlers
        _handlers = new()
        {
            ["menu"] = HandleMenuAsync,
            ["search"] = HandleSearchAsync,
            ["help"] = HandleHelpAsync,
            ["buy"] = HandleBuyAsync,
            ["status"] = HandleStatusAsync
        };
    }
    
    public async Task<string> RouteAsync(
        string userId,
        string message,
        CancellationToken cancellationToken = default)
    {
        _logger.LogInformation("Routing message for user {UserId}: {Message}", userId, message);
        
        // 1. Obtener estado
        var state = await _stateStore.GetAsync(userId, cancellationToken);
        
        // 2. Manejar comandos globales (prioridad máxima)
        var globalResponse = await TryHandleGlobalCommandAsync(message, state);
        if (globalResponse != null)
        {
            state.MessageCount++;
            await _stateStore.SaveAsync(state, cancellationToken);
            return globalResponse;
        }
        
        // 3. Manejar flujo activo
        if (!string.IsNullOrEmpty(state.CurrentFlow))
        {
            var flowResponse = await TryHandleActiveFlowAsync(message, state, cancellationToken);
            if (flowResponse != null)
            {
                state.MessageCount++;
                await _stateStore.SaveAsync(state, cancellationToken);
                return flowResponse;
            }
        }
        
        // 4. Clasificar intención
        var classification = await _intentClassifier.ClassifyAsync(message, cancellationToken);
        
        _logger.LogInformation(
            "Intent classified: {Intent} (confidence: {Confidence})",
            classification.Intent,
            classification.Confidence);
        
        // 5. Enrutar al handler apropiado
        if (_handlers.TryGetValue(classification.Intent, out var handler))
        {
            var context = new RouteContext
            {
                UserId = userId,
                Message = message,
                State = state,
                Classification = classification
            };
            
            var response = await handler(context);
            
            state.MessageCount++;
            await _stateStore.SaveAsync(state, cancellationToken);
            
            return response;
        }
        
        // 6. Fallback
        _logger.LogWarning("No handler found for intent: {Intent}", classification.Intent);
        return "No estoy seguro de entender. ¿Puedes reformular tu pregunta?";
    }
    
    private async Task<string?> TryHandleGlobalCommandAsync(
        string message,
        ConversationState state)
    {
        var normalized = message.ToLowerInvariant().Trim();
        
        // Comando de menú
        if (normalized is "menu" or "menú" or "ayuda" or "help" or "inicio")
        {
            state.CurrentFlow = null;
            state.Context.Clear();
            return BuildMenuMessage();
        }
        
        // Comando de cancelar
        if (normalized is "cancelar" or "cancel" or "salir" or "exit")
        {
            state.CurrentFlow = null;
            state.Context.Clear();
            return "Operación cancelada. ¿En qué puedo ayudarte?";
        }
        
        return null;
    }
    
    private async Task<string?> TryHandleActiveFlowAsync(
        string message,
        ConversationState state,
        CancellationToken cancellationToken)
    {
        // Manejar flujo activo basado en state.CurrentFlow
        return state.CurrentFlow switch
        {
            "purchase" => await HandlePurchaseFlowAsync(message, state, cancellationToken),
            "registration" => await HandleRegistrationFlowAsync(message, state, cancellationToken),
            "feedback" => await HandleFeedbackFlowAsync(message, state, cancellationToken),
            _ => null
        };
    }
    
    private async Task<string> HandleMenuAsync(RouteContext context)
    {
        context.State.CurrentFlow = null;
        context.State.Context.Clear();
        return BuildMenuMessage();
    }
    
    private async Task<string> HandleSearchAsync(RouteContext context)
    {
        var query = context.Classification.Entities?.ContainsKey("query") == true
            ? context.Classification.Entities["query"].ToString()
            : context.Message;
        
        _logger.LogInformation("Handling search for: {Query}", query);
        
        // Implementar búsqueda
        return $"Buscando: {query}...";
    }
    
    private async Task<string> HandleHelpAsync(RouteContext context)
    {
        return """
        Puedo ayudarte con:
        
        🔍 Buscar productos o servicios
        🛒 Realizar compras
        📦 Consultar el estado de pedidos
        📋 Ver el menú de opciones
        
        ¿Qué necesitas?
        """;
    }
    
    private async Task<string> HandleBuyAsync(RouteContext context)
    {
        // Iniciar flujo de compra
        context.State.CurrentFlow = "purchase";
        context.State.Context["step"] = "product_selection";
        
        return "¿Qué producto te gustaría comprar?";
    }
    
    private async Task<string> HandleStatusAsync(RouteContext context)
    {
        var orderId = context.Classification.Entities?.ContainsKey("order_id") == true
            ? context.Classification.Entities["order_id"].ToString()
            : null;
        
        if (orderId == null)
        {
            return "Por favor, proporciona tu número de pedido.";
        }
        
        return $"Consultando estado del pedido {orderId}...";
    }
    
    private async Task<string> HandlePurchaseFlowAsync(
        string message,
        ConversationState state,
        CancellationToken cancellationToken)
    {
        var step = state.Context.TryGetValue("step", out var stepObj)
            ? stepObj?.ToString()
            : "product_selection";
        
        return step switch
        {
            "product_selection" => await HandleProductSelectionAsync(message, state),
            "quantity_selection" => await HandleQuantitySelectionAsync(message, state),
            "confirmation" => await HandlePurchaseConfirmationAsync(message, state),
            _ => "Flujo de compra no válido."
        };
    }
    
    private async Task<string> HandleProductSelectionAsync(
        string message,
        ConversationState state)
    {
        state.Context["selected_product"] = message;
        state.Context["step"] = "quantity_selection";
        
        return $"Has seleccionado: {message}\n\n¿Cuántas unidades deseas?";
    }
    
    private async Task<string> HandleQuantitySelectionAsync(
        string message,
        ConversationState state)
    {
        if (!int.TryParse(message, out var quantity) || quantity <= 0)
        {
            return "Por favor, indica una cantidad válida.";
        }
        
        state.Context["quantity"] = quantity;
        state.Context["step"] = "confirmation";
        
        var product = state.Context["selected_product"];
        
        return $"""
        Resumen de tu pedido:
        • Producto: {product}
        • Cantidad: {quantity}
        
        ¿Confirmas la compra? (sí/no)
        """;
    }
    
    private async Task<string> HandlePurchaseConfirmationAsync(
        string message,
        ConversationState state)
    {
        var normalized = message.ToLowerInvariant().Trim();
        
        if (normalized is "sí" or "si" or "s" or "yes" or "y")
        {
            var product = state.Context["selected_product"];
            var quantity = state.Context["quantity"];
            
            // Procesar pedido
            _logger.LogInformation(
                "Processing purchase: Product={Product}, Quantity={Quantity}",
                product,
                quantity);
            
            // Limpiar flujo
            state.CurrentFlow = null;
            state.Context.Clear();
            
            return $"✅ Pedido confirmado: {quantity}x {product}\n\nRecibirás un correo con los detalles.";
        }
        else
        {
            // Cancelar
            state.CurrentFlow = null;
            state.Context.Clear();
            
            return "Pedido cancelado. ¿Puedo ayudarte con algo más?";
        }
    }
    
    private async Task<string> HandleRegistrationFlowAsync(
        string message,
        ConversationState state,
        CancellationToken cancellationToken)
    {
        // Implementar flujo de registro
        return "Flujo de registro...";
    }
    
    private async Task<string> HandleFeedbackFlowAsync(
        string message,
        ConversationState state,
        CancellationToken cancellationToken)
    {
        // Implementar flujo de feedback
        return "Flujo de feedback...";
    }
    
    private string BuildMenuMessage()
    {
        return """
        🏠 Menú Principal
        
        Opciones disponibles:
        1️⃣ Buscar productos
        2️⃣ Ver mis pedidos
        3️⃣ Hacer una compra
        4️⃣ Ayuda
        
        Escribe el número o describe lo que necesitas.
        """;
    }
}

public class RouteContext
{
    public required string UserId { get; init; }
    public required string Message { get; init; }
    public required ConversationState State { get; init; }
    public required IntentClassificationResult Classification { get; init; }
}

Gestión de Estado con Redis

using Microsoft.Extensions.Caching.Distributed;
using System.Text.Json;

public class RedisConversationStateStore : IConversationStateStore
{
    private readonly IDistributedCache _cache;
    private readonly TimeSpan _stateExpiration = TimeSpan.FromHours(24);
    
    public RedisConversationStateStore(IDistributedCache cache)
    {
        _cache = cache;
    }
    
    public async Task<ConversationState> GetAsync(
        string userId,
        CancellationToken cancellationToken = default)
    {
        var key = GetCacheKey(userId);
        var json = await _cache.GetStringAsync(key, cancellationToken);
        
        if (json == null)
        {
            return new ConversationState { UserId = userId };
        }
        
        return JsonSerializer.Deserialize<ConversationState>(json)
            ?? new ConversationState { UserId = userId };
    }
    
    public async Task SaveAsync(
        ConversationState state,
        CancellationToken cancellationToken = default)
    {
        var key = GetCacheKey(state.UserId);
        var json = JsonSerializer.Serialize(state);
        
        await _cache.SetStringAsync(
            key,
            json,
            new DistributedCacheEntryOptions
            {
                AbsoluteExpirationRelativeToNow = _stateExpiration
            },
            cancellationToken);
    }
    
    public async Task ClearAsync(
        string userId,
        CancellationToken cancellationToken = default)
    {
        var key = GetCacheKey(userId);
        await _cache.RemoveAsync(key, cancellationToken);
    }
    
    private string GetCacheKey(string userId)
    {
        return $"conversation:state:{userId}";
    }
}

Router con Middleware Pattern

public interface IRouterMiddleware
{
    Task<string?> ProcessAsync(
        RouteContext context,
        Func<RouteContext, Task<string>> next);
}

public class LoggingMiddleware : IRouterMiddleware
{
    private readonly ILogger<LoggingMiddleware> _logger;
    
    public LoggingMiddleware(ILogger<LoggingMiddleware> logger)
    {
        _logger = logger;
    }
    
    public async Task<string?> ProcessAsync(
        RouteContext context,
        Func<RouteContext, Task<string>> next)
    {
        _logger.LogInformation(
            "Processing message from {UserId}: {Message}",
            context.UserId,
            context.Message);
        
        var stopwatch = Stopwatch.StartNew();
        var response = await next(context);
        stopwatch.Stop();
        
        _logger.LogInformation(
            "Response generated in {Elapsed}ms",
            stopwatch.ElapsedMilliseconds);
        
        return response;
    }
}

public class RateLimitMiddleware : IRouterMiddleware
{
    private readonly Dictionary<string, Queue<DateTime>> _userRequests = new();
    private readonly int _maxRequestsPerMinute = 10;
    
    public async Task<string?> ProcessAsync(
        RouteContext context,
        Func<RouteContext, Task<string>> next)
    {
        if (!_userRequests.ContainsKey(context.UserId))
        {
            _userRequests[context.UserId] = new Queue<DateTime>();
        }
        
        var userQueue = _userRequests[context.UserId];
        var now = DateTime.UtcNow;
        var oneMinuteAgo = now.AddMinutes(-1);
        
        // Limpiar requests antiguos
        while (userQueue.Count > 0 && userQueue.Peek() < oneMinuteAgo)
        {
            userQueue.Dequeue();
        }
        
        if (userQueue.Count >= _maxRequestsPerMinute)
        {
            return "Has enviado demasiados mensajes. Por favor, espera un momento.";
        }
        
        userQueue.Enqueue(now);
        
        return await next(context);
    }
}

Testing del Router

using Xunit;
using Moq;

public class ConversationRouterTests
{
    [Fact]
    public async Task RouteAsync_MenuCommand_ReturnsMenuMessage()
    {
        // Arrange
        var mockStateStore = new Mock<IConversationStateStore>();
        mockStateStore
            .Setup(x => x.GetAsync(It.IsAny<string>(), It.IsAny<CancellationToken>()))
            .ReturnsAsync(new ConversationState { UserId = "test-user" });
        
        var mockClassifier = new Mock<IIntentClassificationService>();
        var logger = Mock.Of<ILogger<ConversationRouter>>();
        
        var router = new ConversationRouter(
            mockStateStore.Object,
            mockClassifier.Object,
            logger);
        
        // Act
        var response = await router.RouteAsync("test-user", "menu");
        
        // Assert
        Assert.Contains("Menú Principal", response);
    }
    
    [Fact]
    public async Task RouteAsync_PurchaseFlow_CompletesSuccessfully()
    {
        // Arrange
        var state = new ConversationState { UserId = "test-user" };
        var mockStateStore = new Mock<IConversationStateStore>();
        mockStateStore
            .Setup(x => x.GetAsync(It.IsAny<string>(), It.IsAny<CancellationToken>()))
            .ReturnsAsync(state);
        
        var mockClassifier = new Mock<IIntentClassificationService>();
        mockClassifier
            .Setup(x => x.ClassifyAsync(It.IsAny<string>(), It.IsAny<CancellationToken>()))
            .ReturnsAsync(new IntentClassificationResult
            {
                Intent = "buy",
                Confidence = 0.95
            });
        
        var logger = Mock.Of<ILogger<ConversationRouter>>();
        var router = new ConversationRouter(
            mockStateStore.Object,
            mockClassifier.Object,
            logger);
        
        // Act - Start purchase
        var response1 = await router.RouteAsync("test-user", "quiero comprar");
        
        // Act - Select product
        var response2 = await router.RouteAsync("test-user", "libro");
        
        // Act - Select quantity
        var response3 = await router.RouteAsync("test-user", "2");
        
        // Act - Confirm
        var response4 = await router.RouteAsync("test-user", "sí");
        
        // Assert
        Assert.Contains("producto", response1, StringComparison.OrdinalIgnoreCase);
        Assert.Contains("unidades", response2, StringComparison.OrdinalIgnoreCase);
        Assert.Contains("Resumen", response3, StringComparison.OrdinalIgnoreCase);
        Assert.Contains("confirmado", response4, StringComparison.OrdinalIgnoreCase);
    }
}

Mejores Prácticas

1. Prioridad de Comandos

// Global > Flow > Intent > Fallback
private async Task<string> RouteWithPriorityAsync(string message, ConversationState state)
{
    return await TryHandleGlobalCommandAsync(message, state)
        ?? await TryHandleActiveFlowAsync(message, state)
        ?? await TryHandleIntentAsync(message, state)
        ?? GetFallbackMessage();
}

2. Timeouts para Flujos

public bool IsFlowExpired(ConversationState state)
{
    const int FlowTimeoutMinutes = 15;
    return state.LastInteraction.AddMinutes(FlowTimeoutMinutes) < DateTime.UtcNow;
}

3. Context Cleanup

public void CleanupExpiredState(ConversationState state)
{
    if (IsFlowExpired(state))
    {
        state.CurrentFlow = null;
        state.Context.Clear();
    }
}

Conclusión

Un router conversacional bien diseñado es esencial para chatbots robustos. Gestiona estados, enruta correctamente, maneja flujos complejos, y proporciona fallbacks apropiados. El uso de middleware permite agregar funcionalidades como logging y rate limiting de forma modular.

Palabras clave: conversational router, chatbot architecture, state management, intent routing, flow handling, middleware pattern