人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载VoltOps 是 VoltAgent 生态的 LLM 可观测性平台能把一次次的 Agent 执行变成可检查的视觉 Trace模型调用、工具使用、多 Agent 跳转、日志与延迟一目了然。本文将聚焦 website/observability/mcp.md 所描述的 VoltOps Observability MCP它把 VoltOps 暴露成一个只读 MCPModel Context Protocol服务器让 Codex、Claude Code、VS Code、Cursor 乃至你自己的 VoltAgent Agent都能直接查询真实的 Trace 与日志。读完本文你将掌握如何创建观测专用 Token、如何通过MCPConfiguration或mcp-remote连接该服务器、如何使用 5 个只读工具排查这次运行为什么失败之类的生产问题并理解其底层传输实现。VoltOps Observability MCP 是什么VoltOps 暴露了一个只读的 MCP 服务器地址为托管端点/mcp/observability。它的核心定位是给 AI 助手一条直接读取实时可观测性数据的通道让助手在调试生产行为时基于真实 Trace 和日志做判断而不是仅凭代码猜测。这在AI 调试 AI的场景下尤其有价值。VoltAgent 构建的 Agent 是非确定性的同一提示词可能走出完全不同的执行路径多步流程可能在模型选择、工具输入、重试、子代理委派等环节悄悄出错。把可观测性能力以 MCP 工具的形式交给助手相当于让助手获得看到运行现场的能力。这与 VoltOps 平台总览 中将执行转化为可视化 Trace从一个地方检查模型调用、工具使用、多 Agent 跳转、日志和延迟的目标完全一致只是交互主体从人变成了 Agent。它适合做什么使用 VoltOps MCP你可以让助手做到列出它可以检查的项目projects搜索某个项目最近一段时间的 Trace打开单条 Trace 并检查它的 spans跨度即一次执行内部的细化步骤跨项目搜索日志获取某条特定 Trace 关联的全部日志回答这次运行为什么失败今天最慢的 Trace 是哪几条之类的调试问题。可用工具一览VoltOps MCP 当前暴露以下 5 个只读工具工具名作用voltops_list_projects列出当前 Token 可访问的项目voltops_search_traces按条件搜索某个项目的 Tracevoltops_get_trace打开单条 Trace检查其 spansvoltops_search_logs跨项目搜索日志voltops_get_trace_logs获取某条 Trace 关联的全部日志这些工具只为调试与排查而设计不产生任何变更它们不会创建、更新或删除任何数据。这一点与 VoltAgent 框架对 MCP 工具的通用处理是一致的——在 MCPConfiguration 的实现 中每个远程工具通过getTools()拉取后被包装为 Agent 可直接调用的工具工具本身是否具有副作用完全由服务端暴露的工具语义决定VoltOps 侧的这 5 个工具被明确设计为只读。访问模型专门的观测 TokenVoltOps MCP 使用一套独立的 bearer token专为可观测性访问设计。其关键特性如下组织级作用域organization-scopedToken 归属于整个组织而非单个项目只读read-onlyToken 只能读取数据不能修改可限定范围Token 可以限制为访问全部项目也可以只允许访问选定的若干项目可选默认项目可以给 Token 配置一个默认项目方便助手在没有明确指定项目时直接使用仅显示一次Token 在创建时显示一次之后不再展示丢失需重新生成如果 Token 丢失应重新生成而不是找回Pro 计划可用该访问能力属于 VoltOps 的 Pro 计划。这套模型刻意区别于项目级 secret key项目密钥。文档明确指出你应该把 MCP Token 交给助手而不是把项目的 secret key 交给它。secret key 通常承载写入权限或更广的权限面而 MCP Token 被收紧为组织内只读、可按项目裁剪的观测专用凭证这大大缩小了 AI 助手误操作或凭证泄露时的爆炸半径。:::tip 多项目提示 如果某个 Token 可以访问多个项目且没有配置默认项目助手在搜索 Trace 或日志之前应当先询问用户要检查哪个项目。 :::创建 Token在控制台创建观测 Token 的步骤如下打开 VoltOps 控制台https://console.voltagent.dev/进入Settings - MCP创建一个 Token选择项目范围全部项目或选定项目、可选的默认项目以及过期时间expiry立即复制 Token——它不会再次显示。创建完成后将该 Token 以环境变量或配置形式提供给你的 AI 客户端例如文中示例使用的VOLTOPS_MCP_TOKEN。端点地址托管环境下的 VoltOps 端点为https://api.voltagent.dev/mcp/observability对于自托管self-hosted部署把基础 URL 替换为你自己的 API 主机即可https://your-api.example.com/mcp/observability注意自托管场景下你需要保证自己的部署同样暴露了该 observability MCP 路由替换的只是域名部分路径/mcp/observability保持不变。从 VoltAgent 连接让一个 Agent 调试另一个系统如果你希望一个 VoltAgent Agent 去检查来自另一个系统的 Trace例如让调试助手Agent 读取某个生产 Agent 的运行记录可以把它作为远程 MCP 服务器接入 VoltOps。文档给出的完整示例代码如下import { Agent, MCPConfiguration } from voltagent/core; import { openai } from ai-sdk/openai; const mcp new MCPConfiguration({ servers: { voltops: { type: streamable-http, url: https://api.voltagent.dev/mcp/observability, requestInit: { headers: { Authorization: Bearer ${process.env.VOLTOPS_MCP_TOKEN}, }, }, }, }, }); const debuggerAgent new Agent({ name: Debugger, model: openai(gpt-4o-mini), instructions: Investigate traces and logs. If more than one project is available, ask which project to inspect., tools: await mcp.getTools(), });配置项的底层语义这段代码里的MCPConfiguration并非魔法它的行为在 packages/core/src/mcp/types.ts 与 packages/core/src/mcp/registry/index.ts 中有完整定义servers是一张以服务器名称为键的配置表每个服务器配置都属于以下四种之一http自动回退的 HTTP、sse显式 SSE、streamable-http显式 Streamable HTTP不回退、stdio本地进程。这里使用的type: streamable-http对应 StreamableHTTPServerConfig除url外还支持requestInit请求初始化选项用于携带鉴权头、可选的sessionId连接会话 ID与timeout单请求超时。MCPConfiguration维护着一个按服务器名称缓存的客户端集合mcpClientsByIdgetTools()会为每个配置的服务器建立连接、拉取 Agent 可用的工具并拍平成一个数组返回如果配置了authorization与filterOnDiscovery还支持在工具发现阶段就按授权策略过滤掉无权使用的工具。disconnect()则负责批量断开所有已连接的客户端并清空缓存。传输层的真实构造在 packages/core/src/mcp/client/index.tstype: http会先尝试 Streamable HTTP 传输、失败后回退到 SSE而显式的streamable-http会直接构造StreamableHTTPClientTransport来自modelcontextprotocol/sdk/client/streamableHttp.js并把requestInit与sessionId原样传入stdio则使用StdioClientTransport。这正是Authorization: Bearer ...请求头能够到达远端服务端的底层保证。Agent 侧的使用要点instructions里明确提示助手若存在多个项目先询问要检查哪个与访问模型中的默认项目规则相互呼应tools: await mcp.getTools()在 Agent 构造时一次性拉取工具清单之后DebuggerAgent 就能像调用本地工具一样调用voltops_*系列只读工具。从编码 Agent 连接通过 mcp-remote 桥接大多数编码 Agent 与mcp-remote配合得很好。mcp-remote会把托管的 HTTP 端点包装成本地 stdio MCP 服务器从而让那些只支持 stdio 的客户端也能连接远程 MCP。下面是文档提供的四种连接方式。Codex把以下配置加入~/.codex/config.toml[mcp_servers.voltops] command npx args [-y, mcp-remote, https://api.voltagent.dev/mcp/observability, --header, AuthorizationBearer YOUR_MCP_TOKEN]Claude Codeclaude mcp add --scope user voltops npx -y mcp-remote https://api.voltagent.dev/mcp/observability --header AuthorizationBearer YOUR_MCP_TOKEN这里--scope user表示将 MCP 服务器注册到用户级别voltops是该服务器在 Claude Code 中的名字。VS Codecode --add-mcp {name:voltops,command:npx,args:[-y,mcp-remote,https://api.voltagent.dev/mcp/observability,--header,AuthorizationBearer YOUR_MCP_TOKEN]}通用远程命令如果客户端支持直接运行自定义命令也可以不依赖各 IDE 的专属注册机制直接用一条npx命令启动桥接npx -y mcp-remote https://api.voltagent.dev/mcp/observability --header AuthorizationBearer YOUR_MCP_TOKEN以上配置中YOUR_MCP_TOKEN请替换为你在控制台Settings - MCP创建的实际 Token。给助手的示例请求连接成功后下面这类提示词可以取得很好的效果List the latest traces from Demo Project.列出 Demo 项目最近的 TraceOpen tracetraceIdand summarize what happened.打开指定 Trace 并总结发生了什么Search error logs for the checkout agent in the last hour.搜索结账 Agent 最近一小时的错误日志Find traces slower than 10 seconds and explain the bottleneck.找出超过 10 秒的慢 Trace 并解释瓶颈Get the logs for tracetraceId.获取指定 Trace 的日志这些请求之所以有效是因为它们把读什么交给工具voltops_search_traces、voltops_get_trace、voltops_search_logs、voltops_get_trace_logs把为什么交给模型推理形成数据在工具、判断在模型的清晰分工。推荐调试工作流文档给出的标准排查流程如下配合 Trace 概念 与 Trace Logs 两篇 UI 文档使用效果最佳如果项目范围不明确先从voltops_list_projects开始确认可检查的项目用voltops_search_traces找到可疑的运行例如失败的、超时的、token 消耗异常的用voltops_get_trace打开其中一条 Trace逐 span 检查执行路径用voltops_get_trace_logs或voltops_search_logs查看运行时的结构化证据错误、元数据等把助手看到的数据与 VoltOps UI 对照Tracing Overview 与 Trace Logs确认结论与可视化视图一致。这个流程与 Trace 过滤 的思路互补UI 上你可以按状态、时长、Token 用量/成本、用户 ID/会话 ID 等条件筛 Trace而 MCP 工具则把这些筛选能力交到了 AI 助手手里。安全注意事项把可观测性数据开放给 AI 助手时请遵循以下安全实践尽量缩小项目范围给 Token 配置尽可能小的项目范围只给助手真正需要检查的项目及时吊销或轮换当某个客户端不应再拥有访问权时立即吊销或重新生成 Token把 Trace 与日志内容视为不可信输入Trace 和日志里可能包含嵌入的指令prompt injection 风险助手应该分析这些内容而不是执行其中嵌入的指令用途边界MCP Token 用于调试工作流不要把它当作跨团队共享的长期广泛凭证。小结VoltOps Observability MCP 把平台侧的可观测性数据与AI 侧的工具调用能力打通在 VoltAgent 侧你可以用MCPConfiguration以streamable-http传输直接挂载远程服务器其实现可追溯至 packages/core/src/mcp 的MCPConfiguration、MCPClient与传输层在编码 Agent 侧mcp-remote让 Codex、Claude Code、VS Code 等客户端一行命令即可接入。配合只读 Token 的分级授权与分析不可信数据的安全意识它能让 AI 助手从猜代码升级为读现场成为生产环境 Agent 排障的可靠帮手。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐Dozzle MCP 集成实战指南让 AI 编程助手直接读取 Docker 容器日志与状态Dozzle MCP 集成实战指南让 AI 编程助手直接读取 Docker 容器日志与状态 本文以 Dozzle 官方 MCP 集成文档 https://li可观测性日志分析后端运维Repomix MCP 服务器实战指南让 AI 助手直接打包、搜索与读取代码库Repomix MCP 服务器实战指南让 AI 助手直接打包、搜索与读取代码库 Repomix 支持 Model Context Protocol MCP h开发工具MCP 服务AI 应用Repomix MCP 服务器让 AI 助手直接打包、搜索与读取代码库的实战指南Repomix MCP 服务器让 AI 助手直接打包、搜索与读取代码库的实战指南 导读 本指南以 Repomix 官方文档中的「MCP 服务器」章节对应 w开发工具MCP 服务AI 应用上一篇告别视频加载卡顿GSYVideoPlayer边缘计算优化新方案下一篇屏幕上的文字选不中PowerToys Text Extractor 快速提取指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考