listSources
nunca executaDescoberta. Fontes conectadas com campos tipados, módulos de capacidade, assinaturas de função — três modos a partir de uma entrada, para que as specs usem nomes exatos.
Para agentes — a ferramenta de dados governada
Ferramentas para agentes de IA
que respondem com prova.
O SQAI oferece a um modelo com chamada de ferramentas acesso somente leitura a dados estruturados por meio de três ferramentas governadas. O modelo expressa intenção tipada. Um contrato e sua política a verificam. Um motor determinístico a executa. Cada resposta retorna com um hash que a reproduz.
IUma volta do loop
a requisição entra
“Qual região teve a maior receita total?”qualquer modelo com chamada de ferramentasO modelo
Planeja as etapas. Expressa intenção. Nunca toca nos dados.
chamada de ferramenta — intenção tipada, nunca SQL
{ version:"1", kind:"query", spec:{ metric:"revenue", aggregation:"sum", group_by:"region", source:"sales" } }a ferramenta governadaSQAI
contractcontrato de capacidade fixado por hashpolicysuas listas de permissão, verificadas antes da execuçãoengineexecução determinística e somente leitura
status tipado — nunca uma exceção
status: ok · needs_clarification · rejected · errora resposta sai — com seu hash
east — 2,130.50 · plan_hash f87610d8afeb…okSai do loop. As linhas ou o valor — e o hash que os reproduz.
needs_clarification ↺Retorna ao loop. Uma pergunta e os candidatos encontrados — o modelo refina a spec e chama novamente. Nunca adivinha uma coluna.
rejeição e erro percorrem o mesmo caminho de retorno — resultados tipados que o modelo pode ler, não exceções que abortam a execução.
IIAs ferramentas
Três ferramentas. Uma executa.
sqai.tools() retorna exatamente três ferramentas — uma superfície deliberadamente pequena. Descoberta e simulações nunca executam; a execução ocorre em exatamente um lugar.
nunca executa
queryData
o que executaUma entrada versionada — uma union discriminada em kind: uma query ou uma computação. Quatro resultados, sempre tipados, sem exceções.
explainQuery
simulação — nunca executaResolve e valida uma intenção sem executá-la. O modelo usa para depurar clarificações; você usa para visualizar um plano.
O conjunto entra diretamente em generateText ou streamText — tipado, atribuível sem cast. Configuração do Vercel AI SDK →
IIIO contrato de erros
Tools nunca lançam exceções.
Uma exceção aborta uma execução de agente. Por isso nada aqui lança exceções: ambiguidade, recusa e falha retornam como status tipados que o modelo pode ler — e corrigir — dentro do seu orçamento de passos.
retryable marca os transitórios — network_error · timeout · rate_limited · service_unavailable
queryData — os quatro resultados
okO resultado: linhas ou valor, hashes de proveniência, truncamento declarado.plan_hash · invocation_hash · computation_hash · truncatedneeds_clarificationA intenção era ambígua. Uma pergunta com os candidatos — nunca uma suposição.question · candidates · explanationrejectedO resolver recusou a intenção. Nada foi executado.rejection_reason · candidates · explanationerrorUma falha estruturada com código estável — o modelo lê e ajusta.code · message · retryable · nearest_matches?Cada ramificação é dado. O loop mantém seu turno.
O princípio
Trate o modelo como
um cliente não confiável.
política em código · nenhum campo de política em qualquer entrada de tool · somente restrição
IVO princípio, aplicado
A indústria aprendeu isso em produção — um agente de codificação autônomo famosamente deletou um banco de dados em produção. A resposta do SQAI é estrutural, não comportamental: a superfície exposta é somente leitura por construção. Categorias de escrita e não determinísticas nunca são geradas nela, e nenhum flag, política ou entrada do modelo as reativa.
- O que o modelo envia
- Apenas intenção tipada — uma spec versionada. Sem string SQL, sem código, sem handle de conexão.
- O que ele nunca pode enviar
- Política. allowedSources, allowedFields e allowedFunctions são fixos na configuração de createSQAI() — nenhum schema de entrada de tool contém um campo de política, então uma requisição pode restringir a superfície, mas nunca ampliá-la.
- Quando ele pede assim mesmo
- Uma negação estruturada — policy_denied_source, policy_denied_field, policy_denied_function. Não retentável, legível pelo modelo, e a execução continua.
VA conexão
Três linhas. Limitado por padrão.
Um pacote encapsula o cliente em tools. As fontes conectam de forma lazy na primeira chamada; a primeira computação provisiona o runtime uma vez e permanece aquecido — 0,83 ms medidos.
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"
Somente server-side — no Next.js, mantenha o runtime Node, não Edge.
O que chega ao modelo
- maxRowsToModel
- 25linhas que o modelo vê, do total executado pelo engine
- maxCellsToModel
- 250orçamento de células — linhas inteiras são descartadas para caber; uma linha parcial nunca é exibida
- maxBytesToModel
- 32,000orçamento em bytes para o valor visível ao modelo
- maxExecutionRows
- 1,000limite máximo executado pelo engine — defaultLimit 100 quando uma spec omite o limit
O truncamento é sempre declarado — truncated: true, returned_rows < total_rows. Nunca silencioso. Os resultados completos permanecem recuperáveis no código da aplicação via result_id.
VIAnalytics agêntico
Análise que um agente pode defender.
O analytics agêntico falha de formas conhecidas: chamadas de tool malformadas, modelos fazendo sua própria aritmética, números plausíveis que ninguém consegue verificar. Cada uma é respondida estruturalmente, não com um prompt melhor.
01Chamadas de tool inválidas
Uma entrada versionada, validada antes de qualquer execução. Intenção malformada ou ambígua retorna um status tipado — o loop continua em vez de travar.
02O modelo faz as contas
Não aqui. O engine computa. Em um conjunto quantitativo de 16 perguntas, o mesmo modelo passou de 0/16 para 16/16 quando o engine assumiu os cálculos.
03Números inverificáveis
Cada resposta carrega seu hash. Reproduza a mesma intenção contra os mesmos dados e o hash bate — byte a byte idêntico em TypeScript e Python.
04Acúmulo de latência
Um loop multiplica a latência. O plano de queries roda em processo em submilissegundo; computação aquecida medida em 0,83 ms.
VIIPerguntas
Para agentes — as perguntas
Como concedo a um agente de IA acesso somente leitura a um banco de dados?
Não filtre SQL — não o gere. Conecte fontes ao createSQAI() e entregue ao modelo sqai.tools(): a superfície que ele alcança são 4.574 capacidades somente leitura mais suas fontes, sem caminho de escrita por construção. Não há categoria de escrita a bloquear, nem entrada do modelo que a reative.
O que acontece quando a solicitação do agente é ambígua?
queryData retorna needs_clarification com uma pergunta e os campos candidatos encontrados. Nunca infere uma coluna. O modelo responde à pergunta e chama novamente — mais uma volta no loop.
As ferramentas lançam exceções?
Não. Toda falha é um resultado estruturado com um código estável, uma mensagem e um indicador de nova tentativa. Ambiguidade, recusa, negação de política e falhas transitórias retornam como dados que o modelo pode ler.
O modelo pode ampliar suas próprias permissões?
Não. allowedSources, allowedFields e allowedFunctions vivem no código, definidos no momento de createSQAI() e verificados antes da execução. Nenhum esquema de entrada de ferramenta contém um campo de política; nomear uma capacidade negada retorna um erro estruturado policy_denied.
Funciona com o Vercel AI SDK?
Sim — @thyn-ai/sqai-ai-sdk entrega as três ferramentas como um conjunto tipado para generateText e streamText, com ai ^7.0.0 e zod ^4.0.0 como peers, Node 20 ou superior, lado servidor. O cliente subjacente é o mesmo SDK que pode ser integrado a qualquer loop de agente.