/ 目录 / 演练场 / volcano-agent-sdk
● 社区 Kong ⚡ 即开即用

volcano-agent-sdk

作者 Kong · Kong/volcano-agent-sdk

使用 TypeScript 构建 AI 代理,将 LLM 推理与 MCP 工具链接起来 — 支持 100+ 模型、并行执行、内置 OTel 追踪。

Kong 的 Volcano Agent SDK 是一个 TypeScript SDK(不是 MCP server),用于构建多提供商 AI 代理以消费 MCP 工具。支持 OpenAI、Anthropic、Mistral、Bedrock、Vertex、Azure。自动从配置的 MCP endpoint 选择工具、流式传输 token、失败重试、内置 OpenTelemetry 追踪。

为什么要用

核心特性

实时演示

实际使用效果

volcano-agent-sdk.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "volcano-agent-sdk": {
      "command": "npx",
      "args": [
        "-y",
        "volcano-agent-sdk"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "volcano-agent-sdk": {
      "command": "npx",
      "args": [
        "-y",
        "volcano-agent-sdk"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "volcano-agent-sdk": {
      "command": "npx",
      "args": [
        "-y",
        "volcano-agent-sdk"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "volcano-agent-sdk": {
      "command": "npx",
      "args": [
        "-y",
        "volcano-agent-sdk"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "volcano-agent-sdk",
      "command": "npx",
      "args": [
        "-y",
        "volcano-agent-sdk"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "volcano-agent-sdk": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "volcano-agent-sdk"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add volcano-agent-sdk -- npx -y volcano-agent-sdk

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: volcano-agent-sdk

构建使用 GitHub + Sentry MCP 的编码代理

👤 构建内部自动化的 TS 开发者 ⏱ ~60 min advanced

何时使用: 你需要一个可编程的代理,而不是聊天会话。

前置条件
  • Node 20+ — 标准安装
  • 你想要的工具的 MCP endpoint(github、sentry 等) — 使用现有的公开 endpoint 或自己部署
步骤
  1. 安装 + 初始化
    npm install @volcano.dev/agent 并编写一个最小化的代理,使用 Anthropic 作为模型,连接到 github 和 sentry MCP。✓ 已复制
    → 项目正常运行
  2. 编写任务
    代理的任务:每 15 分钟查找新的 Sentry 错误,通过 MCP 关联到 GitHub commit,为明显的问题起草还原 PR。✓ 已复制
    → 代理自主执行任务
  3. 添加监测
    启用 OTel 追踪并导入到 Honeycomb/Grafana。✓ 已复制
    → 可见 span

结果: 一个生产就绪、具有可观测性的自动化代理。

注意事项
  • 代理幻觉式地调用不存在的工具 — 限制传递给代理的 MCP 集合;少而精的工具文档优于功能众多。
  • 重试会放大瞬时上游问题 — 调整重试策略并添加指数退避
搭配使用: github · sentry

组建多代理团队进行研究任务

👤 探索代理模式的开发者 ⏱ ~45 min advanced

何时使用: 任务受益于分工(研究员 + 撰写者 + 审阅者)。

步骤
  1. 定义代理
    创建代理:Researcher(网络搜索 MCP)、Writer(起草)、Reviewer(验证 Researcher 的信息来源)。✓ 已复制
    → 三个类型化的代理实例
  2. 委派任务
    运行团队:主题「2026 年 MCP 的现状」。让 Researcher 收集信息、Writer 起草、Reviewer 验证说法。✓ 已复制
    → 协调的输出

结果: 相比单遍代理,复杂任务的输出质量更高。

搭配使用: omnisearch

构建支持工具访问的流式聊天机器人

👤 将 AI 集成到 TS 应用的产品开发者 ⏱ ~40 min advanced

何时使用: 用户直面的功能,需要实时流式传输 + MCP 工具调用。

步骤
  1. 接入流式传输
    构建一个聊天 endpoint,将 token 流式传输到客户端,并在模型请求时在流中调用工具。✓ 已复制
    → 正常工作的流式 endpoint
  2. 可解释性
    每次响应后,暴露 agent.summary(),让 UI 显示使用了哪些工具。✓ 已复制
    → 工具调用轨迹可见

结果: 一个生产级聊天 UI,工具使用透明。

组合

与其他 MCP 搭配,撬动十倍杠杆

volcano-agent-sdk + github + sentry

跨越事件和代码的自主分类代理

构建一个代理,给定一个 Sentry 告警,获取堆栈、通过 GitHub 找到有问题的 commit,并打开一个包含最小化修复的 PR。✓ 已复制
volcano-agent-sdk + vurb-ts

Vurb 构建服务端;Volcano 构建代理端

通过 Vurb MCP 暴露我的业务数据;构建一个 Volcano 代理来回答用户问题。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
(SDK) 你编写 TS 代码;SDK 从配置的 MCP 自动选择工具 不适用 — Volcano Agent SDK 是一个你用来构建的库,而不是你调用的 MCP server n/a — depends on model + tools

成本与限制

运行它的成本

API 配额
LLM 提供商限制适用;MCP 上游限制适用
每次调用 Token 数
取决于模型和对话长度
费用
SDK 免费;LLM 使用按提供商计费
提示
用便宜的模型(Haiku/GPT-4o-mini)做路由,保留昂贵的模型做推理;Volcano 支持每步选择不同模型。

安全

权限、密钥、影响范围

凭据存储: LLM 提供商密钥 + MCP 凭据存储在环境变量;SDK 注入它们
数据出站: LLM 提供商 API + 配置的 MCP endpoint
切勿授予: 不要将 LLM 密钥传递给同一进程中的不可信代码路径

故障排查

常见错误与修复

启动时 MCP 连接失败

验证 MCP endpoint URL 和身份验证。当设置 --debug 时,SDK 记录完整错误。

验证: Curl the MCP endpoint directly
模型拒绝使用可用工具

工具描述可能措辞不当;改写以提高清晰度,或通过代理配置强制使用。

验证: Inspect tools via agent.listTools()
简单任务的 token 成本高

检查系统 prompt 是否将 MCP 工具定义拖入每个调用;使用懒加载工具模式。

验证: agent.summary() shows token breakdown

替代方案

volcano-agent-sdk 对比其他方案

替代方案何时用它替代权衡
LangChain / LangGraph (TS)你想要最大的集成生态系统更重的抽象;冷启动更慢
Vercel AI SDK你想要与 Next.js 紧密集成对多代理模式的关注较少
Anthropic SDK raw你只需要 Anthropic 和最小化的抽象你需要重新实现工具路由、重试、多提供商支持

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills