Por qué nuestros agentes no tocan la base de datos

Cuando armás un agente que necesita datos, la vía corta es evidente: dale una conexión a la base y que consulte lo que precise. Es menos código, menos latencia y menos piezas.

Nosotros tomamos la decisión contraria y la escribimos como regla dura: el backend es la única puerta a la base de datos. Los agentes hablan por HTTP, como cualquier otro cliente. Sin excepciones.

Las tres razones

La primera es obvia y es la menos importante. Un agente con SQL libre puede escribir un UPDATE sin WHERE. Sí, se puede mitigar con permisos de solo lectura, pero eso resuelve la mitad del problema y ninguno de los dos siguientes.

La segunda es la lógica de negocio. Que un pedido pase a "pagado" no es escribir un campo. Es verificar el pago, generar el comprobante, activar la suscripción, agendar la renovación y avisar por el canal que corresponda. Si el agente escribe el campo directo, todo eso no pasa. Y lo peor es que parece que funcionó: el registro dice "pagado" y nadie se entera hasta que el cliente reclama.

La tercera es la que más nos importó con el tiempo: la trazabilidad. Cuando todo pasa por la API, todo queda en un log con quién, cuándo y con qué payload. Podés reconstruir qué hizo un agente hace tres semanas. Con acceso directo a la base tenés un cambio de estado sin autor.

Cómo se ve el contrato

Los agentes llevan una clave de sistema en cada llamada. No es la sesión de un usuario: es la identidad del propio agente, con su propio rol y sus propios permisos. La API sabe distinguir entre "esto lo pidió una persona logueada" y "esto lo pidió el agente de ventas", y aplica reglas distintas.

Un detalle que resultó más importante de lo que parecía: hay endpoints que un agente no puede llamar aunque tenga la clave. Los datos personales de contactos, por ejemplo, requieren una autorización explícita, para que un agente no se convierta en una forma indirecta de enumerar la base de clientes.

El costo, dicho sin maquillaje

Esta decisión cuesta. Cada dato nuevo que un agente necesita implica un endpoint, su validación y su prueba. Hay días en que lo que serían tres líneas de SQL se convierten en media hora de trabajo.

Lo aceptamos por una razón: la mayoría de los problemas serios que tuvimos no fueron de un agente haciendo algo espectacularmente mal. Fueron de un agente haciendo algo razonable en el lugar equivocado, salteando un paso que no sabía que existía. La API es donde vive ese conocimiento.

Un corolario que apareció solo

Con el tiempo pasó algo que no habíamos previsto. Como los agentes consumían la API, la API tuvo que quedar bien diseñada: nombres claros, errores explícitos, respuestas completas. Un endpoint que devuelve un 500 sin mensaje deja al agente sin saber qué hacer, y eso se nota enseguida.

Terminamos con una API mejor documentada de lo que hubiera estado si solo la consumiera nuestro propio frontend. Los agentes resultaron ser usuarios muy exigentes, y esa exigencia nos hizo bien.