TanStack AI を導入前に読む: provider 抽象と tool 契約の実際

どの問題を解くのか: provider 切り替えと型の断絶

LLM を使うアプリでは、chat のストリーミング、tool 呼び出し、構造化出力、画像や音声の生成といった機能ごとに API の形が違う。provider を OpenAI から Anthropic や Gemini に変えると、リクエストの組み立てとレスポンスの解釈を書き直す必要が出やすい。TanStack/ai はこの層を adapter として切り出し、アプリ側のコードは chat() や toolDefinition() といった共通の関数に寄せる。README は「composable activities and provider adapters」という構成を説明しており、必要な機能だけを import する方針を取る。chat だけを使うことも、image、audio、video、speech、transcription、summarization、realtime、Code Mode、devtools を足すこともできる。対象読者は TypeScript で AI 機能を書く開発者、とくに React、Vue、Svelte、Solid、Preact のいずれかで UI を持ち、サーバーとクライアントの間で tool の型を揃えたいチームである。

composable activities と adapter の分離

パッケージ構成は機能ごとに分かれている。中核が @tanstack/ai で、provider 側は @tanstack/ai-openai、@tanstack/ai-openrouter のように別パッケージになる。UI 側は @tanstack/ai-client と @tanstack/ai-react などの framework 別パッケージに分かれる。README の例では chat() に adapter として openaiText('gpt-5.2') を渡し、戻り値を toServerSentEventsResponse(stream) で Server-Sent Events の Response に変換している。つまりデータの流れは、provider 呼び出しが adapter の内側に閉じ、外側には provider 非依存の stream が出てくる。この境界があるため、provider を差し替えてもアプリ側のハンドラは同じ形を保てる。README は connection adapters という用語も使っており、接続方式そのものを差し替える余地を残している。ここで注意したいのは、抽象化の粒度が provider の全機能を覆うわけではない点だ。realtime voice や token minting のように provider 固有の概念が強い領域は、それぞれ専用の adapter を要求する。どの機能がどのパッケージに属するかは docs の Overview で確認する必要がある。

toolDefinition がサーバーとクライアントで型を共有する仕組み

この SDK の特徴が出るのが tool の定義方法である。README の例では toolDefinition() に name、description、inputSchema、outputSchema を渡し、その戻り値に対して .server(async ({ query }) => ...) を呼んで実装を接続している。inputSchema と outputSchema は Zod で書かれているが、README は structured output の節で JSON Schema、Zod、ArkType、Valibot、plain JSON Schema を挙げている。同じ契約に対してサーバー実装とクライアント実装を別々に付ける設計なので、tool をサーバーで実行するかブラウザ側で実行するかを後から選べる。docs には Tool Approval Flow と Lazy Tool Discovery というページもあり、tool 実行前に人間の承認を挟む流れや、tool を遅延して発見させる仕組みが用意されていることが読み取れる。ただし、これらのページの詳細は今回の材料には含まれていない。承認フローや遅延発見の具体的な API 名、設定キー、失敗時の挙動は docs 本文で確認してほしい。

導入コマンドと最初のサーバー実装

インストールは pnpm を前提に書かれている。最小構成は pnpm add @tanstack/ai @tanstack/ai-openai である。React の chat UI まで作るなら pnpm add @tanstack/ai @tanstack/ai-client @tanstack/ai-react @tanstack/ai-openai を実行する。複数 provider を一つの API key で試したい場合は @tanstack/ai-openrouter を使う選択肢が README に示されている。サーバー側の最小例は、Request を受けて body を JSON として読み、chat({ adapter: openaiText('gpt-5.2'), messages: body.messages }) を呼び、toServerSentEventsResponse(stream) を返すという流れになる。構造化出力が必要なら、この chat() に outputSchema として Zod のスキーマを渡す。README の例では Person という z.object({ name: z.string(), age: z.number() }) を渡し、戻り値を await で受け取っている。ストリーミングのまま使うか、outputSchema で最終オブジェクトを受け取るかは呼び出し側の設計判断になる。サーバー専用で使いたい場合のために Quick Start: Server Only というページが用意されている点も README に記載がある。

Code Mode とサンドボックスという重い選択肢

