SIA: Sistema de Inteligencia para la Atención: arquitectura, decisiones y lecciones aprendidas

El problema que nos trajo hasta aquí

La operación de renta enfrenta tres dolores centrales:

Filas y baja capacidad de atención humana: las demandas repetitivas consumen el tiempo de equipos especializados.
Pérdida de conversión por recorridos largos y con fricción: cuantos más pasos haya entre la intención y la reserva, mayor es el abandono.
Riesgo operativo en etapas críticas: precio, disponibilidad y reserva sin control determinístico generan errores financieros y retrabajo.

El SIA ataca estos tres puntos en paralelo: usa IA para acelerar la comprensión y la comunicación, y APIs determinísticas para garantizar una ejecución segura en las decisiones que impactan los ingresos, el contrato y la experiencia del cliente.

Lo que el SIA entrega en la práctica

Para el negocio:

Conversión: aumenta la tasa de cierre al reducir el tiempo entre la intención y la acción.
Eficiencia: disminuye el costo por atención con la automatización de las demandas repetitivas.
Escala: permite la operación multimarca (white-label) con aislamiento por tenant.
Control de riesgo: reduce errores financieros al separar la generación de lenguaje de la ejecución transaccional.

Para el cliente final:

Velocidad: un recorrido más corto para resolver dudas, cotizar y reservar en el mismo flujo.
Claridad: respuestas objetivas, contextualizadas y con confirmación explícita antes de acciones sensibles.
Confiabilidad: los precios y la disponibilidad provienen del sistema real, no de estimaciones del modelo.
Continuidad: las excepciones se resuelven con handoff humano sin pérdida de contexto.

Alcance y tesis arquitectónica

El SIA combina conversación natural con ejecución determinística para cubrir cuatro recorridos principales: FAQ con RAG, cotización en tiempo real, creación/consulta/cancelación de reservas y handoff para atención humana.

La tesis central es simple: la IA decide el camino de la conversación, pero el precio, la disponibilidad y la reserva solo se confirman mediante APIs determinísticas integradas al sistema oficial.

Requisitos obligatorios desde el inicio: cumplimiento normativo de privacidad de datos, aislamiento por tenant y auditabilidad de punta a punta.

Arquitectura en capas

La solución está organizada en cuatro capas con responsabilidades bien definidas:

Capa	Rol principal	Componentes de referencia
Frontend Web	Experiencia conversacional, control del recorrido y fallback visual	ChatShell, MessageTimeline, QuoteComposer, HandoffPanel
Backend API/Servicios	Contratos, idempotencia, orquestación y reglas de dominio	FastAPI, ConversationService, RecoveryService
IA y Orquestación	Triaje, enrutamiento por intención, llamada de herramientas y gobernanza	LangGraph, SupervisorAgent, RAG/Pricing/Booking/Guardián
Datos y Observabilidad	Persistencia operativa, trazabilidad de auditoría, métricas y tracing	PostgreSQL + pgvector, Redis, audit store, OpenTelemetry

Arquitectura multiagente

En lugar de un único agente genérico, el SIA usa una orquestación multiagente donde cada agente actúa en un dominio específico. Esto mejora la gobernanza, reduce la regresión cruzada y hace que el comportamiento del sistema sea explicable y auditable.

Agentes especializados

SIA Supervisor: orquestador central. Recibe el mensaje normalizado, clasifica la intención y el riesgo, y enruta al agente correcto. No responde directamente: su función es decidir quién debe actuar.

SIA RAG: responde preguntas frecuentes, políticas y términos con base en evidencia documental. Usa retrieval + rerank + generación anclada. Si la confianza es baja, pide aclaración o escala al humano; nunca responde con suposiciones.

SIA Pricing: genera cotizaciones con precio y disponibilidad en tiempo real mediante integración determinística con el ERP. Valida parámetros comerciales (fechas, categoría, ubicación) antes de cualquier llamada.

SIA Booking: ejecuta la creación, consulta y cancelación de reservas con confirmación explícita del usuario, idempotencia obligatoria y validación de precondiciones de negocio.

SIA Guardián: agente de seguridad y gobernanza. Valida la respuesta candidata antes de que llegue al cliente: verifica privacidad/PII, tono institucional, restricciones de contenido y reglas por tenant. Puede aprobar, sanear, bloquear o exigir reformulación.

Flujo algorítmico simplificado

Normalizar la entrada con metadatos obligatorios (tenant_id, session_id, request_id, canal)
Aplicar guardrail de entrada: detectar PII, prompt injection y contenido sensible
Clasificar intención y riesgo
Enrutar al agente especialista
Validar precondiciones y ejecutar dentro del dominio
Pasar por el Guardián para validación de salida
Devolver respuesta con trazabilidad auditada

