Configura los primeros guardrails SQL de tu agente en 5 minutos

Qué es Claix Guard y qué problema resuelve

Claix Guard es un servicio gestionado que comprueba cambios de base de datos propuestos por agentes de IA. Su función no es juzgar si la conversación “parece segura”. Analiza una sentencia SQL y sus parámetros frente a las reglas activas de una conexión, y devuelve si la operación está permitida. Así, “los descuentos no pueden superar el 20%” puede convertirse en una condición revisable. Si el agente propone un 35%, la operación puede denegarse con la regla incumplida. Guard no sustituye los permisos de base de datos, las restricciones del esquema ni el control de acceso de tu aplicación.

Qué reglas puedes definir

La documentación describe reglas sobre operaciones, columnas, valores, condiciones y otros límites de negocio. También contempla casos que se deniegan para que tu propio workflow los derive a una persona. La regla que debes evaluar es la condición exacta que Claix propone y tú apruebas, no solo la frase inicial.

Antes de empezar: separa la propuesta de la ejecución

Para que Guard tenga efecto, el agente no debería poder escribir directamente en la base de datos. El agente propone la operación. Un ejecutor controlado por tu aplicación conserva las credenciales, consulta Guard y decide si ejecuta. Si el agente tiene otro acceso con permisos de escritura, puede saltarse la comprobación. También necesitas una conexión activa y reglas activas. La documentación especifica que, si no hay guards activos, la escritura se permite.

Paso 1. Escribe una primera regla en lenguaje natural

Empieza por un límite que puedas comprobar con ejemplos claros. “El descuento de un pedido no puede superar el 20%” permite un caso permitido y otro denegado. Claix utiliza un modelo para convertir la descripción en propuestas de reglas exactas. Después puedes aceptarlas, rechazarlas o modificarlas. La decisión de cada comprobación posterior no depende de volver a preguntarle a un modelo.

Paso 2. Revisa y activa la regla exacta

Comprueba la tabla, la columna y la unidad del valor. Un descuento del 20% puede almacenarse como 20 o como 0.20. Revisa también qué operaciones cubre. Claix recomienda que una persona apruebe las reglas y que los agentes puedan proponerlas. Un agente no debería poder flexibilizar por sí mismo los límites que después se le aplican.

Paso 3. Prueba casos permitidos y denegados en el Sandbox

Antes de conectar el ejecutor, prueba la regla en el Sandbox de Guard, incluidas sentencias que deberían denegarse.

Paso 4. Llama a Guard antes de ejecutar SQL

El endpoint documentado es POST https://claix.dev/check-sql. La petición incluye la sentencia en sql y los valores de sus placeholders en params. Si tu cuenta tiene varias conexiones activas, indica connection_id. En MySQL y MariaDB se utilizan placeholders ? en lugar de $1, $2.

curl -X POST "https://claix.dev/check-sql" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "UPDATE shop.orders SET discount_percent = $1 WHERE id = $2",
    "params": [35, 4821]
  }'

Si tu política establece un máximo de 20, la comprobación debería denegar el valor 35 conforme a la regla aprobada. La respuesta incluye allowed, un código de decisión, el motivo y un identificador para localizar la comprobación.

Paso 5. Comprueba allowed, no solo el estado HTTP

Una operación denegada también puede devolver HTTP 200. El 200 indica que la comprobación se completó. La autorización está en el campo allowed. Ejecuta la misma sentencia y los mismos parámetros que enviaste a Guard.

Qué significa que los guardrails sean deterministas

Un modelo puede ayudar durante la creación de las reglas, pero no decide en cada comprobación si una escritura está permitida. La comprobación utiliza las reglas aprobadas. No interpretes “determinista” como una promesa de latencia fija. La ventaja práctica es que la autorización no depende de convencer a otro modelo de que una operación “parece razonable”.

Cómo integrar Claix Guard con MCP, n8n o tu backend

La pregunta es qué componente tiene realmente la capacidad de escribir. El paso con credenciales debe exigir una decisión válida, no confiar en que el agente llame a Guard voluntariamente.

Qué puedes revisar en Guard Traces

Cada comprobación devuelve un decision_id. La respuesta también puede incluir la operación, la tabla, el SQL comprobado, reglas evaluadas, infracciones y latencia. Una decisión registrada no demuestra que la escritura se haya ejecutado: tu aplicación debe registrar por separado el resultado real.

Qué no resuelve Claix Guard

Guard no ejecuta las sentencias, no sustituye los permisos de base de datos y no protege cambios que se realicen por otra vía. Tampoco observa toda la lógica interna de la base, como los efectos de triggers.

Empieza por una regla que puedas verificar

Elige un cambio que tu agente necesita realizar y un límite que tu negocio no puede permitirse incumplir. Configura esa regla, prueba un caso permitido y otro denegado y conecta la comprobación al componente que ejecuta la escritura. Empieza en https://www.claix.dev/es/guard y usa la documentación de Check-SQL en https://www.claix.dev/es/documentation/check-sql.