ai-core

TanStack AI — Core Concepts

TanStack AI is a type-safe, provider-agnostic AI SDK. Server-side functions live in @tanstack/ai and provider adapter packages. Client-side hooks live in framework packages (@tanstack/ai-react, @tanstack/ai-solid, etc.). Always import from the framework package on the client — never from @tanstack/ai-client directly (unless vanilla JS).

Sub-Skills

Need to...	Read
Build a chat UI with streaming	ai-core/chat-experience/SKILL.md
Survive a browser reload (no extra package)	ai-core/client-persistence/SKILL.md
Add tool calling (server, client, or both)	ai-core/tool-calling/SKILL.md
Generate images, video, speech, or transcriptions	ai-core/media-generation/SKILL.md
Get typed JSON responses from the LLM	ai-core/structured-outputs/SKILL.md
Choose and configure a provider adapter	ai-core/adapter-configuration/SKILL.md
Implement AG-UI streaming protocol server-side	ai-core/ag-ui-protocol/SKILL.md
Add analytics, logging, or lifecycle hooks	ai-core/middleware/SKILL.md
Coordinate multi-instance work with locks	ai-core/locks/SKILL.md
Connect to a non-TanStack-AI backend	ai-core/custom-backend-integration/SKILL.md
Turn on/off debug logging, pipe into pino/winston	ai-core/debug-logging/SKILL.md
Persist chats server-side (history, runs)	See @tanstack/ai-persistence package skills
Set up Code Mode (LLM code execution)	See @tanstack/ai-code-mode package skills
Give the model a catalog of SKILL.md skills	See @tanstack/ai-skills package skills

Companion packages

Some capabilities live in their own package and ship their own skills. Install the package, then read its skills — do not guess the API from this file.

@tanstack/ai-persistence — durable chat state

Makes a conversation survive a reload, a server restart, a second device, or a paused tool approval. It ships the store contracts (MessageStore, RunStore, InterruptStore, MetadataStore), the withPersistence / withGenerationPersistence middleware, reconstructChat for server-side hydrate, an in-memory reference backend, and a conformance testkit. Multi-instance locks are not in this package — LockStore / withLocks ship in @tanstack/ai/locks; see ai-core/locks. The runs store contract is typed against run lifecycle types (RunStatus, RunRecord, RunStore, defineRunStore, InMemoryRunStore), which ship in @tanstack/ai itself; see ai-core/middleware.

It does not ship a backend for your database — you implement the stores against Postgres, SQLite, D1, Mongo, or whatever you run, and the package's skills walk you through it (including Drizzle, Prisma, and Cloudflare recipes).

pnpm add @tanstack/ai-persistence
npx @tanstack/intent@latest install

The skills ship inside the package, so they only exist on disk once it is installed — the second command re-scans node_modules and wires them into the agent config. Until then the paths below resolve to nothing.

Entry point: node_modules/@tanstack/ai-persistence/skills/ai-persistence/SKILL.md

Need to...	Read
Wire server-side chat history, runs, interrupts	ai-persistence/server/SKILL.md
Implement the store interfaces for your DB	ai-persistence/stores/SKILL.md
Write the adapter for the DB your app runs	ai-persistence/build-*-adapter/SKILL.md

Browser-side persistence is not in this package — it ships with the framework packages, so read ai-core/client-persistence instead.

@tanstack/ai-code-mode — LLM code execution

See the ai-code-mode skill in that package.

@tanstack/ai-skills — portable Agent Skills at runtime

Gives the model a library of SKILL.md skills it can load on demand, on any provider, via the withSkills middleware and a load_skill tool. Skills come from inlineSkill, skillDirectory, or a build-time bundle. This is the runtime feature for the model inside your app, not the coding-assistant skills this file is part of, and not the hosted codeExecutionTool / shellTool skills (those run in a provider sandbox).

pnpm add @tanstack/ai-skills
npx @tanstack/intent@latest install

Entry point: node_modules/@tanstack/ai-skills/skills/ai-skills/SKILL.md

Quick Decision Tree

• Setting up a chatbot? → ai-core/chat-experience
• Adding function calling? → ai-core/tool-calling
• Generating media (images, audio, video)? → ai-core/media-generation
• Need structured JSON output? → ai-core/structured-outputs
• Choosing/configuring a provider? → ai-core/adapter-configuration
• Building a server-only AG-UI backend? → ai-core/ag-ui-protocol
• Adding analytics or post-stream events? → ai-core/middleware
• Surviving reloads / multi-device / durable approvals? → @tanstack/ai-persistence skills
• Connecting to a custom backend? → ai-core/custom-backend-integration
• Turning on debug logging to trace chunks/tools/middleware? → ai-core/debug-logging
• Debugging mistakes? → Check Common Mistakes in the relevant sub-skill

Critical Rules

1. This is NOT the Vercel AI SDK. Use chat() not streamText(). Use openaiText() not createOpenAI(). Import from @tanstack/ai, not ai.
2. Import from framework package on client. Use @tanstack/ai-react (or solid/vue/svelte/preact), not @tanstack/ai-client.
3. Use toServerSentEventsResponse() to convert streams to HTTP responses. Never implement SSE manually.
4. Use middleware for lifecycle events. No onEnd/onFinish callbacks on chat() — use middleware: [{ onFinish: ... }].
5. Ask the user which adapter and model they want. Suggest the latest model. Also ask if they want Code Mode.
6. Tools must be passed to both server and client. Server gets the tool in chat({ tools }); the client passes the .client() implementation through the clientTools() helper into the tools option — useChat({ tools: clientTools(myTool.client(...)) }). There is no clientTools option. See ai-core/tool-calling.

Version

Targets TanStack AI v0.42.0.