TanStack AIとは？使い方・対応プロバイダーとVercel AI SDKとの違い

TanStack AIは、TanStackが開発するMITライセンスのTypeScript向けAI SDKです。リポジトリの説明文は「Type-safe, provider-agnostic TypeScript AI SDK」で、OpenAI・Anthropic・Geminiなどのプロバイダーをアダプタとして差し替えながら、ストリーミングチャット・ツール呼び出し・構造化出力・音声や画像の生成を同じ型付きAPIで書けるようにしています。npmの初版は2025年12月4日、最新版は0.58.0（2026年9月21日公開）で、まだ1.0に到達していません。この記事では、サーバーとクライアントの実装コード、対応プロバイダーとフレームワークの実態、Vercel AI SDKとの違い、そして導入前に踏みやすい制約を整理します。根拠は公式のQuick Start・Overview・Vercel AI SDK比較・AG-UI移行ドキュメントと公式ブログ、およびNode環境での実測です。

まとめ：TanStack AIの要点

• 正体：AIサービスでもホスティング基盤でもなく、自分のサーバーに組み込むライブラリです。中間サーバーやゲートウェイを持たず、選んだプロバイダーへ直接つなぎます。
• バージョン：@tanstack/ai は0.58.0（2026年9月21日）。2026年8月21日にリリースキャンディデート段階入りが宣言されましたが、v1には未到達です。0.0.1の公開から9か月半で90バージョンが出ており、更新頻度は高い状態です。
• 最小構成：サーバーで chat() を呼び toServerSentEventsResponse() でSSEに変換し、クライアントで useChat() から呼び出します。必要なパッケージはコア・フレームワーク・プロバイダーの3つです。
• ツール呼び出し：toolDefinition() で入出力スキーマを1回定義し、.server() と .client() で実装先を切り替えます。
• Vercel AI SDKとの差：ライセンス（MIT対Apache 2.0）、プラットフォーム連携の有無、公式Solid対応の有無が主な違いです。プロバイダー別の一次対応パッケージ数はVercel側が多いと公式比較ドキュメントも認めています。
• 制約：ESM専用で require() は通りません。0.x系のため通信プロトコルにも破壊的変更が入ります。

TanStack AIの現在地：バージョン・ライセンス・利用規模

TanStack AIは、TanStack QueryやTanStack Routerと同じ組織の公開リポジトリとして2025年10月8日に作成されました（GitHub APIの created_at。プロジェクトの着手日そのものではありません）。npmレジストリのメタデータを2026年9月22日に取得したところ、最初の公開は2025年12月4日の0.0.1、最新は0.58.0で、その間に公開されたバージョンは90でした。直近1週間だけでも0.55.0・0.57.0・0.58.0の3版が出ています。dist-tagは latest のみで、alphaやbetaといった別チャネルは用意されていません。

安定度の現在地は公式ブログが示しています。2026年8月21日の記事「TanStack AI Enters the RC Phase」でリリースキャンディデート段階に入ったと宣言し、「We invite you to help us test TanStack AI as we approach a stable v1 release, which is now very close」と書いています。アルファ扱いだった2025年末の紹介記事とは前提が変わっており、日本語の解説で見かける「まだアルファ版」という説明は現状と一致しません。ただしv1そのものは未到達です。

ライセンスはMITで、リポジトリのスター数は3,128です（同じくGitHub APIで2026年9月22日に取得）。利用規模をnpmのダウンロード統計APIで見ると、2026年9月14日から20日の週で @tanstack/ai が301,289、Vercel AI SDKの ai パッケージが18,077,596でした。このダウンロード数だけでは、導入企業数や本番運用の実績までは判断できません。一方で公式ドキュメントのOverviewは「production-ready AI experiences」を作るためのSDKと位置づけており、検証用と限定してはいません。

バージョンが0.xであることは、後述するとおり通信プロトコルの破壊的変更を伴います。導入するなら、バージョンを固定したうえで更新履歴を追う前提で組み込んでください。

ストリーミングチャットの実装：サーバーの chat() とクライアントの useChat

