Per il Vercel AI SDK

Strumenti dati governati per il Vercel AI SDK.

sqai.tools() aggiunge esattamente tre strumenti di sola lettura a generateText. Il modello individua le sorgenti, invia un piano tipizzato e restituisce valori calcolati da un motore deterministico — con hash che riproducono ogni risposta.

Nessuna API key richiesta per iniziarePresente nell'AI SDK Tools Registryai ^7.0.0 · zod ^4.0.0 · Node ≥ 20

IIInstallazione

Una sola dipendenza.

Lato server, Node 20 o superiore — in Next.js, eseguilo in un route handler con runtime = "nodejs". Le peer dependency sono ai ^7.0.0 e zod ^4.0.0, le versioni contro cui i piani sono tipizzati. Nessun account, nessuna chiave, nessun file di configurazione.

IIIAvvio rapido

Prima risposta governata.

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() si connette in modo lazy — nulla viene letto fino alla prima chiamata allo strumento. sqai.tools() restituisce un SqaiToolSet tipizzato, senza cast. isStepCount(12) lascia al modello lo spazio per scoprire, pianificare ed eseguire.

Aggiungi sorgenti, non codice di raccordo.

CSV, JSON, record in memoria e SQLite girano in-process — nulla lascia il tuo server. Postgres, Snowflake, BigQuery e gli altri si collegano tramite il motore. Ogni sorgente assume la stessa forma tipizzata, così a valle gli strumenti non distinguono un CSV da Snowflake. Ogni sorgente, specificata →

const sqai = createSQAI({
  sources: [
    { name: 'orders', path: './orders.csv' },
    { name: 'sessions', provider: 'sqlite',
      path: './app.db', table: 'sessions' },
    { name: 'quotes', records: quotes },
  ],
});

Ogni opzione restringe.

Il troncamento è sempre dichiarato; le righe parziali non vengono mai mostrate. L'input dello strumento che il modello compila non porta alcun campo allowed* — la policy è fissata al momento di createSQAI() e verificata in-process, prima dell'esecuzione. Un modello non può ampliare ciò che gli è stato assegnato. Il modello di governance completo →

const sqai = createSQAI({
  sources,
  allowedSources: ['orders'],
  allowedFields: { orders: ['region', 'revenue'] },
  allowedFunctions: 'all-readonly',
  defaultLimit: 100,
  maxRowsToModel: 25,
});
opzionepredefinitoeffetto
sourcesobbligatorio

Gli unici dati visibili agli strumenti. Registrati una volta — le sorgenti sono immutabili.

allowedSourcestutte le registrate

Restringe le sorgenti che un piano può utilizzare.

allowedFieldstutti i campi

Allow-list di colonne per sorgente. Tutto il resto è invisibile.

allowedFunctions"all-readonly"

Allow-list di funzionalità — solo restrittiva. Nominare qualcosa di più ampio genera unsupported_operation.

defaultLimit100

Righe restituite quando un piano non imposta un proprio limite.

maxExecutionRows1.000

Limite massimo di righe lette da una singola esecuzione.

maxRowsToModel25

Righe mostrate al modello in ogni caso.

maxCellsToModel250

Celle mai mostrate al modello.

maxBytesToModel32.000

Byte di risultato mai mostrati al modello.

IVGli strumenti

Esattamente tre strumenti.

Discovery, esecuzione, prova — uno strumento ciascuno. La superficie non cresce mai alle tue spalle.

01

listSources

non esegue mai

Restituisce campi, tipi e conteggi di righe di ogni sorgente, più le operazioni supportate da ogni campo numerico. Tre modalità di dettaglio mantengono il costo in token costante al crescere delle sorgenti.

sum · avg · count · min · max · eq · in · gt · gte · lt · lte · is_null · is_not_null

02

queryData

l'unico che esegue

Accetta un piano tipizzato — una discriminated union, validata prima di qualsiasi esecuzione. Quattro esiti, mai un'eccezione: il loop riceve sempre una struttura, anche quando la risposta è no.

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

03

explainQuery

dry run

Valida e risolve un piano senza toccare i dati. L'invocation_hash restituito è un'anteprima di ciò che verrebbe eseguito — non l'hash di qualcosa che è già stato eseguito.

invocation_hash = preview ≠ executed

VUn'esecuzione, stampata

Numeri reali da un'esecuzione reale.

generateText · un prompt · tre passi di strumento

utente

Fatturato totale nella regione est — e il VAN del piano di ricavi a un tasso del 10%?

strumento
listSources()orders · 12 righe · region, revenue
strumento
queryData({ kind: "query", version: "1", … })sum(revenue) · region = "east"ok · 2130,50 · 5 ordiniplan_hash f87610d8afeb…
strumento
queryData({ kind: "computation", version: "1", … })finance.npv · rate 0.1 · values ← orders.revenueok · 3188,17 · 0,83 ms
assistente

Il fatturato della regione est è 2.130,50 su 5 ordini. A un tasso del 10%, il VAN del piano di ricavi è 3.188,17.

Il modello non ha eseguito alcun calcolo. Entrambi i numeri provengono dal motore deterministico — e l'hash li rende riproducibili.

VIRispetto agli strumenti generici

I piani tipizzati non hanno giorni no.

uno strumento SQL genericosqai.tools()
il modello scriveuno strumento SQL genericouna stringa SQL grezzasqai.tools()un piano tipizzato — kind «query» o «computation», version «1», validato con zod
una chiamata malformatauno strumento SQL genericolancia un'eccezione, riprova, o non fa nulla in silenziosqai.tools()restituisce needs_clarification con le opzioni — gli strumenti non lanciano mai eccezioni
la stessa domanda due volteuno strumento SQL genericoSQL diverso, risposte diversesqai.tools()lo stesso piano, lo stesso hash — riproducibile
il percorso di scritturauno strumento SQL genericotutto ciò che la connessione consentesqai.tools()nessuno per costruzione — 4.574 capacità in sola lettura, nessuna via di fuga raggiungibile dal modello
provauno strumento SQL genericonessuna — un numero plausibilesqai.tools()plan_hash e computation_hash su ogni risposta

I modi di fallimento sulla sinistra sono documentati, non immaginati: vercel/ai #1905 · #2147 · #12020 · #6913

Progetta il loop agente completo →

Distribuisci gli strumenti.

Nessuna chiave API. Nessun account. La prima chiamata allo strumento funziona subito.

Leggi la documentazione →Il pacchetto su npm →La guida completa all'installazione →

Incluso nell'AI SDK Tools Registry · ai ^7.0.0 · zod ^4.0.0 · Node ≥ 20 · server-side