AI Agents Architecture
Diseño de agentes especializados, medibles y controlados para resolver trabajos concretos dentro de Hampiora Clinic y Hampiora Passport.
Resumen ejecutivo
Decisión central: usar agentes solo cuando exista lenguaje ambiguo, múltiples fuentes o necesidad de tool calling.
Análisis de procesos
Qué conviene resolver con IA, workflow o código convencional.
Priorizar leads
Requiere interpretar intención, contexto multicanal y datos incompletos.
Consultar operación por audio
Necesita transcripción, intención, permisos y múltiples herramientas.
Recordatorios de cita
Evento, plantilla y horario definidos. No necesita razonamiento.
Confirmar pago por webhook
Stripe es la fuente de verdad. La IA no aporta valor.
Clasificar documentos
Contenido no estructurado, extracción y detección de faltantes.
Crear Google Meet
Se ejecuta después de un pago confirmado; no requiere IA.
Lista priorizada de agentes
Impacto, riesgo, complejidad y autonomía recomendada.
| Agente | Problema | Usuario | Acción concreta | Frecuencia | Impacto | Complejidad | Riesgo | Integraciones | Autonomía | Aprobación | Recomendación |
|---|
Agentes descartados
No todo problema necesita un agente.
Asistente general
Alcance difuso, alto riesgo y difícil de medir.
Diagnóstico autónomo
Riesgo clínico, regulatorio y reputacional inaceptable.
Agente financiero autónomo
Nunca debe cobrar o reembolsar sin confirmación y fuente oficial.
Superagente multi-SaaS
Un único agente controlando todo aumenta blast radius y complejidad.
Agente recomendado para el MVP
Mejor relación entre impacto comercial, viabilidad y riesgo.
Lead Conversion Agent
Propósito: recibe un nuevo lead o actividad, consulta contexto comercial y operativo, calcula prioridad, propone la siguiente acción y ejecuta tareas de bajo riesgo dentro de límites definidos.
Entradas y salidas
Contratos explícitos para evitar comportamiento ambiguo.
Entradas
Obligatorias y opcionales- Obligatorio: lead_id o evento de captura.
- Obligatorio: organization_id y workspace_id.
- Opcional: texto de WhatsApp, respuestas de quiz, UTM y servicio.
- Opcional: historial de actividades, disponibilidad y SLA.
- Inválido: solicitud sin identidad, tenant o consentimiento requerido.
Salidas
Estructura verificable- Clasificación de servicio y modalidad.
- Scores: Fit, Intent, Readiness, Value, Engagement y Risk.
- Responsable sugerido o asignado.
- Next-best-action con motivo y fecha límite.
- Borrador de mensaje o tarea creada.
- Escalamiento con contexto si falta información o hay riesgo.
Herramientas del agente
Capa controlada; el modelo nunca consulta directamente la base de datos.
| Herramienta | Objetivo | Entrada | Salida | Permisos | Límites | Errores | Reintentos | Aprobación |
|---|---|---|---|---|---|---|---|---|
| get_lead_context | Consultar lead, canal y actividad | lead_id, workspace_id | Contexto normalizado | CRM read | Solo tenant actual | No encontrado / prohibido | 1 | No |
| get_service_catalog | Validar servicios y reglas | workspace_id | Servicios activos | Catalog read | Versión aprobada | Catálogo vacío | 1 | No |
| check_availability | Consultar horarios | service_id, rango | Slots disponibles | Calendar read | Máx. 14 días | Timeout / sin slots | 2 | No |
| assign_owner | Asignar responsable | lead_id, user_id | Assignment id | CRM write | Reglas de equipo | Usuario inactivo | 1 | No, si regla determinista |
| create_task | Crear próxima acción | lead_id, tipo, deadline | Task id | Task write | Máx. 3 por run | Duplicidad | 1 idempotente | No |
| draft_message | Preparar respuesta | canal, contexto, template | Borrador | Messaging draft | Sin envío | Template inválida | 1 | No |
| send_message | Enviar WhatsApp/email | draft_id, recipient | Delivery status | Messaging send | Plantillas y quiet hours | Opt-out / API | 2 | Sí en MVP |
| update_pipeline | Cambiar etapa comercial | lead_id, stage | Activity id | CRM write | Transiciones válidas | Estado inválido | 1 | Sí para cierres/pérdidas |
Flujo de ejecución
Máquina de estados determinista con IA dentro de pasos controlados.
Ruta incompleta
Solicita el dato faltante o crea tarea para una persona.
Ruta sensible
Prepara la acción, muestra impacto y espera aprobación explícita.
Ruta de error
Registra fallo, evita duplicados y escala con contexto.
Prompt del sistema
Versión base del agente MVP.
Eres Lead Conversion Agent de Hampiora.
OBJETIVO
Recibes un lead o evento comercial, consultas exclusivamente las herramientas autorizadas y entregas una clasificación explicable, una prioridad y la siguiente acción verificable.
ALCANCE
- Clasificar servicio, modalidad, intención y preparación.
- Calcular Fit, Intent, Readiness, Value, Engagement y Risk.
- Consultar contexto del lead, catálogo, SLA y disponibilidad.
- Crear tareas y asignaciones de bajo riesgo.
- Preparar mensajes.
- Solicitar aprobación antes de enviar mensajes, cerrar oportunidades, marcar pérdidas o ejecutar cualquier acción sensible.
REGLAS
1. Nunca inventes datos ni asumas que una acción fue ejecutada.
2. Solo afirma ejecución cuando la herramienta confirme éxito.
3. La base de datos y las APIs oficiales son la fuente de verdad.
4. Nunca diagnostiques, recomiendes tratamientos ni interpretes clínicamente síntomas.
5. No expongas datos de otro workspace u organización.
6. Si la confianza es baja, explica la incertidumbre y escala.
7. No uses conversaciones previas como fuente única para datos críticos.
8. Máximo 6 tool calls por ejecución y máximo 2 reintentos por herramienta.
9. Evita crear tareas, mensajes o actividades duplicadas mediante idempotency_key.
10. Registra una decisión resumida, herramientas usadas, resultado, costo y aprobación.
FORMATO DE SALIDA
{
"classification": {...},
"scores": {...},
"recommended_action": {
"type": "...",
"reason": "...",
"deadline": "...",
"requires_approval": true|false
},
"executed_actions": [...],
"pending_actions": [...],
"confidence": 0.0-1.0,
"escalation": null|{...}
}
ERRORES
Indica qué se pudo completar, qué falló, la causa, si hay acciones pendientes y qué necesita el usuario o un operador humano.
Arquitectura técnica
La opción menos compleja que cumple confiabilidad y trazabilidad.
| Enfoque | Ventajas | Desventajas | Uso recomendado |
|---|---|---|---|
| Function calling simple | Rápido y barato | Menor control en flujos largos | Prototipo con 2–3 herramientas |
| Workflow determinista | Auditable, seguro, testeable | Más código de orquestación | MVP y producción |
| Framework de agentes | Abstracciones y memoria compleja | Mayor costo cognitivo y debugging | Solo si surgen workflows dinámicos reales |
Modelo de datos mínimo
Entidades para versionado, ejecución, aprobación y evaluación.
| Entidad | Propósito | Campos principales | Relaciones | Sensible | Retención |
|---|---|---|---|---|---|
| agents | Definición lógica | id, name, purpose, status | versions, tools | No | Indefinida |
| agent_versions | Versionar prompt y políticas | agent_id, version, model_policy | runs | No | Indefinida |
| agent_runs | Ejecución completa | tenant, trigger, status, cost, confidence | messages, tools, errors | Metadata | 24 meses |
| agent_messages | Entradas y salidas mínimas | run_id, role, content_ref | run | Puede ser PII | Configurable |
| tool_executions | Auditar tool calls | tool, input_hash, output_ref, status | run | Metadata | 24 meses |
| approvals | Confirmaciones humanas | action, approver, expires_at | run, tool | No | 36 meses |
| agent_memories | Preferencias persistentes limitadas | scope, key, value_ref, expires_at | user/org | Variable | 90–365 días |
| agent_errors | Errores y recuperación | code, phase, retryable | run | No | 24 meses |
| agent_evaluations | Quality y safety scoring | case_id, result, scores | version | No | Indefinida |
| usage_records | Costo y billing | tokens, audio_seconds, cost, units | run, tenant | No PHI | 36 meses |
Guardrails y acciones sensibles
Prioridad: confiabilidad sobre autonomía.
Acceso
- Auth y tenant obligatorios.
- RBAC por herramienta.
- RLS en datos.
- Scopes mínimos.
Ejecución
- Máx. 6 tools/run.
- Timeout 30–60 s.
- Idempotency key.
- Step budget.
Protección AI
- Prompt injection filters.
- Structured outputs.
- No tool names en user text.
- Allowlist de herramientas.
| Acción sensible | Permitida | Confirmación requerida | Proceso |
|---|---|---|---|
| Enviar mensaje | Sí | Durante MVP | Mostrar destinatario, texto y canal |
| Marcar lead como perdido | Sí | Sí | Mostrar motivo y efecto en pipeline |
| Cobrar o reembolsar | No para este agente | Siempre | Escalar a Payments workflow |
| Compartir PHI | No | Siempre | Consent service + humano |
| Eliminar datos | No | Siempre | Proceso administrativo separado |
| Decisión médica | Nunca | No aplica | Escalar a profesional |
Control de consumo
Tokens, ejecuciones, tools y presupuesto por plan.
| Plan | Runs/mes | AI Units | Voice minutes | Tool calls/run | Budget AI | Exceso |
|---|---|---|---|---|---|---|
| Free | 100 | 250 | 0 | 3 | $3 | Suspender |
| Starter | 2,000 | 5,000 | 120 | 5 | $75 | Paquetes |
| Professional | 10,000 | 30,000 | 600 | 6 | $350 | Pay-as-you-go |
| Business | 50,000 | 150,000 | 3,000 | 8 | $1,500 | Contrato |
| Enterprise | Custom | Custom | Custom | Custom | Custom | Contrato |
Alertas
70%, 90% y 100% por organización y workspace.
Suspensión
Soft limit, hard limit y degradación a modelo económico.
Facturación
AI Units comprensibles, no tokens expuestos al cliente.
Casos de prueba
24 escenarios normales, ambiguos, maliciosos y de fallo.
Métricas de éxito
El agente debe demostrar impacto, no solo generar respuestas.
Plan de implementación
De prototipo controlado a producción medible.
Clasificar leads y recomendar next-best-action. Dos tools read-only, datos sintéticos, sin memoria persistente.
Usuarios reales, RBAC, auditoría, budgets, create_task y assign_owner. Envíos requieren aprobación.
Evaluaciones automáticas, observabilidad, retries, versionado de prompt y facturación por AI Units.
Nuevos tools, routing por costo, mayor autonomía para acciones reversibles y aprendizaje desde métricas.
Estimación de costos operativos
Ilustrativa; validar con precios vigentesEscenario piloto: 10,000 lead events + 1,000 voice queries podría consumir aproximadamente $80–$450/mes en modelos, antes de infraestructura, almacenamiento y mensajería.