এজেন্টের জন্য — নিয়ন্ত্রিত ডেটা টুল

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

কখনো কার্যকর হয় না

আবিষ্কার। টাইপড ফিল্ড সহ সংযুক্ত সোর্স, ক্যাপাবিলিটি মডিউল, ফাংশন সিগনেচার — একটি ইনপুট থেকে তিনটি মোড, যাতে স্পেক সঠিক নাম ব্যবহার করে।

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। চারটি আউটকাম, সর্বদা টাইপড, কখনো throw নয়।

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

explainQuery

dry run — কার্যকর হয় না

কোনো কিছু চালানো ছাড়াই একটি intent রিজলভ ও যাচাই করে। মডেল এটি ব্যবহার করে clarification ডিবাগ করতে; আপনি ব্যবহার করেন পরিকল্পনা প্রিভিউ করতে।

preview invocation_hash ≠ executed hash

সেটটি সরাসরি generateText বা streamText-এ যায় — টাইপড, কোনো cast ছাড়াই assignable। Vercel AI SDK সেটআপ →

IIIএরর চুক্তি

Tools কখনো throw করে না।

একটি exception এজেন্ট রান বন্ধ করে দেয়। তাই এখানে কিছুই throw করে না: অস্পষ্টতা, প্রত্যাখ্যান, এবং ব্যর্থতা টাইপড স্ট্যাটাস হিসেবে ফেরে — মডেল সেগুলো পড়তে এবং তার স্টেপ বাজেটের মধ্যে সংশোধন করতে পারে।

retryable ক্ষণস্থায়িগুলো চিহ্নিত করে — network_error · timeout · rate_limited · service_unavailable

queryData — চারটি আউটকাম

okফলাফল: rows বা value, provenance হ্যাশ, ঘোষিত truncation।plan_hash · invocation_hash · computation_hash · truncated
needs_clarificationintent অস্পষ্ট ছিল। একটি প্রশ্ন এবং প্রার্থীরা — কখনো অনুমান নয়।question · candidates · explanation
rejectedরিজলভার intent প্রত্যাখ্যান করেছে। কিছুই কার্যকর হয়নি।rejection_reason · candidates · explanation
errorএকটি স্থিতিশীল কোড সহ কাঠামোগত ব্যর্থতা — মডেল পড়ে এবং সমন্বয় করে।code · message · retryable · nearest_matches?

প্রতিটি শাখা ডেটা। লুপ তার পালা রাখে।

নীতিমালা

মডেলকে গণ্য করুন
অবিশ্বস্ত ক্লায়েন্ট হিসেবে।

কোডে নীতি · কোনো tool ইনপুটে policy ফিল্ড নেই · শুধু সংকীর্ণ

IVনীতি, প্রয়োগে

শিল্প এটি প্রোডাকশনে শিখেছে — একটি স্বায়ত্তশাসিত কোডিং এজেন্ট বিখ্যাতভাবে একটি লাইভ ডেটাবেস মুছে দিয়েছিল। SQAI-এর উত্তর কাঠামোগত, আচরণগত নয়: উন্মুক্ত পৃষ্ঠটি নির্মাণগতভাবে read-only। Write এবং non-deterministic ক্যাটাগরি কখনো এতে তৈরি হয় না, এবং কোনো ফ্ল্যাগ, নীতি বা মডেল ইনপুট সেগুলো পুনরায় চালু করে না।

মডেল যা পাঠায়
শুধু টাইপড intent — একটি ভার্সনড স্পেক। কোনো SQL স্ট্রিং নয়, কোনো কোড নয়, কোনো connection handle নয়।
যা কখনো পাঠাতে পারে না
নীতি। allowedSources, allowedFields এবং allowedFunctions createSQAI() কনফিগে স্থির — কোনো tool ইনপুট স্কিমায় policy ফিল্ড নেই, তাই একটি অনুরোধ পৃষ্ঠ সংকীর্ণ করতে পারে কিন্তু কখনো প্রসারিত করতে পারে না।
যখন তবুও চায়
একটি কাঠামোগত প্রত্যাখ্যান — policy_denied_source, policy_denied_field, policy_denied_function। Non-retryable, মডেল-পাঠযোগ্য, এবং রান অব্যাহত থাকে।
সম্পূর্ণ নীতি মডেল →

Vসংযোগ

তিন লাইনে। ডিফল্টে সীমাবদ্ধ।

একটি প্যাকেজ ক্লায়েন্টকে tools-এ মোড়ে। সোর্সগুলো প্রথম কলে lazily সংযুক্ত হয়; প্রথম computation একবার runtime প্রভিশন করে, তারপর 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 দেখে
maxCellsToModel
250cell বাজেট — ফিট করতে পুরো rows বাদ দেওয়া হয়; আংশিক row কখনো দেখানো হয় না
maxBytesToModel
32,000মডেল-দৃশ্যমান মানের জন্য byte বাজেট
maxExecutionRows
1,000ইঞ্জিন যা কার্যকর করে তার hard cap — স্পেক limit বাদ দিলে defaultLimit 100

