HampioraAgent System Design

AI Agents Architecture

Diseño de agentes especializados, medibles y controlados para resolver trabajos concretos dentro de Hampiora Clinic y Hampiora Passport.

Arquitectura recomendada · MVP priorizado

Resumen ejecutivo

Decisión central: usar agentes solo cuando exista lenguaje ambiguo, múltiples fuentes o necesidad de tool calling.

Agentes evaluados117 recomendados · 4 descartados
Agentes MVP2Conversión + Voice Ops limitado
Workflows tradicionales8No requieren agente
Autonomía máxima MVPNivel 3Solo acciones de bajo riesgo
Driver de negocioConversiónLead → cita → ingreso

Análisis de procesos

Qué conviene resolver con IA, workflow o código convencional.

R1
Agente

Priorizar leads

Requiere interpretar intención, contexto multicanal y datos incompletos.

IngresoAlta frecuencia
R2
Agente

Consultar operación por audio

Necesita transcripción, intención, permisos y múltiples herramientas.

AhorroFrecuencia diaria
W1
Workflow

Recordatorios de cita

Evento, plantilla y horario definidos. No necesita razonamiento.

ReglasDeterminista
W2
Workflow

Confirmar pago por webhook

Stripe es la fuente de verdad. La IA no aporta valor.

FinancieroIdempotente
R3
Agente

Clasificar documentos

Contenido no estructurado, extracción y detección de faltantes.

PassportRevisión humana
W3
Workflow

Crear Google Meet

Se ejecuta después de un pago confirmado; no requiere IA.

IntegraciónBajo riesgo

Lista priorizada de agentes

Impacto, riesgo, complejidad y autonomía recomendada.

Catálogo v0.8
AgenteProblemaUsuarioAcción concretaFrecuenciaImpactoComplejidadRiesgoIntegracionesAutonomíaAprobaciónRecomendación

Agentes descartados

No todo problema necesita un agente.

X1
Descartado

Asistente general

Alcance difuso, alto riesgo y difícil de medir.

X2
Descartado

Diagnóstico autónomo

Riesgo clínico, regulatorio y reputacional inaceptable.

X3
Descartado

Agente financiero autónomo

Nunca debe cobrar o reembolsar sin confirmación y fuente oficial.

X4
Descartado

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.

Prioridad 1

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.

Usuario objetivoRecepción, ventas y administradores
Problema específicoLeads sin respuesta o mal priorizados
Resultado esperadoLead asignado con acción y SLA
ImpactoConversión e ingresos
Autonomía MVPNivel 2–3
RiesgoMedio controlable
ImplementaciónWorkflow + function calling

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.

HerramientaObjetivoEntradaSalidaPermisosLímitesErroresReintentosAprobación
get_lead_contextConsultar lead, canal y actividadlead_id, workspace_idContexto normalizadoCRM readSolo tenant actualNo encontrado / prohibido1No
get_service_catalogValidar servicios y reglasworkspace_idServicios activosCatalog readVersión aprobadaCatálogo vacío1No
check_availabilityConsultar horariosservice_id, rangoSlots disponiblesCalendar readMáx. 14 díasTimeout / sin slots2No
assign_ownerAsignar responsablelead_id, user_idAssignment idCRM writeReglas de equipoUsuario inactivo1No, si regla determinista
create_taskCrear próxima acciónlead_id, tipo, deadlineTask idTask writeMáx. 3 por runDuplicidad1 idempotenteNo
draft_messagePreparar respuestacanal, contexto, templateBorradorMessaging draftSin envíoTemplate inválida1No
send_messageEnviar WhatsApp/emaildraft_id, recipientDelivery statusMessaging sendPlantillas y quiet hoursOpt-out / API2Sí en MVP
update_pipelineCambiar etapa comerciallead_id, stageActivity idCRM writeTransiciones válidasEstado inválido1Sí para cierres/pérdidas

Flujo de ejecución

Máquina de estados determinista con IA dentro de pasos controlados.

01 · ReceiveRecibe evento y valida tenant.
02 · UnderstandDetecta intención y servicio.
03 · VerifyVerifica permisos e información mínima.
04 · ContextConsulta lead, catálogo, SLA y agenda.
05 · DecideCalcula score y next-best-action.
06 · ExecuteEjecuta herramientas permitidas.

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.

