TanStack AI: ein TypeScript-SDK, das Provider hinter Adaptern versteckt

Welches Problem die Adapter-Schicht löst

Wer heute einen Chat mit Tool-Aufrufen in TypeScript baut, schreibt zunächst Code gegen ein Anbieter-SDK: OpenAI, Anthropic oder Gemini. Wechselt der Anbieter, ändert sich der Aufruf, die Typen für Nachrichten, die Form der Tool-Definitionen und oft auch das Streaming-Format. Diesen Umbau will das Projekt vermeiden. Nach eigener Beschreibung ist TanStack AI ein provider-agnostisches SDK, das aus zusammensetzbaren Activities und Provider-Adaptern besteht. Der Austausch findet an einer Stelle statt: beim Adapter. Die Dokumentation nennt im Streaming-Beispiel openaiText('gpt-5.2'), und die Installationshinweise zeigen, dass ein zweiter Anbieter über ein eigenes Paket wie @tanstack/ai-openrouter eingebunden wird. Zielgruppe sind damit TypeScript-Teams, die eine Chat-Oberfläche mit Werkzeugen, strukturierten Antworten oder multimodalen Ein- und Ausgaben planen und sich nicht früh auf einen Anbieter festlegen wollen. Die README listet zusätzlich React, Solid, Vue, Svelte und Preact als Zielplattformen, was den Kreis auf Frontend-Teams einschränkt, die die Streaming-Schicht nicht selbst schreiben wollen.

Activities, Adapter und das Streaming als Datenfluss

Das Modell ist in zwei Ebenen geteilt. Unten sitzen die Provider-Adapter, oben die Activities. Eine Activity ist eine Funktion mit einem klaren Auftrag: chat, eine Bildgenerierung, eine Transkription. Der Adapter liefert die anbieterspezifische Umsetzung. Im README-Beispiel erzeugt chat({ adapter: openaiText('gpt-5.2'), messages: body.messages }) einen Stream, der anschließend durch toServerSentEventsResponse in eine HTTP-Antwort im Server-Sent-Events-Format überführt wird. Der Datenfluss verläuft also vom Anbieter über den Adapter in einen Stream und von dort in eine Response, die ein Browser oder ein Framework-Client konsumieren kann. Für die Client-Seite existieren eigene Pakete, im React-Fall @tanstack/ai-client und @tanstack/ai-react. Bemerkenswert ist, dass die Dokumentation von konfigurierbaren Connection Adapters spricht. Der Transportweg zwischen Server und Client ist damit nicht fest verdrahtet, sondern austauschbar. Ein Punkt, den die README nur streift: Ob die Adapter tatsächlich deckungsgleich sind, hängt davon ab, welche Fähigkeiten ein Anbieter überhaupt anbietet. Ein Adapter kann nur abbilden, was die dahinterliegende API hergibt.

Werkzeuge einmal definieren, serverseitig ausführen

Der interessanteste Teil des SDK ist die Tool-Definition. Nach dem README-Muster erzeugt toolDefinition({ name, description, inputSchema, outputSchema }) einen Vertrag, an den eine Implementierung gehängt wird: .server(async ({ query }) => db.products.search(query)). Eingabe- und Ausgabetypen werden über die Schemata festgelegt, im Beispiel mit Zod. Die Dokumentation verweist darauf, dass dieselbe Definition auch mit einer Client-Implementierung versehen werden kann, sodass Server- und Client-Ausführung denselben Typvertrag teilen. Das ist der eigentliche Grund, warum sich die Abstraktion lohnt: Ein Werkzeug, das auf dem Server läuft, und eines, das im Browser läuft, werden nicht zweimal beschrieben. Für strukturierte Antworten existiert outputSchema direkt am chat-Aufruf. Die README nennt JSON Schema, Zod, ArkType und Valibot als unterstützte Validatoren. Wer bereits Zod im Projekt hat, muss also keine zweite Validierungsbibliothek einführen. Zusätzlich erwähnt die Dokumentation einen Tool Approval Flow und Lazy Tool Discovery. Beide Punkte sind in der README nur als Verweise vorhanden, nicht im Detail erklärt. Wer Werkzeuge mit Schreibzugriff einsetzt, sollte diese beiden Seiten vor der Implementierung lesen, weil dort die Frage beantwortet wird, wann ein Aufruf tatsächlich ausgeführt wird.

