从 Vercel AI SDK 的 README 看 TypeScript Agent 开发的工程选型

从一段代码开始：模型字符串背后是两层设计

如果你打开 Vercel AI SDK 的 README，先看到的代码大概率长这样：

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

如果一个调用接口同时接受 anthropic/claude-opus-4.6、openai/gpt-5.4、google/gemini-3-flash，它背后必然存在两层设计：

第一层是模型字符串路由，由 Vercel AI Gateway 处理
第二层是npm 包直连，通过 @ai-sdk/openai、@ai-sdk/anthropic、@ai-sdk/google 等 SDK 包直连各家 Provider

README 对这两种方式都给出了明确示例。这种双路径设计是 AI SDK 的一个关键工程特征：开发者在早期原型阶段可以写字符串走网关，在生产阶段换成熟 Provider SDK 包时，业务代码只需改动 model 的传入方式，generateText 的结构不会变。

README 明确公开的能力边界

README 是官方文档的浓缩入口。基于它实际写出的内容，Vercel AI SDK 公开了以下事实：

1. 定位：provider-agnostic 的 TypeScript 工具包

README 的原话是 “provider-agnostic TypeScript toolkit”，面向的框架包括：

Next.js
React
Svelte
Vue
Angular

运行时则明确提到 Node.js，并且安装条件写得很清楚：Node.js 22+。

这意味着如果你还在 Node.js 18 或 20 的 LTS 版本上维护旧项目，接入 AI SDK 之前需要先处理运行时升级。这是 README 直接给出的硬约束，不是推测。

2. 安装与辅助工具

安装命令很简单：

npm install ai

针对 Claude Code、Cursor 这类编码 Agent，README 额外提供了一个 skill 安装入口：

npx skills add vercel/ai

它的作用是让编码 Agent 在仓库中获得 AI SDK 的 skill 配置。对正在用 Cursor 或 Claude Code 写 AI 应用的团队来说，这是一个值得注意的效率选项。

3. 结构化输出：不是简单 JSON mode

README 展示的结构化数据生成示例使用了 Output.object 配合 Zod schema：

const { output } = await generateText({
  model: 'openai/gpt-5.4',
  output: Output.object({
    schema: z.object({
      recipe: z.object({
        name: z.string(),
        ingredients: z.array(
          z.object({ name: z.string(), amount: z.string() }),
        ),
        steps: z.array(z.string()),
      }),
    }),
  }),
  prompt: 'Generate a lasagna recipe.',
});

这个 API 的设计意图不是让大模型“尽量返回 JSON”，而是通过类型 schema 在 TypeScript 侧获得完整的类型推导和相关校验。对工程团队来说，这类接口有助于减少手写解析层和运行时断言代码。

4. Agent：ToolLoopAgent 是当前 README 的主推形态

在 Agent 部分，README 展示了一个名为 ToolLoopAgent 的类：

import { ToolLoopAgent } from 'ai';

const sandboxAgent = new ToolLoopAgent({
  model: 'openai/gpt-5.4',
  system: 'You are an agent with access to a shell environment.',
  tools: {
    shell: openai.tools.localShell({
      execute: async ({ action }) => {
        const [cmd, ...args] = action.command;
        const sandbox = await getSandbox();
        const command = await sandbox.runCommand({ cmd, args });
        return { output: await command.stdout() };
      },
    }),
  },
});

注意，这个示例里没有 messages 历史参数，也没有“循环次数上限”之类的配置。ToolLoopAgent 对 Tool Calling 的执行封装成循环，并且 openai.tools.localShell 这类工具函数是与具体 Provider SDK 绑定的。还有一点值得留意：示例里同步出现了 Vercel Sandbox，这暗示 README 中“内置工具”运行环境可能和 Vercel 平台存在依赖，但 README 并没有对这一层做更多细节说明。

如果要在自己的项目里使用 ToolLoopAgent，应先去官方 API Reference 确认它目前暴露了哪些构造参数和行为配置，而不是只看 README 示例就默认它能满足所有 Agent 循环控制需求。

5. Agent UI：一个完整的端到端示例

README 还展示了一个有趣的组合：图片生成 Agent 从服务端到 React 组件的完整链路。

服务端 Agent 定义：

import { openai } from '@ai-sdk/openai';
import { ToolLoopAgent, InferAgentUIMessage } from 'ai';

export const imageGenerationAgent = new ToolLoopAgent({
  model: 'openai/gpt-5.4',
  tools: {
    generateImage: openai.tools.imageGeneration({
      partialImages: 3,
    }),
  },
});

export type ImageGenerationAgentMessage = InferAgentUIMessage;

Next.js App Router 路由：

import { imageGenerationAgent } from '@/agent/image-generation-agent';
import { createAgentUIStreamResponse } from 'ai';

export async function POST(req: Request) {
  const { messages } = await req.json();
  return createAgentUIStreamResponse({
    agent: imageGenerationAgent,
    messages,
  });
}

客户端 React 组件通过 useChat 消费流式消息，并对工具类型做 UI 分发：

switch (part.type) {
  case 'text':
    return {part.text};
  case 'tool-generateImage':
    return ;
}