TanStack AIの最小構成は、サーバー側でストリームを作り、クライアント側のフックがそれを受け取る形です。APIキーはサーバーの環境変数に置き、ブラウザへは渡しません。

サーバー側：chat() の戻り値とSSEレスポンスへの変換

サーバーでは chat() にアダプタとメッセージ配列を渡し、返ってきたストリームを toServerSentEventsResponse() でWeb標準の Response に変換します。公式のQuick Startは、この形がTanStack Start・Next.js・SvelteKit・Honoなど「Web標準のResponseを返せるホスト」でそのまま動くと説明しています。

import {
  chat,
  chatParamsFromRequest,
  toServerSentEventsResponse,
} from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'

export async function POST(request: Request) {
  const { messages, threadId, runId } = await chatParamsFromRequest(request)

  const stream = chat({
    adapter: openaiText('gpt-5.6'),
    messages,
    threadId,
    runId,
  })

  return toServerSentEventsResponse(stream)
}

アダプタは実行時に OPENAI_API_KEY を読みます。Expressのように素のNodeストリームを返すサーバーでは、公式が別途「Quick Start: Server Only」を用意しています。

クライアント側：useChat によるメッセージとストリームの状態管理

Reactでは @tanstack/ai-react の useChat を呼び、接続先を fetchServerSentEvents() で指定します。返り値の messages はチャンクが届くたびに更新され、isLoading は実行中だけ true になります。

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

export function Chat() {
  const { messages, sendMessage, isLoading, stop } = useChat({
    connection: fetchServerSentEvents('/api/chat'),
  })

  // messages[n].parts に text, tool, reasoning などのパートが入る
  // sendMessage(text) で送信、stop() で実行中のランを中断する
}

1件のメッセージは文字列ではなく parts の配列で、テキスト・ツール呼び出し・思考過程がパート種別で区別されます。描画側で part.type === 'text' を判定して出し分ける設計です。

対応プロバイダーとアダプタの粒度

各プロバイダーへの接続機能は、コアとは別のアダプタパッケージとして配布されています。READMEが公式アダプタとして掲げるのは次の13パッケージで、リポジトリの packages/ にはこのほかMistral・Cohere・Perplexity・Bedrock・Vercel Gateway向けの実装もあります。

アダプタはプロバイダー単位ではなく「活動」単位で分かれています。@tanstack/ai-openai の公開エクスポートを実際に列挙すると、チャットの openaiText、画像の openaiImage、音声合成の openaiSpeech、文字起こしの openaiTranscription、動画の openaiVideo、埋め込みの openaiEmbedding、リアルタイムの openaiRealtime が別々の関数として並びます。チャットしか使わないアプリのバンドルに画像生成のコードが入らないのは、この分割のおかげです。

コア側の生成APIの名前は活動ごとに決まっており、generateImage・generateSpeech・generateAudio・generateVideo・summarize があります。文字起こしだけは transcribe ではなく generateTranscription です（0.58.0のエクスポートを列挙して確認）。ドキュメントの本文だけを読んで関数名を推測すると、ここで詰まります。

型安全なツール呼び出し：toolDefinition と .server() / .client()

ツール呼び出し（Function calling）は、定義と実装を分ける設計です。toolDefinition() に名前・説明・入力スキーマ・出力スキーマを書いて契約だけを作り、.server() でサーバー実装を、.client() でブラウザ実装を与えます。同じ契約から実装先だけを差し替えられるため、在庫検索のようにDBが要る処理はサーバー、画面操作のようにブラウザが要る処理はクライアント、と置き場所を後から決められます。

import { toolDefinition } from '@tanstack/ai'
import { z } from 'zod'

const getProducts = toolDefinition({
  name: 'getProducts',
  description: 'Search the product catalog',
  inputSchema: z.object({ query: z.string() }),
  outputSchema: z.array(
    z.object({
      id: z.string(),
      name: z.string(),
    }),
  ),
}).server(async ({ query }) => {
  // db はアプリ側で用意済みのDBクライアント
  return db.products.search(query)
})

