Agente Postgres seguro con llamada de función (tutorial)

Creará un agente que responda preguntas en lenguaje natural sobre datos en un proyecto de Postgres, sin dejar que el modelo escriba SQL que se ejecute tal cual. El modelo llama a una herramienta llamada query_database, esta herramienta traduce la pregunta a SQL validado mediante NL2SQL, luego ejecuta este SQL de solo lectura y devuelve las líneas al modelo para que formule su respuesta.

La mayoría de los tutoriales del agente Postgres, incluidas algunas guías oficiales, definen una única herramienta: una función execute_sql que toma una cadena SQL como argumento y la ejecuta tal cual. El modelo escribe esta cadena por sí mismo, según la pregunta del usuario y el esquema que se le proporciona en contexto.

{
  "name": "execute_sql",
  "parameters": {
    "query": { "type": "string" }  // el modelo escribe SQL directamente
  }
}

Esta elección transfiere al modelo una responsabilidad que no puede cumplir de forma fiable. Una inyección rápida en la pregunta puede producir SQL destructivo que la herramienta ejecuta indiscriminadamente, ya que no tiene concepto de cómo debería ser una consulta "legítima". Nuestro artículo dedicado detalla este vector de ataque: asegurando NL2SQL contra inyección SQL.

La alternativa creada en este tutorial expone una herramienta más limitada, query_database(question). El modelo ya no puede escribir SQL directamente: sólo puede hacer una pregunta en su propia llamada a la herramienta. Es el motor Aurabase NL2SQL el que traduce esta pregunta a SQL, antes de pasarla por un validador de árbol sintáctico (SELECT solo, sin subconsultas, diez funciones autorizadas, LIMIT limitado).

Los tres proveedores nativos de LLM de Aurabase (OpenAI, Anthropic, Gemini) aceptan una tabla de definiciones de herramientas en formato JSON Schema. A este agente le basta una sola herramienta: query_database, que responde una pregunta en lenguaje natural y nada más. El modelo no ve el esquema SQL ni un campo query que pueda completar por sí mismo.

export const tools = [
  {
    type: 'function',
    function: {
      name: 'query_database',
      description:
        "Interroge les données du projet en langage naturel. N'accepte pas de SQL : posez une question.",
      parameters: {
        type: 'object',
        properties: {
          question: {
            type: 'string',
            description: 'Question en français sur les données du projet.'
          },
        },
        required: ['question'],
        additionalProperties: false
      },
    },
  },
]

El controlador de herramientas se ejecuta en su backend, nunca en el navegador. Lleva la clave de proyecto service_role, que omite RLS por diseño y, por lo tanto, nunca debe exponerse a un cliente. Realiza dos llamadas al SDK de Aurabase.

La primera llamada traduce la pregunta a SQL validado mediante aura.ai.nl2sql(): solo SELECT, LIMIT limitado, sin acceso al catálogo del sistema. El segundo ejecuta este SQL ya validado a través de aura.db.sql(), con la opción readOnly: true: el propio Postgres rechaza entonces cualquier escritura en esta transacción, independientemente de la validación textual ya aplicada por NL2SQL upstream.

// Cliente inicializado con la clave service_role, nunca en el lado del navegador
import { aura } from '@/lib/aurabase'

export async function queryDatabase(question: string) {
  const { data: validated, error } = await aura.ai.nl2sql(
    question,
    undefined,
    { limit: 50 },
  )
  if (error) return { error: error.message }

  const { data: rows, error: execError } = await aura.db.sql(
    validated.sql,
    [],
    { readOnly: true },
  )
  if (execError) return { error: execError.message }

  return { sql: validated.sql, rows }
}

Aurabase expone tres proveedores LLM nativos, pero su punto final /chat aún no transmite un parámetro tools o función tool. ChatOptions solo transporta temperature, max_tokens y model, y los roles aceptados están limitados a system, user y assistant (verificados en llm/mod.rs y handlers/chat.rs). Por lo tanto, el bucle de llamada a la función se ejecuta hoy directamente a través del SDK del proveedor, no a través del proxy de Aurabase.

