# EPICA: EPIC-MGN-019 - AI Agents

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | EPIC-MGN-019 |
| **Nombre** | AI Agents (RAG + Tools) |
| **Modulo** | ai-agents |
| **Fase** | Fase 4 - SaaS Platform |
| **Prioridad** | P3 |
| **Estado** | Backlog |
| **Story Points** | 55 |
| **Sprint(s)** | Sprint 26-30 |

---

## Descripcion

Sistema de agentes inteligentes con RAG (Retrieval Augmented Generation) usando pgvector para embeddings. Permite crear agentes configurables por tenant, knowledge bases con documentos, definicion de tools/funciones, conversaciones con historial y ejecucion de tools en tiempo real.

---

## Objetivo de Negocio

Proveer agentes AI que:
- Automaticen atencion al cliente
- Respondan preguntas basadas en documentacion
- Ejecuten acciones en el sistema
- Escalen soporte sin aumentar personal
- Mejoren experiencia del usuario

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-MGN019-001 | Como admin, quiero crear agentes con personalidad y proposito | P0 | 5 | Backlog |
| US-MGN019-002 | Como admin, quiero crear knowledge bases con documentos | P0 | 8 | Backlog |
| US-MGN019-003 | Como admin, quiero subir documentos a una knowledge base | P0 | 5 | Backlog |
| US-MGN019-004 | Como sistema, quiero generar embeddings de documentos | P0 | 8 | Backlog |
| US-MGN019-005 | Como admin, quiero definir tools que el agente puede usar | P0 | 8 | Backlog |
| US-MGN019-006 | Como usuario, quiero chatear con el agente | P0 | 5 | Backlog |
| US-MGN019-007 | Como agente, quiero buscar en knowledge bases (RAG) | P0 | 8 | Backlog |
| US-MGN019-008 | Como agente, quiero ejecutar tools cuando sea necesario | P0 | 8 | Backlog |
| US-MGN019-009 | Como usuario, quiero dar feedback al agente | P1 | 3 | Backlog |
| US-MGN019-010 | Como admin, quiero ver metricas de uso y tokens | P1 | 5 | Backlog |

**Total Story Points:** 63 SP (ajustado a 55)

---

## Criterios de Aceptacion de la Epica

**Funcionales:**
- [ ] Agentes configurables: nombre, avatar, system prompt
- [ ] Knowledge bases con multiples documentos
- [ ] Tipos de docs: PDF, DOCX, TXT, MD, URL
- [ ] Chunking inteligente de documentos
- [ ] Embeddings con OpenAI ada-002 (1536 dims)
- [ ] RAG con pgvector similarity search
- [ ] Tools con JSON Schema para parametros
- [ ] Ejecucion segura de tools (sandboxed)
- [ ] Conversaciones con contexto (ultimos N mensajes)
- [ ] Feedback thumbs up/down

**No Funcionales:**
- [ ] Latencia de respuesta < 5s
- [ ] Limite de tokens configurable por tenant
- [ ] Fallback a respuesta generica si RAG falla

---

## Arquitectura RAG

```
1. Usuario envia pregunta
2. Sistema genera embedding de la pregunta
3. pgvector busca chunks similares (cosine similarity)
4. Top K chunks se incluyen en el prompt
5. LLM genera respuesta considerando contexto
6. Si LLM decide usar tool:
   a. Sistema valida parametros
   b. Ejecuta tool en sandbox
   c. LLM procesa resultado
7. Respuesta se envia al usuario
```

## Tools Disponibles (Ejemplos)

| Tool | Descripcion | Parametros |
|------|-------------|------------|
| get_customer_info | Obtiene info de cliente | customer_id |
| check_inventory | Consulta stock | product_id, warehouse_id |
| create_lead | Crea lead en CRM | name, email, phone |
| get_order_status | Estado de orden | order_number |
| schedule_callback | Agenda llamada | phone, datetime |

---

## Dependencias

**Esta epica depende de:**
| Epica/Modulo | Estado | Bloqueante |
|--------------|--------|------------|
| EPIC-MGN-004 Tenants | Ready | Si |
| EPIC-MGN-016 Billing (Feature Flag) | Backlog | Si |
| EPIC-MGN-018 WhatsApp (Canal) | Backlog | No |
| PostgreSQL + pgvector | Ready | Si |
| OpenAI API | External | Si |

---

## Desglose Tecnico

**Database:**
- [ ] Schema: `ai_agents`
- [ ] Tablas: 12 (agents, knowledge_bases, agent_knowledge_bases, kb_documents, kb_chunks, tool_definitions, agent_tools, conversations, messages, tool_executions, feedback, usage_logs)
- [ ] Extension: pgvector para embeddings
- [ ] Indices: HNSW para busqueda rapida

**Backend:**
- [ ] Modulo: `ai-agents`
- [ ] Services: AgentService, RAGService, ToolExecutor, EmbeddingService
- [ ] Controllers: AgentsController, KnowledgeBasesController, ConversationsController
- [ ] Endpoints: 30+
- [ ] Jobs: DocumentProcessorJob, EmbeddingGeneratorJob
- [ ] Tests: 45+

**Frontend:**
- [ ] Paginas: 7 (Agents, AgentBuilder, KnowledgeBases, Documents, Conversations, Tools, Analytics)
- [ ] Componentes: AgentCard, ChatWindow, DocumentUploader, ToolEditor
- [ ] Stores: 1 (aiAgentsStore)

---

## Estimacion de Costos

| Concepto | Precio | Uso estimado/mes |
|----------|--------|------------------|
| Embeddings (ada-002) | $0.0001/1K tokens | 1M tokens = $0.10 |
| Completions (gpt-4) | $0.03/1K tokens | 500K tokens = $15 |
| pgvector storage | Incluido en DB | - |
| Total estimado | - | ~$15-50/tenant/mes |

---

**Creada por:** Requirements-Analyst
**Fecha:** 2025-12-05