Para o Vercel AI SDK
sqai.tools() adiciona exatamente três ferramentas de somente leitura ao generateText. O modelo descobre fontes, envia um plano tipado e retorna números calculados por um motor determinístico — com hashes que reproduzem cada resposta.
IIInstalação
Lado do servidor, Node 20 ou superior — no Next.js, execute em um route handler com runtime = "nodejs". As dependências são ai ^7.0.0 e zod ^4.0.0, as versões contra as quais os planos são tipados. Sem conta, sem chave, sem arquivo de configuração.
IIIInício rápido
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() conecta de forma lazy — nada é lido até a primeira chamada de ferramenta. sqai.tools() retorna um SqaiToolSet tipado, sem necessidade de cast. isStepCount(12) dá ao modelo espaço para descobrir, planejar e executar.
CSV, JSON, registros em memória e SQLite rodam em processo — nada sai do seu servidor. Postgres, Snowflake, BigQuery e os demais se conectam pelo motor. Cada fonte assume o mesmo formato tipado, de modo que as ferramentas não distinguem um CSV de Snowflake. Cada fonte, especificada →
const sqai = createSQAI({
sources: [
{ name: 'orders', path: './orders.csv' },
{ name: 'sessions', provider: 'sqlite',
path: './app.db', table: 'sessions' },
{ name: 'quotes', records: quotes },
],
});O truncamento é sempre declarado; linhas parciais nunca são exibidas. O input da ferramenta preenchido pelo modelo não carrega nenhum campo allowed* — a política é fixada em createSQAI() e verificada internamente, antes da execução. O modelo não pode ampliar o que lhe foi concedido. O modelo de governança completo →
const sqai = createSQAI({
sources,
allowedSources: ['orders'],
allowedFields: { orders: ['region', 'revenue'] },
allowedFunctions: 'all-readonly',
defaultLimit: 100,
maxRowsToModel: 25,
});sourcesobrigatórioOs únicos dados visíveis às ferramentas. Registradas uma vez — as fontes são imutáveis.
allowedSourcestodas registradasRestringe quais fontes qualquer plano pode acessar.
allowedFieldstodos os camposLista de colunas permitidas por fonte. Todo o restante é invisível.
allowedFunctions"all-readonly"Lista de capacidades permitidas — apenas restritiva. Nomear algo mais amplo lança unsupported_operation.
defaultLimit100Linhas retornadas quando um plano não define seu próprio limite.
maxExecutionRows1.000Limite máximo de linhas que uma única execução pode ler.
maxRowsToModel25Linhas que o modelo chega a visualizar.
maxCellsToModel250Células exibidas ao modelo.
maxBytesToModel32.000Bytes do resultado exibidos ao modelo.
IVFerramentas
Descoberta, execução, ensaio — uma ferramenta cada. A superfície nunca cresce às suas costas.
01
nunca executa
Retorna campos, tipos e contagens de linhas de cada fonte, além das operações suportadas por cada campo numérico. Três modos de detalhe mantêm o custo de tokens estável à medida que as fontes se multiplicam.
sum · avg · count · min · max · eq · in · gt · gte · lt · lte · is_null · is_not_null
02
a única que executa
Recebe um plano tipado — uma union discriminada, validada antes de qualquer execução. Quatro resultados possíveis, nunca uma exceção: o loop sempre recebe estrutura de volta, mesmo quando a resposta é não.
kind: "query" | "computation" · version: "1"
ok · needs_clarification · rejected · error
03
dry run
Valida e resolve um plano sem tocar nos dados. O invocation_hash retornado é uma prévia do que seria executado — não o hash de algo que já rodou.
invocation_hash = preview ≠ executed
VUma execução, impressa
generateText · um prompt · três etapas de ferramenta
Receita total na região leste — e o VPL do nosso cronograma de receitas a uma taxa de 10%?
listSources()orders · 12 linhas · region, revenuequeryData({ kind: "query", version: "1", … })sum(revenue) · region = "east"ok · 2130,50 · 5 pedidosplan_hash f87610d8afeb…queryData({ kind: "computation", version: "1", … })finance.npv · rate 0.1 · values ← orders.revenueok · 3188,17 · 0,83 msA receita da região leste é 2.130,50 em 5 pedidos. A uma taxa de 10%, o VPL do cronograma de receitas é 3.188,17.
O modelo não fez nenhum cálculo. Ambos os números vieram do motor determinístico — e o hash os reproduz.
VIVersus ferramentas genéricas
Os modos de falha à esquerda são documentados, não imaginados: vercel/ai #1905 · #2147 · #12020 · #6913
Sem chave de API. Sem conta. A primeira chamada de ferramenta simplesmente funciona.
Listado no AI SDK Tools Registry · ai ^7.0.0 · zod ^4.0.0 · Node ≥ 20 · server-side