listSources
لا تنفّذ أبدًاالاستكشاف. مصادر متصلة بحقول مكتوبة، ووحدات قدرات، وتوقيعات دوال — ثلاثة أوضاع من مدخل واحد، لتستخدم المواصفات الأسماء الدقيقة.
للوكلاء — أداة البيانات المحكومة
أدوات وكيل الذكاء الاصطناعي
تُجيب بدليل.
يمنح SQAI نموذجًا يستدعي الأدوات وصولًا للقراءة فقط إلى البيانات المنظَّمة عبر ثلاث أدوات محكومة. يؤلّف النموذج نيةً مكتوبة. يفحصها عقد وسياستك. ينفّذها محرك حتمي. كل إجابة تعود مع تجزئة تُعيد تشغيلها.
Iدورة واحدة في الحلقة
يدخل الطلب
“أي منطقة حققت أعلى إجمالي إيرادات؟”أي نموذج يستدعي الأدواتالنموذج
يخطط الخطوات. يؤلف النية. لا يلمس البيانات قط.
استدعاء أداة — نية مكتوبة، لا SQL
{ version:"1", kind:"query", spec:{ metric:"revenue", aggregation:"sum", group_by:"region", source:"sales" } }الأداة المحكومةSQAI
contractعقد قدرة مثبَّت بالتجزئةpolicyقوائم السماح الخاصة بك، تُفحص قبل التنفيذengineتنفيذ حتمي للقراءة فقط
حالة مكتوبة — لا استثناءات
status: ok · needs_clarification · rejected · errorتغادر الإجابة — مع تجزئتها
east — 2,130.50 · plan_hash f87610d8afeb…okيخرج من الحلقة. الصفوف أو القيمة — والتجزئة التي تُعيد تشغيلها.
needs_clarification ↺يعود إلى الحلقة. سؤال والمرشحات التي وجدها — يُدقّق النموذج المواصفة ويستدعي مجددًا. لا يخمّن عمودًا قط.
الرفض والخطأ يسلكان مسار الإعادة ذاته — نتائج مكتوبة يستطيع النموذج قراءتها، لا استثناءات تُوقف التشغيل.
IIمجموعة الأدوات
ثلاث أدوات. واحدة تنفّذ.
تُعيد `sqai.tools()` ثلاث أدوات بالضبط — سطح صغير بقصد. الاستكشاف والتشغيل الجاف لا ينفّذان؛ التنفيذ يحدث في مكان واحد فقط.
لا تنفّذ أبدًا
queryData
المنفِّذ الفعليمدخل واحد بإصدار محدد — اتحاد مميَّز على kind: استعلام أو حساب. أربع نتائج، مكتوبة دائمًا، لا استثناء قط.
explainQuery
تشغيل وهمي — لا تنفيذيحلّ النية ويتحقق منها دون تشغيلها. يستخدمه النموذج لتصحيح الاستيضاحات؛ وتستخدمه أنت لمعاينة الخطة.
تنزل المجموعة مباشرةً في generateText أو streamText — مكتوبة، قابلة للإسناد دون تحويل. إعداد Vercel AI SDK →
IIIعقد الأخطاء
الأدوات لا تُطلق استثناءات.
الاستثناء يُوقف تشغيل الوكيل. لذا لا شيء هنا يُطلق استثناءً: الغموض والرفض والفشل تعود كحالات مكتوبة يستطيع النموذج قراءتها — وتصحيحها — ضمن ميزانية خطواته.
retryable يُميِّز العابرة منها — network_error · timeout · rate_limited · service_unavailable
queryData — النتائج الأربع
okالنتيجة: صفوف أو قيمة، تجزئات المصدر، والاقتطاع المُعلَن.plan_hash · invocation_hash · computation_hash · truncatedneeds_clarificationالنية كانت غامضة. سؤال مع المرشحين — لا تخمين قط.question · candidates · explanationrejectedرفض المحلِّل النية. لم يُنفَّذ شيء.rejection_reason · candidates · explanationerrorفشل منظَّم برمز ثابت — يقرأه النموذج ويُعدِّل.code · message · retryable · nearest_matches?كل فرع بيانات. تحتفظ الحلقة بدورها.
المبدأ
تعامل مع النموذج بوصفه
عميلًا غير موثوق.
السياسة في الكود · لا حقل سياسة في أي مدخل أداة · تضييق فقط
IVالمبدأ مُطبَّقًا
تعلّمت الصناعة هذا في الإنتاج — وكيل برمجة مستقل حذف قاعدة بيانات حية في حادثة شهيرة. إجابة SQAI بنيوية لا سلوكية: السطح المكشوف للقراءة فقط بالتصميم. فئات الكتابة وغير الحتمية لا تُولَّد فيه أبدًا، ولا علامة ولا سياسة ولا مدخل نموذج يُعيد تفعيلها.
- ما يُرسله النموذج
- نية مكتوبة فقط — مواصفة بإصدار محدد. لا سلسلة SQL، لا كود، لا مقبض اتصال.
- ما لا يمكنه إرساله أبدًا
- السياسة. allowedSources وallowedFields وallowedFunctions ثابتة في إعداد createSQAI() — لا يحتوي أي مخطط مدخل أداة على حقل سياسة، فالطلب يُضيِّق السطح ولا يوسِّعه أبدًا.
- حين يطلب على أي حال
- رفض منظَّم — policy_denied_source وpolicy_denied_field وpolicy_denied_function. غير قابل للإعادة، مقروء للنموذج، والتشغيل يستمر.
Vالتوصيل
ثلاثة أسطر. محدود بالافتراضي.
حزمة واحدة تُغلِّف العميل في أدوات. تتصل المصادر كسولًا عند أول استدعاء؛ أول حساب يُهيِّئ وقت التشغيل مرة واحدة ثم يبقى دافئًا — 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"
جانب الخادم فقط — في Next.js، احتفظ بوقت تشغيل Node لا Edge.
ما يصل إلى النموذج
- maxRowsToModel
- 25الصفوف التي يراها النموذج، من كل ما نفَّذه المحرك
- maxCellsToModel
- 250ميزانية الخلايا — تُحذف صفوف كاملة للتناسب؛ لا يُعرض صف جزئي أبدًا
- maxBytesToModel
- 32,000ميزانية البايت للقيمة المرئية للنموذج
- maxExecutionRows
- 1,000الحد الأقصى الصارم الذي ينفِّذه المحرك — defaultLimit 100 حين تُغفل المواصفة الحد
الاقتطاع مُعلَن دائمًا — truncated: true، وreturned_rows < total_rows. لا صمت أبدًا. تبقى النتائج الكاملة قابلة للاسترداد في كود التطبيق عبر result_id.
VIتحليلات وكيلة
تحليل يستطيع الوكيل الدفاع عنه.
تفشل التحليلات الوكيلة بطرق معروفة: استدعاءات أدوات مشوَّهة، ونماذج تُجري حساباتها بنفسها، وأرقام معقولة لا يمكن لأحد التحقق منها. كل واحدة تُعالَج بنيويًا، لا بتحسين الموجِّه.
01استدعاءات أدوات غير صالحة
مدخل واحد بإصدار محدد، يُتحقق منه قبل أي تشغيل. النية المشوَّهة أو الغامضة تُعيد حالة مكتوبة — تستمر الحلقة بدلًا من الانهيار.
02النموذج يُجري الحساب
ليس هنا. المحرك يحسب. على مجموعة كمية من 16 سؤالًا، انتقل النموذج ذاته من 0/16 إلى 16/16 حين تولّى المحرك الحساب.
03أرقام لا يمكن التحقق منها
كل إجابة تحمل تجزئتها. أعِد تشغيل النية ذاتها على البيانات ذاتها وستتطابق التجزئة — متطابقة بايتًا في TypeScript وPython.
04تراكم الكمون
الحلقة تُضاعف الكمون. مستوى الاستعلام يعمل داخل العملية بأقل من ميلي ثانية؛ الحساب الدافئ مقاس عند 0.83 ms.
VIIأسئلة
للوكلاء — الأسئلة
كيف أمنح وكيل ذكاء اصطناعي وصولًا للقراءة فقط إلى قاعدة بيانات؟
لا تُصفِّ SQL — لا تُولِّدها. صِل المصادر بـ createSQAI() وسلِّم النموذج sqai.tools(): السطح الذي يصله 4,574 قدرة للقراءة فقط إضافةً إلى مصادرك، بلا مسار كتابة بالتصميم. لا توجد فئة كتابة لحجبها، ولا مدخل نموذج يُعيد تفعيلها.
ماذا يحدث حين يكون طلب الوكيل غامضاً؟
يُعيد queryData نتيجة needs_clarification تتضمن سؤالاً والحقول المرشحة التي رصدها. لا يخمّن عموداً قط. يُجيب النموذج على السؤال ويستدعي الأداة مجدداً — دورة واحدة إضافية في الحلقة.
هل تُطلق الأدوات استثناءات في أي حال؟
لا. كل إخفاق يُعاد كنتيجة منظّمة تحمل رمزاً ثابتاً ورسالةً وعلامةً تشير إلى إمكانية إعادة المحاولة. الغموض والرفض وحظر السياسة والأعطال العابرة — كلها تصل بوصفها بيانات يقرأها النموذج.
هل يستطيع النموذج توسيع صلاحياته بنفسه؟
لا. تعيش allowedSources وallowedFields وallowedFunctions في الكود، وتُضبط عند استدعاء createSQAI() وتُفحص قبل التنفيذ. لا يحتوي مخطط إدخال أي أداة على حقل سياسة؛ تسمية قدرة محظورة يُعيد خطأ policy_denied منظّماً.
هل يعمل مع Vercel AI SDK؟
نعم — يُوفّر @thyn-ai/sqai-ai-sdk الأدوات الثلاث كمجموعة أدوات مكتوبة بأنواع لـ generateText وstreamText، مع ai ^7.0.0 وzod ^4.0.0 كاعتماديات نظيرة، وNode 20 أو أحدث، من جانب الخادم. العميل الأساسي هو ذات SDK الذي يمكن توصيله بأي حلقة وكيل.