import OpenAI from 'openai'
import { tools } from './lib/agent-tools'
import { queryDatabase } from './tools/query-database'

const openai = new OpenAI()

export async function askAgent(question: string) {
  const messages = [{ role: 'user', content: question }]

  const first = await openai.chat.completions.create({
    model: 'gpt-4.1', messages, tools,
  })

  const call = first.choices[0].message.tool_calls?.[0]
  if (!call) return first.choices[0].message.content

  const args = JSON.parse(call.function.arguments)
  const result = await queryDatabase(args.question)

  const second = await openai.chat.completions.create({
    model: 'gpt-4.1',
    messages: [
      ...messages,
      first.choices[0].message,
      { role: 'tool', tool_call_id: call.id, content: JSON.stringify(result) },
    ],
  })

  return second.choices[0].message.content
}

El principio sigue siendo el mismo si organiza el agente con LangChain o un servicio como Azure AI Agent: la herramienta declarada en el marco debe seguir siendo la misma query_database, nunca un ejecutor de SQL sin formato. Nuestra comparación detalla dónde LangChain y LlamaIndex brindan valor real en Postgres, y dónde agregan complejidad especialmente: Agentes de Postgres con LangChain o LlamaIndex.

Pregunta enviada al agente: "¿Cuántos clientes premium realizaron un pedido este mes?" ". La plantilla llama a query_database con esta pregunta tal cual, sin ver ni escribir ningún SQL. Aquí está el resultado de las dos llamadas internas activadas por la herramienta.

{
  "sql": "SELECT count(*) FROM orders WHERE customer_plan = 'premium' AND created_at >= date_trunc('month', now()) LIMIT 50",
  "rows": [{ "count": 128 }]
}

La respuesta final del modelo se basa en estas líneas reales, no en una suposición. Si la herramienta devuelve cero filas, una alucinación numérica se vuelve significativamente menos probable que con un modelo que respondería sin datos verificados.

• La clave service_role nunca sale de su backend: ni en el mensaje enviado al modelo, ni en un registro, ni en una variable de entorno del lado del cliente.
• readOnly: true permanece activo en aura.db.sql() para esta herramienta específica, incluso si su proyecto necesita escribirse en otra parte de la aplicación.
• service_role omite RLS por diseño. Si el agente debe responder de manera diferente según el usuario que hace la pregunta, filtre explícitamente en SQL o recurra a los puntos finales clásicos de PostgREST, que respetan RLS. Consulte aislamiento RLS multiinquilino.
• Registre cada llamada a la herramienta (pregunta formulada, SQL validado, número de líneas): este es el único seguimiento utilizable si una pregunta produce un resultado inesperado.
• La limitación de tarifas y la cuota mensual de Aurabase ya se aplican por proyecto en /nl2sql: un agente hablador no puede exceder silenciosamente su presupuesto de IA.

La herramienta query_database hereda todas las limitaciones del validador NL2SQL: sin subconsultas, sin CTE/WITH, sin UNION y una lista cerrada de diez funciones SQL. Una pregunta que naturalmente requiere una subconsulta (“clientes que nunca han realizado pedidos”) debe reformularse o procesarse con una segunda herramienta dedicada en lugar de forzarla a NL2SQL.

Actualmente no existe ninguna orquestación de llamadas a herramientas dentro del proxy Aurabase /chat: el bucle del agente descrito aquí reside en el código de su aplicación, no en un servicio administrado. Si el agente debe encadenar varias herramientas (base de datos y RAG documental, por ejemplo), es su backend quien organiza las dos llamadas.

Este tutorial cubre preguntas estructuradas sobre datos relacionales. Para preguntas sobre contenido no estructurado (documentos, tickets, notas), el mismo agente puede exponer una segunda herramienta conectada al RAG nativo de Aurabase (pgvector, búsqueda HNSW). Las dos capacidades y su articulación se detallan en la página AI nativa en Postgres.