TanStack AI：不绑定 Next.js 的 TypeScript Agent SDK
阅读时间: 大约 9 分钟
TanStack AI：不绑定 Next.js 的 TypeScript Agent SDK
TanStack（TanStack Table / Query / Form 家族）推出 TanStack AI，一个面向 TypeScript 的 AI 功能与 Agent 构建库：内置 Agent 循环、provider 适配器、持久化、中断（interrupts）、沙箱与工具，接入用户已有的服务端、数据库与 UI。官网当前标注为 RC（候选发布）。本文基于官网内容，解析其设计取向、机制与局限。
一、定位：与 Vercel AI SDK 错位
Koala 周报的观察是：Vercel AI SDK 借 Next.js 生态取得先机，但不断向商业产品绑定；TanStack AI 作为开源社区的回应，主打”无厂商锁定”——不强制 Next.js，支持 React、Solid 与原生 JS，把 OpenAI、Anthropic 等不同模型接口统一，并提供类型安全的工具调用与”思考”类模型（thinking parts）支持。官网首页直接给出”Compare with Vercel AI SDK”入口，错位意图明确。
官网展示的体量口径：累计下载 2.4M、周下载 905,903、GitHub 约 3.2k star（均为官网展示数字，会随时间变动）。
二、核心机制
1. AG-UI 双向合规
客户端发送 AG-UI 请求、消费 AG-UI 事件，因此另一端的 Agent 可替换：同一个客户端指向 Python、Go 或 PHP 运行时也能工作，传输层自带（bring your own transport）。AG-UI 位于 Web 应用与 AI 端点之间，服务端再对接 OpenAI / Anthropic 等 provider。
2. 类型化模型选项
选中模型后 TypeScript 收窄该模型支持的字段：chat 的输入部件、图像模型的像素尺寸、视频模型的时长与档位、世界模型的分辨率，错误值在编辑器阶段暴露而不是等到生产环境。
3. 一次定义、两端运行的工具
一个 schema 同时给出服务端与客户端的输入/输出类型；循环调用工具、在需要时等待批准、把用户编辑结果回喂模型。needsApproval: true 的工具（如 lookup_invoice）会进入批准中断状态，服务端实现用同一个类型化 id 更新数据库，模型本身看不到凭证。
4. 你自己的 UI：消息即 parts
文本、思考、工具调用与结果都是带状态的类型化 part（awaiting-input → input-streaming → input-complete → approval-requested → approval-responded → complete），开发者遍历 parts 自行渲染，或用 createChatHook 按 part 类型分派组件。
5. 持久化与可恢复流
持久化只有两个函数（加载/保存一个 thread），配合 ai-persistence skill 接到自有表与 ORM（PostgreSQL/MySQL/SQLite/MongoDB/D1/Redis，Drizzle/Prisma/localStorage/IndexedDB）。流式耐久性：每个 chunk 先写日志再投递，连接断开或刷新页面时客户端从最后偏移重放，而不是丢失模型回答。
6. 模块化能力包
代码模式（@tanstack/ai-code-mode：模型把工具链成一个脚本在 isolate 里跑，替代每调用一次工具就一次模型往返）、编码 Agent 沙箱（@tanstack/ai-sandbox：在本地进程或沙箱里跑 Claude Code、Codex 或任意 ACP agent，活动流回为 UI 已能渲染的事件）、类型化 MCP 客户端（@tanstack/ai-mcp，带生成类型的 CLI，工具结果可渲染交互组件）、跨会话记忆与长线程压缩（@tanstack/ai-memory / @tanstack/ai-compaction，经 Redis、mem0、Honcho、Hindsight 召回，压缩把长线程压回模型窗口），各自独立成包，按需加载。此外同一套适配器与持久化覆盖图像、视频、语音转写（带词时间戳与说话人分离）、实时语音（OpenAI/Grok/ElevenLabs，含 VAD 与会话内工具调用）、世界模型与直播视频（WebRTC 推入浏览器）等模态，并内建进度更新与成本追踪。
7. Devtools 时间线
官网提供 TanStack devtools：服务端与客户端每一次工具调用、中断、记忆召回、finish reason 都落在同一条时间线上，便于定位”模型为什么没批准工具""记忆注入了哪些事实”这类问题。官网示例中一次退款流程可看到记忆召回注入 3 条事实（214 token）、lookupInvoice 工具调用、chargeCard 进入等待批准中断、run 可恢复等节点。
三、与 Vercel AI SDK 的错位
Koala 周报的判断是：Vercel AI SDK 借 Next.js 取得先机，但不断向商业产品与自家服务绑定；TanStack AI 作为开源社区回应，强调自有数据库、自有服务端、自有 UI，AG-UI 协议让后端运行时可替换。需要客观说明：这种错位主要体现在”立场与依赖”上，能力集（流式、工具、持久化、多模态）两者都在覆盖，选型差异更多来自团队现有技术栈与对锁定的容忍度，而非某一方独有某项功能。
四、局限与口径
- RC 阶段：官网标注 RC，API 仍可能调整，生产选型要预留升级成本；
- 下载量口径需复核：2.4M / 905,903 周下载为官网页面展示值，包名拆分为多个子包后汇总口径未公开，横向对比 Vercel AI SDK 时应分别核对 npm；
- “无锁定”是架构承诺而非零成本：AG-UI 可替换后端，但一旦深度使用其 parts 模型、工具契约与
createChatHook，迁回其他 SDK 仍需重写渲染层； - 生态年轻：约 3.2k star、RC 状态，文档与第三方示例数量不及成熟 SDK，坑要自己填；
- 多模态与沙箱为分层能力：图像/视频/世界模型、code-mode isolate、MCP 等是独立子包，不是核心开箱即用，选型时别把整包能力当成默认包含。
五、优势与适合谁
优势： 类型贯穿模型选项、工具输入输出与 UI 渲染，TS 项目内自洽；持久化与流式耐久把常见的”刷新丢对话、断线丢回答”做成默认能力；不绑定框架与 provider；模块化按需裁剪。
适合： 已经在 TypeScript 技术栈、被 Vercel AI SDK 的 Next.js 倾向约束、需要自管数据库与会话状态的团队；需要把 Agent 后端换成非 Node 运行时、只保留前端客户端的场景。不适合追求”最快跑通一个 demo”的新手，RC 阶段也不建议直接押注关键业务。