TanStack AI + Effect 4: Der First-Party Adapter erklärt (0.1.0)

TanStack AI veröffentlicht @tanstack/ai-effect 0.1.0: AI.chat liefert einen typisierten Effect-Stream, Fehler typisiert, Unterbrechung bricht Modellanfrage ab.

Huifer
Huifer
7. November 20268 min read
Auch verfügbar auf:English · 中文

Geschrieben von Huifer, Solo-Entwickler und Maintainer von TanStack Ship. Ich betreibe Streaming-Chat und Tool-Calling-Agenten in produktiven SaaS-Apps, die auf TanStack Start aufbauen, und ich habe die Fehlermodi ungetippter Streaming-SDKs aus erster Hand erlebt — stilles Verschlucken von Fehlern, verwaiste Modellanfragen nach der Trennung des Clients und nachträglich angeklebte Retry-Logik. Dieser Guide zerlegt @tanstack/ai-effect, eine First-Party-Effect-4-Bindung für TanStack AI: AI.chat liefert einen typisierten Stream, und jede Aktivität läuft als Effect oder Stream. Alles hier verwendet ausschließlich die offiziellen Docs und die veröffentlichten Paket-Metadaten.

Verifizierte Quellen: TanStack AI Effect docs · @tanstack/ai-effect auf npm · TanStack AI docs · Effect 4 docs · TanStack AI repo · TanStack Ship Features

Zuletzt aktualisiert: 2026-11-07 · Changelog

TanStack AI + Effect 4: Der First-Party Adapter erklärt

TanStack AI liefert jetzt einen First-Party-Effect-Adapter für Ihre AI-Apps, und wenn Sie Streaming-Chat auf einem Effect-4-Server bauen, ist dieser Guide für Sie — Sie müssen nicht mehr zwischen Ihrer Effect-Laufzeit und dem AI-SDK wählen. Ein First-Party-Effect-Adapter: @tanstack/ai-effect (veröffentlicht am 2026-11-06, derzeit 0.1.0). Der Pitch in einer Zeile aus dem offiziellen README: Effect 4-Bindungen für TanStack AI — jede Aktivität als Effect oder Stream, plus Effect-Server-Tools. Wenn Ihr Server-Code in Effect 4 geschrieben ist, müssen Sie nicht mehr zwischen Ihrer Effect-Laufzeit und TanStacks AI-SDK wählen.

TL;DR (für TypeScript-Teams, die Effect 4 auf dem Server betreiben): @tanstack/ai-effect ist eine First-Party-Effect-4-Bindung für TanStack AI. Das zentrale chat() liefert ein async iterable und wirft einfache Fehler, was sich nicht in ein Effect-Programm einbinden lässt. AI.chat aus @tanstack/ai-effect liefert stattdessen einen Stream<StreamChunk, AIError> — typisierte Fehler, Stream-Kombinatoren und eine Unterbrechung, die die Modellanfrage tatsächlich abbricht. Installieren Sie @tanstack/ai @tanstack/ai-effect @tanstack/ai-openai @tanstack/ai-react effect, umschließen Sie Ihre Server-Route mit Stream.toAsyncIterable, und halten Sie useChat auf dem Client unverändert.

Was es ist: @tanstack/ai-effect ist eine First-Party-Effect-4-Bindung für das TanStack AI SDK, veröffentlicht als 0.1.0 am 2026-11-06. Dieser Guide richtet sich an TypeScript-Teams, deren Server-Schicht bereits Effect 4 ausführt und die Streaming-Chat, Tool-Calls und strukturierte Ausgaben in ihre Effect-Fehlerkanäle typisiert haben möchten. Wie Sie in einer Zeile entscheiden: Wenn Ihr Server heute effect importiert, übernehmen Sie den Adapter; wenn nicht, ist das zentrale chat() einfacher. Dieser Guide behandelt die Installation, die Server-Route, die Client-Verdrahtung und die Adopt-Entscheidung; außerhalb des Geltungsbereichs sind provider-seitige Preise und Prompt-Engineering.

Warum ein eigenes Adapter-Paket existiert

Etwas Geschichte zur Einordnung: TanStack AI trat 2026 in seine RC-Phase ein, erreichte 1.0 mit dem Release „Still Your AI, Still Your Way", und bewegt sich seit 2026 schnell — 1.1.0 erschien am 2026-11-05 und 1.2.0 folgte innerhalb von Tagen. Der Effect-Adapter ist die neueste Oberfläche: npm zeichnete alle drei seiner Erstveröffentlichungen (0.0.0-stage, 0.0.0, 0.1.0) innerhalb eines einzigen 19-Minuten-Fensters am 2026-11-06 auf, und die Doc-Site erhielt am selben Tag ihren Effect-Abschnitt.