Recomendada
Eventos de entradaWhatsApp · Forms · Quizzes · CRM
API GatewayAuth · tenant · rate limiting
QueueJobs idempotentes y retries
Agent OrchestratorMáquina de estados · function calling · approvals · budgets · audit
Tools ServiceCRM · Calendar · Messaging · Tasks
AI GatewayOpenRouter · fallback · ZDR
ObservabilitySentry · PostHog · usage ledger
EnfoqueVentajasDesventajasUso recomendado
Function calling simpleRápido y baratoMenor control en flujos largosPrototipo con 2–3 herramientas
Workflow deterministaAuditable, seguro, testeableMás código de orquestaciónMVP y producción
Framework de agentesAbstracciones y memoria complejaMayor costo cognitivo y debuggingSolo si surgen workflows dinámicos reales

Modelo de datos mínimo

Entidades para versionado, ejecución, aprobación y evaluación.

EntidadPropósitoCampos principalesRelacionesSensibleRetención
agentsDefinición lógicaid, name, purpose, statusversions, toolsNoIndefinida
agent_versionsVersionar prompt y políticasagent_id, version, model_policyrunsNoIndefinida
agent_runsEjecución completatenant, trigger, status, cost, confidencemessages, tools, errorsMetadata24 meses
agent_messagesEntradas y salidas mínimasrun_id, role, content_refrunPuede ser PIIConfigurable
tool_executionsAuditar tool callstool, input_hash, output_ref, statusrunMetadata24 meses
approvalsConfirmaciones humanasaction, approver, expires_atrun, toolNo36 meses
agent_memoriesPreferencias persistentes limitadasscope, key, value_ref, expires_atuser/orgVariable90–365 días
agent_errorsErrores y recuperacióncode, phase, retryablerunNo24 meses
agent_evaluationsQuality y safety scoringcase_id, result, scoresversionNoIndefinida
usage_recordsCosto y billingtokens, audio_seconds, cost, unitsrun, tenantNo PHI36 meses

Guardrails y acciones sensibles

Prioridad: confiabilidad sobre autonomía.

Mandatory

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 sensiblePermitidaConfirmación requeridaProceso
Enviar mensajeDurante MVPMostrar destinatario, texto y canal
Marcar lead como perdidoMostrar motivo y efecto en pipeline
Cobrar o reembolsarNo para este agenteSiempreEscalar a Payments workflow
Compartir PHINoSiempreConsent service + humano
Eliminar datosNoSiempreProceso administrativo separado
Decisión médicaNuncaNo aplicaEscalar a profesional

Control de consumo

Tokens, ejecuciones, tools y presupuesto por plan.

PlanRuns/mesAI UnitsVoice minutesTool calls/runBudget AIExceso
Free10025003$3Suspender
Starter2,0005,0001205$75Paquetes
Professional10,00030,0006006$350Pay-as-you-go
Business50,000150,0003,0008$1,500Contrato
EnterpriseCustomCustomCustomCustomCustomContrato

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.

Eval set v1

Métricas de éxito

El agente debe demostrar impacto, no solo generar respuestas.

Tareas completadas> 75%Sin intervención humana
Tiempo de resolución< 45 sP95 para clasificación
Costo por ejecución< $0.03Lead text-only
Error de herramienta< 2%Excluye proveedores caídos
Escalamiento correcto> 95%Casos sensibles
Conversión incremental+8–15%Hipótesis de piloto
Trabajo manual reducido30–50%Recepción/comercial
Incidentes seguridad0Objetivo obligatorio

Plan de implementación

De prototipo controlado a producción medible.

Fase 1 · Prototipo

Clasificar leads y recomendar next-best-action. Dos tools read-only, datos sintéticos, sin memoria persistente.

Fase 2 · MVP

Usuarios reales, RBAC, auditoría, budgets, create_task y assign_owner. Envíos requieren aprobación.

Fase 3 · Producción

Evaluaciones automáticas, observabilidad, retries, versionado de prompt y facturación por AI Units.

Fase 4 · Optimización

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 vigentes
Lead text-only$0.002–$0.03/run
Voice query$0.01–$0.10/run
Documento$0.05–$0.35/documento

Escenario 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.

Copiado