TanStack AI

TanStack AI is a type-safe, provider-agnostic TypeScript SDK for building streaming chat, tool-calling agents, structured outputs, realtime voice, and media generation. It is built from composable activities (chat, image, audio, video, speech, transcription, summarization) and swappable provider adapters, so a project can import only the activities it uses and target one provider or switch between many without rewriting application code.

The core @tanstack/ai package defines the activity functions, the toolDefinition() contract for type-safe server/client tools, structured-output support via Zod/ArkType/Valibot/JSON Schema, an interrupt/resume system for tool approval flows, and a middleware pipeline for OpenTelemetry tracing, content guarding, and tool-result caching. Companion packages in the same monorepo add official adapters for OpenAI, Anthropic, Gemini, Grok, Groq, Ollama, Mistral, Bedrock, and OpenRouter, plus framework bindings for React, Vue, Svelte, Solid, Preact, and Angular.

What You Get

• A chat() activity for streaming text generation with typed messages, tool calls, and reasoning parts
• A toolDefinition() contract for defining a tool once and attaching a server or client implementation with shared input/output types
• Structured-output support backed by Zod, ArkType, Valibot, or plain JSON Schema
• Generation activities for images, audio, video, speech, transcription, and summarization behind one shared client pattern
• An interrupt/resume system for human-in-the-loop tool approval flows
• A middleware pipeline covering OpenTelemetry tracing, content guarding, and tool-result caching
• Official adapters for OpenAI, Anthropic, Gemini, Grok, Groq, Ollama, Mistral, Bedrock, and OpenRouter
• Framework-native bindings and hooks for React, Vue, Svelte, Solid, Preact, and Angular

Common Use Cases

• Adding a streaming chat endpoint to a React, Vue, or Svelte app without hand-rolling a provider-specific SDK
• Building type-safe tool-calling agents where a single tool definition drives both server execution and client-side approval UI
• Switching or A/B-testing LLM providers (e.g. OpenAI vs. Anthropic vs. OpenRouter) without changing application call sites
• Generating structured JSON outputs (e.g. extracted entities, form data) validated against a Zod or ArkType schema
• Running Code Mode agents that let a model write and execute TypeScript in an isolated sandbox to orchestrate tool calls
• Wiring OpenTelemetry traces and usage metrics into an LLM application for observability

Under The Hood

Architecture - The core @tanstack/ai package centers on activity functions (chat, summarize, generateImage, generateAudio, generateVideo, generateSpeech, generateTranscription) defined in src/activities/, each accepting an adapter plus activity-specific options and returning a typed async stream. The chat activity (src/activities/chat/index.ts) is the most involved: it composes a MiddlewareRunner (middleware/compose.ts) around tool execution (tools/tool-calls.ts, tools/lazy-tool-manager.ts), interrupt handling (interrupt-resume.ts, interrupt-serialization.ts), MCP tool discovery (mcp/manager.ts), and a sandbox runtime bridge (middleware/sandbox-runtime.ts) for Code Mode agents. Provider adapters live in sibling packages (packages/ai-openai, packages/ai-anthropic, etc.) and satisfy a shared AIAdapter/TextAdapter interface defined in src/types.ts, so the activity layer never depends on a specific provider’s wire format.

Tech Stack - Written entirely in TypeScript (99.5% of the codebase) with strict: true and noUncheckedIndexedAccess enabled repo-wide (tsconfig.base.json). The build uses Vite (vite build) to emit ESM-only output with per-entrypoint type declarations (./client, ./locks, ./adapters, ./middlewares, ./middlewares/otel). Runtime dependencies are minimal and deliberate: @standard-schema/spec for cross-validator schema support, partial-json for streaming JSON parsing, and workspace-internal @tanstack/ai-event-client/@tanstack/ai-utils packages; @opentelemetry/api is an optional peer dependency so tracing has zero cost when unused.

Code Quality - The package ships 71 Vitest test files under packages/ai/tests/ covering tool-call edge cases (tool-calls-null-input.test.ts), structured-output middleware, interrupt/resume validation, MCP chat flows, and standard-schema conversion, alongside oxlint --type-aware linting and a test:types step that runs tsc in CI. publint --strict guards the published package shape. Error handling is explicit and typed throughout (e.g. InterruptResumeValidationError, MiddlewareAbortError), rather than relying on generic thrown errors.

API Design - The public surface favors small, composable entry points over one large client object: activities are plain functions, tools are defined once via toolDefinition() and reused across server/client, and adapters are imported per-activity (openaiText, openaiImage) so unused provider code is tree-shaken. Getting started is a two-line install plus a chat({ adapter, messages }) call, and the 435-file docs/ tree plus 14 runnable framework examples keep the learning curve low despite the SDK’s broad feature surface.