01
listSources
从不执行
返回每个数据源的字段、类型与行数，以及每个数字字段支持的运算。三种详情模式在数据源增多时保持 token 消耗平稳。
sum · avg · count · min · max · eq · in · gt · gte · lt · lte · is_null · is_not_null
适用于 Vercel AI SDK
受治理的数据工具 适用于 Vercel AI SDK。
sqai.tools() 向 generateText 精确添加三个只读工具。模型发现数据源、提交一份类型化计划，并由确定性引擎返回计算结果——附带可重现每个答案的哈希值。
无需 API 密钥即可开始已收录于 AI SDK Tools Registryai ^7.0.0 · zod ^4.0.0 · Node ≥ 20
II安装
一行依赖。
服务端运行，需 Node 20 或更高版本——在 Next.js 中，请在 runtime = "nodejs" 的路由处理器中使用。对等依赖为 ai ^7.0.0 与 zod ^4.0.0，即计划类型所对应的版本。无需账号、密钥或配置文件。
III快速开始
首个受治理的答案。
import { generateText, isStepCount } from 'ai';
import { createSQAI } from '@thyn-ai/sqai-ai-sdk';
const sqai = createSQAI({
sources: [{ name: 'orders', path: './orders.csv' }],
});
const { text } = await generateText({
model: 'anthropic/claude-sonnet-4.5',
tools: sqai.tools(),
stopWhen: isStepCount(12),
prompt: 'Total revenue in the east region?',
});createSQAI() 采用懒连接——首次工具调用前不读取任何数据。sqai.tools() 返回类型化的 SqaiToolSet，无需类型转换。isStepCount(12) 为模型保留了发现、规划与执行的空间。
添加数据源，而非胶水代码。
CSV、JSON、内存记录与 SQLite 在进程内运行——数据不离开您的服务器。Postgres、Snowflake、BigQuery 及其他数据源通过引擎接入。每个数据源均以相同的类型化结构呈现，下游工具无法区分 CSV 与 Snowflake。 查看所有数据源规格 →
const sqai = createSQAI({
sources: [
{ name: 'orders', path: './orders.csv' },
{ name: 'sessions', provider: 'sqlite',
path: './app.db', table: 'sessions' },
{ name: 'quotes', records: quotes },
],
});每个选项均收窄权限。
截断始终会被声明；不完整的行永不显示。模型填写的工具输入不含任何 allowed* 字段——策略在 createSQAI() 时固定，并在执行前于进程内校验。模型无法扩展其被授予的权限。 完整治理模型 →
const sqai = createSQAI({
sources,
allowedSources: ['orders'],
allowedFields: { orders: ['region', 'revenue'] },
allowedFunctions: 'all-readonly',
defaultLimit: 100,
maxRowsToModel: 25,
});选项默认值效果
sources必填工具可见的唯一数据。注册后不可变更。
allowedSources全部已注册限定计划可访问的数据源范围。
allowedFields全部字段按数据源设置列允许列表，其余字段不可见。
allowedFunctions"all-readonly"能力允许列表——只能收窄。指定范围更广的能力将抛出 unsupported_operation。
defaultLimit100计划未自行设置限制时返回的行数。
maxExecutionRows1,000单次执行读取行数的硬性上限。
maxRowsToModel25模型可见的最大行数。
maxCellsToModel250模型所能看到的单元格数量。
maxBytesToModel32,000模型所能看到的结果字节数。
IV工具箱
恰好三个工具。
发现、执行、预演——各一个工具。接口不会在你不知情时悄然扩张。
02
queryData
唯一会执行的工具
接受一个有类型的计划——经过判别联合验证，在任何操作执行前完成校验。四种结果，从不抛出异常：即便答案为否，循环也始终能获得结构化返回。
kind: "query" | "computation" · version: "1"
ok · needs_clarification · rejected · error
03
explainQuery
空运行
在不接触数据的情况下验证并解析计划。返回的 invocation_hash 是对将要执行内容的预览——而非已执行内容的哈希。
invocation_hash = preview ≠ executed
V一次运行，完整呈现
真实运行的真实数字。
generateText · 单次提示 · 三个工具步骤
用户
东部地区的总收入——以及以 10% 折现率计算的收入计划净现值？
工具
listSources()orders · 12 行 · region, revenue工具
queryData({ kind: "query", version: "1", … })sum(revenue) · region = "east"ok · 2130.50 · 5 笔订单plan_hash f87610d8afeb…工具
queryData({ kind: "computation", version: "1", … })finance.npv · rate 0.1 · values ← orders.revenue成功 · 3188.17 · 0.83 毫秒助手
东部地区收入为 2,130.50，共 5 笔订单。以 10% 折现率计算，收入计划的净现值为 3,188.17。
模型未进行任何运算。两个数字均来自确定性引擎——哈希可完整复现。
VI对比通用工具
有类型的计划不会出错。
通用 SQL 工具sqai.tools()
模型生成通用 SQL 工具原始 SQL 字符串sqai.tools()一个有类型的计划——kind 为 "query" 或 "computation"，version 为 "1"，经 zod 验证
调用格式错误通用 SQL 工具抛出异常、重试，或静默无操作sqai.tools()返回带选项的 needs_clarification——工具从不抛出异常
相同问题问两次通用 SQL 工具不同的 SQL，不同的答案sqai.tools()相同的计划，相同的哈希——可复现
写入路径通用 SQL 工具连接允许的任何操作sqai.tools()从结构上不存在——4,574 个只读能力，无模型可触达的逃逸通道
可证明性通用 SQL 工具无——仅为一个看似合理的数字sqai.tools()每个答案均附带 plan_hash 与 computation_hash
左侧的失败模式有据可查，并非凭空想象： vercel/ai #1905 · #2147 · #12020 · #6913