- Publicado
- Actualizado
- Tiempo de lectura
- 5 min
Cada registro se explica solo: el serializador ai_context
Cyril da a sus registros principales un serializador ai_context: una vista determinista y consciente del esquema, construida para el modelo y no para la base de datos. Es el núcleo poco vistoso de que la IA se apoye de verdad en tus datos.
En esta página
La parte emocionante del software nativo de IA es el agente haciendo algo útil. La parte que de verdad lo hace funcionar es aburrida: cómo un registro se describe a sí mismo ante un modelo.
Si eso sale mal, todas las demos que vengan después se construyen sobre arena. Si sale bien, el agente deja de adivinar.
Las filas en bruto son la entrada equivocada
Una fila de una base de datos está hecha para la base de datos. Tiene claves foráneas, enums de estado, columnas que admiten nulos, banderas internas y marcas de tiempo en UTC. Entrégasela a un modelo y le habrás pedido dos trabajos a la vez: reconstruir qué significa el registro y, a partir de ahí, razonar sobre él.
El primero lo hará mal. status: 3 no significa nada sin la tabla de referencia. Un null en closed_at puede querer decir «sigue abierto» o «nunca se registró». Una clave foránea es un número que el modelo no puede seguir. Así que el modelo se inventa el significado que necesita —con total seguridad— y el error se va amplificando en cada paso posterior.
La solución no es un modelo más grande. Es darle al modelo la entrada correcta.
Qué es un serializador ai_context
En Cyril, los registros principales —cuentas, contactos, oportunidades, proyectos, tickets, facturas, documentos y productos— exponen cada uno un serializador ai_context. Es un único método que devuelve una vista determinista y consciente del esquema del registro, construida específicamente para que la IA se apoye en ella.
Esa vista hace la interpretación que el modelo no debería tener que hacer:
- Los enums se resuelven a su significado humano:
status: 3pasa a ser"etapa: negociación". - Los recuentos relacionados se incorporan: una cuenta lleva consigo sus tickets abiertos, el estado de sus proyectos activos y el de sus facturas pendientes, porque es justo lo que va a necesitar cualquier pregunta sobre esa cuenta.
- Los campos de uso interno se eliminan: el modelo nunca ve identificadores de fila, marcas de borrado lógico ni fontanería de multitenencia.
- La forma es estable: el mismo registro produce siempre el mismo contexto, así que los prompts son cacheables y el comportamiento es reproducible.
No es, deliberadamente, ni la respuesta de la API ni la fila de la base de datos. Es una tercera representación cuyo único público es un modelo.
Por qué la cobertura es justo el punto
Sería fácil escribir un serializador ai_context para las tres entidades que toca la demo de lanzamiento. Esa es la trampa. El valor de un único grafo de datos es que una pregunta pueda cruzar cualquier frontera: «¿qué cuentas en riesgo tienen además un proyecto retrasado y una factura sin pagar?» solo funciona si cuentas, proyectos y facturas se explican todas de la misma manera.
Por eso en Cyril el serializador es un requisito, no una función. Los registros principales ya lo tienen; las tareas, los gastos, los registros de horas y los de RR. HH. todavía se están añadiendo, y aún no hay ningún test automático que compruebe que cada entidad nueva lo tenga. Esa disciplina es poco vistosa y es exactamente lo que permite a un agente recorrer la plataforma entera sin toparse con un registro que no sabe leer.
El determinismo también es una propiedad de seguridad
Como el serializador es la única vista de cara a la IA, es también el sitio donde controlamos la exposición. Las decisiones campo a campo sobre qué puede ver un agente viven en un único punto auditable por entidad, acotado por org_id como cualquier otra consulta. No hay una vía aparte de «exportación para IA» que ensanche el radio de daño en voz baja: el mismo serializador que sostiene al modelo es la frontera que lo limita.
Qué te aporta
- Haces una pregunta que cruza módulos y obtienes una respuesta apoyada en datos resueltos, relacionados y actuales, no en filas en bruto que el modelo ha tenido que descifrar.
- Te fías de la respuesta lo suficiente como para actuar sobre ella, porque el mismo registro produce siempre el mismo contexto.
- Sabes que lo que la IA puede ver está definido en un solo sitio por entidad, y no repartido por las integraciones.
El serializador nunca será la función estrella. Es la capa que decide si las funciones estrella son ciertas.
Preguntas frecuentes
¿En qué se diferencia de la respuesta de la API?
La respuesta de la API está pensada para un desarrollador que monta una pantalla: es completa, está normalizada y da por hecho que quien la llama conoce el dominio. El serializador está pensado para un lector que no conoce el esquema y no puede seguir una clave foránea, así que resuelve en lugar de referenciar.
¿Por qué no hacer simplemente recuperación sobre la base de datos?
La recuperación encuentra texto que se parece a la pregunta. Responde a lo que se escribió en algún momento, no a lo que es cierto ahora mismo de un registro; y para «qué cuentas están en riesgo este trimestre», lo que es cierto ahora es toda la pregunta.
¿Construir esa vista ralentiza las consultas?
El estado relacionado que incorpora es estado que una respuesta de verdad habría necesitado igualmente; reunirlo una sola vez, de forma determinista, sale más barato que el modelo pidiéndolo a lo largo de varios turnos. El determinismo, además, hace el resultado cacheable, cosa que la vía de la fila en bruto no permite.
¿Qué pasa cuando se añade una entidad nueva?
No debería publicarse sin el suyo. Hoy es una norma que nos imponemos nosotros, no una que haga cumplir un test, porque el valor del grafo es que una pregunta pueda cruzar cualquier frontera: una sola entidad sin serializador es un agujero por el que se cae un agente.
