# RF-MGN-018-001: Configuración de Agentes IA

**Módulo:** MGN-018 - AI Agents & Chatbots
**Prioridad:** P1
**Story Points:** 13
**Estado:** Definido
**Fecha:** 2025-12-05

## Descripción

El sistema debe permitir a los tenants crear y configurar agentes de IA personalizados. Cada agente tiene un propósito específico, instrucciones de comportamiento, modelo de IA a usar, y canales donde está disponible.

## Actores

- **Actor Principal:** Tenant Admin
- **Actores Secundarios:**
  - Sistema (despliega agente)
  - LLM Provider (procesa mensajes)

## Precondiciones

1. Tenant debe tener suscripción con feature `ai_agents_enabled`
2. Créditos de IA disponibles
3. Al menos un canal de comunicación configurado (opcional)

## Flujo Principal - Crear Agente

1. Admin accede a "AI Agents > Mis Agentes"
2. Admin selecciona "Crear nuevo agente"
3. Sistema muestra wizard de configuración
4. Admin completa configuración básica:
   - Nombre del agente
   - Descripción
   - Avatar (opcional)
5. Admin define comportamiento:
   - System prompt / Instrucciones
   - Personalidad y tono
   - Idioma(s)
6. Admin selecciona modelo de IA:
   - Proveedor (OpenAI, Anthropic)
   - Modelo específico
   - Parámetros (temperature, max_tokens)
7. Admin configura capacidades:
   - Bases de conocimiento a usar
   - Herramientas habilitadas
   - Acciones permitidas
8. Admin define escalación:
   - Condiciones de escalación
   - Equipo/agente humano destino
9. Admin guarda y activa agente
10. Sistema despliega agente en canales seleccionados

## Flujo Alternativo - Usar Template

1. Admin selecciona "Crear desde template"
2. Sistema muestra templates disponibles:
   - Atención al Cliente
   - Asistente de Ventas
   - Soporte Técnico
   - FAQ Bot
3. Admin selecciona template
4. Sistema pre-llena configuración
5. Admin personaliza según necesidad
6. Continúa desde paso 9 del flujo principal

## Configuración del Agente

### Información Básica

```typescript
interface AgentBasicInfo {
  name: string;           // "Asistente de Ventas"
  description: string;    // "Ayuda a clientes con consultas de productos"
  avatar_url?: string;    // URL del avatar
  language: string[];     // ["es", "en"]
  timezone: string;       // "America/Mexico_City"
}
```

### Comportamiento (System Prompt)

```typescript
interface AgentBehavior {
  system_prompt: string;
  personality: 'professional' | 'friendly' | 'casual' | 'custom';
  tone_guidelines: string;

  // Restricciones
  do_not_discuss: string[];      // Temas prohibidos
  required_disclaimers: string[]; // Avisos obligatorios

  // Respuestas predefinidas
  greeting_message: string;
  fallback_message: string;
  escalation_message: string;
  goodbye_message: string;
}
```

### Modelo de IA

```typescript
interface AgentModelConfig {
  provider: 'openai' | 'anthropic';
  model_id: string;              // "gpt-4o-mini", "claude-3-haiku"

  // Parámetros del modelo
  temperature: number;           // 0.0 - 1.0
  max_tokens: number;            // Máximo de tokens en respuesta
  top_p?: number;
  frequency_penalty?: number;
  presence_penalty?: number;

  // Fallback
  fallback_model?: string;       // Modelo alternativo si falla
}
```

### Capacidades

```typescript
interface AgentCapabilities {
  // Bases de conocimiento
  knowledge_base_ids: string[];
  rag_enabled: boolean;

  // Herramientas
  tools_enabled: string[];      // ["check_order", "create_lead", "schedule_call"]
  custom_tools: boolean;

  // Acciones del sistema
  can_create_leads: boolean;
  can_update_contacts: boolean;
  can_query_orders: boolean;
  can_create_tickets: boolean;

  // Integraciones
  whatsapp_enabled: boolean;
  webchat_enabled: boolean;
  email_enabled: boolean;
}
```

### Escalación

```typescript
interface AgentEscalation {
  enabled: boolean;

  triggers: Array<{
    type: 'keyword' | 'sentiment' | 'intent' | 'timeout' | 'user_request';
    condition: string;
    priority: 'low' | 'medium' | 'high';
  }>;

  // Destino
  target_team_id?: string;
  target_agent_id?: string;

  // Contexto a pasar
  include_conversation_history: boolean;
  include_extracted_data: boolean;
  custom_fields_to_pass: string[];
}
```

## Reglas de Negocio

- **RN-1:** Máximo de agentes según plan del tenant
- **RN-2:** System prompt tiene límite de 4,000 caracteres
- **RN-3:** Un agente puede estar en múltiples canales
- **RN-4:** Cambios de configuración se aplican a nuevas conversaciones
- **RN-5:** Agentes inactivos no consumen recursos
- **RN-6:** Modelos premium requieren plan Enterprise
- **RN-7:** API keys propias del tenant tienen prioridad sobre las del sistema

