在 AI SDK 的 README 里，同一个 generateText 可以写成 model: 'openai/gpt-5.4'，也可以写成 model: anthropic('claude-opus-4-6')。前者是默认走 Vercel AI Gateway 的 model 字符串写法，后者是直接安装 Provider SDK 包后的函数写法。对 TypeScript 全栈项目来说，这个差异不是语法糖，而是依赖、凭据和调用边界选择。

安装前提与 Provider 接入

README 明确要求本地开发机安装 Node.js 22+ 和 npm 或其他包管理器，核心包安装命令是 npm install ai。如果使用 Claude Code 或 Cursor，README 推荐运行 npx skills add vercel/ai，把 AI SDK skill 加入仓库。

统一 Provider 架构是 README 强调的能力。默认情况下，AI SDK 使用 Vercel AI Gateway 提供所有主要 provider 的访问，只需传 model 字符串。README 给出的示例包括 'anthropic/claude-opus-4.6'、'openai/gpt-5.4'、'google/gemini-3-flash'。如果不用 Gateway，也可以直接安装 @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google，然后从对应包导入 Provider，例如 import { anthropic } from '@ai-sdk/anthropic'，再写 model: anthropic('claude-opus-4-6')。README 还指向完整的 providers 列表。

这里有一个落地时要核对的点：README 中 Gateway model 字符串和直接 Provider 示例的模型命名并不完全一致，例如前者出现 anthropic/claude-opus-4.6，后者出现 claude-opus-4-6。实际项目不应凭记忆套用，而应以所用 Provider 包和 Gateway 文档为准。

从文本到结构化输出

generateText 在 README 中有两种结果消费方式。文本生成示例直接取 { text }；结构化数据示例则导入 Output，用 Output.object 配合 zod schema，从 { output } 取回对象。示例中的 schema 是一个嵌套的菜谱对象，包含名称、配料数组和步骤数组。

这个接口意味着：开发者可以把模型输出约束到 TypeScript 类型附近的 schema 中，但 README 没有说明校验失败、重试和错误映射策略。对生产代码而言，这些需要单独验证，不能假设 AI SDK 自动完成全部容错。

Agent 在 README 中的最小闭环

README 用 ToolLoopAgent 展示 Agent 构建。一个 shell Agent 示例配置了 model、system 和 tools。工具使用 openai.tools.localShell({ execute })；在 execute 中，示例调用 getSandbox()，注释标注为 Vercel Sandbox，再用 sandbox.runCommand({ cmd, args }) 执行命令并返回 stdout。另一个图像生成 Agent 使用 openai.tools.imageGeneration({ partialImages: 3 })，并导出 InferAgentUIMessage 类型。

从这些代码片段看，Agent 定义、工具定义和 UI 消息类型被放在同一个 TypeScript 模块中。ToolLoopAgent 负责组合模型、system prompt 和工具，InferAgentUIMessage 把 Agent 输出映射为 UI 可消费的消息类型。这是 README 示例展示的接口模式，不代表内部循环、状态机或调度实现。

服务端与 UI 的调用链

Next.js App Router 示例中，POST 路由导入 Agent，解析请求中的 messages，返回 createAgentUIStreamResponse({ agent, messages })。客户端组件使用 useChat()，遍历 message.parts，对 text 和 tool-generateImage 分别渲染。工具视图组件接收 UIToolInvocation>，根据 invocation.state 在 'input-available' 和 'output-available' 之间切换。

这条链可以概括为：Agent 定义在服务端，流式响应通过 createAgentUIStreamResponse 暴露，客户端通过 useChat 和 message parts 消费。对已有 Next.js/React 项目来说，这种模式接入成本较低；但 README 没有说明工具调用权限、审批、超时、重试、并发、状态持久化、可观测性和多 Agent 编排。这些属于需要进一步验证的工程边界。

UI 集成与框架边界

AI SDK UI 模块提供一组 hooks，用于构建聊天机器人和生成式 UI。README 明确说这些 hooks 是 framework agnostic，可用于 Next.js、React、Svelte 和 Vue，并按框架安装对应包，例如 npm install @ai-sdk/react。README 开头列出的支持框架还包含 Angular，但 UI hooks 段落没有列出 Angular，实际集成时需以对应包的可用性和文档为准。

落地前检查项

  • 运行环境是否为 Node.js 22+，是否使用 npm 或其他包管理器。
  • 选择 Gateway model 字符串还是直接 Provider 包；核对模型标识、凭据和配额来源。
  • 直接 Provider 路径需要安装哪些 @ai-sdk/* 包，版本如何锁定。
  • 结构化输出是否准备了 zod schema，以及校验失败后的处理策略。
  • Agent 工具的 execute 返回值是否与 UI 的 UIToolInvocation 状态一致。
  • 服务端流式响应、客户端 useChat 和 message parts 类型是否匹配。
  • 工具权限、沙箱边界、超时、重试、持久化和可观测性是否已单独设计。
  • 目标框架是否在 README 明确列出的 UI 支持范围内。

基于 README 能确认的事实，vercel/ai 是一个 provider-agnostic TypeScript toolkit，面向 AI 应用和 Agent，支持 Next.js、React、Svelte、Vue、Angular 等 UI 框架和 Node.js runtime。它把多 Provider 接入分成 Gateway model 字符串和直接 Provider 包两条路径，并用 ToolLoopAgent、createAgentUIStreamResponse、useChat、UIToolInvocation 等接口串起 Agent 与 UI。要从示例走向生产，仍需要围绕上述检查项补齐资料未覆盖的工程细节。