RAG: responder con evidencia, no con suposición

El flujo de RAG fue diseñado con una regla central: primero buscamos contexto confiable, luego generamos la respuesta.

Las etapas son:

Ingesta documental: base oficial versionada por tenant, dominio, idioma, vigencia y fuente.
Chunking semántico: división en fragmentos con tamaño y superposición controlados para preservar el contexto.
Embedding: cada fragmento se convierte en vector y se almacena con metadatos.
Retrieval con top_k: recuperación de los fragmentos más relevantes con filtros obligatorios de alcance.
Rerank: reordenamiento por adherencia a la pregunta, reduciendo el ruido.
Generación anclada: el modelo responde con base en el contexto construido, con instrucción explícita para no inventar hechos.

Regla obligatoria: las decisiones transaccionales (reserva/cancelación) dependen de una API determinística con idempotencia, nunca solo del LLM.

Backend: capa determinística de la solución

El backend en FastAPI opera en dos roles complementarios: como BFF (Backend for Frontend), adaptando la experiencia para cada canal (web, app, WhatsApp); y como capa de aplicación y orquestación de dominio, ejecutando reglas críticas de negocio.

No es un simple proxy de frontend. Es un BFF inteligente con responsabilidad directa sobre la consistencia operativa y el riesgo de negocio.

Módulos principales

Conversation Service: mantiene el estado conversacional por sesión, controla la etapa del recorrido y las transiciones válidas de estado.
Pricing Service: consulta la cotización determinística en el ERP con validación de parámetros y respuesta trazable.
Booking Service: ejecuta operaciones transaccionales con invariantes de negocio y garantías de idempotencia.
Security & Governance Service: centraliza políticas de privacidad, enmascaramiento de PII y guardrails de contenido.
Escalation Service: detecta disparadores de handoff y transfiere el contexto completo al agente humano.
Recovery Service: gestiona retry con backoff, circuit breaker, timeout budgets y reconciliación con el ERP.

Patrones técnicos adoptados

Clean/Hexagonal Architecture: separación entre entrada, aplicación, dominio y adaptadores de infraestructura.
Idempotent Consumer: las operaciones con efecto financiero usan clave idempotente y verificación de estado antes de reprocesar.
Outbox/Inbox: eventos de dominio persistidos con la transacción local para consistencia eventual sin pérdida.
Observabilidad orientada a la operación: logs JSON estructurados, trazas distribuidas (OpenTelemetry) y métricas por SLO.

Base de datos: simplicidad operativa con capacidad semántica

La arquitectura de datos separa dos responsabilidades: persistencia transaccional y búsqueda vectorial para IA.

Estándar actual: PostgreSQL + pgvector. PostgreSQL es la fuente de verdad transaccional con ACID, constraints, auditoría y aislamiento por tenant. pgvector almacena embeddings en el mismo stack operativo, reduciendo la sobrecarga de infraestructura.

Evolución prevista: migración a Qdrant cuando haya disparadores objetivos: P95 de retrieval por encima de la meta, crecimiento sostenido de la base vectorial o necesidad de tuning avanzado. La decisión se guía por datos, no por preferencia tecnológica.

Seguridad y gobernanza

La seguridad y la gobernanza forman parte del diseño principal, no son un complemento. Los principios adoptados:

Seguridad por defecto: todo dato nace con regla de acceso y clasificación mínima.
Mínimo privilegio: cada servicio accede únicamente a lo necesario para su función.
Aislamiento multi-tenant: los datos y el contexto de cada marca permanecen segregados en todo el recorrido.
Trazabilidad obligatoria: los eventos críticos se registran para auditoría técnica y regulatoria.

Controles implementados: autenticación fuerte, RBAC por tenant, guardrails semánticos, enmascaramiento de PII en entrada y salida, cifrado en tránsito y en reposo, trazabilidad de auditoría y retención por política alineada a la normativa de privacidad vigente.

Guardrails en capas

El riesgo de cada operación se mitiga con controles específicos:

Categoría	Riesgo principal	Control obligatorio
RAG	Respuesta sin evidencia	Retrieval con filtros + rerank + groundedness mínimo
Pricing	Cotización incorrecta por interpretación libre	Schema validation + retorno factual de la API
Booking	Duplicidad/inconsistencia transaccional	Idempotencia + reconciliación + trazabilidad auditada
Seguridad y Gobernanza	Filtración de datos o respuesta inadecuada	Redaction, políticas por tenant y bloqueo/saneamiento

