@voltagent/vercel-ai-exporter：为 Vercel AI SDK 接入 VoltAgent 可观测性的 OpenTelemetry 导出器实战指南

人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载本篇技术指南围绕 VoltAgent 官方 OpenTelemetry 导出器voltagent/vercel-ai-exporter展开它能把 Vercel AI SDK 自动生成的 OpenTelemetry Span 转换为 VoltAgent 时间线事件让你在不改动业务代码的前提下获得 AI 调用、工具执行、Token 用量与多智能体Multi-Agent工作流的完整可观测能力。读完本文你将掌握该包的安装配置、全部元数据选项、多智能体父子追踪的写法以及它底层的 Span 解析、事件模型与错误处理机制从而直接在自己的 Vercel AI 应用中落地生产级 LLM 观测。一、这个包解决什么问题Vercel AI SDK 自带基于 OpenTelemetry 的experimental_telemetry支持会为generateText、streamText等调用生成标准 Span但 Span 只是原始遥测数据需要导出到后端才能形成可阅读、可检索的执行历史。voltagent/vercel-ai-exporter仓库路径packages/vercel-ai-exporter正是连接二者的桥梁它实现 OpenTelemetry 的SpanExporter接口把 Vercel AI SDK 产生的 Span 转写为 VoltAgent 的 trace/事件结构并上报到 VoltAgent 可观测性后端。从源码看其核心类VoltAgentExporter直接implements SpanExporter见 src/exporter.ts同时内部聚合了voltagent/sdk提供的观测能力。整个包对外只导出两个符号VoltAgentExporter类与VoltAgentExporterOptions配置类型见 src/index.tsAPI 面非常收敛。相比裸的 OpenTelemetry 导出该包的主要收益也是 README 明确列出的 Features自动追踪AI 调用与工具使用无需手动打点自动进入观测平台多智能体支持同一工作流中可同时追踪多个 Agent父子层级通过parentAgentId构建 Agent 层级树完整类型安全纯 TypeScript 实现导出完整类型定义Vercel AI SDK 兼容覆盖generateText、streamText、generateObject、streamObject等场景灵活元数据metadata中的自定义字段可透传到观测平台。二、安装与前置条件使用 npm 安装包及其 OpenTelemetry 运行时依赖与 README 一致npm install voltagent/vercel-ai-exporter opentelemetry/sdk-node opentelemetry/auto-instrumentations-nodevoltagent/vercel-ai-exporter本包opentelemetry/sdk-nodeOpenTelemetry Node SDK用于创建NodeSDK实例opentelemetry/auto-instrumentations-node自动插桩集合负责收集进程内各库的遥测数据。Requirements以仓库现状为准依赖版本要求说明Node.js20包内使用crypto.randomUUID()等较新 APICHANGELOG 也记录了放弃 Node 18 的变更Vercel AI SDKaiREADME 声明 3.0当前包版本2.0.2的peerDependencies要求ai^6.0.0即与 AI SDK v6 对齐见 package.jsonOpenTelemetry SDKopentelemetry/core、opentelemetry/sdk-trace-base均要求^2.0.0由opentelemetry/sdk-node引入注意版本差异README 中写的是 Vercel AI SDK 3.0但当前package.json的 peer 依赖已是ai^6.0.02.x 版本与 AI SDK v6 对齐详见 CHANGELOG.md。如果你的项目直接调用 AI SDK请以 v6 的上游迁移指南为准。许可证为 MIT。三、快速开始最小可运行配置在应用入口通常是main文件初始化导出器与 OpenTelemetry SDK然后在 AI 调用上开启 telemetry 即可。import { VoltAgentExporter } from voltagent/vercel-ai-exporter; import { NodeSDK } from opentelemetry/sdk-node; import { getNodeAutoInstrumentations } from opentelemetry/auto-instrumentsations-node; import { openai } from ai-sdk/openai; import { generateText } from ai; // 初始化 VoltAgent 导出器 const voltAgentExporter new VoltAgentExporter({ publicKey: process.env.VOLTAGENT_PUBLIC_KEY, secretKey: process.env.VOLTAGENT_SECRET_KEY, debug: true, // 开发阶段建议开启生产环境建议关闭 }); // 装配 OpenTelemetry SDK const sdk new NodeSDK({ traceExporter: voltAgentExporter, instrumentations: [getNodeAutoInstrumentations()], }); sdk.start(); // 正常使用 Vercel AI SDK只需开启 experimental_telemetry 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);获取 API 密钥以 VoltAgent 可观测性平台的常规流程为准注册并创建组织organization在组织内创建项目project在项目设置中获取两个环境变量VOLTAGENT_PUBLIC_KEY用于客户端标识VOLTAGENT_SECRET_KEY用于安全的服务端通信。建议写入.env并通过process.env注入而非硬编码在源码中。你可能看到的一条提示如果调用时未提供agentId控制台会输出 VoltAgent: Using default agent for tracking. For better tracking, add agentId to your metadata: experimental_telemetry: { isEnabled: true, metadata: { agentId: my-agent } }这是正常行为——导出器会回退到默认 Agent 标识ai-assistant源码中的DEFAULT_AGENT_ID常量见 src/exporter.ts所有活动都会归组到该默认 Agent 下。想要更细粒度的追踪就按提示补上agentId。四、VoltAgentExporter 配置项详解VoltAgentExporterOptions在 src/exporter.ts 中定义字段与默认值如下配置项类型默认值作用publicKeystringVoltAgent 后端公钥用于客户端标识secretKeystringVoltAgent 后端密钥用于安全通信baseUrlstringhttps://api.voltagent.dev可观测性后端地址自托管时可改autoFlushbooleantrue是否自动批量上报flushIntervalnumber5000自动上报间隔毫秒debugbooleanfalse开启详细调试日志从构造器实现可见src/exporter.tsdebug默认关闭baseUrl未传时固定为https://api.voltagent.devautoFlush默认true、flushInterval默认5000毫秒。调试日志统一带[VoltAgentExporter]前缀并包含时间戳方便排查。开发与生产区分生产环境应关闭debug例如按环境切换const voltAgentExporter new VoltAgentExporter({ publicKey: process.env.VOLTAGENT_PUBLIC_KEY, secretKey: process.env.VOLTAGENT_SECRET_KEY, debug: process.env.NODE_ENV development, });五、元数据Metadata选项完整字段与含义experimental_telemetry.metadata是接入观测的关键入口字段会以ai.telemetry.metadata.*前缀写入 Span 属性再由导出器解析还原见 src/exporter.ts 的extractTraceMetadata与parseSpanMetadata。README 给出的完整元数据示例experimental_telemetry: { isEnabled: true, metadata: { agentId: my-agent, // Agent 标识必填建议 parentAgentId: parent-agent, // 父 Agent可选用于构建层级 userId: user-123, // 用户 ID conversationId: conv-456, // 会话 ID tags: [marketing, ai], // 标签数组 instructions: Agent instructions, // Agent 描述/系统指令 // ... 其他任意自定义元数据 }, }各字段在源码中的用途agentId决定该次调用的执行历史归属于哪个 Agent缺省时回退到ai-assistantparentAgentId声明父子关系。导出器发现它后会把子 Agent 的事件递归地向上传播到父 Agent 的历史中见下文多智能体章节userId/conversationId作为 trace 级元数据传递给后端用于按用户、会话过滤tags会被聚合成 trace 级标签parseTagsTraceAttribute会对所有 Span 的 tags 去重合并instructions作为 Agent 描述写入事件元数据便于在控制台快速理解 Agent 职责自定义字段任何以ai.telemetry.metadata.为前缀的属性都会被剥离前缀后透传因此你可以携带environment、version、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, }, }, });六、工具Tools追踪启用 telemetry 后AI 调用中的工具定义与执行会被自动追踪——工具名、入参、出参、执行时间线都会进入观测平台。README 中的示例含 Zod 参数校验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 weather information, parameters: z.object({ location: z.string(), }), execute: async ({ location }) { return { location, temperature: 22 }; }, }, }, experimental_telemetry: { isEnabled: true, metadata: { agentId: weather-assistant, userId: user-123, }, }, });底层实现要点结合 src/exporter.ts导出器通过 Span 名称包含tool或属性ai.toolCall.name来识别工具 SpangetSpanType见 L917-L934每个工具 Span 会被转换为tool:start与tool:success或tool:error两类事件metadata中包含displayName、id工具名以及归属的agentId工具的执行输入来自ai.toolCall.args输出来自ai.toolCall.result若工具 Span 自身没有agentId导出器会尝试从父 Span 或同 trace 中最近的 generation Span 推断归属见extractAgentIdFromSpanL1378-L1443实在推断不出才落到默认 Agent。七、多智能体与父子层级追踪这是该包最具价值的特性。README 的营销计划示例展示了主 Agent 规划 子 Agent 执行的模式// 主 Agent 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, }, }, }); // 子 Agent声明父级关系 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, }, }, });源码级原理多智能体支持远不止打个标记其实现包括Agent 发现discoverAgentsInTrace遍历同 trace 内所有 Span按agentId聚合成AgentInfo含parentAgentId、displayName、起止时间与所属 Span 列表见 src/exporter.ts按依赖排序创建历史sortAgentsByDependency会先创建父 Agent 的执行历史再创建子 Agent 的并内置循环引用检测防止无限递归L334-L400独立历史每个 Agent 拥有独立的 history以agentId_traceId为键同时globalAgentHistories支持跨 trace 关联L98-L100递归事件传播addEventToTrace在写入子 Agent 自身历史后会通过propagateEventToAncestors沿parentChildMap/globalParentChildMap一路向上传播到所有祖先的历史L506-L608。传播时保留原始归属metadata中追加fromChildAgent直接子 Agent、originalAgentId事件最初来源、propagationDepth传播深度与propagationPath可读路径并设置 10 层最大深度与环检测双重保险Agent 生命周期事件每个 Agent 的第一个 generation Span 触发agent:start最后一个完成 Span 触发agent:success出错时触发agent:errorL725-L820。因此即便你的层级深达三层以上如 master → division → specialist子 Agent 的工具调用也会完整出现在每一级祖先的执行历史中且事件始终标注原始发起者——这一点在 src/exporter.spec.ts 的 Deep Nested Multi-Agent Hierarchies (3 Levels) 测试组中有系统验证含 4 层归属保持、循环引用、深度上限、跨 trace 传播等用例。更丰富的多角色示例三个 Agent 串联研究 → 写作 → 审校时只需各自声明agentId与role等元数据即可在控制台分别查看每个角色的执行情况// research-agent负责收集信息 // writing-agent基于研究结果写作 // review-agent审校改进 // 三者均可通过 agentId 独立分组通过 conversationId 关联为同一工作流八、Span 识别与数据解析的底层机制为了更精准地排查问题值得了解导出器如何把 Vercel AI SDK 的 Span 翻译成 VoltAgent 事件。Span 类型判定getSpanTypesrc/exporter.tsgenerationSpan 名称包含generate、stream、generateobject、streamobject大小写不敏感tool名称包含tool或存在属性ai.toolCall.name其他unknown会被忽略。只处理 Vercel AI 的 SpanisVercelAiSpan检查instrumentationScope.name ai其他插桩产生的 Span 不会进入转换流程L896-L901。输入/输出解析parseSpanInput/parseSpanOutputL988-L1046输入优先取ai.prompt.messagesJSON 解析、ai.prompt、ai.toolCall.args输出则按ai.response.objectgenerateObject 场景、ai.response.text、ai.result.text、ai.toolCall.result、ai.response.toolCalls、ai.embedding(s)的顺序取值并兼容 object 与 text 同时存在的组合。Token 用量解析parseUsageL1090-L1114同时兼容新旧属性名——输入侧按gen_ai.usage.prompt_tokens/gen_ai.usage.input_tokens/ai.usage.promptTokens依次回退输出侧对应gen_ai.usage.completion_tokens/gen_ai.usage.output_tokens/ai.usage.completionTokens并自动计算totalTokens。模型参数与首字节耗时parseModelParameters/parseCompletionStartTimeL1116-L1183会抽取model、temperature、maxTokens、finishReason、toolChoice、system、maxRetries、mode、output等参数completionStartTime则基于ai.response.msToFirstChunk旧版为ai.stream.msToFirstChunk加上 Span 开始时间推算用于度量首 token 延迟。错误处理Span 状态码为 2ERROR常量ERROR_STATUS_CODE时generation 生成agent:error事件、工具生成tool:error事件均携带error.message导出过程本身出错时回调会收到ExportResultCode.FAILEDL176-L182。九、内存与生命周期管理导出器内部维护多张 Map活跃历史、父子关系、trace 内 Agent、全局历史、工具 Span 缓存、延迟 Span 队列等并提供两个清理入口src/exporter.tsforceFlush()对所有仍活跃的 trace 调用trace.end()兜底收尾随后清空全部缓存并触发一次sdk.flush()shutdown()内部委托给forceFlush()。对应测试Memory Management 用例组见 src/exporter.spec.ts验证了 forceFlush 与 shutdown 后各类缓存均被清空。生产环境中建议在进程退出前调用shutdown()避免丢失未上报的数据。十、最佳实践与故障排查综合 README 与仓库实现落地时建议使用有意义的agentIdcustomer-support-agent、product-recommendation-agent优于agent1尽量携带上下文instructions、userId、sessionId、category、priority等字段会让历史记录更具可分析性密钥走环境变量# .env VOLTAGENT_PUBLIC_KEYyour_public_key VOLTAGENT_SECRET_KEYyour_secret_key VOLTAGENT_BASE_URLhttps://api.voltagent.dev按环境控制 debug仅开发环境开启避免生产日志刷屏自定义 Span 细化追踪可用opentelemetry/api的trace.getTracer()包裹业务步骤与 AI 调用构成完整执行链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 }); // ... generateText 调用 ... span.end(); return response; });错误自动记录捕获异常后调用span.recordException(error)并setStatus({ code: 2, message })即可在观测平台看到agent:error事件。常见问题排查控制台无数据检查VOLTAGENT_PUBLIC_KEY/VOLTAGENT_SECRET_KEY与网络连通性Span 缺失确认experimental_telemetry.isEnabled: true且sdk.start()在 AI 调用前执行性能生产环境可使用批量上报autoFlush默认开启flushInterval可按需调整归属不清晰优先为每个 Agent 显式声明agentId减少依赖默认 Agent 或推断逻辑。十一、更深入的学习路径完整集成文档见仓库内 website/docs/integrations/vercel-ai.md其中包含安装npm/pnpm/yarn、API 密钥获取、基本/工具/元数据/多智能体分步示例、高级特性自定义 Span、错误追踪与故障排查导出器全部实现源码packages/vercel-ai-exporter/src/exporter.ts单测与多智能体深度用例packages/vercel-ai-exporter/src/exporter.spec.ts包配置与版本约束packages/vercel-ai-exporter/package.json版本演进记录packages/vercel-ai-exporter/CHANGELOG.md。整体来看voltagent/vercel-ai-exporter遵循零侵入接入、元数据驱动追踪、层级化事件传播的设计你只需在调用时开启 telemetry 并声明agentId/parentAgentId就能获得从单次生成到多层多智能体工作流的完整可观测数据同时通过标准 OpenTelemetry 协议与既有可观测性栈无缝共存。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐PentAGI 自定义 LLM 后端报 Failed to parse tool call arguments as JSON 怎么排查PentAGI 自定义 LLM 后端报 Failed to parse tool call arguments as JSON 怎么排查 PentAGI人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音如何通过 rclone 本地 WebDAV 桥把 Super Productivity 接入 Proton Drive如何通过 rclone 本地 WebDAV 桥把 Super Productivity 接入 Proton Drive 如果你的数据放在 Proton Dri人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音Opik Vercel AI SDK 集成用 opik-vercel 为 AI 应用接入端到端可观测性Opik Vercel AI SDK 集成用 opik vercel 为 AI 应用接入端到端可观测性 导读 opik vercel 是 Opik TypeS人工智能LLMOps模型评测可观测性AI AgentAI 应用后端前端上一篇NAS媒体库智能管理5分钟自动化部署终极指南下一篇如何使用Chart.js浏览器扩展xhubGitHub页面图表增强完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考