AI应用SDK选型：协议、类型与持久化

给 Next.js 项目选 AI SDK，作者的默认答案是 Vercel AI SDK 7；如果更看重开放协议、按模型约束参数，以及前后端共用工具定义，他会选 TanStack AI。决定选型的，是客户端接收什么消息、类型检查能覆盖多远，以及服务重启后任务能否继续。

这份比较有个清楚的边界：作者检查了安装包和文档，没有实际调用模型。它适合用来梳理架构取舍，但不能当作性能、稳定性或生产恢复能力的实测报告。

换 SDK 最贵的部分，藏在聊天界面里

作者在 2026 年 11 月 2 日安装两套依赖：ai 为 7.0.159，有 181 个顶层导出；@tanstack/ai 为 1.0.1，有 205 个。导出数量只能说明接口规模，不能直接证明谁更完整。

两者的服务端调用很像：streamText() 对应 chat()，generateText() 对应 chat({ stream: false })，generateObject() 对应 chat({ outputSchema })。只看路由处理函数，迁移似乎就是替换几个名字。

真正分叉的是传输协议。TanStack AI 原生使用 AG-UI，通过有类型的事件描述文本增量、工具调用、状态变化和任务生命周期。Vercel AI SDK 使用自己的 UI Message Stream，周边有 @ai-sdk/react、AI Elements，以及大量模板。接入 AG-UI 则需要外部桥接包。

协议会进入消息组件、工具审批界面、断流恢复逻辑，甚至数据库里的聊天记录格式。服务端调用容易替换，客户端对消息格式的依赖才是迁移的大头。

依赖树也透露了默认方向：ai 直接依赖 @ai-sdk/gateway，使用 'openai/gpt-5' 这样的字符串模型标识时，会通过 Gateway 解析；TanStack 核心直接依赖的是 @ag-ui/core。前者方便接入平台服务，后者优先统一通信协议，但开放协议同样要承担生态规模较小的成本。

作者估计，路由改写可能不到一小时，完整聊天产品则要按天计算。这是经验估算，没有迁移项目的对照记录。TanStack 1.0 还要求客户端和服务端显式提供 threadId，两端都不会自动生成，迁移时必须补齐。

类型检查和工具定义，谁更贴近复杂产品

Vercel AI SDK 已经能检查工具输入、UI 消息片段和供应商参数。v7 支持 Zod 3.25+、Zod 4，以及兼容 Standard Schema 的校验器；渲染端可用 isToolUIPart(part) 收窄类型。

TanStack 多走了一层：按照具体模型约束选项。模型不支持的推理控制、内容类型或生成参数，尽量在编译阶段报错。它还用 InferChatMessages 从服务端定义推导 useChat 的消息类型，让工具输出字段改名有机会直接打断前端构建。AI SDK 也能通过泛型 UIMessage 描述消息，但需要开发者手动连接类型。

工具执行位置也是差别。AI SDK 的 tool() 通常定义服务端执行函数，客户端工具另外通过传输层和 onToolCall 处理。TanStack 用 toolDefinition() 定义一次结构，再通过 .server(fn) 或 .client(fn) 绑定执行位置。对于同时包含「查询数据库」和「高亮页面某行」的产品，这种组织方式更集中。

下面这段原文代码展示了 AI SDK 如何限制工具循环：

// Vercel AI SDK 7: the model is a value, the loop is an option
import { streamText, tool, stepCountIs } from 'ai';
import { openai } from '@ai-sdk/openai';

const result = streamText({
  model: openai('gpt-5'),
  tools: { weather: tool({ /* ... */ }) },
  stopWhen: stepCountIs(5),
});

重点看 stopWhen: stepCountIs(5)：循环通过停止条件控制；工具中的 /* ... */ 是占位内容，这不是完整可运行示例。TanStack 对应的是 agentLoopStrategy: maxIterations(5)，也提供 untilFinishReason(...) 和共享配置的 createChatOptions。

AI SDK 另有 ToolLoopAgent，把指令、工具和运行上下文封装为对象。作者偏爱 TanStack 的函数和策略组合，理由是方便测试，但没有给出测试维护成本的比较。

结构化输出也需要按产品判断：AI SDK 用 generateObject、streamObject 或 Output.object() 返回结果，适合提取、分类等一次性任务；TanStack 的 chat({ outputSchema }) 把对象作为消息片段留在历史中，更适合用户持续修改同一张表或同一份结构化内容的对话。