Die zentrale chat()-Funktion in @tanstack/ai ist bewusst runtime-agnostisch: Sie liefert ein async iterable von Chunks und wirft einfache Errors. Das ist der richtige Standardwert für einen einfachen TypeScript-Server, aber er bricht zwei Verträge, die Effect-Programme betreffen:

  • Fehler sind ungetypt. In Effect leben Fehler im Kanaltyp (Stream<Chunk, Error>). Ein geworfener Fehler entkommt Ihrem typisierten Fehlerfluss und landet im generischen Catch-all, der die Fiber umschließt.
  • Keine strukturierte Unterbrechung. Effect verwaltet Unterbrechung über Fibers. Ein async iterable weiß nicht, wie es eine laufende Modellanfrage abbrechen soll, wenn die Fiber unterbrochen wird — die Verbindung zum Provider läuft einfach aus (Leak).

@tanstack/ai-effect behebt beides. AI.chat liefert Stream<StreamChunk, AIError>, und laut den offiziellen Docs: "Wenn der Browser die Anfrage schließt, stoppt der Stream. Danach bricht AI.chat die Anfrage an das Modell ab." Dieser letzte Teil ist das Produktionsdetail, das zählt — das Abbrechen des nachgelagerten SSE hebt nichts Upstream auf, es sei denn, der Adapter verdrahtet es, und dieser Adapter tut das.

Install

Das Paket benötigt Effect 4 (effect 4.1 oder neuer) und @tanstack/ai 1.2.0+ als Peer-Dependencies:

bash
npm i @tanstack/ai @tanstack/ai-effect @tanstack/ai-openai @tanstack/ai-react effect

Beachten Sie, dass @tanstack/ai-effect null Laufzeit-Dependencies deklariert — effect und @tanstack/ai sind Peer-Dependencies, also kontrolliert Ihre Lockfile die Versionen.

Installationsaufwand, gemessen an der npm-Registry (entpackte Größen, aktuelle neueste Versionen):

PackageUnpacked sizeFiles
@tanstack/ai-effect 0.1.061.4 kB18
@tanstack/ai 1.2.05737.3 kB644
@tanstack/ai-openai 1.1.1989.9 kB182
@tanstack/ai-react 1.0.2491.0 kB99
effect 4.1.255264.1 kB3013

Der Adapter selbst ist mit 61,4 kB auf 18 Dateien das kleinste Paket im Set. effect ist der schwere Peer mit 55264,1 kB entpackt, aber Tree-Shaking und server-only-Bundling halten es vollständig aus dem Client-Bundle heraus — das offizielle Client-Beispiel liefert plain React mit useChat.

Streamen Sie einen Chat von Ihrer Effect-Server-Route

Die offizielle Integration umfasst drei Schritte: Zuerst installieren Sie die Pakete; dann streamen Sie den Chat von Ihrer Server-Route; schließlich zeigen Sie den Chat auf dem Client. Das Server-Beispiel aus den offiziellen Docs ist klein genug, um es vollständig zu reproduzieren:

ts
import { chatParamsFromRequest, toServerSentEventsResponse } from '@tanstack/ai'
import * as AI from '@tanstack/ai-effect'
import { openaiText } from '@tanstack/ai-openai'
import { Stream } from 'effect'

export async function POST(request: Request) {
  const params = await chatParamsFromRequest(request)

  const stream = AI.chat({
    adapter: openaiText('gpt-6.1-sol'),
    messages: params.messages,
    threadId: params.threadId,
    runId: params.runId,
  })

  return toServerSentEventsResponse(Stream.toAsyncIterable(stream))
}

Drei Bausteine, jeder mit einer Aufgabe:

  • AI.chat übernimmt dieselben Optionen wie das zentrale chat() — dieselben Adapter, dieselben Nachrichten, dieselben Thread-/Run-IDs. Es liefert Stream<StreamChunk, AIError>.
  • Stream.toAsyncIterable wandelt den Effect-Stream zurück in das async iterable um, das toServerSentEventsResponse liest, sodass die SSE-Transportschicht unverändert bleibt.
  • Unterbrechung ist verdrahtet: Browser schließt die Anfrage → Stream stoppt → Modellanfrage abgebrochen.

Zeigen Sie den Chat auf dem Client — kein Effect nötig

Der Client bleibt plain React. useChat aus @tanstack/ai-react liest die Server-Sent Events:

tsx
import { useState } from 'react'
import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'

export function Chat() {
  const [input, setInput] = useState('')
  const { messages, sendMessage, isLoading } = useChat({
    connection: fetchServerSentEvents('/api/chat'),
    threadId: 'effect-chat',
  })

  return (
    <div>
      {messages.map((message) => (
        <p key={message.id}>
          {message.role}: {message.parts.map((part) =>
            part.type === 'text' ? part.content : null)}
        </p>
      ))}
      <form onSubmit={(event) => { event.preventDefault(); sendMessage(input); setInput('') }}>
        <input value={input} onChange={(event) => setInput(event.target.value)} />
        <button type="submit" disabled={isLoading}>Send</button>
      </form>
    </div>
  )
}

Die Grenze ist bewusst gewählt: Effect lebt auf dem Server, der Client konsumiert plain SSE. Sie liefern effect nicht an den Browser für eine Chat-Oberfläche. Deployment-seitig verwendet die Route Web-Standard-Request/Response, sodass sie unverändert auf Cloudflare Workers läuft; in TanStack Start können Sie denselben Handler als Server Function ausdrücken, wenn Ihnen diese Form lieber ist.

Holen Sie sich die ganze Antwort als Effect

Wenn Sie keine Token-für-Token-Streaming benötigen, übergeben Sie stream: false. AI.chat liefert dann einen Effect von { text, chunks }, der sich mit Effect.gen komponieren lässt:

ts
import * as AI from '@tanstack/ai-effect'
import { openaiText } from '@tanstack/ai-openai'
import { Effect } from 'effect'

const program = Effect.gen(function* () {
  const { text } = yield* AI.chat({
    adapter: openaiText('gpt-6.1-sol'),
    messages: [{ role: 'user', content: 'Write a haiku about rivers.' }],
    threadId: 'haiku',
    stream: false,
  })
  return text
})

const haiku = await Effect.runPromise(program)

Mit outputSchema liefert derselbe Aufruf einen Effect des geparsten strukturierten Objekts — dieselben Schema-Optionen wie die strukturierten Ausgaben des Core-SDKs.

Was sonst im Adapter ausgeliefert wird

Die offiziellen Docs führen über AI.chat hinaus drei weitere Oberflächen auf, alle nach derselben Regel „jede Aktivität als Effect oder Stream":

  • Effect tools — geben Sie Ihren AI-Tools Effect-Services, sodass die Tool-Ausführung Ihre Dependency Injection und Fehlerkanäle erbt.
  • Effect activities — führen Sie Bilder, Embeddings und Sprache als Effects aus.
  • Effect Chat tutorial — ein vollständiger schrittweiser App-Build in den offiziellen Docs.

Das Entscheidungs-Framework: drei Fragen vor der Übernahme

  1. Importiert Ihr Server heute effect? Wenn ja, ist der Adapter streng additiv: dieselben Optionen wie das zentrale chat(), typisiert in Ihren bestehenden Fehlerkanal. Wenn nein, Effect nur für AI-Calls hinzuzufügen ist eine Laufzeit-Dependency, die Sie nicht brauchen; das zentrale chat() deckt dieselben Features ab.
  2. Brauchen Sie Unterbrechungs-Korrektheit? Lange Agent-Loops mit kostenpflichtigen Modell-Calls lecken Geld, wenn eine Client-Trennung die Provider-Anfrage laufen lässt. Der Adapter bricht Upstream bei Downstream-Trennung ab; handgemachte async iterables erfordern, dass Sie das selbst verdrahten.
  3. Ist Ihr Client React? Der offizielle Client-Vertrag ist useChat plus SSE aus @tanstack/ai-react. Nicht-React-Clients konsumieren denselben SSE-Stream, aber Sie müssen den Hook neu implementieren.

Vorher und nachher: was sich in Ihrem Code ändert

Der Diff auf einer standardmäßigen TanStack-Start-Server-Route, mit den offiziellen Beispielen als Basis:

AspektCore chat() (vorher)AI.chat (nachher)
RückgabetypAsyncIterable<StreamChunk>Stream<StreamChunk, AIError>
Fehlergeworfener plain Error, generisch gefangentypisierter AIError im Kanal
Client-TrennungAnfrage läuft weiter, sofern Sie sie nicht verdrahtenbricht die Modellanfrage ab
Komponierbarkeitmanuelle async-iterable-KombinatorenStream-Modul-Kombinatoren
RoutenformSSE-Route via toServerSentEventsResponseidentisch

Die Routenform ändert sich nicht, und das ist der Punkt: Was sich ändert, ist der Typ des Werts, der hindurchfließt.