Truncation সর্বদা ঘোষিত — truncated: true, returned_rows < total_rows। কখনো নীরব নয়। সম্পূর্ণ ফলাফল result_id দিয়ে অ্যাপ্লিকেশন কোডে পুনরুদ্ধারযোগ্য।

VIএজেন্টিক অ্যানালিটিক্স

বিশ্লেষণ যা এজেন্ট সমর্থন করতে পারে।

এজেন্টিক অ্যানালিটিক্স পরিচিত উপায়ে ব্যর্থ হয়: ত্রুটিপূর্ণ tool call, মডেলের নিজস্ব গণনা, যাচাইযোগ্য নয় এমন সংখ্যা। প্রতিটির উত্তর কাঠামোগতভাবে দেওয়া হয়, ভালো prompt দিয়ে নয়।

01অবৈধ tool call

একটি ভার্সনড ইনপুট, কিছু চালানোর আগে যাচাই করা হয়। ত্রুটিপূর্ণ বা অস্পষ্ট intent একটি টাইপড স্ট্যাটাস ফেরায় — লুপ crash-এর বদলে চলতে থাকে।

02মডেল গণনা করে

এখানে নয়। ইঞ্জিন গণনা করে। 16টি পরিমাণগত প্রশ্নের সেটে, একই মডেল 0/16 থেকে 16/16-তে গেছে যখন ইঞ্জিন গণনা করেছে।

03যাচাইযোগ্য নয় এমন সংখ্যা

প্রতিটি উত্তর তার হ্যাশ বহন করে। একই ডেটার বিপরীতে একই intent পুনরায় চালান এবং হ্যাশ মিলবে — TypeScript এবং Python-এ byte-identical।

04লেটেন্সি স্তূপ

একটি লুপ লেটেন্সি গুণ করে। query plane in-process-এ sub-millisecond-এ চলে; warm compute পরিমাপ করা 0.83 ms।

আরো পড়ুন

Vercel AI SDK টুলস →নীতি ও গভর্ন্যান্স →এটি কীভাবে কাজ করে →

VIIপ্রশ্নাবলি

এজেন্টদের জন্য — প্রশ্নগুলো

আমি কীভাবে একটি AI এজেন্টকে ডেটাবেসে read-only অ্যাক্সেস দেব?

SQL ফিল্টার করবেন না — তৈরিই করবেন না। createSQAI()-এ সোর্স সংযুক্ত করুন এবং মডেলকে sqai.tools() দিন: এটি যে পৃষ্ঠে পৌঁছায় তা 4,574টি read-only ক্যাপাবিলিটি এবং আপনার সোর্স — নির্মাণগতভাবে কোনো write পথ নেই। ব্লক করার মতো কোনো write ক্যাটাগরি নেই, এবং কোনো মডেল ইনপুট নেই যা সেটি পুনরায় সক্রিয় করে।

এজেন্টের অনুরোধ অস্পষ্ট হলে কী হয়?

queryData তখন needs_clarification ফেরত দেয় — একটি প্রশ্ন এবং যে candidate ফিল্ডগুলো পাওয়া গেছে তা সহ। এটি কখনো কোনো কলাম অনুমান করে না। মডেল প্রশ্নের উত্তর দিয়ে আবার কল করে — লুপের আরেকটি পালা।

টুলগুলো কি কখনো exception ছুড়ে দেয়?

না। প্রতিটি ব্যর্থতা একটি কাঠামোবদ্ধ ফলাফল হিসেবে আসে — স্থির কোড, বার্তা এবং retryable ফ্ল্যাগ সহ। অস্পষ্টতা, প্রত্যাখ্যান, নীতি-অস্বীকৃতি এবং ক্ষণস্থায়ী ত্রুটি — সবই মডেলের পাঠযোগ্য ডেটা হিসেবে ফেরত আসে।

মডেল কি নিজের অনুমতি বাড়াতে পারে?

না। allowedSources, allowedFields এবং allowedFunctions কোডে থাকে, createSQAI() কলের সময় নির্ধারিত হয় এবং execution-এর আগে যাচাই করা হয়। কোনো টুলের input schema-তে policy ফিল্ড নেই; অস্বীকৃত কোনো capability নাম দিলে কাঠামোবদ্ধ policy_denied ত্রুটি ফেরত আসে।

এটি কি Vercel AI SDK-এর সাথে কাজ করে?

হ্যাঁ — @thyn-ai/sqai-ai-sdk তিনটি টুল generateText ও streamText-এর জন্য typed tool set হিসেবে সরবরাহ করে, peer হিসেবে ai ^7.0.0 ও zod ^4.0.0 সহ, Node 20 বা তার পরবর্তী সংস্করণে, server-side। অন্তর্নিহিত client সেই একই SDK যা যেকোনো এজেন্ট লুপে যুক্ত করা যায়।

লুপে যুক্ত করুন।

Vercel AI SDK টুল সেট আপ করুন →
ডকুমেন্টেশন পড়ুন →