Para el Vercel AI SDK
sqai.tools() añade exactamente tres herramientas de solo lectura a generateText. El modelo descubre fuentes, envía un plan tipado único y devuelve cifras calculadas por un motor determinista — con hashes que reproducen cada respuesta.
IIInstalación
En el servidor, Node 20 o superior — en Next.js, ejecútelo en un route handler con runtime = \"nodejs\". Las dependencias son ai ^7.0.0 y zod ^4.0.0, las versiones contra las que se tipan los planes. Sin cuenta, sin clave, sin archivo de configuración.
IIIInicio 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 diferida — nada se lee hasta la primera llamada a una herramienta. sqai.tools() devuelve un SqaiToolSet tipado, sin necesidad de conversión. isStepCount(12) da al modelo margen para descubrir, planificar y ejecutar.
CSV, JSON, registros en memoria y SQLite se ejecutan en proceso — nada sale de su servidor. Postgres, Snowflake, BigQuery y el resto se conectan a través del motor. Cada fuente adopta la misma forma tipada, por lo que las herramientas no distinguen un CSV de Snowflake. Cada fuente, especificada →
const sqai = createSQAI({
sources: [
{ name: 'orders', path: './orders.csv' },
{ name: 'sessions', provider: 'sqlite',
path: './app.db', table: 'sessions' },
{ name: 'quotes', records: quotes },
],
});El truncamiento siempre se declara; nunca se muestran filas parciales. La entrada de herramienta que rellena el modelo no lleva ningún campo allowed* — la política se fija en createSQAI() y se verifica en proceso, antes de la ejecución. Un modelo no puede ampliar lo que se le entregó. El modelo de gobernanza completo →
const sqai = createSQAI({
sources,
allowedSources: ['orders'],
allowedFields: { orders: ['region', 'revenue'] },
allowedFunctions: 'all-readonly',
defaultLimit: 100,
maxRowsToModel: 25,
});sourcesobligatorioLos únicos datos visibles para las herramientas. Se registran una vez — las fuentes son inmutables.
allowedSourcestodas las registradasRestringe qué fuentes puede consultar cualquier plan.
allowedFieldstodos los camposLista de columnas permitidas por fuente. Todo lo demás es invisible.
allowedFunctions"all-readonly"Lista de capacidades permitidas — solo restrictiva. Nombrar algo más amplio lanza unsupported_operation.
defaultLimit100Filas devueltas cuando un plan no establece su propio límite.
maxExecutionRows1.000Límite máximo de filas que lee una sola ejecución.
maxRowsToModel25Filas que el modelo llega a ver en cualquier caso.
maxCellsToModel250Celdas que el modelo puede ver en total.
maxBytesToModel32.000Bytes de resultado que el modelo puede ver en total.
IVLas herramientas
Descubrimiento, ejecución, ensayo — una herramienta para cada uno. La superficie nunca crece a tus espaldas.
01
nunca ejecuta
Devuelve los campos, tipos y recuentos de filas de cada fuente, más las operaciones que admite cada campo numérico. Tres modos de detalle mantienen el coste en tokens estable a medida que las fuentes se multiplican.
sum · avg · count · min · max · eq · in · gt · gte · lt · lte · is_null · is_not_null
02
la única que ejecuta
Recibe un plan tipado — una unión discriminada, validada antes de que nada se ejecute. Cuatro resultados posibles, nunca una excepción: el bucle siempre recibe estructura de vuelta, incluso cuando la respuesta es no.
kind: "query" | "computation" · version: "1"
ok · needs_clarification · rejected · error
03
ejecución en seco
Valida y resuelve un plan sin tocar los datos. El invocation_hash que devuelve es una vista previa de lo que se ejecutaría — no el hash de algo que ya se ejecutó.
invocation_hash = preview ≠ executed
VUna ejecución, impresa
generateText · un prompt · tres pasos de herramienta
Ingresos totales en la región este — ¿y el VPN de nuestro calendario de ingresos a una tasa del 10%?
listSources()orders · 12 filas · 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 msLos ingresos de la región este son 2.130,50 en 5 pedidos. A una tasa del 10%, el VPN del calendario de ingresos es 3.188,17.
El modelo no realizó ningún cálculo. Ambos números provienen del motor determinista — y el hash los reproduce.
VIFrente a herramientas genéricas
Los modos de fallo de la izquierda están documentados, no imaginados: vercel/ai #1905 · #2147 · #12020 · #6913
Sin clave API. Sin cuenta. La primera llamada a la herramienta funciona sin más.
Incluido en el AI SDK Tools Registry · ai ^7.0.0 · zod ^4.0.0 · Node ≥ 20 · server-side