Observabilidad profesional

En IA, observar solo la infraestructura no es suficiente. El SIA monitorea cuatro dimensiones:

1. Técnica: latencia por etapa, errores, timeouts, retries y disponibilidad de servicios.

2. LLM: prompt utilizado, versión del prompt, modelo elegido, tokens de entrada/salida y costo estimado por interacción. El prompt no es texto suelto: es un artefacto versionado y auditable.

3. Calidad: tasa de respuestas útiles, tasa de alucinación, bloqueos por guardrail y frecuencia de intervención humana.

4. Negocio: reservas completadas, conversiones, tiempo ahorrado, reducción de atención humana y errores financieros evitados. Sin esta capa, se monitorea tecnología, pero no valor.

Herramientas de referencia: OpenTelemetry + plataforma GenAI (LangSmith, Langfuse o Arize Phoenix) + dashboard operativo.

KPIs ejecutivos

Los indicadores de resultado que se monitorean:

Conversión por conversación: porcentaje de sesiones que terminan en reserva.
Costo por atención: costo promedio por sesión automatizada vs. handoff humano.
Tasa de éxito del recorrido completo: FAQ → cotización → reserva sin interrupción.
Satisfacción del cliente: calificación de atención y percepción de claridad/confiabilidad.

Criterio de gobernanza: un KPI de negocio solo se considera positivo cuando va acompañado de estabilidad técnica y sin aumento de riesgo/compliance.

Cómo interpretar KPIs sin ilusión de corto plazo

Conversión alta con error alto no es éxito: puede ocultar riesgo operativo.
Costo bajo con handoff excesivo no es eficiencia: puede significar traslado de carga a la operación humana.
Satisfacción alta sin cumplimiento normativo no es sostenible: el riesgo regulatorio invalida la ganancia momentánea.
Meta saludable: crecimiento con estabilidad técnica y gobernanza preservada.

Desafíos y lecciones aprendidas

Principales desafíos de desarrollo

Coordinación entre capas: mantener frontend, backend, IA y ERP sincronizados en un recorrido único.
Precisión de la IA: reducir la alucinación sin perder fluidez en la atención.
Confiabilidad transaccional: evitar la duplicidad de reserva/cancelación con idempotencia y confirmación explícita.
Integración multicanal: mantener la continuidad entre app y WhatsApp sin pérdida de contexto.
Gobernanza y compliance: aplicar privacidad de datos, redaction y trazabilidad auditada en todo el recorrido.

Desafíos específicos de la capa de IA

Ambigüedad de intención: diferenciar una pregunta informativa de una acción transaccional con bajo margen de error.
Riesgo de alucinación: evitar respuestas sin fundamento en FAQ/políticas, especialmente en temas comerciales.
Coordinación multiagente: mantener consistencia entre Supervisor, RAG, Pricing, Booking y Guardián sin regresión cruzada.

Mitigaciones arquitectónicas adoptadas

Separación clara entre capa no determinística (interpretación) y determinística (ejecución de negocio).
Guardrails en capas: entrada, contexto, herramientas, transaccional, salida, telemetría y post-ejecución.
Uso obligatorio de APIs determinísticas para precio, disponibilidad, reserva y cancelación.
Recovery con retry/backoff, circuit breaker y handoff humano con snapshot completo de la sesión.
Observabilidad completa con request_id/trace_id y scorecards de calidad.

Lecciones que llevamos a las próximas versiones

La separación de fronteras reduce incidentes: cuando lenguaje y transacción están separados, el riesgo cae de forma consistente.
La observabilidad no es opcional: sin correlación de punta a punta, el diagnóstico se convierte en suposición.
Un handoff bien ejecutado protege la marca: la transferencia con contexto completo mantiene la continuidad y la confianza del cliente.
La gobernanza continua evita la deuda de riesgo: revisar prompt/modelo/política en cada release reduce la regresión.

Cierre

La arquitectura del SIA es saludable cuando entrega resultados de negocio con previsibilidad técnica y gobernanza continua. En resumen: la IA ayuda a conversar y orientar; los sistemas de la empresa confirman los datos importantes; y cuando algo sale de lo esperado, la atención humana toma el control con todo el historial de la conversación.

La estrategia de evolución sigue el mismo principio: empezar simple y controlado (pgvector, arquitectura modular, gobernanza fuerte) y evolucionar mediante disparadores objetivos de escala, latencia, calidad y relación costo-beneficio: nunca por preferencia tecnológica.

Artículo derivado de la documentación técnica didáctica del SIA: ARQUITETURA_DETALHADA.html y resumen técnico completo.