Methodik und Einschränkungen

Alles hier stammt aus der offiziellen Effect-Dokumentationsseite, den veröffentlichten npm-Metadaten für 0.1.0 und dem GitHub-Repository, jeweils oben verlinkt. Ich habe diesen Adapter noch nicht in Produktion ausgeführt; die Vorher/Nachher-Tabelle vergleicht dokumentierte Verträge, nicht gemessene Latenz. Abzuwägende Einschränkungen: Das Paket ist 0.1.0, erst Tage alt, pre-1.0, und seine API kann sich ändern; die Docs behandeln React auf dem Client, sodass Nicht-React-Clients undokumentiertes Terrain sind; und die Übernahme von Effect 4 selbst ist ein teamweites Commitment, das dieser Artikel nicht bewertet. Der wichtigste Vorbehalt für tool-lastige Agenten: Die Docs führen Effect tools und Effect activities als unterstützte Oberflächen auf, aber bei 0.1.0 sollten Sie jedes Tool-Muster, auf das Sie sich verlassen, anhand des offiziellen Effect-Chat-Tutorials verifizieren, bevor Sie eine Produktions-Veröffentlichung darauf setzen.

Versions- und Kompatibilitätsfakten

PaketVersionHinweis
@tanstack/ai-effect0.1.0Veröffentlicht 2026-11-06; null Laufzeit-Deps
effect≥ 4.1.0 (peer)Effect 4 erforderlich
@tanstack/ai≥ 1.2.0 (peer)Aktuelles Stable ist 1.2.0
@tanstack/ai-openai—Im Docs verwendeter Provider-Adapter
@tanstack/ai-react—Client useChat / SSE-Transport

Status heute: 0.1.0, erst Tage alt, API vor 1.0 änderbar. Die Docs behandeln es bereits als First-Class-Oberfläche, was das Signal ist, dass dies kein Experiment ist — die Doc-Site erhielt einen ganzen Effect-Abschnitt, ein Effect-Chat-Tutorial und Effect-Beispiele am selben Tag, an dem das Paket veröffentlicht wurde.

Wann Sie es übernehmen sollten (und wann nicht)

Übernehmen Sie es, wenn: Ihr Server bereits Effect 4 ist — der Adapter beseitigt die Impedance-Mismatch, anstatt dass Sie chat() von Hand umschließen müssen; Sie typisierten AIError in Ihrem Fehlerkanal brauchen statt geworfener Fehler; Unterbrechungs-Korrektheit zählt (langlaufende Agent-Loops, bei denen auslaufende Provider-Anfragen echtes Geld kosten).

Lassen Sie es weg, wenn: Ihr Server plain TypeScript ohne Effect ist — das zentrale chat() gibt Ihnen bereits das async iterable und den SSE-Transport mit weniger beweglichen Teilen; oder Ihr Client nicht-React ist und Sie nur den SSE-Vertrag brauchen, den der Adapter nicht ändert.

Für ein auf TanStack Start gebautes SaaS ist der interessante Mittelweg server-seitige Agenten: Tool-Calling-Loops in Effect mit Retries, die in den Kanal typisiert sind, einem React-Client über denselben useChat-Vertrag wie jede andere TanStack-AI-App ausgesetzt.

FAQ

Braucht der Client auch Effect?

Nein. Der offizielle Beispiel-Client ist plain React mit useChat, das Server-Sent Events liest. Die Effect-Laufzeit bleibt auf dem Server.

Welche Effect-Version ist erforderlich?

Effect 4 — konkret effect 4.1.0 oder neuer, deklariert als Peer-Dependency zusammen mit @tanstack/ai 1.2.0+.

Bricht die Unterbrechung die Modellanfrage tatsächlich ab?

Ja, laut den offiziellen Docs: Wenn der Browser die Anfrage schließt, stoppt der Stream, und AI.chat bricht dann die Anfrage an das Modell ab.

Kann ich ein einzelnes geparstes Objekt statt eines Streams erhalten?

Ja. Übergeben Sie stream: false, um einen Effect von { text, chunks } zu erhalten, oder verwenden Sie outputSchema, um einen Effect der geparsten strukturierten Ausgabe zu erhalten.

Ist 0.1.0 produktionsreif?

Es ist erst Tage alt und pre-1.0, aber es ist als First-Class-Oberfläche dokumentiert (eigener Docs-Abschnitt, Tutorial, Beispiele) statt als experimentelles Add-on. Pinne Sie Ihre Versionen und lesen Sie den Changelog vor einem Upgrade.

Weiterführende Literatur