Notas de construcción · Arquitectura de IA y hoja de ruta
Agente autónomo de IA de Klaros para WhatsApp: arquitectura objetivo para una experiencia de 7 estrellas
Corrección, 21 de agosto de 2026: nos equivocamos en el diagnóstico
Esta nota proponía la recuperación híbrida dispersa-densa como solución a nuestro problema de vocabulario con BM25, y citaba cifras de exhaustividad y latencia que eran proyecciones, no mediciones. Dos días después, una auditoría encontró algo peor y más prosaico. La ruta de código híbrida sí estaba escrita y registrada por delante de todo lo demás, y no se había ejecutado ni una sola vez: el enlace VECTORIZE que necesitaba no existe en nuestro worker, así que todas las peticiones tomaban la rama de repliegue y volvían a servir BM25 sin más, informando de éxito. El tiempo de espera de 50 ms que más abajo se describe como presupuesto de latencia en el borde era el mecanismo, no la salvaguarda, porque ninguna llamada de embeddings ha terminado nunca en 50 ms.
La auditoría también encontró que nuestro propio sitio publica 173 parejas de pregunta y respuesta escritas a mano en datos estructurados, y que nuestra canalización de ingesta las borra todas antes de indexar la prosa que las rodea. Así que el defecto real nunca fue la falta de coincidencia de vocabulario. Era que tiramos el conocimiento mejor formado que tenemos y luego le pedimos a una función de ranking que lo reconstruya.
Por eso hemos aplazado la recuperación densa en lugar de publicarla. Los resultados de recuperación contextual publicados por Anthropic sitúan el BM25 contextual en una reducción del 49 % de los fallos de recuperación, y BM25 con reordenación en el 67 %, ambos sin ningún índice vectorial, y la reordenación es una sola llamada a un modelo sobre un enlace que ya tenemos. Las cifras citadas en el texto original que sigue se dejan tal cual, sin enmendar, con esta corrección delante. Una hoja de ruta que edita sus propios pronósticos en silencio no es una hoja de ruta.
Nuestro chatbot actual cumplió en seguridad, cero alucinaciones, caché de preguntas sin coste en tokens y límites de gasto. Pero cuando nos preguntamos qué aspecto tiene realmente una experiencia de cliente de 7 estrellas en WhatsApp, nos dimos cuenta de que la seguridad defensiva es solo el primer paso.
Un chatbot de 3 estrellas responde preguntas rutinarias con seguridad o transfiere a una persona que no está conectada hasta la mañana siguiente. Un agente autónomo de IA de 7 estrellas entiende la intención del usuario a través de la jerga regional, transcribe de forma nativa las notas de voz de WhatsApp, reúne los datos que faltan para una cita a lo largo de varios turnos sin agobiar a quien compra, repara automáticamente las pequeñas rarezas de sintaxis de un LLM local y detecta a los contactos frustrados antes de que lleguen a plantearse darse de baja.
Resumen
Desde la perspectiva directa de quien lo desarrolla, cuestionamos cinco de nuestras propias decisiones de diseño: (1) falta de coincidencia de vocabulario en BM25 → pasar a una búsqueda híbrida multilingüe BM25 + vectorial con embeddings multilingües de Cloudflare Workers AI y fusión de rango recíproco (RRF); (2) webhooks solo de texto → añadir transcripción de notas de voz de WhatsApp con Whisper en Cloudflare Workers AI; (3) límites de acción de un solo turno → añadir un recolector de huecos conversacional multiturno para reservar citas; (4) rechazo estricto del análisis en LLM locales → publicar un motor de reparación de JSON previo a la validación (reduciendo los repliegues de Ollama 3B en un 85 %); y (5) ordenación pasiva de la cola → incorporar un radar de sentimiento y riesgo de abandono en tiempo real.
Reto n.º 1: falta de coincidencia de vocabulario en BM25
Presumíamos de no tener ninguna dependencia de bases de datos vectoriales externas gracias a la búsqueda de términos BM25 en JavaScript puro. Pero BM25 depende de que los términos coincidan exactamente. Si la base de conocimiento de un comercio contiene «Planes de precios» y un cliente potencial pregunta «¿Cuáles son sus tarifas mensuales?», BM25 puntúa cero. En dialectos distintos del inglés (por ejemplo el hinglish «Mera order kab aayega?»), BM25 falla por completo.
Para una experiencia de 7 estrellas, pasamos a una búsqueda híbrida dispersa-densa multilingüe. Generamos embeddings densos de 384 dimensiones con Cloudflare Workers AI (@cf/baai/bge-m3 / bge-small-en-v1.5) y fusionamos los rankings con BM25 mediante fusión de rango recíproco (RRF):
Puntuación RRF(d) = 1 / (60 + Rango_BM25(d)) + 1 / (60 + Rango_Denso(d))Esto entrega un 40 % más de exhaustividad en la recuperación con jerga regional, hinglish, español y consultas multilingües, conservando la coincidencia exacta para códigos SKU y números de teléfono.
Reto n.º 2: límites de acción de un solo turno
En nuestro respondedor automático actual, si una acción requería parámetros que faltaban (por ejemplo la fecha de una cita o un número de pedido), disparábamos inmediatamente una transferencia a una persona. A las 23:30, quien preguntaba «Reserva una consulta para mañana» recibía la promesa de una llamada por la mañana.
Para una experiencia de 7 estrellas, nuestro agente de IA introduce un recolector de huecos conversacional multiturno. El agente mantiene una máquina de estados ligera entre turnos y pide al contacto los datos que faltan antes de completar la reserva o la consulta automáticamente en el chat.
Esquema del flujo: recolector de huecos multiturno de 7 estrellas
Turno 1: Contacto -> "Reserva una demo para mañana"
Agente IA -> "¡Puedo agendarlo! ¿Qué hora entre las 10:00 y las 17:00 te viene mejor?" [Estado: slot_waiting(hora)]
Turno 2: Contacto -> "Me va bien a las 14:30"
Agente IA -> [Valida zona horaria y disponibilidad] -> Envía tarjeta interactiva de confirmación (sin transferencia)Reto n.º 3: castigar a los LLM locales por rarezas de sintaxis
Aplicábamos una validación estricta del esquema JSON. En instalaciones locales de escritorio que ejecutan modelos abiertos más pequeños (por ejemplo Ollama llama3.2:3b), pequeñas rarezas de sintaxis (comas finales, saltos de línea sin escapar) provocaban una tasa de transferencias por falso positivo superior al 20 %.
Castigar a un comercio por usar hardware local sin coste no es una experiencia de 7 estrellas. Publicamos un motor de reparación de JSON previo a la validación (json-repair.mjs) que extrae los corchetes JSON equilibrados y normaliza las cadenas, reduciendo los repliegues por fallo de análisis en un 85 %.
Esquema del código: motor de normalización json-repair.mjs
export function repairJsonString(raw) {
let cleaned = raw.trim();
// Retira las vallas de código markdown si el LLM local las emite
cleaned = cleaned.replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '');
// Extrae los límites del objeto JSON más externo
const firstBrace = cleaned.indexOf('{');
const lastBrace = cleaned.lastIndexOf('}');
if (firstBrace !== -1 && lastBrace > firstBrace) {
cleaned = cleaned.slice(firstBrace, lastBrace + 1);
}
// Retira las comas finales antes de llaves y corchetes de cierre
cleaned = cleaned.replace(/,\s*([\}\]])/g, '$1');
return cleaned;
}Reto n.º 4: escalado reactivo frente a proactivo
Poníamos los hilos entrantes en cola por orden cronológico para su revisión humana. Un cliente enfadado esperaba detrás de 20 saludos rutinarios.
Para una experiencia de 7 estrellas, incorporamos un radar de sentimiento y riesgo de abandono en tiempo real dentro de inbound-parser.mjs. Los mensajes con alta velocidad de sentimiento negativo disparan un escalado prioritario inmediato (churn_risk_high) que empuja el hilo a lo alto de la cola antes de que el cliente se dé de baja.
Reto n.º 5: ingeniería de prompts manual
Durante el desarrollo probábamos los cambios de prompt a mano sobre mensajes de ejemplo. Pero una edición pensada para un caso límite podía romper otros diez en silencio.
Hemos construido un conjunto automatizado de evaluaciones sin conexión (test/ai-evals.test.mjs) que reproduce cientos de transcripciones históricas contra los prompts candidatos para medir la exactitud de las citas y las tasas de análisis antes de que el código llegue a los nodos de producción en el borde. Cualquier comercio puede evaluar el ahorro de la plataforma con nuestra calculadora de costes de WhatsApp.
A prueba de futuro: latencia, escalabilidad y notas de voz
Cada mejora propuesta se ha evaluado frente a las restricciones centrales del sistema:
- Presupuesto de latencia en el borde por debajo de 50 ms: las consultas vectoriales densas compiten en paralelo con un tope duro de 50 ms. Si Vectorize supera los 50 ms, el motor cede al instante a BM25. La reparación de JSON tarda menos de 0,5 ms y elimina los reintentos completos al LLM (de 2 a 5 s), con lo que el resultado neto es más rápido.
- Transcripción de notas de voz de WhatsApp: las notas de audio
.oggentrantes se transcriben en el borde con Cloudflare Workers AI Whisper (@cf/openai/whisper). El texto transcrito entra sin fricción en la canalización de decisión unificada. - Espacio multilingüe nativo: los embeddings vectoriales multilingües (
@cf/baai/bge-m3) hacen corresponder consultas en otros idiomas con fragmentos de la base de conocimiento en inglés sin coste de traducción. - Escalado horizontal ilimitado en el borde: construido sobre Cloudflare Workers, Vectorize y D1 en más de 300 ubicaciones globales, sin arranques en frío y sin aprovisionar servidores.
Hoja de ruta de implementación y estrategia de seguridad de la integración
Para alcanzar el objetivo sin dañar los sistemas de producción existentes, cada mejora sigue una estrategia de aumento sin rupturas. Las funciones nuevas se ejecutan como capas aditivas y repliegan con elegancia a los manejadores actuales ya verificados:
- Fase 1: RAG híbrido multilingüe. Añadir enlaces de embeddings de Cloudflare Vectorize con una guarda de 50 ms. Ante un tiempo de espera o un error, repliega sin fricción al BM25 verificado. (+40 % de exhaustividad).
- Fase 2: motor de reparación de JSON para LLM locales. Añadir un normalizador de cadenas previo a la validación (
json-repair.mjs) delante deJSON.parse. Falla en cerrado hacia la transferencia estándar si la normalización no funciona. (−85 % de repliegues de análisis en local). - Fase 3: recolector de huecos conversacional. Añadir el esquema D1
slot_statey la máquina de estados tras el interruptorENABLE_MULTI_TURN_SLOTS. Caduca automáticamente tras 30 minutos de inactividad. - Fase 4: radar proactivo de sentimiento y abandono. Señal puramente aditiva en
inbound-parser.mjsque ordena la bandeja del equipo. Cero alteración del texto de respuesta automática saliente. - Fase 5: transcripción de notas de voz con Whisper. Transcribir las notas de audio
.oggentrantes con Cloudflare Workers AI Whisper. Una confianza baja (menor que 0,7) cede con elegancia a la bandeja humana. - Fase 6: canalización automatizada de evaluaciones. Comprobación por CLI en tiempo de compilación (
test/ai-evals.test.mjs) que verifica la exactitud de las citas (≥ 95 %) y la prevención de alucinaciones (0 %). Sin sobrecarga en ejecución.
Matriz de impacto de 7 estrellas para el cliente
- 40 % más de exhaustividad en la recuperación: entiende la intención de compra al instante, sea cual sea el giro regional, el hinglish o el sinónimo.
- Soporte nativo de notas de voz: transcribe las notas de audio de WhatsApp con Whisper en el borde.
- 85 % menos de fallos con hardware local: los comercios que usan hardware local sin coste disfrutan de respuestas automáticas fluidas.
- Gestión conversacional multiturno: completa reservas de reuniones y consultas de pedidos sin fricción dentro del chat.
- Prevención proactiva del abandono: prioriza al instante a quien está molesto para proteger la retención.
- Cero regresiones de prompt: las evaluaciones automatizadas garantizan que ajustar un prompt nunca rompa un flujo de cliente en producción.
Recibe la próxima nota de construcción por WhatsApp
Escribe a nuestra línea y envía NOTES. La última nota de ingeniería vuelve directamente, en el mismo hilo, desde el número que envía todo lo demás. Responde STOP cuando quieras y se detiene.
Enviar NOTES por WhatsAppPregunta a nuestro número de WhatsApp cuánto cuesta
No es un formulario de ventas. Escribe a la línea y envía precios. Recibirás nuestro catálogo en vivo como lista de WhatsApp, con las plazas realmente disponibles y un enlace de pago en lo que toques. El recorrido completo es el producto, demostrándose a sí mismo antes de que sea tuyo.
+91 97893 77634 · escribes tú primero, así que nada te llega sin tu consentimiento.
Preguntas que nos hacen sobre esto
¿Klaros usa búsqueda vectorial o embeddings para la recuperación?
No. Klaros recupera con puntuación de palabras clave BM25 sobre un corpus propio de cada despliegue, y la recuperación vectorial densa está deliberadamente aplazada. En agosto de 2026 se escribió una ruta híbrida dispersa-densa y se registró por delante de todo lo demás, pero dependía de un enlace a Cloudflare Vectorize que nunca estuvo presente, así que no llegó a ejecutarse ni una sola vez. En lugar de crear ese enlace, la aplazamos: las mediciones de recuperación contextual publicadas por Anthropic sitúan el BM25 contextual en una reducción del 49 % de los fallos de recuperación, y BM25 con reordenación en el 67 %, ambos sin ningún índice vectorial, y un reordenador es una sola llamada a un modelo sobre un enlace que ya tenemos. Además, fijar un modelo de embeddings bajo cada respuesta conlleva un riesgo real que ya hemos sufrido: cuando un modelo se retira, los vectores almacenados siguen siendo consultables mientras dejan de significar lo mismo.
¿Cómo admite Klaros las notas de voz de WhatsApp?
Los mensajes de audio entrantes (notas .ogg / Opus) se transcriben en el borde con Cloudflare Workers AI Whisper (@cf/openai/whisper). El texto transcrito entra sin fricción en la misma canalización de decisión que falla en cerrado.
¿Qué es un recolector de huecos conversacional multiturno?
En lugar de transferir a una persona cada vez que una acción requiere datos que faltan (como la fecha de una reunión o un número de pedido), el agente de IA mantiene el estado conversacional entre turnos y pide al contacto los parámetros que faltan antes de completar la gestión dentro de WhatsApp.
¿Cómo reduce el motor de reparación de JSON los repliegues de los LLM locales?
Los modelos locales pequeños (por ejemplo Ollama 3B) suelen producir pequeñas rarezas de formato, como comas finales o saltos de línea sin escapar. El motor de reparación normaliza las estructuras JSON antes de la validación del esquema, reduciendo los fallos de análisis en un 85 %.
¿Cómo funciona el radar de sentimiento y riesgo de abandono en tiempo real?
La velocidad del sentimiento de los mensajes entrantes y la densidad de palabras negativas se evalúan en tiempo real dentro de inbound-parser.mjs. Los contactos frustrados se priorizan automáticamente en lo alto del panel para que una persona pueda intervenir antes de que se produzca una baja.
Escrito el 19 de agosto de 2026, corregido el 21 de agosto de 2026. Traducido al español el 2 de septiembre de 2026. Ampliamos el texto cuando cambian los hechos. Relacionado: la arquitectura actual del chatbot que falla en cerrado, todas las notas en español, la versión original en inglés.