ایجنٹس کے لیے — منضبط ڈیٹا ٹول

AI ایجنٹ ٹولز
جو ثبوت کے ساتھ جواب دیتے ہیں۔

SQAI ایک ٹول-کالنگ ماڈل کو تین منضبط ٹولز کے ذریعے ساختہ ڈیٹا تک صرف-پڑھنے کی رسائی دیتا ہے۔ ماڈل ٹائپڈ ارادہ تحریر کرتا ہے۔ ایک معاہدہ اور آپ کی پالیسی اسے جانچتی ہے۔ ایک یکساں انجن اسے چلاتا ہے۔ ہر جواب ایک ہیش کے ساتھ لوٹتا ہے جو اسے دوبارہ چلا سکتا ہے۔

Iلوپ کا ایک چکر

درخواست داخل ہوتی ہے“کس خطے میں کل آمدنی سب سے زیادہ تھی؟”
کوئی بھی ٹول-کالنگ ماڈلماڈل

اقدامات طے کرتا ہے۔ ارادہ تحریر کرتا ہے۔ ڈیٹا کو کبھی نہیں چھوتا۔

ٹول کال — ٹائپڈ ارادہ، SQL نہیں{ version:"1", kind:"query", spec:{ metric:"revenue", aggregation:"sum", group_by:"region", source:"sales" } }
منضبط ٹولSQAI
  1. contractہیش-پِنڈ کیپیبلٹی معاہدہ
  2. policyآپ کی اجازت-فہرستیں، ایگزیکیوشن سے پہلے جانچی گئیں
  3. engineیکساں، صرف-پڑھنے ایگزیکیوشن
ٹائپڈ اسٹیٹس — کبھی ایکسیپشن نہیںstatus: ok · needs_clarification · rejected · error
جواب نکلتا ہے — اپنے ہیش کے ساتھeast — 2,130.50 · plan_hash f87610d8afeb…
ok

لوپ سے باہر۔ قطاریں یا قدر — اور وہ ہیش جو انہیں دوبارہ چلاتا ہے۔

needs_clarification ↺

لوپ میں واپس۔ ایک سوال اور اس کے ملے ہوئے امیدوار — ماڈل اسپیک کو بہتر کرتا ہے اور دوبارہ کال کرتا ہے۔ یہ کبھی کالم کا اندازہ نہیں لگاتا۔

مسترد اور ایرر ایک ہی ریٹرن لین پر سفر کرتے ہیں — ٹائپڈ نتائج جو ماڈل پڑھ سکتا ہے، نہ کہ ایکسیپشنز جو رن ختم کر دیں۔

IIٹول سیٹ

تین ٹولز۔ ایک چلاتا ہے۔

sqai.tools() بالکل تین ٹولز لوٹاتا ہے — جان بوجھ کر چھوٹی سطح۔ ڈسکوری اور ڈرائی رنز کبھی نہیں چلتے؛ ایگزیکیوشن بالکل ایک جگہ ہوتی ہے۔

listSources

کبھی نہیں چلتا

دریافت۔ ٹائپ شدہ فیلڈز کے ساتھ منسلک ذرائع، صلاحیت کے ماڈیول، فنکشن سگنیچر — ایک ان پٹ سے تین طریقے، تاکہ specs عین درست نام استعمال کریں۔

sources · capabilitySearch · module
ops: sum avg count min max eq in gt gte lt lte is_null is_not_null

queryData

وہ جو چلاتا ہے

ایک ورژن شدہ ان پٹ — kind پر ایک discriminated union: ایک query یا computation۔ چار نتائج، ہمیشہ typed، کبھی throw نہیں۔

version "1" · kind: query | computation
ok · needs_clarification · rejected · error

explainQuery

dry run — کبھی نہیں چلتا

بغیر چلائے intent کو resolve اور validate کرتا ہے۔ ماڈل اسے clarifications ڈیبگ کرنے کے لیے استعمال کرتا ہے؛ آپ اسے پلان کا پیش نظارہ کرنے کے لیے۔

preview invocation_hash ≠ executed hash

یہ سیٹ براہ راست generateText یا streamText میں جاتا ہے — typed، بغیر کسی cast کے قابل تفویض۔ Vercel AI SDK سیٹ اپ →

IIIخرابی کا معاہدہ

Tools کبھی throw نہیں کرتے۔

