12 KiB
12 KiB
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
| ID | Nombre | Prioridad | Story Points | Estado |
|---|---|---|---|---|
| RF-MGN-018-001 | Configuración de Agentes | P1 | 13 | Definido |
| RF-MGN-018-002 | Bases de Conocimiento | P1 | 13 | Definido |
| RF-MGN-018-003 | Procesamiento de Mensajes | P1 | 8 | Definido |
| RF-MGN-018-004 | Acciones y Herramientas | P2 | 13 | Definido |
| RF-MGN-018-005 | Entrenamiento y Feedback | P2 | 8 | Definido |
| RF-MGN-018-006 | Analytics y Métricas | P2 | 8 | Definido |
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_statuspara consultar estado de pedidos - MGN-009: Tool
create_leadpara 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