Vercel AI SDK 5 技术解析与 VoltAgent 深度集成指南：从 LLM 调用到可观测智能体编排

Vercel AI SDK 5 技术解析与 VoltAgent 深度集成指南从 LLM 调用到可观测智能体编排【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址: https://gitcode.com/gh_mirrors/vo/voltagentVercel AI SDK 是构建 AI 应用的 TypeScript 统一工具库它屏蔽了 OpenAI、Anthropic、Google Gemini 等多模型提供商的差异而 VoltAgent 是基于 TypeScript 的开源 AI Agent 工程框架提供指令、工具、记忆、子智能体与可观测性等编排能力。本文以 AI SDK 5.02025 年 7 月发布为核心系统梳理其新增能力并结合 VoltAgent 仓库源码讲解如何用 VoltAgent 构建自主智能体、通过voltagent/vercel-ai-exporter接入 VoltOps 可观测性以及 4→5 版本迁移要点。读完本文你将掌握从单次文本生成到多智能体可观测工作流的完整实战方案。Vercel AI SDK 概览一套 API 连接所有主流模型Vercel AI SDK 为 LLM 应用提供了一个统一工具包通过单一 API 即可接入 OpenAI、Anthropic、Google Gemini、Hugging Face 等多家模型提供商免去为每家模型提供商分别编写集成代码的重复工作。核心价值与其为每个模型提供商维护一套集成不如用一套一致的 API。在选择技术栈时可以参考以下原则简单 AI 功能如聊天、文本补全——单独使用 Vercel AI SDK 可能已经足够自主智能体需要记忆与决策能力——将 Vercel AI SDK 与 VoltAgent 结合使用。VoltAgent 恰好定位为“在 LLM 通信之上提供自主行为、记忆与可观测性的智能体架构层”两者形成互补的完整生态。AI SDK 5 核心特性截至 2025-10-14 更新Vercel 于2025 年 7 月 31 日发布AI SDK 5引入了一系列架构性变更与新能力关键新增能力Typed Chat Messages类型化聊天消息——引入UIMessage与ModelMessage的区分在流式传输前将 UI 消息转换为模型消息以支持持久化与类型安全。Agentic Loop Control智能体循环控制——通过stopWhen与prepareStep微调或停止多步工具调用SDK 内置轻量Agent类封装了generateText与streamText。SSE-based Streaming基于 SSE 的流式传输——用 Server-Sent Events 取代 WebSockets实现稳定的实时响应与部分数据流式传输。Dynamic Tooling动态工具——使用inputSchema与outputSchema替代旧的parameters与result定义工具支持运行时定义工具并强化 schema 校验。Speech Audio APIs语音与音频 API——实验性的文本转语音与转录支持覆盖 OpenAI、ElevenLabs、Deepgram。Global Provider System全局提供商系统——模型可以直接以openai/gpt-4o这种provider/model字符串引用提供商配置自动处理。Zod 4 MCP V2 支持——升级 schema 与协议覆盖 reasoning、sources 与图像生成。核心 SDK 函数模型提供商支持通过单一 API 支持 OpenAI、Anthropic、Google Gemini、Hugging Face 等多个提供商无需为每个模型编写提供商专属集成代码。流式传输SDK 支持文本与结构化数据JSON的流式响应。对于 Next.js 应用useChat、useCompletion等 React Hooks 可处理常见 UI 模式。其他组件generateText/streamText——支持流式输出的文本生成函数generateObject/streamObject——使用 Zod 做 schema 校验生成结构化 JSON 数据模型输出严格符合所定义 schema结构化输出的模型支持因提供商而异Function Calling函数调用——模型可调用预定义函数或工具智能体可在对话中获取 API 数据或执行动作Multi-modal Support多模态支持——处理文本之外的输入如图像SDK 会将多模态消息传递给支持该能力的模型Provider-Specific Options提供商专属选项——通过provider对象将提供商专属参数直接传给底层 SDK 函数启用模型专属特性。:::important 性能提示 使用streamObject()处理大型响应结构时应实现渐进式 UI 渲染以保持响应性复杂嵌套结构的 schema 校验可能引入延迟。 :::架构总览从整体架构看AI SDK v5 处于中心位置向上对接模型提供商OpenAI、Anthropic、Google Gemini、Hugging Face向下提供流式传输、动态工具、语音 API、智能体循环控制、全局提供商与 Zod 4 Schema 等特性并通过useChat、useCompletion等 UI Hooks 支撑前端界面。快速上手示例AI SDK 5最基础的文本生成只需要generateText 一个模型实例import { generateText } from ai; import { openai } from ai-sdk/openai; const result await generateText({ model: openai(gpt-4o), prompt: Explain what an agentic loop is in one sentence., }); console.log(result.text);该结构现在支持类型化响应、流式输出与自定义数据块custom data chunks。:::note API Key 管理 SDK 会读取OPENAI_API_KEY、ANTHROPIC_API_KEY等环境变量。请在开发环境或部署配置中设置这些变量。 :::VoltAgent构建自主 AI 智能体VoltAgent 是一个用于创建自主 AI 智能体的 TypeScript 框架。与专注于模型通信的 Vercel AI SDK 不同VoltAgent 提供智能体的架构工具、记忆、推理与协调能力。其核心概念包括Instructions指令——定义行为与目的Tools工具——外部动作或 APIMemory记忆——状态与上下文Sub-agents子智能体——任务委派Providers提供商——模型连接层。从仓库源码看VoltAgent 的全局提供商体系非常契合 AI SDK 5 的provider/model字符串模型引用方式。例如 with-vercel-ai 示例 中直接以model: openai/gpt-4o-mini配置 Agent而核心包 model-provider-registry.ts 中的splitModelId会按/或:拆分模型 ID 为providerId与modelId并据此解析对应的提供商适配器。这意味着 VoltAgent 与 AI SDK 5 在“字符串化全局模型引用”这一设计上天然对齐Agent 配置既可以是 SDK 对象也可以是provider/model字符串。与 Vercel AI SDK 集成VoltAgent 通过voltagent/vercel-aiprovider 与 AI SDK 5 集成让智能体能够直接使用 Vercel 的模型 APIgenerateText、streamText、generateObject。import { Agent } from voltagent/core; import { openai } from ai-sdk/openai; const agent new Agent({ name: Vercel Powered Assistant, instructions: Use OpenAI model via Vercel AI SDK., model: openai(gpt-4o), }); async function run() { const res await agent.generateText(Hello from VoltAgent!); console.log(res.text); }安装依赖npm install voltagent/core ai-sdk/openai:::tip 从示例工程开始 仓库中的 with-vercel-ai 示例展示了完整工程形态它用voltagent/core创建带记忆的 AgentLibSQLMemoryAdapter持久化到file:./.voltagent/memory.db用voltagent/logger创建 Pino 日志再用voltagent/server-hono在 3141 端口启动服务其package.json中依赖ai^6.0.0与zod^3.25.76。可执行npm create voltagent-applatest -- --example with-vercel-ai快速克隆体验。 :::通过这套组合VoltAgent 可以使用 AI SDK 5 的高级特性类型化流式、工具调用、智能体循环并通过 VoltOps 增加记忆与可观测性。Observability 与 VoltOps 集成VoltAgent 从 VoltOps 接入遥测实现可追踪的 AI 调用import { withTelemetry } from voltagent/vercel-ai-exporter; import { generateText } from ai; await withTelemetry({ traceName: order_agent, metadata: { agentId: 123, session: abc }, })(async () { const result await generateText({ model: openai(gpt-4o), prompt: Hi!, }); });VoltOps 收集结构化 traces、工具调用耗时与元数据用于调试与优化。源码级原理VoltAgentExporter如何工作仓库中对应的实现是 packages/vercel-ai-exporter 包核心类是 exporter.ts 中的VoltAgentExporter。它实现 OpenTelemetry 的SpanExporter接口把 Vercel AI SDK 产生的 OTel spans 转换为 VoltAgent 的 timeline 事件。从源码可以梳理出以下关键机制Span 识别isVercelAiSpan通过instrumentationScope.name ai判定 Vercel AI spanexporter.tsSpan 分类getSpanType依据 span 名称中的generate/stream/generateObject/streamObject归为 generation依据tool或ai.toolCall.name归为 toolexporter.ts事件模型generation span 生成agent:start/agent:success/agent:error事件tool span 生成tool:start/tool:success/tool:error事件多智能体支持discoverAgentsInTracebuildParentChildMap构建父子层级事件会递归向上传播到所有祖先智能体的 history深度上限 10含循环引用保护并支持跨 trace 的全局父子关系查找exporter.ts元数据提取从ai.telemetry.metadata.*前缀属性中解析agentId、userId、conversationId、tags与自定义元数据exporter.ts默认兜底当未提供agentId时使用默认ai-assistant并输出引导提示对应文档中DEFAULT_AGENT_ID ai-assistant常量exporter.ts。最小接入步骤安装依赖npm install voltagent/vercel-ai-exporter opentelemetry/sdk-node opentelemetry/auto-instrumentations-node在应用入口初始化 exporter 与 OpenTelemetry SDKimport { VoltAgentExporter } from voltagent/vercel-ai-exporter; import { NodeSDK } from opentelemetry/sdk-node; import { getNodeAutoInstrumentations } from opentelemetry/auto-instrumentations-node; const voltAgentExporter new VoltAgentExporter({ publicKey: process.env.VOLTAGENT_PUBLIC_KEY, secretKey: process.env.VOLTAGENT_SECRET_KEY, baseUrl: https://api.voltagent.dev, // 默认值 debug: true, // 开发环境可开启详细日志 }); const sdk new NodeSDK({ traceExporter: voltAgentExporter, instrumentations: [getNodeAutoInstrumentations()], }); sdk.start();之后照常调用 Vercel AI SDK并在调用中开启experimental_telemetryimport { generateText } from ai; import { openai } from ai-sdk/openai; const result await generateText({ model: openai(gpt-4o-mini), prompt: Hello, how are you?, experimental_telemetry: { isEnabled: true, metadata: { agentId: my-assistant, userId: user-123, }, }, }); console.log(result.text);VoltAgentExporterOptions的配置项exporter.ts包括配置项说明默认值publicKeyVoltOps 平台客户端标识secretKey服务端安全通信密钥baseUrlVoltAgent 后端地址https://api.voltagent.devautoFlush是否自动刷新trueflushInterval自动刷新间隔毫秒5000debug是否输出详细日志false关于 API Key 的获取流程对应 VoltOps LLM Observability 平台注册账号 → 创建组织 → 在组织内创建项目 → 在项目设置中获取VOLTAGENT_PUBLIC_KEY与VOLTAGENT_SECRET_KEY。工具调用追踪同样的最小配置即可看到工具调用被完整记录import { generateText } from ai; import { z } from zod; const result await generateText({ model: openai/gpt-4o-mini, prompt: Whats the weather like in Tokyo?, tools: { weather: { description: Get the weather in a location, parameters: z.object({ location: z.string().describe(The location to get the weather for), }), execute: async ({ location }) { await new Promise((resolve) setTimeout(resolve, 1000)); return { location, temperature: 72 Math.floor(Math.random() * 21) - 10 }; }, }, }, maxSteps: 5, experimental_telemetry: { isEnabled: true }, });开启后你会额外获得工具调用被追踪并可视化、工具输入输出可见、工具执行时间线清晰呈现。丰富元数据追踪为每次调用附加agentId、instructions、userId、sessionId等上下文能让追踪数据更有价值const result await generateText({ model: openai/gpt-4o-mini, prompt: Tell me a joke, experimental_telemetry: { isEnabled: true, metadata: { agentId: comedy-assistant, instructions: You are a fun comedian assistant, userId: user123, sessionId: session456, environment: production, version: 1.2.0, }, }, });可用元数据字段一览experimental_telemetry: { isEnabled: true, metadata: { agentId: my-agent, // 智能体标识 parentAgentId: parent-agent, // 父智能体可选用于层级关系 userId: user-123, // 用户 ID conversationId: conv-456, // 会话 ID tags: [marketing, ai], // 标签 instructions: Agent instructions, // 智能体描述 // ... 其他自定义元数据 }, }注意如果未提供agentIdVoltAgent 会自动归入默认智能体ai-assistant控制台会给出提示——这是正常行为。多智能体工作流追踪在同一个应用内追踪不同角色的智能体只需为每次调用设置不同agentId并通过parentAgentId表达父子层级vercel-ai-exporter README 中的多智能体示例// 主智能体 const { text: plan } await generateText({ model: openai(gpt-4o-mini), prompt: Create a marketing plan, experimental_telemetry: { isEnabled: true, metadata: { agentId: planning-agent, userId: user-123, conversationId: marketing-workflow, }, }, }); // 子智能体声明 parentAgentId 建立父子关系 const { text: execution } await generateText({ model: openai(gpt-4o-mini), prompt: Execute this plan: ${plan}, experimental_telemetry: { isEnabled: true, metadata: { agentId: execution-agent, parentAgentId: planning-agent, // 父子关系 userId: user-123, conversationId: marketing-workflow, }, }, });多智能体追踪带来的能力每个智能体在控制台中独立记录、父子层级关系清晰呈现、事件会向祖先智能体历史递归传播、角色化组织让工作流一目了然。高级特性自定义 Span 与错误追踪用 OpenTelemetry 自定义 span 包裹关键操作import { trace } from opentelemetry/api; const tracer trace.getTracer(my-app); const result await tracer.startActiveSpan(user-request-processing, async (span) { span.setAttributes({ user.id: user123, request.type: question, }); const response await generateText({ model: openai/gpt-4o-mini, prompt: Whats the capital of France?, experimental_telemetry: { isEnabled: true, metadata: { agentId: geography-assistant }, }, }); span.setAttributes({ response.length: response.text.length }); span.end(); return response; });错误自动追踪import { trace } from opentelemetry/api; try { const result await generateText({ model: openai/gpt-4o-mini, prompt: Some prompt that might fail, experimental_telemetry: { isEnabled: true, metadata: { agentId: error-prone-agent }, }, }); } catch (error) { const span trace.getActiveSpan(); if (span) { span.recordException(error); span.setStatus({ code: 2, message: error.message }); } throw error; }典型使用场景流式聊天机器人面向客服或问答场景的聊天机器人流式响应能显著改善用户体验。VoltAgent 配合VercelAIProvider使用streamText边生成边返回。结构化数据提取从文本中提取特定信息关键词、技术规格并输出为 JSON。VoltAgent 使用 Vercel AI SDK 的generateObject Zod schema 强制输出结构。:::danger Schema 复杂度 使用generateObject做 schema 校验时从简单结构开始。深度嵌套的 schema 可能产生难以调试的校验错误应循序渐进地增加复杂度。 :::智能体自动化VoltAgent 动态编排多个 AI SDK 工具完成复杂工作流Vercel AI Provider 支持在需要时透传提供商专属配置选项。AI SDK 4 → 5 迁移要点从 AI SDK 4 升级到 5 时需要注意将依赖更新为ai5.0.0与ai-sdk/provider2.0.0用inputSchema替换已废弃的parameters更新 UI 状态partial-call→input-streamingresult→output-available运行 Vercel 官方 codemods 自动重构。总结Vercel AI SDK 5带来了新的类型化协议、智能体循环、SSE 流式、语音 API、动态工具与全局提供商系统VoltAgent在此基础上叠加自主行为、记忆与 VoltOps 可观测性。两者组合构成完整的现代 AI 智能体生态——从 LLM 通信到全量智能体编排。如果要在自己的项目中快速验证可以对照仓库中的 with-vercel-ai 示例 与 voltagent/vercel-ai-exporter 文档 逐步落地集成细节还可参考 VoltAgent 官方集成指南 与 VoltOps 可观测性文档。【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址: https://gitcode.com/gh_mirrors/vo/voltagent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考