Notas de construcción · Arquitectura y Evaluación de IA

Ingeniería del Agente de IA para WhatsApp de Klaros con Evaluación Rigurosa

1 de Septiembre de 2026 · Fundador, Klaros

Detalles Técnicos de la Construcción de un Orquestador de Producto de Voz y Texto de Grado de Producción.

1. La Brecha Humana: La Nota de Voz de Priya a las 11:42 PM

A las 11:42 PM de un martes, Priya envía una nota de voz de 14 segundos por WhatsApp a una joyería boutique: “Bhaiya, mi pedido #ORD-9821 cancélalo y devuélveme ₹4,500 a la cuenta, estoy viajando ahora mismo.”

Un chatbot de 3 estrellas impulsado por ingeniería de prompts básica hace una de dos cosas malas. O responde con una promesa educada (“¡Tu pedido ha sido cancelado!”) mientras falla al llamar al backend de reembolsos, o identifica mal el ID de pedido ruidoso y cancela la reserva de otra persona.

La distancia digital es la brecha entre lo que un cliente cree que tu empresa recuerda sobre él y lo que tu software realmente ejecuta. Cerrar esa distancia en un agente de voz y texto requiere más que decirle a un LLM que “tenga cuidado.” Requiere límites a nivel de código que se nieguen a actuar cuando la evidencia es incierta, y un arnés de evaluación que pruebe que esos límites se mantienen bajo presión en producción.

2. La Arquitectura de Verdad en Cuatro Capas

La mayoría de las plataformas de IA evalúan sus modelos únicamente por la **salida de lenguaje natural**—preguntando si el texto generado suena fluido y educado. En un CRM transaccional que maneja dinero real y pedidos, la fluidez del texto es peligrosamente engañosa.

Klaros evalúa cada turno de conversación en **Cuatro Capas de Verdad**:

Si un agente genera una respuesta al cliente diciendo “He actualizado tu dirección a Indiranagar,” pero la Capa 3 revela que la escritura en la base de datos D1 falló o escribió en la columna incorrecta, la prueba falla de inmediato. La fluidez sin fidelidad de estado se marca como un defecto crítico.

3. Salvaguardas de Voz Multimodal y Límites de IA Autogobernada

La **Gobernanza de IA** en el mundo real no es un PDF de políticas estático sentado en un servidor—es un arnés de ejecución determinista. Un sistema de IA es verdaderamente **autogobernado** cuando mide su propia incertidumbre en tiempo real y voluntariamente entrega el control (fallando a un colega humano) en lugar de adivinar cuando el contexto es ambiguo.

Las notas de voz de WhatsApp (audio .ogg / Opus) presentan desafíos severos: ruido de tráfico de fondo, acentos regionales, vocabulario mixto y habla rápida.

En lugar de alimentar la salida del Reconocimiento Automático del Habla (ASR) directamente al motor de razonamiento, Klaros implementa una **Salvaguarda de Micro-Confianza en Palabras Críticas** dentro de src/shared/voice-adapter.mjs:

Snippet de Código: Umbral de Micro-Confianza en voice-adapter.mjs

// Evaluar transcripcion general Y micro-confianzas individuales en entidades criticas
const overallConf = transcription.confidence;
const criticalEntities = extractCriticalTokens(transcription.words); // IDs de pedido, Monedas, Verbos de accion

const minCriticalConf = Math.min(...criticalEntities.map(w => w.confidence));

if (overallConf < 0.70 || minCriticalConf < 0.70) {
  // FALLO CERRADO: Derivar a inbox humano con cero escrituras autonomas
  return triggerHumanHandoff({
    reason: "LOW_VOICE_CONFIDENCE",
    audioUrl: message.mediaUrl,
    transcript: transcription.text,
    overallConf,
    minCriticalConf
  });
}