上の例にはZodの追加インストールが必要です。定義したgetProductsは、サーバー側のchat()にtools: [getProducts]として渡します。スキーマはZod専用ではなく、公式READMEは構造化出力にJSON Schema・Zod・ArkType・Valibotを挙げています。chat() に outputSchema を渡すと、返り値がフリーテキストではなく型付きオブジェクトになります。承認フローが必要なツールには needsApproval を付けられます。

対応フレームワークと実行環境：TypeScript SDKと他言語サーバーの連携

UIフレームワークごとにバインディングのパッケージが分かれています。関数名はReact・Vue・Solid・Preactが useChat、Svelteは createChat です（Remix向けの @tanstack/ai-remix も createChat を使います）。

利用できるフレームワーク・実行環境として、公式Overviewが名前を挙げているのはNext.js（API RoutesとApp Router）、TanStack Start、Remix 3、React Native/Expo、Express、React Router v7です。TanStack Startは同じTanStack製で、ドキュメントでも推奨と明記されています。

ここで混同しやすいのが、SDKを書く言語と、接続先のエージェントサーバーの言語です。SDK本体はTypeScriptで、2026年9月22日にGitHub APIで取得した packages/ の69パッケージはすべてTypeScript実装、リポジトリの言語構成もTypeScriptが18,710,999バイトでPHPとPythonは0バイトです。PHPやPythonのプロジェクトにこのSDKをそのまま入れることはできません。

一方で、接続先は別です。公式サイトは通信の互換性について「point the same client at a Python, Go, or PHP runtime and it keeps working」と書いており、AG-UI準拠のサーバーであれば実装言語を問わず同じクライアントから使えます。すでにPythonでエージェントを組んでいるなら、フロントだけTanStack AIに寄せる構成が取れます。

Vercel AI SDKとの違いと選定基準

比較対象として最も名前が挙がるのはVercel AI SDKです。TanStack側が公開している比較ドキュメントは、両者の差を「ライブラリの組み合わせ問題として扱うか、フルスタックのプラットフォーム問題として扱うか」と整理しています。以下は同ドキュメントの記述をもとにした対照です（TanStack側の主張である点は差し引いて読む必要があります）。

選定の判断はここで分かれます。すでにVercelにデプロイしていて、AI Gatewayで複数プロバイダーを1本の鍵に束ねたい、あるいは特定のプロバイダーの一次対応パッケージが欲しいなら、Vercel AI SDKのほうが手数が少なくて済みます。逆に、プラットフォームに紐づかない純粋なライブラリが欲しい、公式のSolidやPreact向けバインディングを重視する、バンドルサイズを活動単位で削りたい、という条件ならTanStack AIが合います。

公式比較ドキュメントが自ら「プロバイダーの幅は今日時点でVercel側が広い」と書いている点は、選定時にそのまま受け取ってよい情報です。TanStack AI側はOpenRouterアダプタや openaiCompatible でモデル数を補う設計になっており、「一次対応パッケージの数」と「到達できるモデルの数」は別の指標として扱われています。

導入前に確認したい3つの制約

ドキュメントの紹介文には出てきませんが、実際にインストールすると最初にぶつかる点を3つ挙げます。検証環境はNode v26.5.0、TypeScript 7.0.2、@tanstack/ai 0.58.0、@tanstack/ai-openai 0.23.1、@tanstack/ai-client 0.33.2です。

ESM専用パッケージのrequire()による読み込み制約

@tanstack/ai の package.json は "type": "module" で、main フィールドを持ちません。CommonJSから読み込もうとすると、次のエラーで停止します。

$ node -e "require('@tanstack/ai')"
Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined in
  /tmp/tsai/node_modules/@tanstack/ai/package.json

@tanstack/ai-openai と @tanstack/ai-client も同じ構成です。CommonJSのままのNodeサーバーに後付けする場合は、ESMへの移行か動的 import() への書き換えが先に必要になります。

0.x系の通信プロトコル変更と更新時の互換性確認

