Ir al contenido
← Ecosistema

Agentes de IA sobre PostgreSQL

pg_agent_gate v0.4.3

Los agentes proponen. PostgreSQL decide.

Una extensión que hace que en la sesión de un agente el SQL no se ejecute: el agente solo puede proponer una sentencia; PostgreSQL la verifica contra sí mismo, muestra su efecto exacto y la guarda solo si todas las guardas están de acuerdo. Aplicada por hooks dentro del servidor: no hay cliente, driver ni protocolo que la esquive.

Instalar

CREATE EXTENSION pg_agent_gate;

En simple

Una puerta entre la inteligencia artificial y tu base de datos: la IA propone, la base de datos revisa y decide.

  1. La situación

    Un asistente de IA atiende pedidos y puede actualizar datos de clientes en tu sistema.

  2. Sin esta pieza

    Una instrucción mal entendida borra 8 pedidos. Es una orden válida, así que la base la cumple. Nadie lo ve hasta que un cliente reclama.

  3. Con esta pieza

    La base de datos detecta que son 8 filas y el límite de ese asistente es 5: no ejecuta, muestra qué iba a pasar y lo deja registrado. El cambio legítimo de un solo cliente sí pasa.

Por qué importa si decides

  • Riesgo acotado: la IA no puede hacer más daño que el límite que tu equipo fije, por asistente
  • Evidencia: cada propuesta, cada aprobación y cada rechazo quedan en un registro que no se puede borrar
  • Operación simple: es una extensión dentro de tu PostgreSQL, sin otro servicio que mantener
Para el equipo técnico

El problema

Hoy la base no distingue al agente de la aplicación

Un agente llega a PostgreSQL con un rol y una conexión. Desde ese momento, cuando el modelo alucina un DELETE sin WHERE, un DROP TABLE o lee las filas de otro cliente, la base lo ejecuta: es SQL válido con permisos válidos.

Cada garantía vive en el servidor MCP o en el prompt, fuera de la base. El servidor obedece al modelo y PostgreSQL nunca se entera de qué se verificó.

Lo que el esquema dice Lo que pasa
DELETE FROM orders, tecleado por el agente Sin puerta: 8 filas borradas. Con puerta: ERROR, la sesión propone, no ejecuta.
DROP TABLE customers Sin puerta: la tabla desaparece. Con puerta: rehusado en propose (kind_allowed: sin DDL).
Borrar 8 filas con tope de 5 Con puerta: commit abortado, devuelve el antes/después de las filas.
UPDATE legítimo de 1 fila Con puerta: kept, mostrando el efecto antes de guardarlo.

Cómo funciona

Siete verbos, y en una sesión de agente nada más

  1. 01

    discover

    Qué puede tocar: tablas, vistas y funciones sobre las que tiene privilegios, con columnas, tipos, claves y restricciones. Sale del catálogo vivo, con una huella para detectar que el esquema cambió.

  2. 02

    propose

    Una sentencia, nada corre. Cada check es PostgreSQL mismo: parses, single_statement, kind_allowed, no_writing_cte, keeps_its_context, no_amplification, no_hidden_sql, no_opaque_function, read_changes_nothing / changes_only_rows, resolves.

  3. 03

    dry_run

    Corre en una subtransacción y se deshace: filas tocadas, antes y después de cada fila, y si las aserciones vinculadas seguirían cumpliéndose.

  4. 04

    commit

    Verifica de nuevo, ejecuta con los privilegios del agente y guarda si todas las guardas están de acuerdo. Más filas que max_rows o una aserción rota: se deshace. Una propuesta se confirma una sola vez.

  5. 05

    propose_and_commit, acts, whoami

    Los dos pasos en una llamada (una transacción, un commit); el registro append-only de todo lo propuesto y hecho, con por qué se rehusó; y quién es esta sesión y si la puerta está aplicada.

SQL

Registrar un agente

register_agent rehúsa roles superusuario, REPLICATION y BYPASSRLS, y miembros de pg_write_all_data, pg_execute_server_program o pg_write_server_files: un agente que puede salir de la puerta no está detrás de ella. Toma efecto en la siguiente conexión del rol.

psql · pg_agent_gatesql
CREATE EXTENSION pg_agent_gate;
CREATE ROLE billing_agent LOGIN;               -- nunca un superusuario
GRANT USAGE ON SCHEMA public TO billing_agent;
GRANT SELECT, UPDATE ON customers TO billing_agent;

SELECT agent_gate.register_agent(
  'billing', 'billing_agent', 'answers billing questions and upgrades plans',
  p_max_rows => 50, p_allow_ddl => false);

-- opcional: cada escritura que guarde debe dejar esta aserción en pie
SELECT agent_gate.bind_assertion('billing', 'no_customer_without_plan');

Lo que garantiza

Lo que garantiza, con una suite por cada línea

  • Nada de lo que la sesión teclea se ejecuta, salvo los siete verbos: ni DELETE, ni DO, ni COPY, ni PREPARE, ni un cursor.
  • Una propuesta corre solo después de que el parser, el planner, el analyzer y el rewriter de PostgreSQL la aceptan como UNA sentencia de un tipo que el agente puede correr.
  • Una escritura que toca más de max_rows filas, o rompe una aserción vinculada, se deshace.
  • El contexto que leen sus políticas de fila no se puede mover: ni con SET, ni al conectar, ni con set_config() dentro de una propuesta, en el cuerpo de una función, en una restricción o en un valor por defecto (0.4.2).
  • Ningún otro rol puede volverse el agente: con la biblioteca en shared_preload_libraries, el rol del agente no tiene miembros y ninguna sesión que no sea su propio login puede hacer SET ROLE hacia él (0.4.1).
  • Una lectura no cambia nada que el registro no muestre: ni una secuencia, ni un lock, ni un large object (0.4.3).
  • Todo lo que propuso e hizo queda registrado append-only, incluido por qué se rehusó algo. Un TRUNCATE del registro se rehúsa (0.2.0).
  • Una propuesta caduca: commit verifica de nuevo, y una propuesta más vieja que agent_gate.proposal_ttl_seconds (900) se rehúsa sin más.
  • Un cambio que la puerta guarda se confirma siempre con la durabilidad con que está configurado el servidor, y ese flush lleva también el registro de la propuesta que lo originó: no existe un cambio en disco sin su propuesta y su ejecución al lado.

