Agent 框架 12:Vercel AI SDK——全栈 TypeScript 智能体开发实战

在 AI 智能体开发的日常中,许多算法或后端团队常常遇到这样一个工程瓶颈:在 Jupyter Notebook 或本地终端里,Agent 的多轮调用和工具派发跑得非常顺畅;但一旦业务方要求将这个 Agent 交付为一个具有丝滑打字机动效、能随时中断流式响应、支持多端适配的现代化 Web 生产系统时,工程复杂度立刻指数级上升——前后端 SSE 协议解析、流式数据反序列化、状态与输入框防抖管理、React 渲染抖动等细节让人焦头烂额。

Vercel AI SDK(npm 包名 ai)正是为了终结这种前后端断层而生。作为现代 Web 全栈开发领域最流行、增长最快的开源 AI 框架,它以 TypeScript 强类型保证、流式优先(Stream-first)和框架无关(Framework Agnostic) 为设计核心,彻底打通了大模型与 Web 前端交互的“最后一公里”。


核心分层架构体系

Vercel AI SDK 在架构上划分为三个高度正交的清晰层次:

核心层级权责

分层模块 引入方式 核心职责
AI SDK Core import { generateText, streamText } from 'ai' 服务端通用底座,负责与各大模型 API 交互、Zod 结构化校验与多步工具执行
AI SDK UI import { useChat, useCompletion } from 'ai/react' 前端状态驱动层,将复杂的流式接收、消息历史与加载态封装为一行 Hook
AI SDK RSC import { streamUI } from 'ai/rsc' 深度适配 React Server Components,支持从服务端直接流式传输渲染后的 React 组件

安装与多模型 Provider 配置

安装核心库及所需的模型供应商驱动包:

1
2
# 核心编排库与常见模型供应商
npm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google zod

AI SDK Core 服务端核心 API

1. 流式文本生成(streamText)

在 Node.js 或 Edge Runtime 中,通过 streamText 获取可异步迭代的流:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";

async function runStreaming() {
const result = await streamText({
model: openai("gpt-4o-mini"),
system: "你是一名资深全栈工程师,回答精准干练。",
prompt: "请解释 React 19 的 Server Actions 对前后端通信范式带来了什么改变?",
});

// 服务端控制台直接流式消费
for await (const textChunk of result.textStream) {
process.stdout.write(textChunk);
}
}

2. 强类型结构化输出(generateObject)

结合 TypeScript 最流行的验证库 Zod,大模型可以直接输出 100% 满足类型定义的结构化 JSON,免去任何手动正则提取与类型断言:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import { generateObject } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { z } from "zod";

// 声明严格的返回 Schema
const ServerMetricsSchema = z.object({
serviceName: z.string().describe("微服务名称"),
healthStatus: z.enum(["HEALTHY", "DEGRADED", "DOWN"]),
cpuUsagePercent: z.number().describe("CPU 占用百分比 (0-100)"),
criticalAlerts: z.array(z.string()).describe("告警事件摘要"),
});

type ServerMetrics = z.infer<typeof ServerMetricsSchema>;

async function inspectServer() {
const { object } = await generateObject({
model: anthropic("claude-3-5-sonnet-20241022"),
schema: ServerMetricsSchema,
prompt: "生产集群的结算中心服务目前延迟飙升至 2500ms,内存已达 88%,生成审计快照。",
});

// object 自动具备 ServerMetrics 完整 TypeScript 类型提示
console.log("解析出的状态:", object.healthStatus);
console.log("告警列表:", object.criticalAlerts);
}

3. 多步自主工具调用闭环(maxSteps)

在过去,让大模型调用工具往往需要自己写一个 while 循环不断判断 stop_reason。在 Vercel AI SDK 中,只需声明 tools 并配置 maxSteps,框架会在底层自动完成“思考 -> 调工具 -> 观察结果 -> 再思考”的完整 ReAct 循环:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
import { generateText, tool } from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";

const { text, steps } = await generateText({
model: openai("gpt-4o"),
tools: {
getWeather: tool({
description: "查询指定城市的当前天气",
parameters: z.object({
city: z.string().describe("城市名,例如:北京、上海"),
}),
execute: async ({ city }) => {
// 实际业务逻辑或第三方 API 调用
return { city, temperature: 24, condition: "Sunny" };
},
}),
computeExpression: tool({
description: "执行高精度数学运算",
parameters: z.object({
expression: z.string().describe("数学算式,例如 '120 * 4.5'"),
}),
execute: async ({ expression }) => {
return { result: eval(expression) };
},
}),
},
// 核心:允许大模型在一次请求内最多自主迭代 5 步
maxSteps: 5,
prompt: "先帮我查一下北京今天的天气,然后算一下 120 乘以 8 等于多少。",
});