Installation und der erste Server-Endpunkt

Die Installation folgt dem TanStack-Muster: Kernpaket plus das Paket für Anbieter und Framework. Für einen Server-Endpunkt genügt laut README pnpm add @tanstack/ai @tanstack/ai-openai. Für eine React-Oberfläche kommt die längere Variante mit @tanstack/ai-client und @tanstack/ai-react hinzu. Der minimale Endpunkt besteht aus zwei Importen, chat und toServerSentEventsResponse aus @tanstack/ai sowie openaiText aus @tanstack/ai-openai, gefolgt von der Rückgabe des konvertierten Streams. Bemerkenswert ist der Versionsstand: Die Release-Liste zeigt @tanstack/ai@0.53.0 vom 3. September 2026, während die Adapter-Pakete eigene Nummern tragen, etwa @tanstack/openai-base@0.10.10 am selben Tag. Kern und Adapter werden also getrennt versioniert. Wer aktualisiert, muss beide Seiten im Blick behalten. Für Coding-Agenten liefert das Repository unter skills/ Anweisungen, die sich per /plugin marketplace add TanStack/ai und /plugin install tanstack-ai in Claude Code oder Cursor einbinden lassen, alternativ über npx skills add TanStack/ai -g --skill tanstack-ai tanstack-ai-migration. Innerhalb eines Projekts richtet npx @tanstack/intent@latest install die Skills der installierten Pakete in AGENTS.md beziehungsweise CLAUDE.md ein. Das ist ungewöhnlich für ein SDK, aber nachvollziehbar: Die Dokumentation liegt verteilt über viele Pakete, und ein Agent soll die passende Seite finden, ohne dass jemand sie manuell sucht.

Wo der Ansatz an Grenzen stößt

Die Abstraktion kostet etwas. Ein Adapter kann nur abbilden, was der Anbieter anbietet. Sobald ein Anbieter eine Funktion zuerst ausliefert, etwa eine neue Form des Tool-Aufrufs oder ein eigenes Streaming-Ereignis, muss der Adapter nachziehen. Zwischen Kern und Adaptern liegen getrennte Versionsnummern, und die Release-Liste zeigt mehrere Veröffentlichungen von @tanstack/openai-base innerhalb eines Tages, was auf eine hohe Änderungsrate hindeutet. Wer auf einen bestimmten Anbieter optimiert, verliert durch die Zwischenschicht Zeit gegenüber dem direkten SDK. Ein zweiter Punkt betrifft die Bandbreite der Funktionen. Die README nennt Chat, Tools, strukturierte Ausgaben, multimodale Ein- und Ausgaben, Bild-, Audio-, Video-, Sprach-, Transkriptions- und Zusammenfassungs-Workflows, Realtime Voice, Code Mode, Devtools und OpenTelemetry. Diese Liste ist lang, und die README beschreibt sie überwiegend als Aufzählung mit Verweisen. Ob eine Fähigkeit produktionsreif ist oder gerade erst eingeführt wurde, lässt sich aus dem Material nicht ableiten. Wer Realtime Voice oder Code Mode einplant, sollte die jeweilige Dokumentationsseite prüfen, bevor er sie als gegeben annimmt. Und Code Mode, bei dem ein Modell TypeScript in einer isolierten Sandbox schreibt und ausführt, verlagert einen Teil der Kontrolle in das Modell. Die README nennt die Sandbox, geht aber nicht darauf ein, wie die Isolation im Einzelnen aussieht. Das ist ein Punkt, der vor einem Einsatz mit Schreibzugriff auf echte Systeme geklärt werden muss.

