Pour le Vercel AI SDK

Outils de données gouvernés pour le Vercel AI SDK.

sqai.tools() ajoute exactement trois outils en lecture seule à generateText. Le modèle découvre les sources, soumet un plan typé unique, et retourne des valeurs calculées par un moteur déterministe — avec des hachages qui rejouent chaque réponse.

Aucune clé API requise pour démarrerRéférencé dans l'AI SDK Tools Registryai ^7.0.0 · zod ^4.0.0 · Node ≥ 20

IIInstallation

Une seule dépendance.

Côté serveur, Node 20 ou supérieur — dans Next.js, exécutez-le dans un gestionnaire de route avec runtime = \"nodejs\". Les pairs sont ai ^7.0.0 et zod ^4.0.0, les versions contre lesquelles les plans sont typés. Aucun compte, aucune clé, aucun fichier de configuration.

IIIDémarrage rapide

Première réponse gouvernée.

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() se connecte en différé — rien n'est lu avant le premier appel d'outil. sqai.tools() retourne un SqaiToolSet typé, sans conversion nécessaire. isStepCount(12) laisse au modèle la latitude de découvrir, planifier et exécuter.

Ajoutez des sources, pas du code de liaison.

CSV, JSON, enregistrements en mémoire et SQLite s'exécutent en cours de processus — rien ne quitte votre serveur. Postgres, Snowflake, BigQuery et les autres se connectent via le moteur. Chaque source adopte la même forme typée, si bien qu'en aval les outils ne distinguent pas un CSV de Snowflake. Chaque source, spécifiée →

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

Chaque option restreint.

La troncature est toujours déclarée ; les lignes partielles ne sont jamais affichées. L'entrée outil que remplit le modèle ne comporte aucun champ allowed* — la politique est fixée à la création de createSQAI() et vérifiée en cours de processus, avant exécution. Un modèle ne peut pas élargir ce qui lui a été accordé. Le modèle de gouvernance complet →

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

Les seules données visibles par les outils. Enregistrées une fois — les sources sont immuables.

allowedSourcestoutes enregistrées

Restreint les sources qu'un plan peut consulter.

allowedFieldstous les champs

Liste d'autorisation de colonnes par source. Tout le reste est invisible.

allowedFunctions\"all-readonly\"

Liste d'autorisation de capacités — restrictive uniquement. Nommer quoi que ce soit de plus large lève unsupported_operation.

defaultLimit100

Lignes retournées lorsqu'un plan ne définit pas sa propre limite.

maxExecutionRows1 000

Plafond absolu de lignes lues par une seule exécution.

maxRowsToModel25

Lignes jamais présentées au modèle.

maxCellsToModel250

Cellules jamais montrées au modèle.

maxBytesToModel32 000

Octets de résultat jamais montrés au modèle.

IVLa boîte à outils

Exactement trois outils.

Découverte, exécution, répétition — un outil chacun. La surface n'évolue jamais dans votre dos.

01

listSources

n'exécute jamais

Retourne les champs, types et nombres de lignes de chaque source, ainsi que les opérations prises en charge par chaque champ numérique. Trois modes de détail maintiennent le coût en tokens constant à mesure que les sources se multiplient.

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

02

queryData

le seul qui exécute

Prend un plan typé — une union discriminée, validée avant toute exécution. Quatre résultats possibles, jamais d'exception : la boucle reçoit toujours une structure en retour, même quand la réponse est non.

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

03

explainQuery

simulation

Valide et résout un plan sans toucher aux données. L'invocation_hash retourné est un aperçu de ce qui s'exécuterait — non le hash de quelque chose qui a déjà tourné.

invocation_hash = preview ≠ executed

VUne exécution, imprimée

Des chiffres réels, d'une vraie exécution.

generateText · une invite · trois étapes d'outil

utilisateur

Chiffre d'affaires total dans la région est — et la VAN de notre calendrier de revenus à un taux de 10 % ?

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

Le chiffre d'affaires de la région est s'élève à 2 130,50 sur 5 commandes. À un taux de 10 %, la VAN du calendrier de revenus est de 3 188,17.

Le modèle n'a effectué aucun calcul. Les deux chiffres proviennent du moteur déterministe — et le hash permet de les rejouer.

VIFace aux outils génériques

Les plans typés n'ont pas de mauvais jours.

un outil SQL génériquesqai.tools()
le modèle écritun outil SQL génériqueune chaîne SQL brutesqai.tools()un plan typé — kind « query » ou « computation », version « 1 », validé par zod
un appel malforméun outil SQL génériquelève une exception, réessaie, ou échoue silencieusementsqai.tools()retourne needs_clarification avec des choix — les outils ne lèvent jamais d'exception
la même question deux foisun outil SQL génériqueSQL différent, réponses différentessqai.tools()le même plan, le même hash — rejouable
le chemin d'écritureun outil SQL génériquetout ce que la connexion autorisesqai.tools()aucun par construction — 4 574 capacités en lecture seule, aucune échappatoire accessible au modèle
preuveun outil SQL génériqueaucune — un chiffre plausiblesqai.tools()plan_hash et computation_hash sur chaque réponse

Les modes d'échec à gauche sont documentés, non imaginés : vercel/ai #1905 · #2147 · #12020 · #6913

Concevoir la boucle agent complète →

Livrez la boîte à outils.

Aucune clé API. Aucun compte. Le premier appel d'outil fonctionne directement.

Lire la documentation →Le package sur npm →L'entrée dans le Tools Registry →

Référencé dans l'AI SDK Tools Registry · ai ^7.0.0 · zod ^4.0.0 · Node ≥ 20 · côté serveur