公式の移行ドキュメントは、クライアントからサーバーへのリクエスト本文がAG-UI 0.0.52の RunAgentInput 形式に変わったことを「The HTTP wire is a breaking 0.x change」と明記しています。旧形式の data フィールドは互換のため残されていますが、将来のメジャー更新で削除予定とされています。@tanstack/ai と @tanstack/ai-client は、この移行に対応する版へ併せて更新することが推奨されています。両パッケージのバージョン番号を同一にするという意味ではありません。9か月半で90バージョンという頻度を踏まえると、バージョン固定と移行ドキュメントの確認を運用に組み込んでおくべきです。

モデルIDと入力モダリティの型検査の差

モデルIDの型安全は実際に機能します。存在しないモデル名を渡してTypeScript 7.0.2でコンパイルすると、53件のモデルIDのユニオン型に代入できないというエラーになります。

chat({ adapter: openaiText('gpt-5.6-typo'), messages })

error TS2345: Argument of type '"gpt-5.6-typo"' is not assignable to
  parameter of type '"chatgpt-4o-latest" | "codex-mini-latest" | ...

一方で、公式比較ドキュメントが書いている「テキスト専用モデルに画像パートを渡すとコンパイル時に捕まる」ほうは、手元では再現しませんでした。アダプタのモデル定義で gpt-3.5-turbo の入力は ["text"] のみと宣言されているにもかかわらず、画像パートを含むメッセージを渡したコードがエラーなくコンパイルを通っています。モダリティの取り違えは型で止まる前提を置かず、対応モダリティを自分で確認してください。

よくある質問

TanStack AI SDKは本番環境で使えますか？

公式ブログは2026年8月21日にリリースキャンディデート段階入りを宣言し、安定版v1が近いと述べています。npmにalphaやbetaのdist-tagもありません。ただしバージョンは0.58.0で1.0に到達しておらず、通信プロトコルの破壊的変更も0.x系の範囲で実施されています。本番採用では、バージョン固定と移行資料の確認に加え、利用するモデル・ツール・通信処理の動作検証が必要です。

OpenAI以外のプロバイダーに後から切り替えられますか？

アダプタを差し替える形で切り替えます。chat() に渡す adapter を openaiText('gpt-5.6') から anthropic 系や ollama 系の関数に変えるのが基本で、実行時に切り替える方法も用意されています。ただしモデル固有のオプションは型で絞り込まれているため、切り替え時にオプションの指定を直す必要が出ます。

TanStack Start以外のフレームワークでも使えますか？

使えます。サーバー側はWeb標準の Response を返せるホストであれば動き、公式OverviewはNext.js・Remix 3・Express・React Router v7・React Native/Expoを挙げています。TanStack Startは同一プロジェクトであるぶん統合が厚く、ドキュメント上は推奨扱いです。

@tanstack/ai-react だけをインストールすれば動きますか？

動きません。公式Quick StartがReact向けに指定しているのは、コアの @tanstack/ai、フックの @tanstack/ai-react、プロバイダーの @tanstack/ai-openai の3つです。@tanstack/ai は @tanstack/ai-react の peerDependency なので明示的に入れる必要があり、@tanstack/ai-client のほうは @tanstack/ai-react の依存として自動で入ります（0.27.3の依存関係で確認）。プロバイダーのアダプタを忘れると chat() に渡すアダプタが用意できません。

Vercel AI SDKから移行できますか？

公式リポジトリに移行ドキュメント（migration-from-vercel-ai）が用意されています。ただしツール定義は tool() オブジェクトから toolDefinition() と .server() の組み合わせへ、エージェントループは stopWhen から戦略関数へと書き方が変わるため、置換ではなく書き直しに近い作業になります。永続化やレジューム可能ストリームを自前で組んでいる場合は、その部分の設計も見直しが必要です。

関連記事

• TanStack Startとは？フルスタックReactフレームワークの特徴・使い方・デプロイ【2026年版】
• TanStack Queryとは？React Queryとの違い・v5の使い方と脆弱性対策
• TanStack DBとは？TanStack Queryとの違い・使い方とv0.9系の注意点
• TanStack Routerとは？型安全ルーティングの特徴・導入手順とReact Routerとの違い
• TanStack Formとは？使い方・React Hook Formとの違いとzodバリデーションを解説