Der Unterschied zum Vercel AI SDK

Die Dokumentation enthält eine eigene Vergleichsseite mit dem Titel TanStack AI vs Vercel AI SDK, in der laut README Architektur, Funktionsumfang und Abwägungen gegenübergestellt werden. Aus dem vorliegenden Material lässt sich nur ein Unterschied sicher benennen: TanStack AI trennt Activities und Provider-Adapter und liefert für jede Frontend-Bibliothek ein eigenes Bindings-Paket, was dem Aufbau des übrigen TanStack-Ökosystems entspricht. Wer bereits TanStack Query oder TanStack Router nutzt, findet dieselbe Aufteilung in Kern und Framework-Pakete wieder. Wer das nicht tut, hat mit dem Vercel AI SDK eine Alternative, die ebenfalls auf TypeScript zielt und in der Next.js-Welt verbreitet ist. Die tatsächliche Entscheidung hängt an Details, die in der Vergleichsseite stehen und nicht in dieser README: welche Anbieter unterstützt werden, wie die Tool-Ausführung zwischen Server und Client verteilt ist und welche Transportwege möglich sind. Wer zwischen beiden wählt, sollte diese Seite lesen, statt sich auf die Paketnamen zu verlassen.

Lizenz, Pflegeaufwand und Aktualisierungsrisiko

Das Projekt steht unter MIT. Das ist eine permissive Lizenz, die kommerzielle Nutzung, Änderung und Weitergabe erlaubt, sofern der Urheberrechtshinweis und der Lizenztext beibehalten werden. Für eingebettete SDKs ist das die unkomplizierte Variante. Eine rechtliche Bewertung ersetzt das nicht, insbesondere wenn das Paket in einem Produkt mit eigenen Lizenzauflagen weitergegeben wird. Der Pflegeaufwand liegt weniger in der Lizenz als in der Versionierung. Kern und Adapter erscheinen getrennt, und die Release-Liste zeigt für @tanstack/openai-base zwei Veröffentlichungen am 3. September 2026 sowie @tanstack/ai@0.53.0 am selben Tag. Wer eine Anwendung über Monate betreibt, muss damit rechnen, dass ein Update des Kerns ein Update des Adapters nach sich zieht oder umgekehrt. Das Repository ist nicht archiviert, und der letzte Push liegt laut Metadaten im September 2026. Der Auszeichnungshinweis in der README (ein Award für das KI-Projekt des Jahres 2026) ist eine Außenwahrnehmung, kein technisches Merkmal, und sollte bei der Bewertung nicht als Qualitätsnachweis dienen. Entscheidend für den Aufwand ist, wie viele der genannten Fähigkeiten tatsächlich genutzt werden: Wer nur Chat und Tools braucht, installiert zwei Pakete und hat einen kleinen Aktualisierungsradius. Wer multimodale Generierung, Realtime und Devtools gleichzeitig einsetzt, hängt an vielen Paketen mit jeweils eigener Versionsnummer.

Redaktionelles Fazit

Sinnvoll ist TanStack AI für Teams, die bereits in der TanStack-Welt arbeiten (Query, Router, Form) und React, Solid, Vue, Svelte oder Preact als Frontend einsetzen, weil sie dann denselben Denkstil für Server-Funktionen und Streaming-Handler wiederverwenden. Wer nur einen einzelnen Anbieter anspricht und dessen SDK direkt nutzt, gewinnt durch die zusätzliche Abstraktion wenig. Vor dem ersten Commit ist zu prüfen, welche Versionen von @tanstack/ai und dem passenden Provider-Paket tatsächlich zusammen veröffentlicht wurden, ob die benötigte Fähigkeit (etwa Realtime Voice oder Code Mode) bereits stabil oder nur angekündigt ist, und ob die eigene Runtime mit dem SSE-Ausgabeformat von toServerSentEventsResponse umgehen kann.

Offizielle Quellen

1. License: MIT
2. Project website
3. README
4. Releases
5. TanStack/ai on GitHub