Si la confianza general o la confianza en entidades críticas cae por debajo de **0.70**, el límite autogobernado se activa. El sistema transcribe la nota, marca la conversación y la deriva al equipo humano con **cero mutaciones autónomas de estado**.

4. El Banco de Pruebas y Mutación agent-eval v1.0

Para garantizar que nuestro agente nunca sufra regresiones, construimos tools/agent-eval/, un marco de evaluación automatizado que comprende cuatro tracks especializados:

En el Track B2 (Mutación Sintética de Defectos), demostramos que nuestro arnés de evaluación realmente detecta errores al romper deliberadamente nuestro propio código. El arnés detectó el **100% de las mutaciones inyectadas (20/20)**, probando que las pruebas aprobadas reflejan la verdadera integridad del sistema.

5. La Escalera de Presupuesto de Fidelidad de Infraestructura (F0 a F5)

Un conjunto de pruebas que se aprueba en Node.js local pero falla en la infraestructura edge de Cloudflare Workers es inútil. Establecimos la **Escalera de Presupuesto de Fidelidad de Infraestructura** para garantizar la paridad entre runtimes:

F5: Observacion en Produccion ── Observacion de trafico real de clientes y recoleccion de trazas
 ▲
F4: Sandbox de Proveedor Vivo ── Worker de Staging desplegado + Sandboxes de Deepgram / LLM / Meta
 ▲
F3: Staging Desplegado ──────── Worker de Staging en Cloudflare (createTestHarness) + D1/DO/Queue
 ▲
F2: Runtime Local de Produccion ─ Motor real workerd de Cloudflare + D1 SQLite local + DO + Queue
 ▲
F1: Codigo Real en Proceso ────── Node.js + Modulos reales de Klaros + Mocks controlados (CI)
 ▲
F0: Pruebas Unitarias Puras ──── Afirmaciones de funciones aisladas

Al ejecutar el Track C0 (workerd local) y el Track C1 (staging desplegado en Cloudflare), certificamos una **paridad de resultados del 100% entre los runtimes F1, F2 y F3**, eliminando sorpresas en el runtime edge.

6. Protocolo de Despliegue Gradual en Producción sin Interrupciones

Rechazamos los despliegues de "subir y rezar." La promoción de la build candidata 4144d7d a producción siguió una secuencia de 8 pasos guiada por máquinas:

7. Evidencias Empíricas y Puertas de Máquina Auditables

En cada etapa de despliegue (25% y 50%), nuestro motor de decisión consumió conteos brutos de eventos y métricas derivadas directamente, eliminando la ambigüedad en transcripción de porcentajes:

Cada evaluación de puerta produjo una firma canónica RFC 8785 JSON Canonicalization Scheme (JCS) SHA-256, verificada independientemente por el controlador antes de avanzar el tráfico:

{
  "hash_verification": {
    "stored_hash": "4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
    "recomputed_hash": "4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
    "match": true,
    "canonicalization_version": "1.0-JCS"
  }
}

8. Lecciones Honestas y Problemas Abiertos

Una nota de construcción que solo reporta triunfos es marketing, no ingeniería. Esto fue lo difícil y lo que queda abierto:

1. **Hashes Sintéticos de Ejemplo**: En las primeras iteraciones, nuestro registrador emitía hashes SHA-256 simulados (ej. e3b0c442...). Tras una auditoría, reemplazamos las cadenas de reporte con verificación estricta de máquina sobre bytes canónicos RFC 8785 JCS.
2. **Ambigüedad en Porcentajes**: Nuestras primeras reglas verificaban error_rate < 0.01%, creando confusión al alcanzar exactamente 0.010%. Actualizamos el motor para operar sobre ratios enteros explícitos (errors / eligible ≤ 0.0001).
3. **Lo Que Queda Abierto**: El Recolector B4 está operando en **Modo Observación en Cuarentena**. Expandir el pipeline de aprobación automática para casos no sensibles en PRs de benchmarks está programado para la versión `v1.1`.