listSources
从不执行发现。带类型字段的已连接数据源、能力模块、函数签名——三种模式，单一输入，规格直接使用精确名称。
面向智能体的受治理数据工具
AI 智能体工具
每个答案，皆有凭证。
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错误契约
工具从不抛出异常。
异常会中止 agent 运行。因此这里没有任何抛出：歧义、拒绝与失败均以带类型的状态返回，模型可在其步骤预算内读取并纠正。
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原则的落地
业界已在生产中汲取了这一教训——一个自主编程 agent 曾因此删除了线上数据库。SQAI 的应对是结构性的，而非行为性的：暴露的接口在构造上即为只读。写入与非确定性类别从不被生成其中，任何标志、策略或模型输入均无法将其重新开启。
- 模型发送的内容
- 仅限类型化意图——版本化规格。无 SQL 字符串、无代码、无连接句柄。
- 模型永远无法发送的内容
- 策略。allowedSources、allowedFields 与 allowedFunctions 固定于 createSQAI() 配置中——任何工具输入 schema 均不含策略字段，因此请求只能收窄接口，永远无法扩展。
- 当模型仍然尝试时
- 结构化拒绝——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引擎执行的硬上限——规格省略 limit 时默认为 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常见问题
关于智能体的问题
如何为 AI 智能体提供数据库的只读访问权限？
不要过滤 SQL——也不要生成它。将数据源连接至 createSQAI()，并将 sqai.tools() 交给模型：它所能触达的接口在构造上即为 4,574 项只读能力加上你的数据源，不存在写入路径。没有需要屏蔽的写入类别，也没有任何模型输入能重新启用它。
当智能体的请求存在歧义时会发生什么？
queryData 将返回 needs_clarification，附带一个问题及其找到的候选字段。它绝不会猜测列名。模型回答该问题后再次调用——循环多走一轮。
工具会抛出异常吗？
不会。每次失败均以结构化结果返回，包含稳定的错误码、消息及可重试标志。歧义、拒绝、策略拦截与瞬时故障，全部以模型可读的数据形式呈现。
模型能自行扩大权限吗？
不能。allowedSources、allowedFields 与 allowedFunctions 均写在代码中，在 createSQAI() 时确定，并在执行前完成校验。工具的输入 schema 中不含任何策略字段；引用被拒绝的能力只会返回结构化的 policy_denied 错误。
它与 Vercel AI SDK 兼容吗？
兼容——@thyn-ai/sqai-ai-sdk 将三个工具打包为适用于 generateText 和 streamText 的类型化工具集，对等依赖为 ai ^7.0.0 与 zod ^4.0.0，需 Node 20 或更高版本，仅限服务端。底层客户端与可接入任意智能体循环的 SDK 完全一致。