وكيل 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، قبل تمريره عبر أداة التحقق من صحة الشجرة النحوية (حدد وحده، لا توجد استعلامات فرعية، عشر وظائف معتمدة، LIMIT محدود).

يقبل مقدمو خدمات LLM الثلاثة الأصليون في Aurabase (OpenAI وAnthropic وGemini) جدول تعريفات الأدوات بتنسيق مخطط JSON. أداة واحدة تكفي لهذا الوكيل: 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). تم تفصيل الإمكانيتين والتعبير عنهما على صفحة Native AI على Postgres.