Beveiligde Postgres-agent met functieaanroep (tutorial)

U bouwt een agent die vragen in natuurlijke taal over gegevens in een Postgres-project beantwoordt, zonder het model ooit SQL te laten schrijven die wordt uitgevoerd zoals het is. Het model roept een tool aan genaamd query_database, deze tool vertaalt de vraag naar SQL gevalideerd via NL2SQL, voert vervolgens deze alleen-lezen SQL uit en stuurt de regels terug naar het model zodat het zijn antwoord formuleert.

De meeste tutorials voor agenten van Postgres, inclusief enkele officiële handleidingen, definiëren één enkele tool: een execute_sql-functie die een SQL-tekenreeks als argument neemt en deze uitvoert zoals hij is. Het model schrijft deze string zelf, op basis van de vraag van de gebruiker en het schema dat eraan wordt gegeven in de context.

{
  "name": "execute_sql",
  "parameters": {
    "query": { "type": "string" }  // het model schrijft SQL rechtstreeks
  }
}

Deze keuze draagt ​​een verantwoordelijkheid over aan het model die het niet op betrouwbare wijze kan vervullen. Een promptinjectie in de vraag kan destructieve SQL opleveren die de tool zonder onderscheid uitvoert, omdat deze geen idee heeft hoe een 'legitieme' query eruit zou moeten zien. Ons speciale artikel beschrijft deze aanvalsvector: NL2SQL beveiligen tegen SQL-injectie.

Het alternatief dat in deze tutorial is ingebouwd, maakt gebruik van een smallere tool, query_database(question). Het model kan niet langer rechtstreeks SQL schrijven: het kan alleen een vraag stellen in zijn eigen tool call. Het is de Aurabase NL2SQL-engine die deze vraag in SQL vertaalt, voordat deze door een syntactische boomvalidator wordt geleid (alleen SELECT, geen subquery's, tien geautoriseerde functies, beperkte LIMIT).

De drie native LLM-providers van Aurabase (OpenAI, Anthropic, Gemini) accepteren een tabel met tooldefinities in JSON Schema-indeling. Eén enkele tool is voldoende voor deze agent: query_database, waarmee een vraag in natuurlijke taal kan worden gesteld en niets anders. Het model ziet noch het SQL-schema, noch een query-veld dat het zelf zou kunnen invullen.

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
      },
    },
  },
]

De toolhandler draait op uw backend, nooit in de browser. Het bevat de projectsleutel service_role, die RLS door het ontwerp omzeilt en daarom nooit aan een client mag worden blootgesteld. Er worden twee oproepen gedaan naar de Aurabase SDK.

De eerste aanroep vertaalt de vraag in SQL, gevalideerd via aura.ai.nl2sql(): alleen SELECT, LIMIT beperkt, geen toegang tot de systeemcatalogus. De tweede voert deze SQL uit die al is gevalideerd via aura.db.sql(), met de optie readOnly: true: Postgres weigert vervolgens zelf elk schrijven in deze transactie, onafhankelijk van de tekstuele validatie die NL2SQL upstream al heeft toegepast.

// Client geïnitialiseerd met de service_role-sleutel, nooit aan de browserzijde
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 stelt drie native LLM-providers beschikbaar, maar het /chat-eindpunt geeft nog geen tools-parameter of tool-rol door. ChatOptions bevat alleen temperature, max_tokens en model, en geaccepteerde rollen zijn beperkt tot system, user en assistant (geverifieerd in llm/mod.rs en handlers/chat.rs). De functieaanroepende lus loopt daarom vandaag rechtstreeks via de SDK van de provider, niet via de Aurabase-proxy.

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
}

Het principe blijft hetzelfde als u de agent orkestreert met LangChain of een service zoals Azure AI Agent: de tool die in het raamwerk is gedeclareerd, moet dezelfde query_databaseblijven, nooit een onbewerkte SQL-uitvoerder. Onze vergelijkingsdetails laten zien waar LangChain en LlamaIndex echte waarde bieden op Postgres, en waar ze vooral complexiteit toevoegen: Postgres-agents met LangChain of LlamaIndex.

Vraag verzonden naar agent: “Hoeveel premiumklanten hebben deze maand een bestelling geplaatst?” ". De sjabloon roept query_database aan met deze vraag zoals deze is, zonder ooit een SQL te zien of te schrijven. Hier is het resultaat van de twee interne oproepen die door de tool zijn geactiveerd.

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

Het uiteindelijke antwoord van het model is gebaseerd op deze werkelijke lijnen, en niet op een gok. Als de tool nul rijen retourneert, wordt een getallenhallucinatie aanzienlijk minder waarschijnlijk dan bij een model dat zou reageren zonder geverifieerde gegevens.

• De sleutel service_role verlaat nooit uw backend: noch in de prompt die naar het model wordt verzonden, noch in een logbestand, noch in een omgevingsvariabele aan de clientzijde.
• readOnly: true blijft actief op aura.db.sql() voor deze specifieke tool, zelfs als uw project elders in de applicatie moet worden geschreven.
• service_role omzeilt RLS door zijn ontwerp. Als de agent anders moet reageren, afhankelijk van de gebruiker die de vraag stelt, filter dan expliciet de SQL in of val terug op klassieke PostgREST-eindpunten, die RLS respecteren. Zie RLS-isolatie voor meerdere tenants.
• Registreer elke tooloproep (stelde vraag, SQL gevalideerd, aantal regels): dit is de enige bruikbare tracering als een vraag een onverwacht resultaat oplevert.
• De tarieflimiet en het maandelijkse quotum van Aurabase gelden al per project op /nl2sql: een spraakzame agent kan niet stilletjes uw AI-budget overschrijden.

De tool query_database erft alle beperkingen van de NL2SQL-validator: geen subquery's, geen CTE/WITH, geen UNION en een gesloten lijst van tien SQL-functies. Een vraag die uiteraard om een ​​subquery vraagt ​​(“klanten die nog nooit besteld hebben”) moet opnieuw geformuleerd worden, of verwerkt worden door een tweede speciale tool, in plaats van in NL2SQL geforceerd te worden.

Er bestaat momenteel geen orkestratie van tooloproepen binnen de Aurabase /chat proxy: de hier beschreven agentlus bevindt zich in uw applicatiecode, niet in een beheerde service. Als de agent meerdere tools aan elkaar moet koppelen (bijvoorbeeld database en documentaire RAG), is het uw backend die de twee oproepen orkestreert.

Deze tutorial behandelt gestructureerde vragen over relationele gegevens. Voor vragen over ongestructureerde inhoud (documenten, tickets, notities) kan dezelfde agent een tweede tool beschikbaar stellen die is verbonden met de native RAG van Aurabase (pgvector, HNSW search). De twee mogelijkheden en hun articulatie worden gedetailleerd beschreven op de pagina Native AI op Postgres.