Безопасный агент Postgres с вызовом функций (учебник)

Вы создадите агент, который отвечает на вопросы на естественном языке о данных в проекте Postgres, не позволяя модели писать SQL, который выполняется как есть. Модель вызывает инструмент с именем query_database, этот инструмент переводит вопрос в SQL, проверенный через NL2SQL, затем выполняет этот SQL только для чтения и возвращает строки в модель, чтобы она сформулировала свой ответ.

В большинстве руководств по агентам Postgres, включая некоторые официальные руководства, определяется один инструмент: функция execute_sql, которая принимает строку SQL в качестве аргумента и выполняет ее как есть. Модель сама записывает эту строку на основе вопроса пользователя и схемы, заданной ей в контексте.

{
  "name": "execute_sql",
  "parameters": {
    "query": { "type": "string" }  // модель пишет SQL напрямую
  }
}

Этот выбор перекладывает на модель ответственность, которую она не может надежно выполнить. Внедрение подсказки в вопрос может привести к деструктивному SQL-коду, который инструмент выполняет без разбора, поскольку он не имеет представления о том, как должен выглядеть «законный» запрос. В нашей специальной статье подробно описан этот вектор атаки: защита NL2SQL от SQL-инъекций.

Альтернатива, созданная в этом руководстве, предоставляет более узкий инструмент query_database(question). Модель больше не может писать SQL напрямую: она может только задавать вопросы при вызове собственного инструмента. Это механизм Aurabase NL2SQL, который переводит этот вопрос в SQL, прежде чем передать его через валидатор синтаксического дерева (только SELECT, без подзапросов, десять разрешенных функций, ограниченный LIMIT).

Три собственных поставщика LLM Aurabase (OpenAI, Anthropic, Gemini) принимают таблицу определений инструментов в формате JSON Schema. Для этого агента достаточно одного инструмента: query_database, который принимает вопрос на естественном языке и ничего больше. Модель не видит ни схемы SQL, ни поля query, которое она могла бы заполнить сама.

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

Обработчик инструмента запускается на вашем сервере, а не в браузере. Он содержит ключ проекта service_role, который по своей конструкции обходит RLS и поэтому никогда не должен быть доступен клиенту. Он выполняет два вызова Aurabase SDK.

Первый вызов переводит вопрос в SQL, проверенный через aura.ai.nl2sql(): только SELECT, ограничено LIMIT, нет доступа к системному каталогу. Второй выполняет этот SQL, уже проверенный через aura.db.sql(), с опцией readOnly: true: сам Postgres затем отказывается от любой записи в этой транзакции, независимо от текстовой проверки, уже примененной вышестоящим NL2SQL.

// Клиент инициализируется с помощью ключа service_role, а не на стороне браузера.
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 предоставляет три собственных поставщика LLM, но его конечная точка /chat еще не передает параметр tools или роль tool. ChatOptions содержит только temperature, max_tokens и model, а допустимые роли ограничены system, user и assistant (проверено в llm/mod.rs и handlers/chat.rs). Таким образом, цикл вызова функции сегодня выполняется непосредственно через SDK провайдера, а не через прокси-сервер 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
}

Принцип остается тем же, если вы организуете агент с помощью LangChain или такой службы, как Azure AI Agent: инструмент, объявленный в платформе, должен оставаться тем же query_database, а не просто исполнителем SQL. Подробное сравнение, где LangChain и LlamaIndex обеспечивают реальную ценность Postgres, а где они особенно усложняют: Агенты Postgres с LangChain или LlamaIndex.

Вопрос отправлен агенту: «Сколько премиальных клиентов разместили заказ в этом месяце?» ". Шаблон вызывает query_database с этим вопросом как есть, даже не видя и не записывая никакого SQL. Вот результат двух внутренних вызовов, инициированных инструментом.

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

Окончательный ответ модели основан на этих реальных линиях, а не на догадках. Если инструмент возвращает ноль строк, числовые галлюцинации становятся значительно менее вероятными, чем в случае с моделью, которая реагирует без проверенных данных.

• Ключ service_role никогда не покидает ваш сервер: ни в приглашении, отправленном в модель, ни в журнале, ни в переменной среды на стороне клиента.
• readOnly: true остается активным на aura.db.sql() для этого конкретного инструмента, даже если ваш проект требует записи в другом месте приложения.
• service_role намеренно обходит RLS. Если агент должен отвечать по-разному в зависимости от пользователя, задающего вопрос, явно отфильтруйте SQL или вернитесь к классическим конечным точкам PostgREST, которые соблюдают RLS. См. раздел многопользовательской изоляции RLS.
• Регистрируйте каждый вызов инструмента (заданный вопрос, проверка SQL, количество строк): это единственная полезная трассировка, если вопрос дает неожиданный результат.
• Ограничение скорости и ежемесячная квота Aurabase уже применяются к каждому проекту на /nl2sql: разговорчивый агент не может молча превысить ваш бюджет на ИИ.

Инструмент query_database наследует все ограничения валидатора NL2SQL: отсутствие подзапросов, отсутствие CTE/WITH, отсутствие UNION и закрытый список из десяти функций SQL. Вопрос, который, естественно, требует подзапроса («клиенты, которые никогда не заказывали»), должен быть переформулирован или обработан вторым специальным инструментом, а не принудительно перенесен в NL2SQL.

Сегодня внутри прокси-сервера Aurabase /chat не существует никакой оркестрации вызовов инструментов: описанный здесь цикл агента находится в коде вашего приложения, а не в управляемом сервисе. Если агенту необходимо объединить несколько инструментов (например, базу данных и документацию RAG), именно ваш бэкэнд организует эти два вызова.

В этом руководстве рассматриваются структурированные вопросы по реляционным данным. Для вопросов о неструктурированном контенте (документы, заявки, заметки) тот же агент может использовать второй инструмент, подключенный к встроенному RAG Aurabase (pgvector, поиск HNSW). Эти две возможности и их сочетание подробно описаны на странице Собственный искусственный интеллект в Postgres.