# 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](./RF-MGN-018-001-configuracion-agentes.md) | Configuración de Agentes | P1 | 13 | Definido |
| [RF-MGN-018-002](./RF-MGN-018-002-bases-conocimiento.md) | Bases de Conocimiento | P1 | 13 | Definido |
| [RF-MGN-018-003](./RF-MGN-018-003-procesamiento-mensajes.md) | Procesamiento de Mensajes | P1 | 8 | Definido |
| [RF-MGN-018-004](./RF-MGN-018-004-acciones-herramientas.md) | Acciones y Herramientas | P2 | 13 | Definido |
| [RF-MGN-018-005](./RF-MGN-018-005-entrenamiento-feedback.md) | Entrenamiento y Feedback | P2 | 8 | Definido |
| [RF-MGN-018-006](./RF-MGN-018-006-analytics-metricas.md) | 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_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

```sql
-- 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

1. **Aislamiento de Datos:** Cada tenant solo accede a sus KBs y agentes
2. **API Keys:** Encriptadas, tenant puede usar propias o del sistema
3. **Rate Limiting:** Límites por tenant según plan
4. **Content Filtering:** Detección de contenido inapropiado
5. **PII Protection:** No almacenar datos sensibles en logs
6. **Audit Trail:** Historial completo de conversaciones

## Feature Flags

```json
{
  "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

```typescript
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

1. **Vector Store:** Usar pgvector para simplicidad, Pinecone para escala
2. **Streaming:** Soportar respuestas en streaming para mejor UX
3. **Caching:** Cachear respuestas comunes para reducir costos
4. **Fallbacks:** Siempre tener opción de escalar a humano
5. **Timeouts:** Límites de tiempo para respuestas de LLM
6. **Retry Logic:** Reintentos con backoff para APIs externas