listSources
führt nie ausErkundung. Verbundene Quellen mit typisierten Feldern, Capability-Modulen und Funktionssignaturen — drei Modi aus einer Eingabe, damit Specs exakte Namen verwenden.
Für Agenten — das kontrollierte Datenwerkzeug
KI-Agenten-Tools,
die mit Nachweis antworten.
SQAI gibt einem tool-aufrufenden Modell schreibgeschützten Zugriff auf strukturierte Daten über drei kontrollierte Tools. Das Modell verfasst typisierte Absichten. Ein Vertrag und Ihre Richtlinie prüfen sie. Eine deterministische Engine führt sie aus. Jede Antwort wird mit einem Hash zurückgegeben, der sie reproduzierbar macht.
IEin Durchlauf der Schleife
die Anfrage trifft ein
“Welche Region hatte den höchsten Gesamtumsatz?”jedes tool-aufrufende ModellDas Modell
Plant die Schritte. Verfasst Absichten. Berührt die Daten nie.
Tool-Aufruf — typisierte Absicht, kein SQL
{ version:"1", kind:"query", spec:{ metric:"revenue", aggregation:"sum", group_by:"region", source:"sales" } }das kontrollierte ToolSQAI
contracthash-fixierter Capability-VertragpolicyIhre Zulassungslisten, vor der Ausführung geprüftenginedeterministisch, schreibgeschützt ausgeführt
typisierter Status — kein Throw
status: ok · needs_clarification · rejected · errordie Antwort verlässt die Schleife — mit ihrem Hash
east — 2,130.50 · plan_hash f87610d8afeb…okVerlässt die Schleife. Die Zeilen oder der Wert — und der Hash, der sie reproduziert.
needs_clarification ↺Tritt erneut in die Schleife ein. Eine Frage und die gefundenen Kandidaten — das Modell verfeinert die Spezifikation und ruft erneut auf. Es rät nie eine Spalte.
Ablehnung und Fehler nehmen dieselbe Rückgabespur — typisierte Ergebnisse, die das Modell lesen kann, keine Ausnahmen, die den Lauf abbrechen.
IIDas Toolset
Drei Tools. Eines führt aus.
sqai.tools() gibt genau drei Tools zurück — eine bewusst kleine Oberfläche. Discovery und Probeläufe führen nie aus; die Ausführung findet an genau einer Stelle statt.
führt nie aus
queryData
der ausführendeEine versionierte Eingabe — eine diskriminierte Union auf kind: eine Abfrage oder eine Berechnung. Vier Ergebnisse, stets typisiert, niemals ein Throw.
explainQuery
Probelauf — führt nie ausLöst eine Absicht auf und validiert sie, ohne sie auszuführen. Das Modell nutzt es zum Debuggen von Rückfragen; Sie nutzen es zur Vorschau eines Plans.
Das Set fällt direkt in generateText oder streamText — typisiert, zuweisbar ohne Cast. Vercel AI SDK Setup →
IIIDer Fehlervertrag
Tools werfen nie.
Eine Exception bricht einen Agentenlauf ab. Daher wirft hier nichts: Mehrdeutigkeit, Ablehnung und Fehler kommen als typisierte Statuses zurück, die das Modell lesen — und korrigieren — kann, innerhalb seines Step-Budgets.
retryable markiert die transienten — network_error · timeout · rate_limited · service_unavailable
queryData — die vier Ergebnisse
okDas Ergebnis: Zeilen oder Wert, Provenienz-Hashes, deklarierte Kürzung.plan_hash · invocation_hash · computation_hash · truncatedneeds_clarificationDie Absicht war mehrdeutig. Eine Frage plus die Kandidaten — niemals eine Vermutung.question · candidates · explanationrejectedDer Resolver hat die Absicht abgelehnt. Nichts wurde ausgeführt.rejection_reason · candidates · explanationerrorEin strukturierter Fehler mit stabilem Code — das Modell liest ihn und passt sich an.code · message · retryable · nearest_matches?Jeder Zweig ist Daten. Die Schleife behält ihren Zug.
Das Prinzip
Das Modell behandeln als
nicht vertrauenswürdigen Client.
Policy im Code · kein Policy-Feld in einer Tool-Eingabe · nur einschränkend
IVDas Prinzip, angewandt
Die Branche hat dies in der Produktion gelernt — ein autonomer Coding-Agent löschte bekanntlich eine Live-Datenbank. SQAIs Antwort ist strukturell, nicht verhaltensbasiert: Die exponierte Oberfläche ist konstruktionsbedingt schreibgeschützt. Schreib- und nicht-deterministische Kategorien werden nie in sie generiert, und kein Flag, keine Policy und keine Modelleingabe aktiviert sie wieder.
- Was das Modell sendet
- Nur typisierte Absicht — eine versionierte Spec. Kein SQL-String, kein Code, kein Connection-Handle.
- Was es nie senden kann
- Policy. allowedSources, allowedFields und allowedFunctions sind in der createSQAI()-Konfiguration festgelegt — kein Tool-Input-Schema enthält ein Policy-Feld, sodass eine Anfrage die Oberfläche einschränken, aber nie erweitern kann.
- Wenn es trotzdem fragt
- Eine strukturierte Ablehnung — policy_denied_source, policy_denied_field, policy_denied_function. Nicht wiederholbar, modelllesbar, und der Lauf geht weiter.
VDie Verdrahtung
Drei Zeilen rein. Standardmäßig begrenzt.
Ein Paket kapselt den Client in Tools. Quellen verbinden sich lazy beim ersten Aufruf; die erste Berechnung provisioniert die Runtime einmalig, dann bleibt sie warm — gemessen 0,83 ms.
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"
Nur serverseitig — bei Next.js die Node-Runtime verwenden, nicht Edge.
Was das Modell erreicht
- maxRowsToModel
- 25Zeilen, die das Modell sieht, von allem, was die Engine ausgeführt hat
- maxCellsToModel
- 250Zell-Budget — ganze Zeilen werden verworfen, um zu passen; eine unvollständige Zeile wird nie angezeigt
- maxBytesToModel
- 32,000Byte-Budget für den modellsichtbaren Wert
- maxExecutionRows
- 1,000hartes Limit, das die Engine ausführt — defaultLimit 100, wenn eine Spec kein Limit angibt
Kürzung wird stets deklariert — truncated: true, returned_rows < total_rows. Niemals still. Vollständige Ergebnisse bleiben im Anwendungscode über result_id abrufbar.
VIAgentische Analytik
Analysen, die ein Agent vertreten kann.
Agentische Analytik scheitert auf bekannte Weisen: fehlerhafte Tool-Aufrufe, Modelle, die eigene Arithmetik betreiben, plausible Zahlen, die niemand verifizieren kann. Jedes Problem wird strukturell beantwortet, nicht mit einem besseren Prompt.
01Ungültige Tool-Aufrufe
Eine versionierte Eingabe, validiert bevor irgendetwas läuft. Fehlerhafte oder mehrdeutige Absicht gibt einen typisierten Status zurück — die Schleife läuft weiter, statt abzustürzen.
02Das Modell rechnet selbst
Nicht hier. Die Engine berechnet. Bei einem quantitativen Set mit 16 Fragen stieg dasselbe Modell von 0/16 auf 16/16, sobald die Engine die Berechnungen übernahm.
03Nicht verifizierbare Zahlen
Jede Antwort trägt ihren Hash. Dieselbe Absicht gegen dieselben Daten wiederholen, und der Hash stimmt überein — byte-identisch in TypeScript und Python.
04Latenz-Stapelung
Eine Schleife multipliziert Latenz. Die Query-Ebene läuft in-process im Submillisekunden-Bereich; warme Berechnung gemessen bei 0,83 ms.
VIIFragen
Für Agenten — die Fragen
Wie gebe ich einem KI-Agenten schreibgeschützten Zugriff auf eine Datenbank?
SQL nicht filtern — nicht generieren. Quellen mit createSQAI() verbinden und dem Modell sqai.tools() übergeben: Die erreichbare Oberfläche umfasst 4.574 schreibgeschützte Capabilities plus Ihre Quellen, konstruktionsbedingt ohne Schreibpfad. Es gibt keine Schreibkategorie zu sperren und keine Modelleingabe, die eine wieder aktiviert.
Was passiert, wenn die Anfrage des Agenten mehrdeutig ist?
queryData gibt needs_clarification zurück – mit einer Rückfrage und den gefundenen Kandidatenfeldern. Es wird nie eine Spalte geraten. Das Modell beantwortet die Frage und ruft erneut auf – ein weiterer Durchlauf der Schleife.
Werfen die Tools jemals eine Exception?
Nein. Jeder Fehler ist ein strukturiertes Ergebnis mit einem stabilen Code, einer Meldung und einem Retryable-Flag. Mehrdeutigkeit, Ablehnung, Policy-Verweigerung und transiente Fehler kommen alle als Daten zurück, die das Modell lesen kann.
Kann das Modell seine eigenen Berechtigungen erweitern?
Nein. allowedSources, allowedFields und allowedFunctions sind im Code festgelegt – zum Zeitpunkt von createSQAI() gesetzt und vor der Ausführung geprüft. Kein Tool-Input-Schema enthält ein Policy-Feld; das Benennen einer verweigerten Capability gibt einen strukturierten policy_denied-Fehler zurück.
Funktioniert es mit dem Vercel AI SDK?
Ja – @thyn-ai/sqai-ai-sdk liefert die drei Tools als typisiertes Tool-Set für generateText und streamText, mit ai ^7.0.0 und zod ^4.0.0 als Peers, Node 20 oder neuer, serverseitig. Der zugrunde liegende Client ist dasselbe SDK, das sich in jede Agentenschleife einbinden lässt.