上生产要看的，是失败之后怎么收场

作者把生产默认票投给 Vercel，主要依据是恢复能力、观测和控制机制。

长任务方面，@ai-sdk/workflow 中的 WorkflowAgent 会在步骤之间持久化执行状态。按原文描述，它已经 GA，可以跨部署、进程重启和长时间审批继续运行，代价是接受 Workflow SDK 的执行模型及平台假设。这个能力来自额外的 Workflow 集成，不能理解为普通 streamText() 自动具备持久性。

TanStack 1.0 核心支持任务脱离、记录日志、由其他进程接管和清理孤立任务，设计面向 11 个 sandbox provider。上层 @tanstack/ai-harness 提供线程会话日志、跨重启审批等待和运行中干预，但仍是实验性的 0.x。原文明示，子 Agent 等待仍有内存状态无法跨主机恢复的限制。

审批方面，两者都有 needsApproval；TanStack 支持批量审批和中断后恢复。AI SDK 7 进一步提供审批策略函数，以及可选的 HMAC 签名，把批准的工具输入绑定到审批令牌，并在恢复前重新验证输入和策略。

观测方面，AI SDK 7 通过 registerTelemetry(new OpenTelemetry()) 统一注册追踪，覆盖步骤、工具执行和用量，还记录首次输出耗时、每秒 token 数等指标。TanStack 有 ./middlewares/otel 和贯穿整个运行过程的中间件，withPersistence、memoryMiddleware 也建立在这套扩展点上，客户端与服务端共用的 devtools 时间线则更偏向开发调试。

错误与超时同样影响排障。AI SDK 提供 APICallError、RetryError、InvalidToolInputError、ToolCallRepairError、InvalidToolApprovalSignatureError、NoObjectGeneratedError 等分类，以及总任务、单步骤、单数据块、单工具超时和 TimeoutError。作者在 TanStack 1.0 核心导出中没有找到同等统一的超时接口；这不能推导为应用无法自行实现超时。

两者都支持不用真实模型的测试：AI SDK 的 ai/test 提供 MockLanguageModelV3、simulateReadableStream；TanStack 的 @tanstack/ai/testing 提供 fakeText()、FakeTextAdapter。作者验证了前两项能够导入，没有执行真实模型对比。

我的判断

我赞同把协议和故障处理放到选型前面。前端一旦积累大量消息组件，仅封装服务端函数，并不能隔离协议迁移成本。

但原文的「更成熟」需要拆开看。Vercel 每周超过 1600 万次下载来自厂商统计，能说明使用规模，不能证明某条恢复路径可靠。「最完整的 TypeScript AI 持久化方案」也是作者判断，文中没有故障注入、重启恢复或性能对照实验。

版本条件则很具体：按作者检查的 engines，ai 要求 Node 22+，TanStack 支持 Node 18+。运行环境固定在 Node 18 或 20 的团队，选择范围可能直接收窄。

维护成本也不能忽略。AI SDK 在 2025 年发布 v5，2025 年 12 月 22 日发布 v6，2026 年 6 月 25 日发布 v7，本轮提供 npx @ai-sdk/codemod v7。大约半年一次大版本，是需要预算的工作。TanStack 于 2026 年 10 月 23 日发布 1.0，承诺核心 API 稳定，但团队只有 3 位维护者、143 位贡献者，且 harness 不在稳定承诺内。

另外，TanStack 可以用于 Next.js，也支持 9 种框架绑定。是否采用 Next.js 可以影响选择，却不足以单独决定选择。已有 AI SDK 前端的项目，继续使用通常比为了接口偏好迁移更划算。

能拿来做什么

• 新建聊天功能时，先列出消息片段、工具审批、历史存储和断流恢复需要消费哪些事件，再选协议。这样能提前发现 UI 与 SDK 的绑定位置。
• 在项目内建立一个薄模块，集中管理模型选择、工具定义和聊天调用；同时明确哪些客户端组件仍依赖 SDK 消息类型，避免高估封装的隔离能力。
• 涉及代码合并、数据删除等工具时，把审批、超时和恢复作为验收项目。用两套 SDK 的测试适配器覆盖工具输入错误与异常分支，再单独验证部署重启后的行为。
• 普通问答和短请求可以先不引入持久化 Agent。确实需要跨重启运行时，再评估 Workflow 的执行约束，或 TanStack harness 当前公开的恢复限制。