ایک exception ایجنٹ رن کو روک دیتا ہے۔ اس لیے یہاں کچھ بھی throw نہیں ہوتا: ابہام، انکار، اور ناکامی typed statuses کے طور پر واپس آتے ہیں جنہیں ماڈل پڑھ سکتا ہے — اور اپنے step budget کے اندر درست کر سکتا ہے۔

retryable عارضی کو نشان زد کرتا ہے — network_error · timeout · rate_limited · service_unavailable

queryData — چار نتائج

okنتیجہ: rows یا value، provenance hashes، اعلان شدہ truncation۔plan_hash · invocation_hash · computation_hash · truncated
needs_clarificationintent مبہم تھا۔ ایک سوال اور امیدوار — کبھی اندازہ نہیں۔question · candidates · explanation
rejectedresolver نے intent سے انکار کیا۔ کچھ بھی نہیں چلا۔rejection_reason · candidates · explanation
errorایک مستحکم کوڈ کے ساتھ منظم ناکامی — ماڈل اسے پڑھتا اور ایڈجسٹ کرتا ہے۔code · message · retryable · nearest_matches?

ہر شاخ ڈیٹا ہے۔ لوپ اپنی باری برقرار رکھتا ہے۔

اصول

ماڈل کو سمجھیں
ایک غیر بھروسہ مند client کے طور پر۔

کوڈ میں پالیسی · کسی tool input میں پالیسی فیلڈ نہیں · صرف تنگ کرنا

IVاصول، عملی طور پر

صنعت نے یہ production میں سیکھا — ایک خودمختار coding agent نے مشہوری سے ایک live database حذف کر دیا۔ SQAI کا جواب ساختی ہے، رویاتی نہیں: بے نقاب سطح تعمیری طور پر read-only ہے۔ Write اور non-deterministic زمرے کبھی اس میں generate نہیں ہوتے، اور کوئی flag، پالیسی، یا model input انہیں دوبارہ فعال نہیں کرتا۔

ماڈل کیا بھیجتا ہے
صرف typed intent — ایک ورژن شدہ spec۔ کوئی SQL string نہیں، کوئی کوڈ نہیں، کوئی connection handle نہیں۔
وہ کیا کبھی نہیں بھیج سکتا
پالیسی۔ allowedSources، allowedFields اور allowedFunctions createSQAI() config میں مقرر ہیں — کسی tool input schema میں پالیسی فیلڈ نہیں، اس لیے درخواست سطح کو تنگ کر سکتی ہے مگر کبھی وسیع نہیں۔
جب وہ پھر بھی مانگے
ایک منظم انکار — policy_denied_source، policy_denied_field، policy_denied_function۔ Non-retryable، ماڈل کے قابل مطالعہ، اور رن جاری رہتا ہے۔
مکمل پالیسی ماڈل →

Vوائرنگ

تین لائنیں اندر۔ بطور ڈیفالٹ محدود۔

ایک پیکج client کو tools میں لپیٹتا ہے۔ ذرائع پہلی کال پر lazily جڑتے ہیں؛ پہلی computation runtime کو ایک بار provision کرتی ہے، پھر warm رہتی ہے — 0.83 ms ناپا گیا۔

import { generateText } from "ai";
import { createSQAI } from "@thyn-ai/sqai-ai-sdk";

const sqai = createSQAI({
  sources: [{ data: "./data/sales.csv", name: "sales" }],
});

const { text, steps } = await generateText({
  model,                  // any AI SDK model
  tools: sqai.tools(),    // listSources · queryData · explainQuery
  prompt: "Which region had the highest total revenue?",
});
ai ^7.0.0zod ^4.0.0node ≥ 20runtime = "nodejs"

صرف Server-side — Next.js پر Node runtime رکھیں، Edge نہیں۔

ماڈل تک کیا پہنچتا ہے

maxRowsToModel
25وہ rows جو ماڈل دیکھتا ہے، engine کے چلائے گئے سب میں سے
maxCellsToModel
250cell budget — فٹ کرنے کے لیے پوری rows گرائی جاتی ہیں؛ ادھوری row کبھی نہیں دکھائی جاتی
maxBytesToModel
32,000ماڈل کے قابل مشاہدہ value کے لیے byte budget
maxExecutionRows
1,000engine کا hard cap — جب spec میں limit نہ ہو تو defaultLimit 100

Truncation ہمیشہ اعلان کیا جاتا ہے — truncated: true، returned_rows < total_rows۔ کبھی خاموش نہیں۔ مکمل نتائج application code میں result_id سے قابل بازیافت رہتے ہیں۔

