Agente sicuro Postgres con chiamata di funzione (tutorial)

Costruirai un agente che risponde a domande in linguaggio naturale sui dati in un progetto Postgres, senza mai lasciare che il modello scriva SQL che viene eseguito così com'è. Il modello chiama uno strumento denominato query_database, questo strumento traduce la domanda in SQL convalidato tramite NL2SQL, quindi esegue questo SQL di sola lettura e restituisce le righe al modello in modo che formuli la sua risposta.

La maggior parte dei tutorial sugli agenti Postgres, incluse alcune guide ufficiali, definiscono un singolo strumento: una funzione execute_sql che accetta una stringa SQL come argomento e la esegue così com'è. Il modello scrive questa stringa da solo, in base alla domanda dell'utente e allo schema fornito nel contesto.

{
  "name": "execute_sql",
  "parameters": {
    "query": { "type": "string" }  // il modello scrive direttamente SQL
  }
}

Questa scelta trasferisce al modello una responsabilità che non può adempiere in modo affidabile. Una pronta iniezione inserita nella domanda può produrre SQL distruttivo che lo strumento esegue indiscriminatamente, poiché non ha idea di come dovrebbe apparire una query "legittima". Il nostro articolo dedicato descrive in dettaglio questo vettore di attacco: proteggere NL2SQL dall'iniezione SQL.

L'alternativa creata in questo tutorial espone uno strumento più ristretto, query_database(question). Il modello non può più scrivere direttamente SQL: può solo porre una domanda nella propria chiamata allo strumento. È il motore Aurabase NL2SQL che traduce questa domanda in SQL, prima di passarla attraverso un validatore di albero sintattico (solo SELECT, nessuna sottoquery, dieci funzioni autorizzate, LIMITE limitato).

I tre fornitori LLM nativi di Aurabase (OpenAI, Anthropic, Gemini) accettano una tabella di definizioni di strumenti in formato JSON Schema. A questo agente basta un unico strumento: query_database, che accetta una domanda in linguaggio naturale e nient'altro. Il modello non vede né lo schema SQL né un campo query che potrebbe compilare da solo.

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

Il gestore dello strumento viene eseguito sul tuo backend, mai nel browser. Contiene la chiave del progetto service_role, che ignora RLS in base alla progettazione e pertanto non dovrebbe mai essere esposta a un client. Effettua due chiamate all'SDK di Aurabase.

La prima chiamata traduce la domanda in SQL convalidato tramite aura.ai.nl2sql(): solo SELECT, LIMIT limitato, nessun accesso al catalogo di sistema. Il secondo esegue questo SQL già convalidato tramite aura.db.sql(), con l'opzione readOnly: true: Postgres stesso rifiuta quindi qualsiasi scrittura in questa transazione, indipendentemente dalla convalida testuale già applicata da NL2SQL upstream.

// Client inizializzato con la chiave service_role, mai sul lato browser
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 espone tre provider LLM nativi, ma il suo endpoint /chat non inoltra ancora un parametro tools o un ruolo tool. ChatOptions trasporta solo temperature, max_tokens e modele i ruoli accettati sono limitati a system, user e assistant (verificati in llm/mod.rs e handlers/chat.rs). Il ciclo di chiamata delle funzioni viene quindi eseguito oggi direttamente tramite l'SDK del provider, non tramite il proxy 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
}

Il principio rimane lo stesso se si orchestra l'agente con LangChain o un servizio come Azure AI Agent: lo strumento dichiarato nel framework deve rimanere lo stesso query_database, mai un esecutore SQL grezzo. Il nostro confronto descrive in dettaglio dove LangChain e LlamaIndex forniscono valore reale su Postgres e dove aggiungono complessità in particolare: Agenti Postgres con LangChain o LlamaIndex.

Domanda inviata all'agente: "Quanti clienti premium hanno effettuato un ordine questo mese?" ". Il modello chiama query_database con questa domanda così com'è, senza mai vedere o scrivere alcun codice SQL. Ecco il risultato delle due chiamate interne attivate dallo strumento.

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

La risposta finale del modello si basa su queste linee effettive, non su un'ipotesi. Se lo strumento restituisce zero righe, un'allucinazione numerica diventa significativamente meno probabile rispetto a un modello che risponderebbe senza dati verificati.

• La chiave service_role non lascia mai il tuo backend: né nel prompt inviato al modello, né in un log, né in una variabile di ambiente lato client.
• readOnly: true rimane attivo su aura.db.sql() per questo strumento specifico, anche se il tuo progetto necessita di essere scritto altrove nell'applicazione.
• service_role ignora RLS in base alla progettazione. Se l'agente dovesse rispondere in modo diverso a seconda dell'utente che pone la domanda, filtrare esplicitamente l'SQL o ricorrere agli endpoint PostgREST classici, che rispettano la RLS. Vedere isolamento RLS multi-tenant.
• Registra ogni chiamata dello strumento (domanda posta, SQL convalidato, numero di righe): questa è l'unica traccia utilizzabile se una domanda produce un risultato inaspettato.
• La limitazione della tariffa e la quota mensile di Aurabase si applicano già al progetto su /nl2sql: un agente loquace non può superare silenziosamente il budget dell'IA.

Lo strumento query_database eredita tutte le limitazioni del validatore NL2SQL: nessuna sottoquery, nessuna CTE/WITH, nessuna UNION e un elenco chiuso di dieci funzioni SQL. Una domanda che richiede naturalmente una sottoquery (“clienti che non hanno mai ordinato”) deve essere riformulata o elaborata da un secondo strumento dedicato anziché forzata in NL2SQL.

Oggi non esiste alcuna orchestrazione delle chiamate agli strumenti all'interno del proxy Aurabase /chat: il loop dell'agente qui descritto risiede nel codice dell'applicazione, non in un servizio gestito. Se l'agente deve concatenare diversi strumenti (database e RAG documentari, ad esempio), è il tuo backend che orchestra le due chiamate.

Questo tutorial copre domande strutturate sui dati relazionali. Per domande su contenuti non strutturati (documenti, ticket, note), lo stesso agente può esporre un secondo strumento collegato al RAG nativo di Aurabase (pgvector, ricerca HNSW). Le due funzionalità e la loro articolazione sono dettagliate nella pagina Native AI on Postgres.