# RF-MGN-018-006: Analytics y Métricas **Módulo:** MGN-018 - AI Agents & Chatbots **Prioridad:** P2 **Story Points:** 8 **Estado:** Definido **Fecha:** 2025-12-05 ## Descripción El sistema debe proporcionar dashboards y reportes completos sobre el rendimiento de los agentes de IA, incluyendo métricas de conversaciones, satisfacción del usuario, consumo de recursos, y análisis de costos. Los dashboards permiten a los administradores tomar decisiones informadas sobre configuración y optimización. ## Actores - **Actor Principal:** Tenant Admin - **Actores Secundarios:** - Supervisor (métricas operativas) - Sistema (recolección de datos) ## Precondiciones 1. Agente con conversaciones procesadas 2. Permiso de ver analytics ## Métricas Principales ### 1. Métricas de Conversación ```typescript interface ConversationMetrics { period: DateRange; // Volumen total_conversations: number; conversations_by_channel: Record; conversations_by_day: Array<{ date: string; count: number }>; // Estados active_conversations: number; completed_conversations: number; escalated_conversations: number; expired_conversations: number; // Tasas resolution_rate: number; // Completadas sin escalación escalation_rate: number; // Escaladas a humano abandonment_rate: number; // Expiradas // Duración avg_conversation_duration_minutes: number; avg_messages_per_conversation: number; avg_response_time_ms: number; } ``` ### 2. Métricas de Satisfacción ```typescript interface SatisfactionMetrics { period: DateRange; // Ratings total_ratings: number; average_rating: number; // 1-5 rating_distribution: Record<1|2|3|4|5, number>; // NPS nps_score: number; // -100 a 100 promoters: number; // 9-10 passives: number; // 7-8 detractors: number; // 0-6 // Feedback helpful_percentage: number; would_recommend_percentage: number; // Trending rating_trend: 'improving' | 'stable' | 'declining'; rating_by_day: Array<{ date: string; avg_rating: number }>; } ``` ### 3. Métricas de Consumo ```typescript interface UsageMetrics { period: DateRange; // Tokens total_tokens_used: number; input_tokens: number; output_tokens: number; tokens_by_model: Record; tokens_by_day: Array<{ date: string; tokens: number }>; // Costos estimated_cost_usd: number; cost_by_model: Record; cost_per_conversation: number; cost_per_message: number; // Budget monthly_budget_usd?: number; budget_used_percentage?: number; projected_month_end_cost?: number; // RAG rag_queries: number; rag_tokens_used: number; // Tools tool_executions: number; tool_executions_by_type: Record; } ``` ### 4. Métricas de Rendimiento ```typescript interface PerformanceMetrics { period: DateRange; // Latencia avg_response_time_ms: number; p50_response_time_ms: number; p95_response_time_ms: number; p99_response_time_ms: number; // Disponibilidad uptime_percentage: number; failed_requests: number; timeout_rate: number; // LLM llm_success_rate: number; llm_avg_latency_ms: number; fallback_usage_count: number; // RAG rag_avg_search_time_ms: number; rag_hit_rate: number; // % de queries con resultados útiles } ``` ### 5. Métricas de Knowledge Base ```typescript interface KBMetrics { period: DateRange; // Uso total_queries: number; queries_with_results: number; queries_without_results: number; hit_rate: number; // Por documento document_usage: Array<{ document_id: string; document_name: string; times_referenced: number; avg_similarity_score: number; }>; // Gaps common_queries_without_results: Array<{ query_pattern: string; frequency: number; }>; // Tamaño total_documents: number; total_chunks: number; storage_used_mb: number; } ``` ## Dashboard Principal ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ 📊 Analytics - Asistente de Ventas [Últimos 30 días ▼]│ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐│ │ │ Conversaciones│ │ Resolución │ │ Satisfacción │ │ Costo ││ │ │ 1,234 │ │ 78.5% │ │ ⭐ 4.2 │ │ $45.67 USD ││ │ │ ↑ 12% │ │ ↑ 5% │ │ ↑ 0.3 │ │ ↓ 8% ││ │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘│ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐│ │ │ Conversaciones por Día ││ │ │ 80 ┤ ╭─╮ ││ │ │ 60 ┤ ╭─╮ ╭─╮ │ │ ╭─╮ ││ │ │ 40 ┤ ╭─╮ ╭─╮ │ │ ╭─╮ │ │ │ │ │ │ ││ │ │ 20 ┤ ╭─╮│ │ │ │ │ │ │ │ │ │ ╭─╮ │ │ │ │ ││ │ │ 0 ┴─┴─┴┴─┴───┴─┴───┴─┴──┴─┴───┴─┴──┴─┴─┴─┴───┴─┴────────────── ││ │ │ 1 3 5 7 9 11 13 15 17 19 21 23 25 27 29 ││ │ └─────────────────────────────────────────────────────────────────────┘│ │ │ │ ┌─────────────────────────────┐ ┌─────────────────────────────────────┐│ │ │ Distribución de Ratings │ │ Uso por Canal ││ │ │ │ │ ││ │ │ ⭐⭐⭐⭐⭐ ████████ 45% │ │ WhatsApp ████████████ 72% ││ │ │ ⭐⭐⭐⭐ ██████ 32% │ │ Web Chat █████ 28% ││ │ │ ⭐⭐⭐ ███ 15% │ │ ││ │ │ ⭐⭐ █ 5% │ │ ││ │ │ ⭐ █ 3% │ │ ││ │ └─────────────────────────────┘ └─────────────────────────────────────┘│ │ │ │ [Ver detalles] [Exportar CSV] [Programar reporte] │ └─────────────────────────────────────────────────────────────────────────┘ ``` ## Dashboard de Costos ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ 💰 Consumo y Costos - Diciembre 2025 │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ Presupuesto Mensual: $100 USD │ │ ┌─────────────────────────────────────────────────────────────────────┐│ │ │ Usado: $45.67 (46%) █████████████████░░░░░░░░░░░░░░░░░░ Restante ││ │ └─────────────────────────────────────────────────────────────────────┘│ │ Proyección fin de mes: $72.50 USD (✓ Dentro de presupuesto) │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐│ │ │ Desglose por Modelo ││ │ │ ││ │ │ gpt-4o-mini $28.45 ████████████████████ 62% ││ │ │ text-embedding-3 $12.20 ████████ 27% ││ │ │ claude-3-haiku $5.02 ████ 11% ││ │ └─────────────────────────────────────────────────────────────────────┘│ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐│ │ │ Tokens Consumidos ││ │ │ ││ │ │ Input tokens: 2,345,678 ($18.76) ││ │ │ Output tokens: 1,234,567 ($24.69) ││ │ │ Embeddings: 456,789 ($2.22) ││ │ │ ───────────────────────────────── ││ │ │ Total: 4,037,034 ($45.67) ││ │ └─────────────────────────────────────────────────────────────────────┘│ │ │ │ Métricas de Eficiencia: │ │ • Costo promedio por conversación: $0.037 USD │ │ • Costo promedio por mensaje: $0.012 USD │ │ • Tokens promedio por respuesta: 287 │ │ │ │ [Descargar factura] [Configurar alertas] [Optimización sugerida] │ └─────────────────────────────────────────────────────────────────────────┘ ``` ## Reportes Programados ### Configuración de Reporte ```typescript interface ScheduledReportConfig { id: string; name: string; // Contenido metrics_to_include: string[]; // ['conversations', 'satisfaction', 'costs', 'performance'] // Filtros agent_ids?: string[]; channels?: string[]; // Programación frequency: 'daily' | 'weekly' | 'monthly'; day_of_week?: number; // 0-6 para weekly day_of_month?: number; // 1-31 para monthly time_utc: string; // "08:00" // Entrega delivery_method: 'email' | 'webhook'; recipients?: string[]; // Emails webhook_url?: string; // Formato format: 'pdf' | 'csv' | 'json'; is_active: boolean; } ``` ### Template de Reporte Email ``` ┌─────────────────────────────────────────────────────────────────┐ │ 📊 Reporte Semanal - AI Agents │ │ Período: 25 Nov - 1 Dic 2025 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Resumen Ejecutivo: │ │ ───────────────── │ │ • 1,234 conversaciones procesadas (+12% vs semana anterior) │ │ • 78.5% tasa de resolución (+5%) │ │ • 4.2/5.0 satisfacción promedio (+0.3) │ │ • $45.67 USD en costos (-8%) │ │ │ │ Top Insights: │ │ ───────────── │ │ ✓ Mejora en satisfacción gracias a nuevos documentos en KB │ │ ⚠ 23% de escalaciones por "políticas de devolución" │ │ ✓ Costo por conversación reducido 15% con modelo optimizado │ │ │ │ Recomendaciones: │ │ ──────────────── │ │ 1. Agregar FAQ sobre políticas de devolución │ │ 2. Considerar activar herramienta de consulta de sucursales │ │ │ │ [Ver dashboard completo] [Descargar PDF] │ └─────────────────────────────────────────────────────────────────┘ ``` ## Reglas de Negocio - **RN-1:** Métricas se calculan en tiempo real con caché de 5 minutos - **RN-2:** Datos históricos disponibles hasta 12 meses - **RN-3:** Exportación de datos respeta límites (máx 10,000 registros) - **RN-4:** Reportes programados máximo 1 por día por tipo - **RN-5:** Alertas de presupuesto al 50%, 75%, 90% y 100% - **RN-6:** Comparativas solo disponibles con mínimo 7 días de datos ## Criterios de Aceptación - [ ] Dashboard principal con métricas clave - [ ] Gráficos de tendencias temporales - [ ] Filtros por agente, canal, período - [ ] Dashboard de costos detallado - [ ] Alertas de presupuesto configurables - [ ] Reportes exportables (PDF, CSV) - [ ] Reportes programados por email - [ ] Comparativas período vs período - [ ] Drill-down a conversaciones individuales - [ ] API de métricas para integraciones ## Entidades Involucradas ### ai_agents.daily_metrics (Tabla agregada) ```sql CREATE TABLE ai_agents.daily_metrics ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), tenant_id UUID NOT NULL, agent_id UUID NOT NULL, date DATE NOT NULL, -- Conversaciones total_conversations INT DEFAULT 0, completed_conversations INT DEFAULT 0, escalated_conversations INT DEFAULT 0, expired_conversations INT DEFAULT 0, -- Mensajes total_messages INT DEFAULT 0, user_messages INT DEFAULT 0, agent_messages INT DEFAULT 0, -- Duración avg_duration_seconds INT, avg_messages_per_conversation DECIMAL(5,2), avg_response_time_ms INT, -- Satisfacción total_ratings INT DEFAULT 0, sum_ratings INT DEFAULT 0, -- Para calcular promedio rating_1_count INT DEFAULT 0, rating_2_count INT DEFAULT 0, rating_3_count INT DEFAULT 0, rating_4_count INT DEFAULT 0, rating_5_count INT DEFAULT 0, -- Consumo input_tokens BIGINT DEFAULT 0, output_tokens BIGINT DEFAULT 0, embedding_tokens BIGINT DEFAULT 0, estimated_cost_usd DECIMAL(10,4) DEFAULT 0, -- RAG rag_queries INT DEFAULT 0, rag_hits INT DEFAULT 0, -- Tools tool_executions INT DEFAULT 0, tool_successes INT DEFAULT 0, -- Performance p50_response_ms INT, p95_response_ms INT, p99_response_ms INT, failed_requests INT DEFAULT 0, -- Por canal conversations_whatsapp INT DEFAULT 0, conversations_webchat INT DEFAULT 0, conversations_email INT DEFAULT 0, created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP, CONSTRAINT uq_daily_metrics UNIQUE (tenant_id, agent_id, date) ); CREATE INDEX idx_daily_metrics_tenant ON ai_agents.daily_metrics(tenant_id); CREATE INDEX idx_daily_metrics_agent ON ai_agents.daily_metrics(agent_id); CREATE INDEX idx_daily_metrics_date ON ai_agents.daily_metrics(date); ``` ### ai_agents.scheduled_reports ```sql CREATE TABLE ai_agents.scheduled_reports ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), tenant_id UUID NOT NULL, name VARCHAR(200) NOT NULL, -- Contenido metrics_to_include TEXT[] NOT NULL, agent_ids UUID[], channels TEXT[], -- Programación frequency VARCHAR(20) NOT NULL, -- daily, weekly, monthly day_of_week INT, -- 0-6 day_of_month INT, -- 1-31 time_utc TIME NOT NULL, -- Entrega delivery_method VARCHAR(20) NOT NULL, recipients TEXT[], webhook_url VARCHAR(500), format VARCHAR(20) DEFAULT 'pdf', -- Estado is_active BOOLEAN DEFAULT true, last_run_at TIMESTAMPTZ, last_run_status VARCHAR(20), next_run_at TIMESTAMPTZ, created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP, created_by UUID, CONSTRAINT chk_frequency CHECK (frequency IN ('daily', 'weekly', 'monthly')), CONSTRAINT chk_delivery CHECK (delivery_method IN ('email', 'webhook')) ); ``` ### ai_agents.budget_alerts ```sql CREATE TABLE ai_agents.budget_alerts ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), tenant_id UUID NOT NULL, -- Configuración monthly_budget_usd DECIMAL(10,2) NOT NULL, alert_thresholds INT[] DEFAULT '{50, 75, 90, 100}', -- Porcentajes -- Notificaciones notify_emails TEXT[], notify_webhook VARCHAR(500), -- Estado current_month_usage_usd DECIMAL(10,2) DEFAULT 0, last_alert_threshold INT, -- Último umbral notificado last_alert_at TIMESTAMPTZ, is_active BOOLEAN DEFAULT true, created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP ); ``` ## API Endpoints ### Obtener Métricas ```typescript // GET /api/v1/ai-agents/{id}/metrics // Query params: period=30d, metrics=conversations,satisfaction,costs interface GetMetricsResponse { period: { from: string; to: string; }; conversations: ConversationMetrics; satisfaction: SatisfactionMetrics; usage: UsageMetrics; performance: PerformanceMetrics; } ``` ### Comparar Períodos ```typescript // GET /api/v1/ai-agents/{id}/metrics/compare // Query params: period1=2025-11-01:2025-11-30&period2=2025-10-01:2025-10-31 interface CompareMetricsResponse { period1: MetricsSummary; period2: MetricsSummary; changes: { conversations: number; // Porcentaje de cambio resolution_rate: number; satisfaction: number; cost: number; }; } ``` ### Exportar Datos ```typescript // POST /api/v1/ai-agents/{id}/metrics/export interface ExportRequest { format: 'csv' | 'json' | 'pdf'; period: { from: string; to: string }; metrics: string[]; include_conversations?: boolean; } interface ExportResponse { download_url: string; expires_at: string; } ``` ### Configurar Alertas ```typescript // PUT /api/v1/ai-agents/budget-alerts interface BudgetAlertConfig { monthly_budget_usd: number; alert_thresholds: number[]; notify_emails: string[]; notify_webhook?: string; } ``` ## Job de Agregación ```typescript // Ejecutar diariamente a las 00:05 UTC async function aggregateDailyMetrics(date: Date): Promise { const tenants = await getAllActiveAITenants(); for (const tenant of tenants) { const agents = await getAgentsByTenant(tenant.id); for (const agent of agents) { const metrics = await calculateDailyMetrics(agent.id, date); await upsertDailyMetrics(tenant.id, agent.id, date, metrics); } } // Actualizar proyecciones de costos await updateCostProjections(); // Verificar alertas de presupuesto await checkBudgetAlerts(); } ``` ## Referencias - [Google Analytics 4 Metrics](https://support.google.com/analytics/answer/9143382) - [Intercom Analytics](https://www.intercom.com/help/en/articles/4458730-analyze-your-team-s-performance) - [Datadog APM](https://docs.datadoghq.com/tracing/metrics/) ## Dependencias - **RF Requeridos:** RF-018-003 (Procesamiento), RF-018-005 (Feedback) - **Bloqueante para:** Ninguno (RF terminal del módulo)