Cómo Funciona la IA de Este Sitio: Un Desglose de Mastra en Producción

El asistente con el que estás hablando es la demo

La mayoría de las agencias te muestran una captura de pantalla de un chatbot. El asistente de IA de este sitio es el sistema real, en producción, construido sobre Mastra. Esta guía lo abre por dentro. Nada de teatro de diagramas, solo la arquitectura, los compromisos y las partes que de verdad importan cuando una funcionalidad de IA tiene que sobrevivir al tráfico real.

El titular que la mayoría de los equipos pasa por alto: el modelo de lenguaje es quizá el diez por ciento de un asistente de IA en producción. El otro noventa por ciento es enrutamiento, herramientas, estado, idioma, seguridad y las aburridas garantías de entrega que deciden si un lead llega alguna vez a una persona. Cubrimos el patrón general en De Prototipo de IA a Producción. Esta es la construcción concreta.

La forma del sistema

El asistente es un conjunto de agentes Mastra, cada uno con una tarea acotada, expuestos a través de rutas de API de Next.js:

• quoteAgent: el asistente conversacional en las superficies de presupuesto y contacto. Responde preguntas sobre servicios, califica de forma natural y captura leads.
• chatbotAgent: un asistente ligero para la demo interactiva.
• visionAgent, voiceAgent, analyticsAgent: agentes enfocados detrás del playground de la demo.

Cada agente es una declaración sencilla: un nombre, un conjunto de instrucciones, un modelo y las herramientas que tiene permitido llamar. El id del modelo está centralizado en un único módulo, así que cambiarlo en todos los agentes es una edición de una línea y un despliegue, no un buscar y reemplazar por todo el código.

export const quoteAgent = new Agent({
  name: "quoteAgent",
  instructions: `...`,
  model: MODEL,
  tools: { submitProposal, scheduleCall, draftEmail, sendSummary },
});

Esa estructura es justo el punto. El agente no contiene lógica de negocio. Decide qué herramienta llamar y cuándo. Las herramientas contienen la lógica.

El tool calling es donde ocurre el trabajo

Un chat que solo devuelve texto es un juguete. El quote agent tiene cuatro herramientas, y las instrucciones están escritas para que las llame en el momento en que tiene los campos requeridos, sin pedirle permiso al usuario para continuar:

• submitProposal: captura un lead de proyecto (nombre, email, resumen).
• scheduleCall: agenda una llamada con el equipo.
• sendSummary: envía por email un resumen de la conversación.
• draftEmail: prepara un email para que el equipo lo revise.

La disciplina que hace esto usable está en el prompt: recopila el mínimo de campos requeridos y luego actúa. Nada de bucles de "¿procedo?", nada de confirmaciones vacías. Cuando el usuario ha dado un nombre, un email y un resumen del proyecto, la herramienta de propuesta se dispara. El usuario obtiene un resultado claro, no un callejón sin salida.

El idioma vive en el contexto de ejecución, no en el prompt

Este sitio se publica en cinco idiomas: inglés, alemán, francés, español y árabe. El asistente tiene que responder en el idioma del visitante y respetar el registro, el Sie formal en alemán por ejemplo, y la escritura de derecha a izquierda para el árabe.

La forma equivocada de hacerlo es incrustar el idioma en el system prompt y reconstruir un prompt por idioma. La forma correcta es el contexto de ejecución. Cada petición lleva el idioma, resuelto a partir de un valor explícito, una cabecera x-i18n-locale o la cabecera Accept-Language, y el agente lo lee en el momento de la generación:

const runtimeContext = new RuntimeContext();
if (finalLocale) runtimeContext.set("locale", finalLocale);
runtimeContext.set("requestId", requestId);

Un agente, un conjunto de instrucciones, cinco idiomas. El mismo request id fluye por los logs, así que una sola conversación puede trazarse de principio a fin.

Estado que se degrada en lugar de romperse

El almacenamiento de conversaciones usa LibSQL cuando hay una URL de base de datos configurada, y cae en un almacén en memoria cuando no la hay. El import es perezoso y está envuelto en un try y catch, así que una dependencia opcional faltante nunca tira abajo al asistente. Simplemente corre sin historial persistente.