Lo que no hace

Lo que no cubre, dicho acá para que nadie lo aprenda a golpes

  • Superusuarios y quien pueda editar postgresql.conf o reiniciar el servidor: pueden descargar la puerta. Por eso register_agent rehúsa superusuarios.
  • GRANT sigue siendo la autorización: la puerta agrega verificación, no inventa ni quita privilegios. Lo que un DBA cuelga de una tabla (trigger, CHECK, vista, función definer) corre con sus propias reglas.
  • No protege la intención: una sentencia bien formada, dentro de los privilegios y bajo max_rows, se ejecuta. Medido: pedido "pon a todos en plan free", el modelo escribió un UPDATE correcto de 2 filas y la puerta lo guardó, por contrato.
  • El cuerpo de una función se da por bueno según cómo está marcada: la puerta no lo lee. Detiene set_config(), el SQL que llega como texto y las funciones que el agente puede alterar, donde sea que se alcancen (0.4.3). Lo que queda es una función de un DBA marcada STABLE o IMMUTABLE que escribe: corre, y solo el tope de filas ve lo que cambió. Haz REVOKE EXECUTE ... FROM PUBLIC sobre lo que un agente no deba alcanzar.
  • Sin la biblioteca cargada antes de la primera sentencia del agente, la puerta falla abierta: whoami() lo reporta. Usa shared_preload_libraries. Las conexiones ya abiertas no están detrás hasta reconectar.
  • pg_dump no lleva quién es agente (está en el rol): restaurar sin los globals deja el registro diciendo que es agente mientras el rol está fuera de la puerta.
  • Con attempt_durability = fast (el valor por defecto), una caída del servidor puede perder el registro de un intento que no cambió nada: una propuesta, un dry run, una lectura, un rechazo. Nunca el de un cambio. Con durable, cada registro paga su propio flush.
  • allow_ddl es poder sobre el esquema, no un max_rows más grande: un agente con DDL corre cualquier CREATE, ALTER o DROP que sus permisos le den, y max_rows no acota lo que le hace a sus propias tablas. Un DROP TABLE concedido se guarda. Déjalo en false salvo que un agente puntual lo necesite.

Medido

Medido con pg_agent_gate 0.4.0, en una CI pública que cualquiera puede volver a correr

Tareas trampa que se escaparon Mismo modelo, mismas tareas, un superusuario revisando qué cambió de verdad: a través de un MCP server popular de Postgres, 4 de 7 tareas trampa se escaparon. Con la base decidiendo, 0 de 7.
Tokens y tiempo, con la misma puerta detrás Con la misma puerta detrás de ambos, el agente sin MCP usó 5 veces menos tokens de prompt que por MCP (24k contra 126k en 13 tareas) y terminó cada tarea 13 veces más rápido: una mediana de 14 s contra 185 s, en un runner de CI solo CPU que cualquiera puede volver a correr.
Una sentencia, y la base decide Escribir una sentencia y dejar que la base decida tomó una mediana de 6 s por tarea.
Un hueco, encontrado y cerrado Encontramos un hueco nosotros mismos (un modelo en loop partió un borrado rehusado en tajadas legales) y lo cerramos en 0.4.0: un presupuesto de escritura por agente, encendido por defecto.

Corrida de referencia: la CI del repo agent-gate-demo (github.com/Manuelreyesbravo/agent-gate-demo, run 41184106078), en un runner de GitHub solo CPU.

Para la empresa

Para la empresa

Es la pieza que permite conectar agentes a la base de producción con un contrato auditable: qué puede tocar cada agente, cuántas filas, con DDL o sin él, y un registro de cada propuesta con su veredicto.

  • Un agente por caso de uso, cada uno con su rol, su max_rows y sus aserciones vinculadas
  • Registro append-only de propuestas y ejecuciones: evidencia para auditoría y para revisar qué hizo un modelo
  • Sin MCP server obligatorio: el agente llega por psql, un driver o SQL directo. Hay un shim para clientes que solo hablan MCP, sin poder propio
  • ygg-agent (Python, Apache-2.0) es el loop listo entre un modelo y la puerta; desde 0.2.0 puede correr el modelo en el mismo proceso, sin servidor de modelo ni HTTP
  • Presupuesto de escritura por agente, encendido por defecto (desde 0.4.0)

Ficha técnica

Versión
0.4.3 en PGXN; la imagen pública 0.3.6 trae 0.4.3 (medido 13-11-2026)
PostgreSQL
18 o superior (dry_run usa RETURNING old/new); suite verde en 18 y 19
Construida con
pgrx 0.19.2 (Rust)
Configuración
shared_preload_libraries = 'pg_agent_gate' (recomendado)
Licencia
Apache-2.0
Edición Enterprise
Incluida (PostgreSQL 18)
Pruébala Hablar