console.log("Agent 最终综合答复:\n", text);
console.log(`总共自主经历了 ${steps.length} 轮工具决策交互。`);

Next.js App Router 生产级端到端实战

下面演示如何在 Next.js 现代化全栈架构中,用极少的代码构建一个工业级流式对话界面。

1. 后端路由处理函数(app/api/chat/route.ts)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";

// 选用 Edge Runtime 获得更低冷启动延迟
export const runtime = "edge";

export async function POST(req: Request) {
const { messages } = await req.json();

const result = await streamText({
model: openai("gpt-4o-mini"),
system: "你是一名精通现代前端工程的虚拟助手。",
messages,
});

// 转化为符合 Vercel AI 规范的 SSE 数据流响应
return result.toDataStreamResponse();
}

2. 前端客户端页面(app/chat/page.tsx)

客户端直接引入 useChat,无需手动管理 fetch、ReadableStream 或 WebSocket:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
"use client";

import { useChat } from "ai/react";

export default function ChatView() {
const { messages, input, handleInputChange, handleSubmit, isLoading, stop } =
useChat({
api: "/api/chat", // 后端流式接口地址
});

return (
<div className="max-w-2xl mx-auto p-4 flex flex-col h-screen">
<div className="flex-1 overflow-y-auto space-y-4 mb-4">
{messages.map((m) => (
<div
key={m.id}
className={`p-3 rounded-lg ${
m.role === "user"
? "bg-blue-600 text-white ml-auto max-w-[80%]"
: "bg-gray-100 text-gray-900 mr-auto max-w-[80%]"
}`}
>
<p className="text-xs font-bold mb-1">
{m.role === "user" ? "我" : "AI 助手"}
</p>
<div className="whitespace-pre-wrap">{m.content}</div>
</div>
))}
</div>

<form onSubmit={handleSubmit} className="flex gap-2">
<input
value={input}
onChange={handleInputChange}
placeholder="请输入你的技术问题..."
disabled={isLoading}
className="flex-1 border p-2 rounded-md outline-none focus:ring-2 focus:ring-blue-500"
/>
{isLoading ? (
<button
type="button"
onClick={stop}
className="px-4 py-2 bg-red-500 text-white rounded-md"
>
中断
</button>
) : (
<button
type="submit"
className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700"
>
发送
</button>
)}
</form>
</div>
);
}

零成本多模型无缝切换

Vercel AI SDK 统一了底层 Provider 的接口规范。当需要对比不同供应商的模型效果时,业务逻辑层 100% 保持不变,只需切换一行 Provider 实例:

1
2
3
4
5
6
7
8
9
10
11
12
13
import { openai } from "@ai-sdk/openai";
import { anthropic } from "@ai-sdk/anthropic";
import { google } from "@ai-sdk/google";

// 任意切换底层模型供应商
// const selectedModel = openai("gpt-4o");
// const selectedModel = anthropic("claude-3-5-sonnet-20241022");
const selectedModel = google("gemini-2.0-flash");

const { text } = await generateText({
model: selectedModel,
prompt: "对比 React 与 Vue 的响应式原理差异。",
});

优缺点分析与工程选型边界

核心优势

  1. 前后端开发体验极致丝滑:useChat 抹平了所有前端流式交互的样板代码,20 分钟内即可交付生产级 Web 界面。
  2. TypeScript 生态首选:与 Zod 深度契合,编译期强类型推导无懈可击。
  3. 极佳的性能与 Edge 原生:体积极小,零臃肿的 Python 虚拟机依赖,天然适配 Vercel、Cloudflare Workers 等边缘云部署。
  4. 多模型适配标准最统一:在 JS/TS 生态中,其 Provider 接口已成为事实上的业界标准。

现实痛点与妥协

  1. 超复杂图编排能力较弱:主要面向单 Agent、多步工具调用和人机交互界面;若要处理类似 AutoGen、LangGraph 那样涉及数十个 Agent 的复杂多分支图状态回溯,架构上并不原生支持。
  2. 生态偏向 Web 技术栈:对于纯数据科学、离线批处理与模型微调为主的算法团队,其优势无法充分体现。

关联导航