## Criterios de Aceptación

- [ ] Admin puede crear nuevo agente con wizard
- [ ] Templates pre-configurados disponibles
- [ ] System prompt editable con preview
- [ ] Selección de modelo con descripción de costos
- [ ] Configuración de capacidades granular
- [ ] Reglas de escalación configurables
- [ ] Preview de conversación antes de activar
- [ ] Activar/desactivar agente sin eliminar
- [ ] Duplicar agente existente
- [ ] Historial de cambios de configuración

## Entidades Involucradas

### ai_agents.agents

```sql
CREATE TABLE ai_agents.agents (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES core_tenants.tenants(id),

    -- Información básica
    name VARCHAR(100) NOT NULL,
    description TEXT,
    avatar_url VARCHAR(500),
    languages TEXT[] DEFAULT '{es}',
    timezone VARCHAR(50) DEFAULT 'America/Mexico_City',

    -- Estado
    status VARCHAR(20) NOT NULL DEFAULT 'draft', -- draft, active, paused, archived

    -- Comportamiento
    system_prompt TEXT NOT NULL,
    personality VARCHAR(20) DEFAULT 'professional',
    tone_guidelines TEXT,
    do_not_discuss TEXT[] DEFAULT '{}',

    -- Mensajes predefinidos
    greeting_message TEXT,
    fallback_message TEXT DEFAULT 'Lo siento, no pude entender tu consulta. ¿Podrías reformularla?',
    escalation_message TEXT DEFAULT 'Te estoy transfiriendo con un agente humano...',

    -- Modelo
    provider VARCHAR(50) NOT NULL DEFAULT 'openai',
    model_id VARCHAR(100) NOT NULL DEFAULT 'gpt-4o-mini',
    model_config JSONB DEFAULT '{"temperature": 0.7, "max_tokens": 1000}',
    fallback_model VARCHAR(100),

    -- Capacidades
    capabilities JSONB DEFAULT '{}',
    -- {
    --   "knowledge_base_ids": [],
    --   "tools_enabled": [],
    --   "can_create_leads": false,
    --   "can_query_orders": true
    -- }

    -- Escalación
    escalation_config JSONB DEFAULT '{"enabled": true}',
    -- {
    --   "enabled": true,
    --   "triggers": [{"type": "keyword", "condition": "humano|agente"}],
    --   "target_team_id": "uuid"
    -- }

    -- Canales
    channels JSONB DEFAULT '[]',
    -- ["whatsapp", "webchat"]

    -- Stats
    total_conversations INT DEFAULT 0,
    total_messages INT DEFAULT 0,
    avg_satisfaction DECIMAL(3,2),

    -- Template
    template_id VARCHAR(50), -- Si fue creado desde template

    -- Timestamps
    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    activated_at TIMESTAMPTZ,
    created_by UUID,

    CONSTRAINT chk_status CHECK (status IN ('draft', 'active', 'paused', 'archived')),
    CONSTRAINT chk_provider CHECK (provider IN ('openai', 'anthropic', 'custom'))
);

CREATE INDEX idx_agents_tenant ON ai_agents.agents(tenant_id);
CREATE INDEX idx_agents_status ON ai_agents.agents(status);
```

### ai_agents.agent_versions

```sql
CREATE TABLE ai_agents.agent_versions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    agent_id UUID NOT NULL REFERENCES ai_agents.agents(id),
    version INT NOT NULL,

    -- Snapshot de configuración
    config_snapshot JSONB NOT NULL,

    -- Metadata
    change_description TEXT,
    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    created_by UUID,

    CONSTRAINT uq_agent_version UNIQUE (agent_id, version)
);
```

### ai_agents.agent_templates

```sql
CREATE TABLE ai_agents.agent_templates (
    id VARCHAR(50) PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    description TEXT,
    category VARCHAR(50), -- customer_service, sales, support, general

    -- Configuración base
    default_config JSONB NOT NULL,

    -- Preview
    sample_conversation JSONB,

    is_system BOOLEAN DEFAULT true, -- Templates del sistema vs tenant
    tenant_id UUID, -- NULL para templates del sistema

    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
);

-- Templates del sistema
INSERT INTO ai_agents.agent_templates (id, name, description, category, default_config) VALUES
('customer_service', 'Atención al Cliente', 'Agente para responder consultas generales de clientes', 'customer_service', '{
  "system_prompt": "Eres un asistente de atención al cliente amable y profesional. Tu objetivo es ayudar a los clientes con sus consultas de manera eficiente.",
  "personality": "friendly",
  "capabilities": {"can_query_orders": true, "can_create_tickets": true}
}'),
('sales_assistant', 'Asistente de Ventas', 'Agente para calificar leads y responder sobre productos', 'sales', '{
  "system_prompt": "Eres un asistente de ventas experto. Ayudas a los clientes a encontrar los productos adecuados y respondes sus dudas.",
  "personality": "professional",
  "capabilities": {"can_create_leads": true, "can_query_products": true}
}'),
('tech_support', 'Soporte Técnico', 'Agente para resolver problemas técnicos comunes', 'support', '{
  "system_prompt": "Eres un agente de soporte técnico. Ayudas a resolver problemas paso a paso de manera clara.",
  "personality": "professional",
  "capabilities": {"can_create_tickets": true}
}'),
('faq_bot', 'FAQ Bot', 'Agente simple para responder preguntas frecuentes', 'general', '{
  "system_prompt": "Responde preguntas frecuentes de manera concisa. Si no sabes algo, indica que no tienes esa información.",
  "personality": "casual",
  "model_id": "gpt-4o-mini"
}');
```

