関数呼び出しによる安全な Postgres エージェント (チュートリアル)

そのまま実行される SQL をモデルに記述させることなく、Postgres プロジェクト内のデータに関する自然言語の質問に答えるエージェントを構築します。モデルは query_databaseという名前のツールを呼び出します。このツールは質問を NL2SQL で検証された SQL に変換し、この読み取り専用 SQL を実行してモデルに行を返し、答えを定式化します。

一部の公式ガイドを含むほとんどの Postgres エージェント チュートリアルでは、SQL 文字列を引数として受け取り、それをそのまま実行する execute_sql 関数という単一のツールが定義されています。モデルは、ユーザーの質問とコンテキストで与えられたスキーマに基づいて、この文字列自体を書き込みます。

{
  "name": "execute_sql",
  "parameters": {
    "query": { "type": "string" }  // モデルは SQL を直接書き込みます
  }
}

この選択により、モデルが確実に果たせない責任がモデルに移ることになります。質問にプロンプ​​トインジェクションが組み込まれると、ツールが「正当な」クエリがどのようなものであるべきかについての概念がないため、ツールが無差別に実行する破壊的な SQL が生成される可能性があります。この攻撃ベクトルについては、専用の記事で詳しく説明しています: SQL インジェクションから NL2SQL を保護する。

このチュートリアルに組み込まれている代替ツールでは、より範囲の狭いツール query_database(question)が公開されています。モデルは SQL を直接書くことができなくなり、独自のツール呼び出しで質問することしかできなくなります。 Aurabase NL2SQL エンジン は、この質問を構文ツリー検証ツール (SELECT のみ、サブクエリなし、許可される関数は 10 個、制限付き LIMIT) に渡す前に SQL に変換します。

Aurabase の 3 つのネイティブ LLM プロバイダ (OpenAI、Anthropic、Gemini) は、JSON スキーマ形式のツール定義のテーブルを受け入れます。このエージェントには query_databaseという 1 つのツールで十分です。このツールは自然言語のみで質問を受けます。モデルは、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 に対して 2 つの呼び出しを行います。

最初の呼び出しでは、質問が aura.ai.nl2sql()によって検証された SQL に変換されます: SELECT のみ、LIMIT 制限あり、システム カタログへのアクセスなし。 2 つ目は、 aura.db.sql()経由で検証済みの SQL を readOnly: true オプションを使用して実行します。その後、上流の NL2SQL によってすでに適用されているテキスト検証とは関係なく、Postgres 自体がこのトランザクションでの書き込みを拒否します。

// クライアントは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 は 3 つのネイティブ LLM プロバイダを公開していますが、その /chat エンドポイントはまだ tools パラメータまたは toolロールを中継していません。 ChatOptions は temperature、 max_tokens 、 modelのみをサポートし、受け入れられるロールは system、 user 、 assistant に限定されます ( llm/mod.rs および handlers/chat.rsで検証)。したがって、関数呼び出しループは現在、Aurabase プロキシ経由ではなく、プロバイダーの SDK 経由で直接実行されます。

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 で実際の価値を提供する場所と、特に複雑さを増す場所を詳しく説明します: LangChain または LlamaIndex を備えた Postgres エージェント。

エージェントに送信された質問: 「今月注文したプレミアム顧客は何名ですか?」 "。テンプレートは、SQL を見たり書いたりすることなく、この質問をそのまま使用して query_database を呼び出します。ツールによってトリガーされた 2 つの内部呼び出しの結果は次のとおりです。

{
  "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 で明示的にフィルターするか、RLS を尊重する従来の PostgREST エンドポイントにフォールバックします。 マルチテナント RLS 分離を参照してください。
• 各ツール呼び出しをログに記録します (質問された質問、検証された SQL、行数)。これは、質問によって予期しない結果が生じた場合に使用できる唯一のトレースです。
• Aurabase のレート制限と月次割り当ては、 /nl2sqlのプロジェクトごとにすでに適用されています。おしゃべりなエージェントが黙って AI 予算を超えることはできません。

query_database ツールは、NL2SQL バリデーターの制限をすべて継承しています。つまり、サブクエリなし、CTE/WITH なし、UNION なし、および 10 個の SQL 関数のクローズド リストです。必然的にサブクエリを必要とする質問 (「注文したことのない顧客」) は、NL2SQL に強制的に組み込むのではなく、再定式化するか、2 番目の専用ツールで処理する必要があります。

現在、Aurabase /chat プロキシ内にはツール呼び出しのオーケストレーションは存在しません。ここで説明されているエージェント ループは、マネージド サービス内ではなく、アプリケーション コード内に存在します。エージェントが複数のツール (データベースとドキュメンタリー RAG など) をチェーンする必要がある場合、2 つの呼び出しを調整するのはバックエンドです。

このチュートリアルでは、リレーショナル データに関する構造化された質問について説明します。非構造化コンテンツ (ドキュメント、チケット、メモ) に関する質問については、同じエージェントが Aurabase のネイティブ RAG (pgvector、HNSW 検索) に接続された 2 番目のツールを公開できます。 2 つの機能とその表現については、 Postgres のネイティブ AIページで詳しく説明されています。