Este es un principio recurrente en todo el sistema: la infraestructura opcional se degrada a un valor por defecto seguro en lugar de lanzar una excepción. La agregación que no puede alcanzar una fuente devuelve vacío. El asistente que no puede alcanzar una base de datos sigue respondiendo. Nada de cara al usuario depende de que un servicio opcional esté presente.

La capa de seguridad alrededor de cada petición

El modelo es la parte fácil. El límite de la petición es donde las funcionalidades de IA en producción salen lastimadas. Cada llamada al asistente pasa por las mismas puertas antes de que se genere un solo token:

1. Validación de método y entrada: solo POST, longitud de entrada acotada, cuerpos malformados rechazados con un error estructurado y un request id.
2. Rate limiting: límites por petición, para que un solo cliente no pueda agotar el presupuesto de inferencia.
3. Verificación de origen y CSRF: las llamadas del navegador deben venir de un origen permitido y llevar un token CSRF válido. El token se establece como cookie y se comprueba en cada llamada que muta estado.
4. Autorización interna: las llamadas servidor a servidor desde nuestro propio backend saltan las comprobaciones del navegador a través de una ruta de autenticación interna explícita, nunca un bypass implícito.

Estas no son específicas de la IA. Son las mismas puertas que necesita cualquier endpoint serio. El error que cometen los equipos es tratar una ruta de IA como especial y saltárselas. Un endpoint de LLM sigue siendo un endpoint, y gasta dinero en cada llamada, lo que convierte al rate limit en un control de costos tanto como en un control de seguridad.

Cero pérdida silenciosa de leads

Un lead que la IA captura pero que el sistema deja caer es peor que no tener IA en absoluto. Por eso los leads se registran en el flujo de logs antes de intentar la entrega, y los fallos de entrega se registran de forma explícita en lugar de tragárselos. Si un proveedor de email está caído, el lead todavía existe en el registro y puede recuperarse. La ruta de captura y la ruta de entrega están desacopladas a propósito, porque lo costoso de perder es la intención, no el email.

Streaming, porque la latencia es una funcionalidad

Las respuestas se transmiten token por token en lugar de bloquear hasta que la respuesta completa esté lista. En una superficie de ventas, la latencia percibida es la diferencia entre un visitante que espera y uno que se va. El streaming se maneja en un pequeño helper dedicado, así que cada ruta de agente obtiene el mismo comportamiento sin repetir la fontanería.

Lo que deliberadamente no construimos

Una buena arquitectura también es una lista de cosas a las que dijiste que no.

• Nada de asistente de propósito general. El quote agent está acotado solo al negocio de Oronts. Pídele que escriba un FizzBuzz o que cuente letras en una palabra y declina y redirige. Un asistente de ventas que responde trivias es un pasivo, no una funcionalidad, y un asistente abierto es una superficie de ataque abierta.
• Nada de números inventados. El asistente declara las bandas de precios publicadas al pie de la letra y nunca construye una estimación específica de proyecto. Los rangos de planificación vienen de un ingeniero senior tras el scoping, nunca de un modelo que quiere ser útil.
• Nada de promesas. Nunca confirma viabilidad, no compromete un plazo ni garantiza un resultado. Recopila información y la traspasa a personas.

Esas restricciones viven en las instrucciones y son las líneas más importantes de todo el sistema. La capacidad de un modelo está acotada por las barreras a su alrededor, y en un sitio comercial las barreras son el producto.

La conclusión para tu propia construcción

Si vas a poner una funcionalidad de IA en producción, la elección del modelo es la decisión de la que menos tiempo pasarás arrepintiéndote. Invierte tu esfuerzo en el límite: validación, rate limiting, idioma, degradación elegante y una ruta de captura que nunca pierda la intención. Frameworks como Mastra te dan las primitivas de agente y herramienta para que puedas invertir ese esfuerzo donde rinde.

Para los patrones que lo rodean, consulta nuestras guías sobre arquitectura multi-agente, observabilidad de IA y IA con humano en el bucle. Si quieres este tipo de sistema construido dentro de tu propio producto, inicia una conversación o solicita un presupuesto.