AI SDKVercel AI Toolkit实战指南统一 Provider 架构、结构化输出、Agent 循环与生成式 UI【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/aiAI SDK 是一个 provider-agnostic与模型提供商解耦的 TypeScript 工具包目标是让开发者用同一套 API 构建基于大语言模型的应用程序与 Agent。本文以仓库中 packages/ai/README.md 为骨架结合packages/ai核心包源码与packages/openai等提供商包实现完整覆盖从安装、统一模型接入、文本/结构化数据生成到ToolLoopAgent工具循环与生成式 UI 集成的全链路实战方案读完即可上手搭建一个可运行的 AI 应用。什么是 AI SDKAI SDK 是 Vercel 与 Next.js 团队出品的免费开源 TypeScript 库用于构建 AI 驱动的应用与 Agent。它支持流行的 UI 框架Next.js、React、Svelte、Vue、Angular与运行时Node.js并针对不同框架提供对应的 UI 集成包。从仓库结构看packages/ai是 SDK 核心包其 package.json 描述为以单一接口构建 ChatGPT、Claude、Gemini 等应用可直接经由 Vercel AI Gateway 或直连 OpenAI、Anthropic、Google 等任意模型提供商。核心包运行时只依赖三个内部包ai-sdk/gatewayAI Gateway 接入ai-sdk/provider统一模型提供商抽象层ai-sdk/provider-utilsSchema 校验、解析等公共工具核心包在 packages/ai/src/index.ts 中统一导出能力模块包括generate-text文本生成、generate-object对象生成、generate-image图像生成、generate-speech、generate-video、transcribe、translate、embed、batch、agentAgent 体系、ui生成式 UI以及realtime、registry、telemetry等覆盖了从基础推理到多模态与 Agent 编排的完整能力面。环境要求与安装环境要求Node.js 22核心包 package.json 中engines.node明确为22npm 或其他包管理器安装核心包npm install ai仓库中核心包当前版本为7.0.97采用 ESM 模块type: module开源协议为 Apache-2.0可通过exports字段提供主入口、./internal内部 API与./test测试工具三条导入路径。核心包将zod声明为 peerDependency^3.25.76 || ^4.1.8结构化输出场景需要自行安装 zod。为编码 Agent 安装技能可选如果你使用 Claude Code、Cursor 等编码 AgentREADME 建议将 AI SDK skill 加入仓库让编码助手掌握 SDK 用法npx skills add vercel/ai统一 Provider 架构两种接入方式AI SDK 的核心设计是「统一 API」无论底层是 OpenAI、Anthropic、Google 还是其他提供商上层调用方式完全一致。README 给出了两种接入路径。方式一通过 Vercel AI Gateway默认默认情况下AI SDK 经由 Vercel AI Gateway 接入只需把「提供商/模型」字符串直接传给model字段即可开箱使用所有主流提供商const result await generateText({ model: anthropic/claude-opus-4.6, // 或 openai/gpt-5.4、google/gemini-3-flash 等 prompt: Hello!, });其中provider/model的模型字符串约定以当前仓库 README 为准如anthropic/claude-opus-4.6、openai/gpt-5.4、google/gemini-3-flash。方式二直连提供商 SDK 包若需直连提供商绕过网关先安装对应提供商包npm install ai-sdk/openai ai-sdk/anthropic ai-sdk/google再导入提供商实例并传入模型 IDimport { anthropic } from ai-sdk/anthropic; const result await generateText({ model: anthropic(claude-opus-4-6), // 或 openai(gpt-5.4)、google(gemini-3-flash) 等 prompt: Hello!, });这种「统一调用层 可插拔提供商」的架构在仓库中体现得很清晰packages/ai只依赖抽象的ai-sdk/provider而每个具体提供商如packages/openai、packages/anthropic、packages/google作为独立包实现该抽象接口。这意味着业务代码与特定模型厂商解耦未来切换模型只需更换 provider 包与模型字符串。生成文本最简单的用法是调用generateText一次性生成文本import { generateText } from ai; const { text } await generateText({ model: openai/gpt-5.4, // 使用 Vercel AI Gateway prompt: What is an agent?, });从源码看packages/ai/src/index.ts 将generate-text模块整体导出generateText返回结果中包含text完整文本、output结构化输出见下文、usagetoken 用量、finishReason等字段。在更复杂场景下generateText还支持tools工具调用、output结构化输出、stopWhen停止条件等参数是 Agent 循环的基础构建块。生成结构化数据generateText配合Output可以强制模型输出符合 Schema 的 JSON适合「从模型拿结构化数据」的场景。README 给出了生成菜谱对象的完整示例import { generateText, Output } from ai; import { z } from zod; 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., });output字段会被解析、校验为符合z.object定义的 TypeScript 类型对象实现「类型安全的结构化数据」直出。源码层面的实现细节packages/ai/src/generate-text/output.ts 定义了Output接口与多种输出模式Output.text()默认模式直接返回纯文本对应responseFormat: { type: text }Output.object({ schema, name?, description? })按 Schema 输出对象。name与description为可选参数部分提供商会利用它们如作为 tool 或 schema 名称给模型额外引导该文件还支持Output.array(...)、Output.choice(...)、Output.json()等模式在 generate-text.test-d.ts 中有类型级验证。Output.object的内部流程是将 zod schema 转为 JSON Schema 作为模型的responseFormat模型返回文本后先经safeParseJSON解析 JSON再经safeValidateTypes做 Schema 校验任一环节失败都会抛出NoObjectGeneratedError并携带原始文本、响应元数据与用量信息便于排查「模型没按格式输出」的问题。对应的行为测试可参考 generate-text.test.ts 中大量Output.object用例。构建 AgentToolLoopAgent 与工具循环Agent 是 AI SDK 的高阶能力。README 展示了基于ToolLoopAgent的沙箱 Agent 示例——它把「执行 shell 命令」暴露为模型可调用的工具并经由 Vercel Sandbox 隔离执行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(); // Vercel Sandbox const command await sandbox.runCommand({ cmd, args }); return { output: await command.stdout() }; }, }), }, });工具循环的底层原理packages/ai/src/agent/tool-loop-agent.ts 是ToolLoopAgent的实现version agent-v1。其工作方式为每一轮调用 LLM若模型返回工具调用则执行对应工具并把结果作为新消息回传给 LLM进入下一轮。循环终止条件有四个源码注释明确列出模型返回的finishReason不再是tool-calls被调用的工具没有提供execute函数即只声明、不执行工具调用需要人工审批通过toolApproval或工具级needsApproval命中停止条件——默认停止条件为isStepCount(20)最多 20 步可在构造 Agent 时通过stopWhen覆盖。此外ToolLoopAgent支持id、tools属性以及prepareCall、callOptionsSchema对调用参数做 Schema 校验等高级配置generate与stream分别对应非流式与流式调用并暴露onStart、onStepStart、onToolExecutionStart、onToolExecutionEnd、onStepFinish、onFinish等回调用于观测每一步。请求还会自动附带ai-sdk-agent/tool-loop的 User-Agent 后缀便于用量归因。localShell 工具的参数约定示例中的openai.tools.localShell由 packages/openai/src/tool/local-shell.ts 提供其输入 Schema 为参数类型说明action.typeexec动作类型当前仅支持执行命令action.commandstring[]要执行的命令命令与参数数组action.timeoutMsnumber可选命令超时时间毫秒action.userstring可选以指定用户执行命令action.workingDirectorystring可选命令的工作目录action.envRecordstring, string可选为命令注入的环境变量输出 Schema 为{ output: string }——这也是示例中execute回调需要返回{ output: ... }结构的原因。execute是开发者自己实现的执行体可自由接入本地 Shell、沙箱或远程环境。UI 集成在 Next.js 中构建生成式 UIAI SDK UI 模块提供一组框架无关的 hooks用于构建聊天机器人与生成式 UI可在 Next.js、React、Svelte、Vue 中使用。首先安装对应框架的包npm install ai-sdk/reactREADME 以「图像生成 Agent」为例给出了一条完整的 Next.jsApp Router集成链路包含四个文件。1. 定义 Agent/agent/image-generation-agent.tsimport { 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 typeof imageGenerationAgent ;InferAgentUIMessagetypeof agent会根据 Agent 的工具集自动推导出消息类型让前端消息获得完整类型提示。openai.tools.imageGeneration由 packages/openai/src/tool/image-generation.ts 定义其参数 Schema 支持actiongenerate/edit/auto、backgroundauto/opaque/transparent、inputFidelity、inputImageMask、model、moderation、outputCompression0–100、outputFormatpng/jpeg/webp、partialImages0–3 的整数示例中的3即请求 3 张候选图、quality、size如1024x1024、1024x1536、1536x1024、auto或任意WxH字符串。2. 暴露 API 路由/app/api/chat/route.tsimport { 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, }); }createAgentUIStreamResponse将 Agent 的执行过程编码为流式 UI 消息响应前端可增量渲染。3. 编写工具对应的 UI 组件/component/image-generation-view.tsximport { openai } from ai-sdk/openai; import { UIToolInvocation } from ai; export default function ImageGenerationView({ invocation, }: { invocation: UIToolInvocationReturnTypetypeof openai.tools.imageGeneration; }) { switch (invocation.state) { case input-available: return divGenerating image.../div; case output-available: return img src{data:image/png;base64,${invocation.output.result}} /; } }UIToolInvocation携带工具调用的生命周期状态input-available工具入参就绪、正在执行与output-available输出可用。invocation.output.result为 base64 编码的 PNG 数据可直接渲染为img。这种「按工具状态渲染 UI」的机制正是生成式 UI 的核心——模型调用工具时前端自动切换到对应组件并实时反映执行状态。4. 组合页面/app/page.tsxuse client; import { ImageGenerationAgentMessage } from /agent/image-generation-agent; import ImageGenerationView from /component/image-generation-view; import { useChat } from ai-sdk/react; export default function Page() { const { messages, status, sendMessage } useChatImageGenerationAgentMessage(); const [input, setInput] useState(); const handleSubmit e { e.preventDefault(); sendMessage({ text: input }); setInput(); }; return ( div {messages.map(message ( div key{message.id} strong{${message.role}: }/strong {message.parts.map((part, index) { switch (part.type) { case text: return div key{index}{part.text}/div; case tool-generateImage: return ImageGenerationView key{index} invocation{part} /; } })} /div ))} form onSubmit{handleSubmit} input value{input} onChange{e setInput(e.target.value)} disabled{status ! ready} / /form /div ); }页面通过useChat管理消息状态messages中每条消息的parts数组按类型分发text部分直接渲染文本tool-generateImage部分交给ImageGenerationView渲染图片。status字段如ready用于控制输入框的可用状态避免生成过程中重复提交。由此一个「输入文字 → Agent 调用图像生成工具 → 页面流式展示生成图片」的完整交互闭环就搭建完成。更多资源模板TemplatesREADME 提到官方构建了集成 AI SDK 的模板覆盖不同用例、提供商与框架可直接作为项目起点。端到端示例仓库 examples 目录提供了大量可运行的完整示例其中 examples/ai-e2e-next 是 Next.js 端到端示例含 agent、工具、UI 组件等完整目录结构examples/harness-e2e-next 与 examples/harness-e2e-tui 则分别展示 Harness 体系的 Next.js 与 TUI 集成方式可作为本文各章节代码的落地参考。文档与贡献仓库 content/docs 目录按主题组织了大量 .mdx 文档含 07-reference 的 API 参考与 08-migration-guides 的迁移指南若想参与贡献可阅读仓库根目录的 CONTRIBUTING.md。小结AI SDK 的价值在于「一套 API全模型可用」统一 Provider 架构让模型切换成本趋近于零Output让非结构化的大模型输出变为类型安全的结构化数据ToolLoopAgent把「调用模型—执行工具—再次调用」的循环封装为声明式 Agent而框架无关的 UI hooks 则让生成式 UI 的构建变得直观。你可以从npm install ai开始按「文本生成 → 结构化输出 → Agent → UI 集成」的顺序逐步深入结合仓库 examples 中的端到端示例验证每个环节。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
