企业官网建设流程全解析

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/voltagent

Vercel AI SDK 是构建 AI 应用的 TypeScript 统一工具库，它屏蔽了 OpenAI、Anthropic、Google Gemini 等多模型提供商的差异；而 VoltAgent 是基于 TypeScript 的开源 AI Agent 工程框架，提供指令、工具、记忆、子智能体与可观测性等编排能力。本文以 AI SDK 5.0（2025 年 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（工具）——外部动作或 API；
• Memory（记忆）——状态与上下文；
• 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 的模型 API（generateText、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创建带记忆的 Agent（LibSQLMemoryAdapter持久化到file:./.voltagent/memory.db），用@voltagent/logger创建 Pino 日志，再用@voltagent/server-hono在 3141 端口启动服务，其package.json中依赖ai@^6.0.0与zod@^3.25.76。可执行npm create voltagent-app@latest -- --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 span（exporter.ts）；
• Span 分类：getSpanType依据 span 名称中的generate/stream/generateObject/streamObject归为 generation，依据tool或ai.toolCall.name归为 tool（exporter.ts）；
• 事件模型：generation span 生成agent:start/agent:success/agent:error事件，tool span 生成tool:start/tool:success/tool:error事件；
• 多智能体支持：discoverAgentsInTrace+buildParentChildMap构建父子层级，事件会递归向上传播到所有祖先智能体的 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 SDK：

import { 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_telemetry：

import { 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）包括：

关于 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: "What's 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", // 智能体描述 // ... 其他自定义元数据 }, }

注意：如果未提供agentId，VoltAgent 会自动归入默认智能体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: "What's 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 时需要注意：

• 将依赖更新为ai@5.0.0与@ai-sdk/provider@2.0.0；
• 用inputSchema替换已废弃的parameters；
• 更新 UI 状态（partial-call→input-streaming，result→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