README が挙げる機能のなかで、導入判断に影響が大きいのが Code Mode である。説明によれば、LLM に TypeScript を書かせ、分離されたサンドボックスで実行させ、ループや分岐、並列呼び出しで tool を編成させる。通常の tool 呼び出しはモデルが一つずつ tool を選ぶが、Code Mode はモデルがコードを書いて複数の tool をまとめて扱う点が違う。柔軟性は高いが、実行環境の隔離、実行時間、ファイルシステムやネットワークへの到達範囲を自分で決める必要がある。README はサンドボックスの実装方式や制限については触れていないため、どの程度の隔離が保証されるのかはこの材料からは判断できない。Code Mode を使わない構成なら、この検討は不要である。chat、tool、structured output だけでも SDK としての用途は成立する。機能が多いぶん、使う範囲を最初に絞ったほうが導入は軽くなる。

Vercel AI SDK との違いはどこにあるか

README は TanStack AI vs Vercel AI SDK という比較ページを明示的に用意している。差異として README が示すのはアーキテクチャ、機能カバレッジ、トレードオフの3点であり、どちらが優れているかという結論は書かれていない。判断材料として読み取れるのは、TanStack 側が composable activities と provider adapters という構成を採り、framework binding を React、Solid、Vue、Svelte、Preact 向けに分けて提供している点である。TanStack の他ライブラリ、たとえば Router や Query をすでに使っているチームなら、client 側の設計思想が揃う利点がある。一方で、Vercel AI SDK は Next.js との組み合わせを前提にした資料や事例が多く、Next.js 中心の構成では移行の動機が弱い。比較ページの存在自体は、両者の差が単なる API 名の違いではなく、パッケージ分割と抽象の置き方にあることを示唆している。実際にどちらを選ぶかは、provider を差し替える予定があるか、framework binding をどの UI ライブラリに合わせるかで決めるのが現実的だ。

バージョンの刻み方とメンテナンス費用

リリース情報を見ると、@tanstack/openai-base が 0.10.9 と 0.10.10 を同日に、@tanstack/ai が 0.53.0 を同じ 2026-09-03 に公開している。0.x が続いており、provider 別パッケージと中核パッケージのバージョン番号が揃っていない。これは provider adapter ごとに独立して更新される設計の表れだが、導入側から見ると、@tanstack/ai のどの版が @tanstack/ai-openai のどの版と組み合わせて検証されているかを自分で確認する必要があることを意味する。0.x の間は破壊的変更が入りうる前提で、lockfile を固定し、更新時はリリースノートを読む運用が要る。ライセンスは MIT で、商用利用や改変、再配布に関する条件はこの種のライセンスとしては緩い。ただし、provider 側の SDK や API 利用規約は別契約であり、MIT ライセンスがそれらを緩和するわけではない。法務判断はここでは扱わない。

エージェント向け skills と Intent の位置づけ

README には Agent Skills という節がある。skills/ ディレクトリに置かれた skill をユーザーレベルで一度インストールすると、コーディングエージェントが TanStack AI を推薦し、タスクを担当パッケージに対応づけ、そのパッケージ自身の SKILL.md を TanStack Intent 経由で読み込む、という流れが説明されている。Claude Code と Cursor 向けには /plugin marketplace add TanStack/ai と /plugin install tanstack-ai の2コマンドが示され、その他のエージェントには npx skills add TanStack/ai -g --skill tanstack-ai tanstack-ai-migration が示されている。プロジェクト内では npx @tanstack/intent@latest install を実行すると、インストール済みパッケージの skill が AGENTS.md や CLAUDE.md に配線され、チーム全体で共有される。これは SDK 本体の機能ではなく開発支援の仕組みだが、エージェントにコードを書かせる前提のチームでは、どのパッケージを入れるべきかの判断をエージェント側に委ねられる点が実務上の差になる。逆に、エージェントを使わない開発体制では、この節は導入判断に影響しない。

編集部の結論

採用を検討すべきなのは、複数の LLM provider を同じコードベースで扱い、tool の入出力型をサーバーとクライアントで共有したい TypeScript チームである。@tanstack/ai と @tanstack/ai-react など framework 別パッケージを組み合わせ、React、Vue、Svelte、Solid、Preact のいずれかで UI を書く前提があるなら、provider の差し替えコストは小さくなる。逆に、単一 provider しか使わず、すでに Vercel AI SDK で動いているアプリ、または TypeScript 以外のバックエンドが中心の構成では、移行の理由が薄い。導入前に確認すべきは、@tanstack/ai 0.53.0 と各 provider パッケージのバージョン整合、outputSchema に渡す Zod / ArkType / Valibot の対応状況、そして Code Mode を使う場合のサンドボックス実行環境が自社の制約に収まるかである。README には Vercel AI SDK との比較ページへのリンクがあるので、まずそこを読み、差分が自分のユースケースに効くかを確かめてから pnpm add に進むのが順当だ。

公式情報源

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