MGN-018: AI Agents & Chatbots
Descripción del Módulo
El módulo de AI Agents permite a los tenants crear, configurar y desplegar agentes de inteligencia artificial que pueden:
- Responder consultas de clientes automáticamente
- Integrarse con canales de comunicación (WhatsApp, Web Chat, Email)
- Utilizar bases de conocimiento propias del tenant
- Ejecutar acciones en el sistema (crear leads, consultar pedidos, etc.)
Requerimientos Funcionales
Total Story Points: 63
Arquitectura
┌─────────────────────────────────────────────────────────────────────────┐
│ TENANT │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ AI Agents │ │ Knowledge │ │ Actions │ │
│ │ Config │ │ Bases │ │ Tools │ │
│ └───────┬────────┘ └───────┬────────┘ └───────┬────────┘ │
│ │ │ │ │
└──────────┼────────────────────┼─────────────────────┼────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ AI Processing Layer │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ LLM Router │ │ Embeddings │ │ Tool Executor │ │
│ │ (Multi-model) │ │ Generator │ │ │ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ External Services │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ OpenAI API │ │ Claude API │ │ Vector Store │ │
│ │ GPT-4, etc │ │ Anthropic │ │ (Pinecone) │ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
Dependencias
Dependencias Internas
- MGN-001 (Multi-Tenant): Aislamiento de datos por tenant (corrección: es MGN-001, no MGN-004)
- MGN-007 (Sales): Tools para consultas de pedidos
- MGN-009 (CRM): Tools para acciones sobre leads y contactos
- MGN-014 (Mensajería): Auditoría de conversaciones y feedback
- MGN-015 (Billing): Control de consumo de tokens/créditos de IA
Dependencias Opcionales (Canales)
- MGN-017 (WhatsApp): Canal de comunicación para agentes
Dependencias Externas
- OpenAI API (GPT-4, GPT-4o, embeddings)
- Anthropic API (Claude 3.5, Claude 3)
- Vector Database (pgvector en PostgreSQL, o Pinecone para escala)
- Cloud Storage (para documentos de KB)
Integraciones Requeridas
- MGN-015: Implementar control de tokens con
billing.get_feature_limit(tenant_id, 'ai_monthly_token_limit')
- MGN-015: Alertas automáticas al 80% y 100% de consumo
- MGN-007: Tool
check_order_status para consultar estado de pedidos
- MGN-009: Tool
create_lead para crear leads desde conversaciones
Nota sobre Canales
MGN-018 es agnóstico al canal de comunicación. Puede recibir mensajes de:
- WhatsApp (via MGN-017)
- Web Chat (frontend directo)
- Email (via integración futura)
- API directa (para integraciones custom)
Esto evita dependencia circular con MGN-017. MGN-018 es la capa de inteligencia, MGN-017 es la capa de transporte.
Actores del Módulo
| Actor |
Descripción |
RFs Relacionados |
| Tenant Admin |
Configura agentes y bases de conocimiento |
RF-001, RF-002 |
| Sistema |
Procesa mensajes y ejecuta acciones |
RF-003, RF-004 |
| AI Agent |
Genera respuestas y decide acciones |
RF-003, RF-004 |
| Cliente Final |
Interactúa con el agente |
RF-003 |
| Supervisor |
Revisa y entrena agente |
RF-005 |
Entidades Principales
-- Schema: ai_agents
ai_agents.agents -- Configuración de agentes
ai_agents.knowledge_bases -- Bases de conocimiento
ai_agents.kb_documents -- Documentos en KB
ai_agents.kb_chunks -- Chunks con embeddings
ai_agents.conversations -- Conversaciones con agente
ai_agents.messages -- Mensajes de conversación
ai_agents.tool_definitions -- Herramientas disponibles
ai_agents.tool_executions -- Historial de ejecuciones
ai_agents.feedback -- Feedback de usuarios/supervisores
ai_agents.usage_logs -- Consumo de tokens
Modelos de IA Soportados
| Proveedor |
Modelo |
Uso Principal |
Costo/1K tokens |
| OpenAI |
gpt-4o |
Conversación avanzada |
$0.005 input, $0.015 output |
| OpenAI |
gpt-4o-mini |
Conversación económica |
$0.00015 input, $0.0006 output |
| OpenAI |
text-embedding-3-small |
Embeddings KB |
$0.00002 |
| Anthropic |
claude-3-5-sonnet |
Conversación avanzada |
$0.003 input, $0.015 output |
| Anthropic |
claude-3-haiku |
Conversación económica |
$0.00025 input, $0.00125 output |
Tipos de Agentes
1. Agente de Atención al Cliente
- Responde FAQs
- Consulta estado de pedidos
- Escala a humanos cuando necesario
2. Agente de Ventas
- Califica leads
- Responde sobre productos
- Agenda citas/demos
3. Agente de Soporte Técnico
- Resuelve problemas comunes
- Guía paso a paso
- Crea tickets de soporte
4. Agente Personalizado
- Configuración libre
- Instrucciones específicas del tenant
- Herramientas personalizadas
Flujo de Procesamiento
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Mensaje │────▶│ Router │────▶│ Contexto │
│ Entrante │ │ Canal │ │ Builder │
└─────────────┘ └─────────────┘ └─────────────┘
│
▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Respuesta │◀────│ LLM │◀────│ RAG │
│ al Usuario │ │ Provider │ │ Search │
└─────────────┘ └─────────────┘ └─────────────┘
│ │
│ ▼
│ ┌─────────────┐
│ │ Tools │
│ │ Executor │
│ └─────────────┘
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Log de │ │ Acciones │
│ Consumo │ │ Sistema │
└─────────────┘ └─────────────┘
Seguridad
- Aislamiento de Datos: Cada tenant solo accede a sus KBs y agentes
- API Keys: Encriptadas, tenant puede usar propias o del sistema
- Rate Limiting: Límites por tenant según plan
- Content Filtering: Detección de contenido inapropiado
- PII Protection: No almacenar datos sensibles en logs
- Audit Trail: Historial completo de conversaciones
Feature Flags
{
"ai_agents_enabled": true,
"ai_max_agents": 3,
"ai_kb_max_documents": 100,
"ai_kb_max_size_mb": 500,
"ai_custom_tools": false,
"ai_model_selection": ["gpt-4o-mini", "claude-3-haiku"],
"ai_monthly_token_limit": 1000000
}
Pricing / Consumo
Modelo de Créditos
- Cada tenant tiene créditos de IA mensuales según plan
- Créditos = tokens consumidos (input + output)
- Overage: se cobra extra o se limita servicio
Ejemplo de Planes
| Plan |
Créditos/mes |
Agentes |
KBs |
Documentos KB |
| Starter |
100K tokens |
1 |
1 |
20 |
| Professional |
500K tokens |
3 |
3 |
100 |
| Enterprise |
5M tokens |
Ilimitado |
10 |
500 |
Métricas Clave
interface AIAgentMetrics {
conversations: {
total: number;
resolved_by_ai: number;
escalated: number;
resolution_rate: number;
};
messages: {
processed: number;
avg_response_time_ms: number;
tokens_consumed: number;
};
satisfaction: {
positive_feedback: number;
negative_feedback: number;
nps_score: number;
};
costs: {
tokens_this_month: number;
estimated_cost_usd: number;
cost_per_conversation: number;
};
}
Notas de Implementación
- Vector Store: Usar pgvector para simplicidad, Pinecone para escala
- Streaming: Soportar respuestas en streaming para mejor UX
- Caching: Cachear respuestas comunes para reducir costos
- Fallbacks: Siempre tener opción de escalar a humano
- Timeouts: Límites de tiempo para respuestas de LLM
- Retry Logic: Reintentos con backoff para APIs externas
