16 KiB
16 KiB
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
- Tenant debe tener suscripción con feature
ai_agents_enabled - Créditos de IA disponibles
- Al menos un canal de comunicación configurado (opcional)
Flujo Principal - Crear Agente
- Admin accede a "AI Agents > Mis Agentes"
- Admin selecciona "Crear nuevo agente"
- Sistema muestra wizard de configuración
- Admin completa configuración básica:
- Nombre del agente
- Descripción
- Avatar (opcional)
- Admin define comportamiento:
- System prompt / Instrucciones
- Personalidad y tono
- Idioma(s)
- Admin selecciona modelo de IA:
- Proveedor (OpenAI, Anthropic)
- Modelo específico
- Parámetros (temperature, max_tokens)
- Admin configura capacidades:
- Bases de conocimiento a usar
- Herramientas habilitadas
- Acciones permitidas
- Admin define escalación:
- Condiciones de escalación
- Equipo/agente humano destino
- Admin guarda y activa agente
- Sistema despliega agente en canales seleccionados
Flujo Alternativo - Usar Template
- Admin selecciona "Crear desde template"
- Sistema muestra templates disponibles:
- Atención al Cliente
- Asistente de Ventas
- Soporte Técnico
- FAQ Bot
- Admin selecciona template
- Sistema pre-llena configuración
- Admin personaliza según necesidad
- Continúa desde paso 9 del flujo principal
Configuración del Agente
Información Básica
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)
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
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
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
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
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
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
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
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
// 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
// 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
// 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
Dependencias
- RF Requeridos: Ninguno (RF base del módulo)
- Bloqueante para: RF-002 (Bases de Conocimiento), RF-003 (Procesamiento)