vercel/ai 是 Vercel 维护的开源仓库，仓库描述称其为 provider-agnostic TypeScript toolkit，用于构建 AI 应用与 Agent，由 Vercel 与 Next.js 团队成员创建，并有开源社区贡献。README 正文给出的安装前提是 Node.js 22+ 与 npm（或其他包管理器），安装命令为 npm install ai。此外，若使用 Claude Code、Cursor 这类编码 Agent，README 建议执行 npx skills add vercel/ai，把 AI SDK skill 加入仓库。

说明：仓库 stars、forks、提交次数等元数据会随时间漂移，本文不引用具体数值；如需引用，请以 GitHub 仓库首页当日快照为准。

两条接入路径，汇合在 model 字段

README 强调的核心设计是 unified provider architecture：AI SDK 提供 unified API 对接 OpenAI、Anthropic、Google 等模型 provider，并给出两种接入方式。

第一种是默认走 Vercel AI Gateway，不引入 provider 包，直接传模型字符串：

const result = await generateText({
  model: 'anthropic/claude-opus-5.5',
  prompt: 'Hello!',
})

README 注释中还举出 'openai/gpt-6-astra'、'google/gemini-3.8-flash' 等字符串作为示例。

第二种是直连 provider，安装对应 SDK 包：

npm install @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google

import { anthropic } from '@ai-sdk/anthropic'
const result = await generateText({
  model: anthropic('claude-opus-5-5'),
  prompt: 'Hello!',
})

两条路径的汇合点是 generateText 的 model 参数：它既接受模型字符串，也接受 provider 函数调用返回的模型对象。该结论由 README 两组示例归纳得出，具体可接受的类型以官方 API Reference 为准。这是多 Provider 接入在调用入口层面的组织方式，也是切换 provider 时改动面最小的位置。

Provider 差异被收在命名空间之下

统一 API 之外，README 为 provider 特有能力保留了位置。Agent 示例用 ToolLoopAgent 构造器传入 model、system 与 tools，其中 shell 工具写成 openai.tools.localShell({ execute })，图片生成示例写成 openai.tools.imageGeneration({ partialImages: 3 })。也就是说，跨 provider 的通用调用走 generateText 与 ToolLoopAgent，provider 独有的工具能力通过 openai.tools.* 这类命名空间暴露。对开发者而言，这部分能力并不随统一 API 平移。

类型约束出现在哪几层

README 示例集中展示了几个类型推导点：

  • 结构化输出：Output.object({ schema: z.object({...}) }) 与 zod 配合，由 schema 约束生成结果的形状。
  • Agent 消息类型：InferAgentUIMessage，从 Agent 实例反推 UI 侧消息类型。
  • 工具调用状态：组件侧 UIToolInvocation>，在 switch 中区分 'input-available' 与 'output-available'，并从 invocation.output.result 取结果。
  • 路由层：createAgentUIStreamResponse({ agent, messages }) 在 Next.js App Router 的 POST 处理函数中，把 Agent 的响应返回给 UI。

类型链主要由泛型与 ReturnType 推导；结构化输出还会借助 zod schema 参与输出解析与校验，两者作用不同，需分别以官方 API Reference 为准。因此类型链能否闭合，取决于所用 provider 包的类型定义与实际行为是否一致，这是接入时需要自行确认的工程点。

UI 层与仓库结构

AI SDK UI 提供一组 hooks。README 明确写明这些 hooks 是 framework agnostic，可用于 Next.js、React、Svelte 与 Vue，使用时需安装对应框架的包，例如 npm install @ai-sdk/react，页面侧通过 useChat() 拿到 messages、status 与 sendMessage。

仓库文件树中可见 packages、examples、apps/docs 等目录（以当日仓库文件树快照为准）。更细的目录与文件清单请以仓库文件树快照为准，本文不逐一列举。

接入前值得确认的几件事（工程分析）

以下为工程分析，不是官方结论：

  1. 接入路径决定治理面。走 Vercel AI Gateway 时只传模型字符串，provider 的鉴权、配额与路由策略由网关侧承担；直连 provider 时，这些需要由自己的基础设施承接。切换成本低，不代表运维成本低。（需官方文档/源码验证）
  2. provider 特有能力是迁移的硬边界。localShell、imageGeneration 这类 provider.tools.* 入口无法直接换到另一家 provider，跨模型迁移前要先确认目标 provider 是否覆盖所需工具能力。（需官方文档/源码验证）
  3. 类型安全需要验证运行时对齐。示例中的推导链依赖 provider 包类型，建议先用最小示例跑通 generateText、ToolLoopAgent 到 UI hook 的完整链路，再决定目录组织。
  4. 版本与运行时约束。Node.js 22+ 是 README 明示的前提；provider 包与主包 ai 的版本匹配关系，需要以官方文档与 API Reference 为准。

对已在 TypeScript 技术栈上的团队，这个库的价值在于把多 provider 调用、结构化输出、Agent 工具调用与 UI hooks 放进同一套类型体系；代价是在 provider 特有能力、接入路径治理与版本对齐上，需要按自身技术栈逐项验证。