这套流程的关键在于类型：InferAgentUIMessage 从 Agent 定义推断出消息类型，UIToolInvocation 泛型则将工具调用信息传给 UI 组件。也就是说，Agent 的工具输出不仅是运行时数据，还能成为 TypeScript 类型层面的 UI 契约。这对团队协作的价值很明显：后端 Agent 增加了新工具，前端的消息类型会自动“暴露”变更，减少协议不同步的问题。

当然，这里还有一个官方 README 明确提到的限制：AI SDK UI 模块是框架无关的，但要想使用它，需要先安装对应框架的包：

npm install @ai-sdk/react

React、Svelte、Vue 各自有对应包，README 只明确给了 React 的安装命令。其他框架的包名与具体 hooks 支持程度，仍需到官方文档中进一步确认。

对选型者来说，哪些是事实，哪些需要进一步验证

已知事实

AI SDK 是一个 provider-agnostic 的 TypeScript 工具包，支持 Next.js、React、Svelte、Vue、Angular，运行时要求 Node.js 22+
可以通过 Vercel AI Gateway 用模型字符串访问多家模型；也可以通过 @ai-sdk/* 包直连 OpenAI、Anthropic、Google 等 Provider
README 展示了 generateText、Output.object 结构化输出、ToolLoopAgent 等 API
提供 @ai-sdk/react 等 UI 集成包，README 中的 UI 示例基于 Next.js App Router 和 useChat

官方资料没有直接说明的部分

生成式 UI 对 React/Svelte/Vue 三个框架的支持深度：README 只展示了一个 Next.js/React 的图片生成组件示例，没有逐框架列出 hooks 差异
ToolLoopAgent 的执行控制细节：没有说明循环上限、停止条件、中间状态回调、错误恢复策略等参数
本地 Shell 工具的沙箱方式：示例调用 Vercel Sandbox，但 README 没有展开说明它是否只支持 Vercel 环境，或者是否有本地可用的隔离方案
AI Gateway 模式和大规模生产环境的成本与延迟行为：README 没有给出任何性能数据或计费方式

这些内容不能从 README 推导出来，需要在官方 API Reference 或源码中进一步核实。

工程判断：这套 SDK 适合解决什么问题

从标准出发，对三类团队来说 AI SDK 的“形状”比较明确：

1. 正在做多模型接入 PoC 的团队

如果团队处于“哪个模型效果更好”的验证阶段，AI SDK 的模型字符串+统一 API 能显著降低切换成本。README 中 generateText 从 openai/gpt-5.4 改到 anthropic/claude-opus-4.6 只改一个字符串，这种体验对快速对比模型结果很有价值。

但要注意：生产环境直接依赖 AI Gateway 还是需要评估网络链路和企业合规要求。如果不希望所有请求都经过 Vercel 的网关，也可以改用各 Provider SDK 包，但这些包的行为是否与字符串方式完全等价，需要逐一验证。

2. 在 Next.js 技术栈上构建 Agent 交互应用的团队

README 的 UI 示例展示了一条完整的链路：服务端 Agent 定义 → 流式响应 API → useChat 消费 → 前端类型推断。如果你的应用本身就是 Next.js，这套机制省去的是前后端协议设计工作。而且 InferAgentUIMessage 提供的是“Agent 与 UI 在类型层面同步”的开发模式，这在现有 Agent 框架中比较少见。

值得强调的是，该示例实现的是“Agent 生成图片并让前端渲染图片”，而不是简单的流式文本。这意味着 AI SDK 在 Agent 工具产生的多模态 UI 结果上已经提供了直接的编码路径。

3. 需要结构化输出稳定性的团队

Output.object + Zod 的写法把“大模型非结构化输出”变成“TypeScript 可校验的类型”，而不是让每个业务方自己写解析和校验。这种约束对数据质量要求高的场景有实际工程价值。

从源码层面评估它的实践方式

如果想在深入使用之前自行评估 AI SDK 的工程质量，有三个看得见的入口：

1. 看包结构

在 node_modules 中查看 ai 包的导出和 @ai-sdk/* 系列包的划分。重点观察核心抽象层和 Provider 适配层是否分离干净。一个良好的 provider 抽象，应当允许你替换 Provider 包时不需要修改业务调用逻辑。

2. 看 pull request 与社区交流密度

Vercel Community 设有专门的 AI SDK 分类，README 也明确将社区入口指向那里。可以观察官方对 issue 的回应速度、不兼容变更的管理方式。对基础库来说，破坏性变更处理得是否规范，直接影响团队升级成本。

3. 跑通 README 中与自己场景最近的示例

如果是做 Agent，就跑 ToolLoopAgent 的示例；如果是做对话应用，就跑 useChat 的示例。README 已经给出了安装命令和最小代码路径，把示例跑通是成本最低的验证方式。

结论

Vercel AI SDK 在 TypeScript Agent 开发中的定位可以概括为：一个试图统一应用层 AI 接入方式的工具包。它把模型调用、Provider 切换、结构化输出、Agent 工具循环、UI 流式消息串成了一套相对完整的 TypeScript API。

对已经在 Next.js 技术栈上的团队，它天然亲和；对需要多模型快速比对的团队，它的统一入口能减少早期实验成本；对运行环境不在 Node.js 22+、或者不希望依赖 Vercel 生态的团队，则需要先验证边界，再决定是否引入。

现在它真正值得做的是：用它跑通一个与你业务最接近的 PoC，然后在真实负载下观察类型推导、错误信息和迭代速度是否符合预期。