Для Vercel AI SDK

Управляемые инструменты данных для Vercel AI SDK.

sqai.tools() добавляет в generateText ровно три инструмента только для чтения. Модель обнаруживает источники, отправляет один типизированный план и возвращает числа, вычисленные детерминированным движком, — с хешами, позволяющими воспроизвести каждый ответ.

Для старта API-ключ не нуженВключён в реестр инструментов AI SDKai ^7.0.0 · zod ^4.0.0 · Node ≥ 20

IIУстановка

Одна строка зависимости.

pnpmnpmyarnbun

Серверная сторона, Node 20 или новее — в Next.js запускайте в обработчике маршрута с runtime = \"nodejs\". Зависимости: ai ^7.0.0 и zod ^4.0.0 — версии, под которые типизированы планы. Без аккаунта, без ключа, без конфигурационного файла.

IIIБыстрый старт

Первый управляемый ответ.

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() подключается лениво — данные не читаются до первого вызова инструмента. sqai.tools() возвращает типизированный SqaiToolSet, приведение типов не требуется. isStepCount(12) оставляет модели достаточно шагов для обнаружения, планирования и выполнения.

Добавляйте источники, а не связующий код.

CSV, JSON, записи в памяти и SQLite работают внутри процесса — данные не покидают ваш сервер. Postgres, Snowflake, BigQuery и остальные подключаются через движок. Каждый источник приводится к одной типизированной форме, поэтому на уровне инструментов CSV неотличим от Snowflake. Все источники с описанием →

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

Каждая опция сужает доступ.

Усечение всегда объявляется; неполные строки никогда не показываются. Входные данные инструмента, которые заполняет модель, не содержат поля allowed* — политика фиксируется в момент вызова createSQAI() и проверяется внутри процесса, до выполнения. Модель не может расширить то, что ей было передано. Полная модель управления →

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

опцияпо умолчаниюдействие

sourcesобязательно

Единственные данные, доступные инструментам. Регистрируются один раз — источники неизменяемы.

allowedSourcesвсе зарегистрированные

Ограничивает источники, к которым может обращаться любой план.

allowedFieldsвсе поля

Список разрешённых столбцов для каждого источника. Всё остальное невидимо.

allowedFunctions«all-readonly»

Список разрешённых возможностей — только сужение. Указание чего-либо шире вызывает unsupported_operation.

defaultLimit100

Строк возвращается, если план не задаёт собственный лимит.

maxExecutionRows1 000

Жёсткий предел строк, читаемых за одно выполнение.

maxRowsToModel25

Строк, которые модель видит в любом случае.

maxCellsToModel250

Ячейки, которые когда-либо видит модель.

maxBytesToModel32 000

Байты результата, которые когда-либо видит модель.

IVИнструменты

Ровно три инструмента.

Обнаружение, выполнение, репетиция — по одному инструменту на каждое. Поверхность не расширяется у вас за спиной.

listSources

никогда не выполняет

Возвращает поля, типы и количество строк каждого источника, а также операции, поддерживаемые каждым числовым полем. Три режима детализации удерживают расход токенов на одном уровне по мере роста числа источников.

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

queryData

единственный, кто выполняет

Принимает один типизированный план — размеченное объединение, проверяемое до запуска. Четыре исхода, никаких исключений: цикл всегда получает структуру в ответ, даже когда ответ — нет.

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

explainQuery

пробный прогон

Проверяет и разрешает план, не обращаясь к данным. Возвращаемый invocation_hash — это предварительный просмотр того, что было бы выполнено, а не хеш уже выполненного.

invocation_hash = preview ≠ executed

VОдин прогон — в деталях

Реальные числа из реального прогона.

generateText · один промпт · три шага инструмента

пользователь

Общая выручка по восточному региону — и NPV нашего графика выручки при ставке 10%?

инструмент

listSources()orders · 12 строк · region, revenue

инструмент

queryData({ kind: "query", version: "1", … })sum(revenue) · region = "east"ok · 2130.50 · 5 заказовplan_hash f87610d8afeb…

инструмент

queryData({ kind: "computation", version: "1", … })finance.npv · rate 0.1 · values ← orders.revenueok · 3188.17 · 0.83 мс

ассистент

Выручка по восточному региону составляет 2 130,50 по 5 заказам. При ставке 10% NPV графика выручки равен 3 188,17.

Модель не выполняла никаких вычислений. Оба числа получены от детерминированного движка — и хеш позволяет их воспроизвести.

VIVs. универсальные инструменты

Типизированные планы не дают сбоев.

типовой SQL-инструментsqai.tools()

модель формируеттиповой SQL-инструментсырую SQL-строкуsqai.tools()один типизированный план — kind «query» или «computation», version «1», проверяется через zod

некорректный вызовтиповой SQL-инструментвыбрасывает исключение, повторяет попытку или молча игнорируетсяsqai.tools()возвращает needs_clarification с вариантами — инструменты никогда не выбрасывают исключений

один и тот же вопрос дваждытиповой SQL-инструментразный SQL, разные ответыsqai.tools()один и тот же план, один и тот же хеш — воспроизводимо

путь записитиповой SQL-инструментвсё, что допускает соединениеsqai.tools()отсутствует по конструкции — 4 574 возможности только для чтения, без лазейки, доступной модели

доказательствотиповой SQL-инструментотсутствует — правдоподобное числоsqai.tools()plan_hash и computation_hash в каждом ответе

Сценарии отказов слева зафиксированы, а не выдуманы: vercel/ai #1905 · #2147 · #12020 · #6913

Проектирование полного цикла агента →

Подключите инструменты.

Без API-ключа. Без аккаунта. Первый вызов инструмента работает сразу.

Читать документацию →Пакет на npm →Полное руководство по установке →

Включён в AI SDK Tools Registry · ai ^7.0.0 · zod ^4.0.0 · Node ≥ 20 · server-side