यह ट्यूटोरियल फ़ंक्शन कॉलिंग के साथ एक एजेंट बनाता है जहां मॉडल के संपर्क में आने वाला टूल कभी भी मनमाना SQL निष्पादित नहीं करता है। यह Aurabase कोड में पहले से सत्यापित दो तंत्रों को जोड़ता है: NL2SQL सत्यापनकर्ता और एक रीड-ओनली Postgres लेनदेन,मूल AI की दो ईंटेंबैकएंड में एकीकृत हैं। आवश्यकताएँ: एक Aurabase प्रोजेक्ट, इसकी service_roleकुंजी, और तीन मूल एलएलएम प्रदाताओं (ओपनएआई, एंथ्रोपिक, जेमिनी) में से एक के साथ एक खाता।
अनिवार्य है
- वास्तविक जोखिम स्वयं फ़ंक्शन को कॉल करना नहीं है, बल्कि मॉडल के संपर्क में आने वाला टूल है: एक कच्चा
execute_sql(query)इसे पूर्ण SQL एक्सेस देता है। - सुरक्षित आर्किटेक्चर एक
query_database(question)टूल को उजागर करता है जो सीधे निष्पादन के बजाय एक सिंटैक्स ट्री सत्यापनकर्ता (केवल चयन, सीमित सीमा, पृथक स्कीमा) को सौंपता है। - Aurabase इस सत्यापनकर्ता को मूल रूप से उजागर करता है (
/nl2sql): इसे उपकरण के कार्यान्वयन के रूप में पुन: उपयोग करने से SQL सत्यापन को स्वयं दोबारा कोड करने से बचा जाता है। - प्रतिबद्ध SQL तब
readOnly: trueमोड मेंaura.db.sql()के माध्यम से निष्पादित होता है, एक वास्तविक रीड-ओनली Postgres लेनदेन, न कि एक साधारण टेक्स्ट फ़िल्टर। - Aurabase का मूल
/chatसमापन बिंदु अभी तकtoolभूमिका स्वीकार नहीं करता है और न हीtoolsपैरामीटर (कोड में सत्यापित): एजेंट लूप वर्तमान में LLM प्रदाता के SDK के माध्यम से चलता है, Aurabase प्रॉक्सी के माध्यम से नहीं। service_roleकुंजी डिज़ाइन द्वारा RLS को बायपास करती है: इसे आपके बैकएंड को कभी नहीं छोड़ना चाहिए, और एजेंट को एक सामान्य प्रमाणित उपयोगकर्ता की तुलना में व्यापक पहुंच प्राप्त होती है।
आप क्या बनाएंगे
आप एक ऐसा एजेंट बनाएंगे जो Postgres प्रोजेक्ट में डेटा के बारे में प्राकृतिक भाषा के सवालों का जवाब देता है, बिना मॉडल को एसक्यूएल लिखने की अनुमति दिए जो कि वैसे ही निष्पादित होता है। मॉडल query_database नामक टूल को कॉल करता है, यह टूल प्रश्न को NL2SQL के माध्यम से सत्यापित SQL में अनुवादित करता है, फिर इस रीड-ओनली SQL को निष्पादित करता है और लाइनों को मॉडल में लौटाता है ताकि वह अपना उत्तर तैयार कर सके।
यह ट्यूटोरियल सर्वर साइड पर @aurabase/aurabase-js JavaScript SDK का उपयोग करता है (ब्राउज़र साइड पर कभी भी, service_role कुंजी क्लाइंट के सामने नहीं आनी चाहिए) और एजेंट लूप के लिए OpenAI फ़ंक्शन कॉलिंग एपीआई का उपयोग करता है। एंथ्रोपिक या जेमिनी एसडीके के साथ भी यही सिद्धांत लागू होता है।
"यह SQL चलाएँ" उपकरण खतरनाक क्यों है?
अधिकांश Postgres एजेंट ट्यूटोरियल, जिनमें कुछ आधिकारिक गाइड भी शामिल हैं, एक एकल टूल को परिभाषित करते हैं: एक execute_sql फ़ंक्शन जो SQL स्ट्रिंग को एक तर्क के रूप में लेता है और इसे वैसे ही निष्पादित करता है। मॉडल इस स्ट्रिंग को उपयोगकर्ता के प्रश्न और संदर्भ में दिए गए स्कीमा के आधार पर स्वयं लिखता है।
{
"name": "execute_sql",
"parameters": {
"query": { "type": "string" } // मॉडल सीधे SQL लिखता है
}
}
यह विकल्प मॉडल पर एक जिम्मेदारी स्थानांतरित करता है जिसे वह विश्वसनीय रूप से पूरा नहीं कर सकता है। प्रश्न में डाला गया एक त्वरित इंजेक्शन विनाशकारी एसक्यूएल उत्पन्न कर सकता है जिसे उपकरण अंधाधुंध रूप से निष्पादित करता है, क्योंकि इसमें इसकी कोई अवधारणा नहीं है कि "वैध" क्वेरी कैसी दिखनी चाहिए। हमारा समर्पित लेख इस आक्रमण वेक्टर का विवरण देता है: SQL इंजेक्शन के विरुद्ध NL2SQL को सुरक्षित करना।
इस ट्यूटोरियल में निर्मित विकल्प एक संकीर्ण टूल, query_database(question) को उजागर करता है। मॉडल अब सीधे SQL नहीं लिख सकता: यह केवल अपने टूल कॉल में ही एक प्रश्न पूछ सकता है। यह Aurabase NL2SQL इंजन है जो इस प्रश्न को सिंटैक्टिक ट्री वैलिडेटर (अकेले चयन करें, कोई सबक्वेरी नहीं, दस फ़ंक्शन अधिकृत, सीमित सीमा) के माध्यम से पारित करने से पहले SQL में अनुवाद करता है।
एक execute_sql(query: string) टूल मॉडल को पूर्ण SQL एक्सेस देता है, भले ही आपका सिस्टम प्रॉम्प्ट कितना भी अच्छा क्यों न हो। एक निर्देश ("केवल SELECTs को निष्पादित करता है") एक निर्देश बना रहता है जिसका मॉडल अनुसरण कर सकता है, गलत व्याख्या कर सकता है, या उपयोगकर्ता के प्रश्न में डाले गए इंजेक्शन द्वारा बाधित हो सकता है।
मॉडल के संपर्क में आने वाले टूल की स्कीमा को परिभाषित करें
Aurabase के तीन मूल एलएलएम प्रदाता (ओपनएआई, एंथ्रोपिक, जेमिनी) 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
},
},
},
]
उपकरण लागू करें: NL2SQL फिर केवल पढ़ने के लिए
टूल हैंडलर आपके बैकएंड पर चलता है, ब्राउज़र में कभी नहीं। इसमें प्रोजेक्ट कुंजी service_role है, जो डिज़ाइन द्वारा RLS को बायपास करती है और इसलिए इसे कभी भी क्लाइंट के सामने उजागर नहीं किया जाना चाहिए। यह Aurabase SDK पर दो कॉल करता है।
पहली कॉल प्रश्न को aura.ai.nl2sql() के माध्यम से सत्यापित SQL में अनुवादित करती है: केवल चयन करें, सीमा सीमित है, सिस्टम कैटलॉग तक कोई पहुंच नहीं है। दूसरा, aura.db.sql() के माध्यम से पहले से ही सत्यापित इस 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 }
}
readOnly: true वास्तविक रीड-ओनली Postgres लेनदेन को ट्रिगर करता है: इंजन लिखने से इंकार कर देता है, यह अनुरोध पाठ पर लागू फ़िल्टर नहीं है। NL2SQL के चयन-केवल सत्यापन के साथ संयुक्त, एजेंट के पास दो स्वतंत्र परतें हैं: यदि एक में दोष है, तो दूसरा अभी भी बरकरार है।
एजेंट लूप: आपूर्तिकर्ता के एसडीके पक्ष पर फ़ंक्शन कॉलिंग
Aurabase तीन मूल एलएलएम प्रदाताओं को उजागर करता है, लेकिन इसका /chat समापन बिंदु अभी तक tools पैरामीटर या toolभूमिका को रिले नहीं करता है। ChatOptions में केवल temperature, max_tokens और model हैं, और स्वीकृत भूमिकाएं system, user और assistant (llm/mod.rs और handlers/chat.rs में सत्यापित) तक सीमित हैं। इसलिए फ़ंक्शन कॉलिंग लूप आज सीधे प्रदाता के SDK के माध्यम से चलता है, Aurabase प्रॉक्सी के माध्यम से नहीं।
जब तक Aurabase मूल रूप से टूल कॉल को व्यवस्थित नहीं करता है, तब तक आपके बैकएंड को ओपनएआई, एंथ्रोपिक या जेमिनी एसडीके के साथ लूप को स्वयं प्रबंधित करना होगा। NL2SQL और SQL निष्पादन इस लूप के अंदर क्लासिक 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 एजेंट जैसी सेवा के साथ व्यवस्थित करते हैं तो सिद्धांत वही रहता है: फ्रेमवर्क में घोषित टूल वही रहना चाहिए 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पर प्रति प्रोजेक्ट लागू है: एक बातूनी एजेंट चुपचाप आपके AI बजट को पार नहीं कर सकता है।
वर्तमान सीमाओं के बारे में जागरूक होना चाहिए
query_database उपकरण को NL2SQL सत्यापनकर्ता की सभी सीमाएँ विरासत में मिली हैं: कोई सबक्वेरी नहीं, कोई CTE/WITH नहीं, कोई UNION नहीं, और दस SQL फ़ंक्शंस की एक बंद सूची। एक प्रश्न जो स्वाभाविक रूप से एक उप-क्वेरी ("ग्राहक जिन्होंने कभी ऑर्डर नहीं किया है") को NL2SQL में मजबूर करने के बजाय दूसरे समर्पित टूल द्वारा पुनर्निर्मित या संसाधित किया जाना चाहिए।
Aurabase /chat प्रॉक्सी के अंदर टूल कॉल का कोई ऑर्केस्ट्रेशन आज मौजूद नहीं है: यहां वर्णित एजेंट लूप आपके एप्लिकेशन कोड में रहता है, प्रबंधित सेवा में नहीं। यदि एजेंट को कई टूल (उदाहरण के लिए डेटाबेस और डॉक्यूमेंट्री आरएजी) की श्रृंखला बनानी होगी, तो यह आपका बैकएंड है जो दो कॉलों को व्यवस्थित करता है।
RAG और फ़ंक्शन कॉलिंग संयुक्त
यह ट्यूटोरियल संबंधपरक डेटा पर संरचित प्रश्नों को शामिल करता है। असंरचित सामग्री (दस्तावेज़, टिकट, नोट्स) के बारे में प्रश्नों के लिए, वही एजेंट Aurabase के मूल RAG (pgvector, HNSW खोज) से जुड़े दूसरे टूल को उजागर कर सकता है। दो क्षमताएं और उनकी अभिव्यक्ति पृष्ठ नेटिव AI पर Postgres पर विस्तृत हैं।