## API Keys del Tenant

```sql
CREATE TABLE ai_agents.tenant_api_keys (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES core_tenants.tenants(id),

    provider VARCHAR(50) NOT NULL, -- openai, anthropic
    api_key_encrypted BYTEA NOT NULL,

    is_active BOOLEAN DEFAULT true,

    -- Límites personalizados
    monthly_budget_usd DECIMAL(10,2),

    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    created_by UUID,

    CONSTRAINT uq_tenant_provider UNIQUE (tenant_id, provider)
);
```

## Endpoints API

### Crear Agente

```typescript
// POST /api/v1/ai-agents
interface CreateAgentRequest {
  name: string;
  description?: string;
  template_id?: string;  // Si usa template

  system_prompt: string;
  personality?: string;

  provider: string;
  model_id: string;
  model_config?: object;

  capabilities?: object;
  escalation_config?: object;
  channels?: string[];
}

// Response
interface CreateAgentResponse {
  id: string;
  name: string;
  status: 'draft';
  // ... resto de campos
}
```

### Activar/Desactivar Agente

```typescript
// POST /api/v1/ai-agents/{id}/activate
// POST /api/v1/ai-agents/{id}/deactivate

interface ActivateResponse {
  id: string;
  status: 'active' | 'paused';
  activated_at?: string;
}
```

### Preview de Conversación

```typescript
// POST /api/v1/ai-agents/{id}/preview
interface PreviewRequest {
  messages: Array<{
    role: 'user' | 'assistant';
    content: string;
  }>;
  mock_context?: object; // Variables de contexto simuladas
}

interface PreviewResponse {
  response: string;
  tokens_used: number;
  tools_called?: string[];
  would_escalate?: boolean;
}
```

## Interfaz de Usuario

### Wizard de Creación

```
┌─────────────────────────────────────────────────────────────────┐
│  Crear Nuevo Agente                                    [1/5]    │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ○ Crear desde cero                                             │
│  ● Usar template                                                │
│                                                                  │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │  🎧 Atención    │  │  💼 Ventas      │  │  🔧 Soporte     │ │
│  │  al Cliente     │  │                 │  │  Técnico        │ │
│  │                 │  │  Califica leads │  │                 │ │
│  │  Consultas      │  │  y responde     │  │  Resuelve       │ │
│  │  generales      │  │  sobre productos│  │  problemas      │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
│                                                                  │
│                                    [Cancelar]  [Siguiente →]    │
└─────────────────────────────────────────────────────────────────┘
```

### Editor de System Prompt

```
┌─────────────────────────────────────────────────────────────────┐
│  Comportamiento del Agente                             [3/5]    │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Instrucciones (System Prompt):                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Eres un asistente de ventas de {{company_name}}.        │   │
│  │                                                          │   │
│  │ Tu objetivo es:                                          │   │
│  │ - Responder consultas sobre productos                    │   │
│  │ - Ayudar a los clientes a tomar decisiones              │   │
│  │ - Capturar información de contacto cuando sea apropiado │   │
│  │                                                          │   │
│  │ Siempre sé amable y profesional.                        │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                 2,340 / 4,000   │
│                                                                  │
│  Variables disponibles: {{company_name}}, {{agent_name}},       │
│                         {{current_date}}, {{customer_name}}     │
│                                                                  │
│  Personalidad: [Profesional ▼]                                  │
│                                                                  │
│                                   [← Anterior]  [Siguiente →]   │
└─────────────────────────────────────────────────────────────────┘
```

## Referencias

- [OpenAI Chat Completions](https://platform.openai.com/docs/guides/chat-completions)
- [Anthropic Messages API](https://docs.anthropic.com/en/api/messages)
- [Best Practices for Prompt Engineering](https://platform.openai.com/docs/guides/prompt-engineering)

## Dependencias

- **RF Requeridos:** Ninguno (RF base del módulo)
- **Bloqueante para:** RF-002 (Bases de Conocimiento), RF-003 (Procesamiento)