VIایجنٹک تجزیات

وہ تجزیہ جسے ایجنٹ ثابت کر سکے۔

Agentic analytics معلوم طریقوں سے ناکام ہوتا ہے: خراب tool calls، ماڈل کا اپنا حساب، قابل یقین اعداد جنہیں کوئی تصدیق نہیں کر سکتا۔ ہر ایک کا جواب ساختی ہے، بہتر prompt سے نہیں۔

01غلط tool calls

ایک ورژن شدہ ان پٹ، کچھ بھی چلنے سے پہلے validate۔ خراب یا مبہم intent ایک typed status لوٹاتا ہے — loop crash کی بجائے جاری رہتا ہے۔

02ماڈل حساب کرتا ہے

یہاں نہیں۔ engine حساب کرتا ہے۔ 16 سوالوں کے quantitative سیٹ پر، وہی ماڈل 0/16 سے 16/16 ہو گیا جب engine نے computing کی۔

03ناقابل تصدیق اعداد

ہر جواب اپنا hash رکھتا ہے۔ اسی intent کو اسی ڈیٹا کے خلاف دوبارہ چلائیں اور hash ملتا ہے — TypeScript اور Python میں byte-identical۔

04Latency کا جمع ہونا

ایک loop latency کو ضرب دیتا ہے۔ query plane in-process پر sub-millisecond چلتا ہے؛ warm compute 0.83 ms ناپا گیا۔

پڑھتے رہیں

Vercel AI SDK ٹولز →پالیسی اور گورننس →یہ کیسے کام کرتا ہے →

VIIسوالات

ایجنٹس کے لیے — سوالات

میں AI ایجنٹ کو ڈیٹا بیس تک read-only رسائی کیسے دوں؟

SQL فلٹر نہ کریں — generate ہی نہ کریں۔ ذرائع کو createSQAI() سے جوڑیں اور ماڈل کو sqai.tools() دیں: جس سطح تک وہ پہنچتا ہے وہ تعمیری طور پر 4,574 read-only صلاحیتیں اور آپ کے ذرائع ہیں، کوئی write راستہ نہیں۔ بلاک کرنے کے لیے کوئی write زمرہ نہیں، اور کوئی model input نہیں جو اسے دوبارہ فعال کرے۔

جب ایجنٹ کی درخواست مبہم ہو تو کیا ہوتا ہے؟

queryData ایک سوال اور ملنے والے ممکنہ فیلڈز کے ساتھ needs_clarification لوٹاتا ہے۔ یہ کبھی کوئی کالم خود نہیں چنتا۔ ماڈل سوال کا جواب دیتا ہے اور دوبارہ کال کرتا ہے — لوپ کا ایک اور چکر۔

کیا ٹولز کبھی استثنا پھینکتے ہیں؟

نہیں۔ ہر ناکامی ایک منظم نتیجہ ہے جس میں ایک مستحکم کوڈ، ایک پیغام، اور دوبارہ کوشش کا اشارہ ہوتا ہے۔ ابہام، انکار، پالیسی رد، اور عارضی خرابیاں — سب ڈیٹا کی صورت میں آتی ہیں جسے ماڈل پڑھ سکتا ہے۔

کیا ماڈل اپنی اجازتیں خود بڑھا سکتا ہے؟

نہیں۔ allowedSources، allowedFields اور allowedFunctions کوڈ میں موجود ہیں، createSQAI() کے وقت مقرر ہوتے ہیں اور عمل سے پہلے جانچے جاتے ہیں۔ کسی ٹول کے ان پٹ اسکیما میں پالیسی فیلڈ نہیں ہوتی؛ کسی ممنوع صلاحیت کا نام لینے پر منظم policy_denied خطا ملتی ہے۔

کیا یہ Vercel AI SDK کے ساتھ کام کرتا ہے؟

ہاں — @thyn-ai/sqai-ai-sdk تینوں ٹولز کو generateText اور streamText کے لیے ایک typed tool set کے طور پر فراہم کرتا ہے، جس میں ai ^7.0.0 اور zod ^4.0.0 بطور peers، Node 20 یا جدید تر، سرور سائیڈ شامل ہیں۔ بنیادی کلائنٹ وہی SDK ہے جسے آپ کسی بھی ایجنٹ لوپ میں جوڑ سکتے ہیں۔

لوپ میں شامل کریں۔

Vercel AI SDK ٹولز ترتیب دیں →
دستاویزات پڑھیں →