Zabezpiecz agenta Postgres za pomocą wywołania funkcji (samouczek)

Stworzysz agenta, który odpowiada na pytania w języku naturalnym dotyczące danych w projekcie Postgres, nigdy nie pozwalając modelowi na zapisanie kodu SQL, który będzie wykonywany w niezmienionej postaci. Model wywołuje narzędzie o nazwie query_database, narzędzie to tłumaczy pytanie na język SQL zweryfikowany przez NL2SQL, następnie wykonuje ten kod SQL tylko do odczytu i zwraca linie do modelu, aby sformułował odpowiedź.

Większość samouczków dotyczących agentów Postgres, w tym niektóre oficjalne przewodniki, definiuje jedno narzędzie: funkcję execute_sql, która przyjmuje ciąg SQL jako argument i wykonuje go w niezmienionej postaci. Model sam zapisuje ten ciąg na podstawie pytania użytkownika i schematu podanego mu w kontekście.

{
  "name": "execute_sql",
  "parameters": {
    "query": { "type": "string" }  // model zapisuje bezpośrednio SQL
  }
}

Wybór ten przenosi na model odpowiedzialność, której nie jest w stanie rzetelnie spełnić. Natychmiastowy zastrzyk włożony w pytanie może spowodować destrukcyjny kod SQL, który narzędzie wykonuje bezkrytycznie, ponieważ nie ma pojęcia, jak powinno wyglądać „uprawnione” zapytanie. W naszym dedykowanym artykule szczegółowo opisano ten wektor ataku: zabezpieczanie NL2SQL przed wstrzyknięciem SQL.

Alternatywa wbudowana w tym samouczku udostępnia węższe narzędzie, query_database(question). Model nie może już bezpośrednio pisać kodu SQL: może jedynie zadawać pytania w ramach własnego wywołania narzędzia. To silnik Aurabase NL2SQL tłumaczy to pytanie na SQL przed przekazaniem go przez walidator drzewa syntaktycznego (sam SELECT, bez podzapytań, autoryzowanych dziesięć funkcji, ograniczony LIMIT).

Trzej natywni dostawcy LLM Aurabase (OpenAI, Anthropic, Gemini) akceptują tabelę definicji narzędzi w formacie schematu JSON. Dla tego agenta wystarczy jedno narzędzie: query_database, które zadaje pytanie w języku naturalnym i nic więcej. Model nie widzi schematu SQL ani pola query, które mógłby sam wypełnić.

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

Moduł obsługi narzędzi działa na Twoim backendzie, nigdy w przeglądarce. Zawiera klucz projektu service_role, który z założenia omija RLS i dlatego nigdy nie powinien być udostępniany klientowi. Wykonuje dwa wywołania pakietu Aurabase SDK.

Pierwsze wywołanie tłumaczy pytanie na język SQL sprawdzany za pomocą aura.ai.nl2sql(): tylko SELECT, ograniczenie LIMIT, brak dostępu do katalogu systemowego. Drugi wykonuje ten SQL już zweryfikowany przez aura.db.sql(), z opcją readOnly: true: sam Postgres następnie odmawia jakiegokolwiek zapisu w tej transakcji, niezależnie od sprawdzania poprawności tekstu zastosowanego już przez NL2SQL wyższego szczebla.

// Klient zainicjowany kluczem service_role, nigdy po stronie przeglądarki
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 udostępnia trzech natywnych dostawców LLM, ale jego punkt końcowy /chat nie przekazuje jeszcze parametru tools ani roli tool. ChatOptions przenosi tylko temperature, max_tokens i model, a akceptowane role są ograniczone do system, user i assistant (zweryfikowane w llm/mod.rs i handlers/chat.rs). Dlatego pętla wywoływania funkcji działa obecnie bezpośrednio za pośrednictwem pakietu SDK dostawcy, a nie za pośrednictwem serwera 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
}

Zasada pozostaje taka sama, jeśli koordynujesz agenta za pomocą LangChain lub usługi takiej jak Azure AI Agent: narzędzie zadeklarowane w strukturze musi pozostać takie samo query_database, nigdy surowy moduł wykonujący SQL. Nasze szczegóły porównania, gdzie LangChain i LlamaIndex zapewniają prawdziwą wartość w Postgres i gdzie szczególnie zwiększają złożoność: Agenci Postgres z LangChain lub LlamaIndex.

Pytanie wysłane do agenta: „Ilu klientów premium złożyło zamówienie w tym miesiącu?” ". Szablon wywołuje query_database z tym pytaniem w niezmienionej postaci, nigdy nie wyświetlając ani nie zapisując żadnego kodu SQL. Oto wynik dwóch wewnętrznych wywołań wywołanych przez narzędzie.

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

Ostateczna odpowiedź modelu opiera się na tych rzeczywistych liniach, a nie na domysłach. Jeśli narzędzie zwróci zero wierszy, halucynacja liczbowa stanie się znacznie mniej prawdopodobna niż w przypadku modelu, który odpowiedziałby bez zweryfikowanych danych.

• Klucz service_role nigdy nie opuszcza Twojego backendu: ani w podpowiedzi wysyłanej do modelu, ani w dzienniku, ani w zmiennej środowiskowej po stronie klienta.
• readOnly: true pozostaje aktywny na aura.db.sql() dla tego konkretnego narzędzia, nawet jeśli projekt wymaga napisania w innym miejscu aplikacji.
• service_role zgodnie z projektem omija RLS. Jeśli agent powinien reagować inaczej w zależności od użytkownika zadającego pytanie, jawnie odfiltruj kod SQL lub wróć do klasycznych punktów końcowych PostgREST, które uwzględniają RLS. Zobacz izolacja RLS dla wielu dzierżawców.
• Rejestruj każde wywołanie narzędzia (zadane pytanie, walidacja SQL, liczba wierszy): jest to jedyny użyteczny ślad, jeśli pytanie daje nieoczekiwany wynik.
• Limity stawek i miesięczny limit Aurabase obowiązują już dla każdego projektu w dniu /nl2sql: gadatliwy agent nie może po cichu przekroczyć budżetu AI.

Narzędzie query_database dziedziczy wszystkie ograniczenia walidatora NL2SQL: brak podzapytań, brak CTE/WITH, brak UNION i zamkniętą listę dziesięciu funkcji SQL. Pytanie, które w naturalny sposób wymaga zapytania dodatkowego („klienci, którzy nigdy nie zamawiali”), należy przeformułować lub przetworzyć za pomocą drugiego dedykowanego narzędzia, a nie wtłaczać do NL2SQL.

Obecnie w serwerze proxy Aurabase /chat nie istnieje żadna orkiestracja wywołań narzędzi: opisana tutaj pętla agenta znajduje się w kodzie aplikacji, a nie w usłudze zarządzanej. Jeśli agent musi połączyć kilka narzędzi (na przykład bazę danych i dokument RAG), to Twój backend koordynuje te dwa połączenia.

W tym samouczku opisano pytania strukturalne dotyczące danych relacyjnych. W przypadku pytań dotyczących zawartości nieustrukturyzowanej (dokumenty, bilety, notatki) ten sam agent może udostępnić drugie narzędzie połączone z natywnym RAG Aurabase (pgvector, wyszukiwanie HNSW). Obie możliwości i ich artykulacja są szczegółowo opisane na stronie Natywna sztuczna inteligencja w Postgres.