人工智能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 CLI 的eval命令族为主线系统讲解从安装初始化、数据集 push/pull 上传下载到eval run执行 Agent 实验评估的完整流程。结合 cli-reference.md 文档与 packages/cli 的源码实现你将掌握所有命令行参数、环境变量、退出码与错误处理机制并能在本地与 VoltOps 云端之间无缝管理评估数据、跑通带评分与通过标准的回归实验。VoltAgent CLI 为评估工作流提供了两个核心能力数据集管理上传/下载用于评估的测试用例与实验执行针对数据集运行 Agent 并打分。所有评估相关命令都统一挂在voltagent eval之下也可以通过npx voltagent/cli eval直接调用。本文将按照「安装初始化 → 数据集推送/拉取 → 实验运行 → 配置与排错」的顺序结合仓库源码逐层拆解。一、安装与项目初始化1. 快速初始化voltagent init在任意 Node.js 项目中执行下面这条命令即可完成集成npx voltagent/cli init从 init 命令源码 可以看到它实际完成的工作比文档描述的更细致校验package.json存在命令必须在 Node.js 项目根目录运行否则直接报错退出Exit code 1自动探测包管理器优先根据pnpm-lock.yaml判定为pnpm根据yarn.lock判定为yarn否则回退为npm并据此选择对应的安装命令pnpm add voltagent/cli --save-dev/yarn add voltagent/cli --dev/npm install voltagent/cli --save-dev写入volt脚本在package.json的scripts中新增volt: volt若已存在且值相同则跳过安装 CLI 为 dev dependency若本地node_modules中尚不存在创建.voltagent目录作为后续数据集等文件的默认存放位置。因此文档中的描述可以对应为安装voltagent/cli为开发依赖在package.json中添加volt: volt脚本创建初始配置目录结构2. 手动安装如果你希望自己控制安装方式可以手动安装# 作为开发依赖安装 npm install --save-dev voltagent/cli # 或全局安装 npm install -g voltagent/cli然后在package.json中手动补充脚本{ scripts: { volt: volt } }安装完成后两种调用方式等价# 通过 npm script 调用CLI 参数需要放在 -- 之后npm 才会转发给 volt npm run volt eval dataset push -- --name my-dataset # 直接调用等价写法 npx voltagent/cli eval dataset push --name my-dataset注意npm run volt ... -- args中的--是 npm 转发参数的约定如果直接用voltagent或npx voltagent/cli调用则不需要。二、数据集管理命令数据集Dataset是评估的基础——它是测试用例的集合每个条目包含输入input、期望输出expected可选与附加元数据extra。关于数据集的 JSON 结构与字段含义可参考 数据集文档。1. 上传数据集eval dataset push将本地数据集 JSON 文件上传到 VoltOps# 通过 npm script npm run volt eval dataset push -- --name dataset-name # 或直接调用 voltagent eval dataset push --name dataset-name选项选项说明默认值--name name数据集名称必填---file path数据集 JSON 文件路径.voltagent/datasets/name.json环境变量VOLTAGENT_DATASET_NAME— 默认数据集名称VOLTAGENT_API_URL— VoltOps API 端点默认https://api.voltagent.devVOLTAGENT_PUBLIC_KEY— 认证公钥VOLTAGENT_SECRET_KEY— 认证私钥VOLTAGENT_CONSOLE_URL— 用于生成数据集链接的控制台地址示例# 通过环境变量指定数据集名称 export VOLTAGENT_DATASET_NAMEproduction-qa npm run volt eval dataset push # 推送指定文件 npm run volt eval dataset push -- --name qa-tests --file ./data/custom-qa.json # 推送到不同环境 VOLTAGENT_API_URLhttps://staging-api.voltagent.dev \ npm run volt eval dataset push -- --name staging-data底层实现dataset-push.ts揭示了 push 的真实流程从--name或VOLTAGENT_DATASET_NAME解析数据集名称缺失时报错提示两者必须提供其一通过resolveAuthConfig解析认证信息环境变量缺失时会弹出交互式输入解析文件路径--file优先否则默认.voltagent/datasets/name.json并校验文件存在创建数据集向${API_URL}/evals/datasets发送POST若返回 409/400重名冲突则通过名称查询已存在的数据集并复用其 ID创建版本向/evals/datasets/${datasetId}/versions发送POST携带description、metadata、checksum逐条写入条目遍历dataset.data逐条向/evals/datasets/${datasetId}/versions/${versionId}/items发送POST字段映射为{ input, expected, extra, label: item.name }成功后输出datasetId、datasetVersionId、itemCount并打印VOLTAGENT_CONSOLE_URL默认https://console.voltagent.dev下的数据集查看链接。这意味着 push 是「数据集 版本 条目」三层结构的一次性同步同名数据集再次 push 会生成新版本而不是覆盖历史版本。2. 下载数据集eval dataset pull从 VoltOps 将数据集版本下载到本地npm run volt eval dataset pull -- [options]选项选项说明默认值--name name要拉取的数据集名称交互式提示--id id数据集 ID优先级高于 name---version id指定版本 ID最新版本--output path输出文件路径.voltagent/datasets/name.json--overwrite直接覆盖已存在文件不询问false--page-size n每次 API 请求的条目数1-1000200交互模式不带任何选项运行时会弹出交互菜单从数据集列表中选择列表按名称排序并显示每个数据集拥有的版本数若存在多个版本则选择要拉取的版本版本按v1/v2/v3倒序或创建时间倒序排列展示条目数与描述确认文件保存位置。文件冲突处理当目标文件已存在时弹出操作选择覆盖现有文件 / 另存为新文件 / 取消传入--overwrite则跳过询问直接覆盖「另存为新文件」默认建议形如name-remote.json、name-remote-1.json的递增文件名见 eval.ts 中的 buildAlternateFilePath若本地文件与远端内容一致CLI 会做内容比对直接提示 already up to date 并跳过写入。示例# 交互模式 npm run volt eval dataset pull # 拉取指定数据集 npm run volt eval dataset pull -- --name production-qa # 拉取指定版本 npm run volt eval dataset pull -- --name qa-tests --version v3 # 按 ID 拉取并指定输出路径 npm run volt eval dataset pull -- \ --id dataset_abc123 \ --version version_xyz789 \ --output ./test-data/qa.json # 强制覆盖 npm run volt eval dataset pull -- --name staging-data --overwrite底层实现dataset-fetch.ts解析目标--id优先其次--name都未提供时进入交互选择resolveDatasetDetail版本解析顺序为--version→VOLTAGENT_DATASET_VERSION_ID→ 数据集最新版本通过VoltOpsRestClient来自voltagent/sdk以limit offset分页拉取条目--page-size控制每页大小默认 200并在过程中实时汇报下载进度fetched/total将条目映射回本地格式{ name: label, input, expected, extra }写入目标文件。三、实验执行命令eval run1. 命令概览npm run volt eval run -- --experiment path [options]选项选项说明默认值--experiment path实验模块文件路径必填---dataset name运行时覆盖数据集名称---experiment-name name运行时覆盖 VoltOps 实验名称---tag triggerVoltOps 触发来源标签cli-experiment--concurrency n最大并发条目数1-1001--dry-run仅本地运行不提交 VoltOpsfalse环境变量VOLTAGENT_PUBLIC_KEY— VoltOps 集成所需非 dry-run 时VOLTAGENT_SECRET_KEY— VoltOps 集成所需非 dry-run 时VOLTAGENT_API_URL— VoltOps API 端点VOLTAGENT_DATASET_NAME— 默认数据集名称2. 实验文件格式实验文件必须默认导出一个createExperiment的结果来自voltagent/evals// experiments/my-test.experiment.ts import { createExperiment } from voltagent/evals; export default createExperiment({ id: my-test, dataset: { name: test-data }, runner: async ({ item }) ({ output: await processItem(item.input), }), scorers: [ /* ... */ ], passCriteria: { type: passRate, min: 0.95 }, });关于createExperiment的完整配置runner上下文、scorers、passCriteria、voltOps集成、experiment绑定等可参考 实验配置文档。模块加载细节run-experiment.tsCLI 支持.ts/.tsx/.mts/.cts等 TypeScript 模块通过bundleRequire现场打包加载因此实验文件无需预先编译即可直接运行.js模块则通过import()原生加载模块导出可以是default、experiment或definition字段最终必须是一个kind EXPERIMENT_DEFINITION_KIND的有效实验定义否则报错Provided module does not export a valid experiment definition. Use createExperiment(...)。3. 运行时行为一次完整的eval run遵循以下流程加载并校验实验模块解析绝对路径加载模块校验导出有效性应用运行时覆盖--dataset、--experiment-name、--tag会分别覆盖配置中的数据集名称、VoltOps 实验名称与触发来源applyOverrides同时写入对应环境变量创建 VoltOps Run非 dry-run 时使用VOLTAGENT_API_URL/VOLTAGENT_PUBLIC_KEY/VOLTAGENT_SECRET_KEY构造VoltOpsRestClient--dry-run会设置VOLTAGENT_DISABLE_REMOTE_SUBMIT1并跳过云端客户端按并发上限处理条目--concurrency控制并发源码中通过Math.max(1, Math.trunc(n) || 1)保证至少为 1应用 scorers 并聚合结果每个条目的结果由voltagent/evals的runExperiment汇总产出meanScore、passRate、成功/失败/错误计数等流式输出进度通过onItem/onProgress回调实时刷新 spinner进度显示completed/total items、百分比、最近条目状态符号 ✓/✗/⚠、分数、耗时等输出最终摘要与通过/失败结论打印 Completed/Success/Failures/Errors/Mean score/Pass rate若存在 VoltOps run 则输出控制台链接。典型输出Running experiment: my-test Dataset: test-data (100 items) Concurrency: 4 Progress: [ ] 50/100 (50%) Item 42 ✓ (score: 0.95) Item 43 ✗ (score: 0.45) Summary: - Success: 95/100 (95%) - Mean Score: 0.92 - Pass Criteria: ✓ PASSED VoltOps Run: https://console.voltagent.dev/evals/runs/run_abc123注意上面输出中的进度条与逐条信息是示意格式实际 CLI 采用ora动态 spinner 实时刷新run-experiment.ts 的 buildSpinnerText最终 Summary 部分则与上述结构一致。4. 使用示例# 基础运行 npm run volt eval run -- --experiment ./experiments/qa-test.ts # 覆盖数据集 npm run volt eval run -- \ --experiment ./experiments/qa-test.ts \ --dataset production-qa-v2 # 高并发 npm run volt eval run -- \ --experiment ./experiments/batch-test.ts \ --concurrency 20 # 本地测试不提交 VoltOps npm run volt eval run -- \ --experiment ./experiments/dev-test.ts \ --dry-run # CI/CD 场景 npm run volt eval run -- \ --experiment ./experiments/regression.ts \ --tag github-actions \ --experiment-name PR #123 Regression # 全参数 npm run volt eval run -- \ --experiment ./src/experiments/comprehensive.ts \ --dataset large-dataset \ --experiment-name Nightly Regression \ --tag scheduled \ --concurrency 10--tag与--experiment-name的组合非常适合 CI 场景通过--tag标记触发来源如github-actions、scheduled通过--experiment-name为每次运行赋予可读名称如 PR #123 Regression便于在 VoltOps 控制台按触发来源与运行名称检索历史结果。同时CLI 还支持 VoltOps 实验的auto-create当--experiment-name指定的实验在云端不存在时会尝试自动创建详见 run-experiment.ts 的 applyExperimentOverride 与 VoltOpsExperimentInfo。5. 错误处理eval run对各类异常有明确的分级处理实验文件缺失 → 报错并给出完整路径实验模块格式非法 → 显示校验错误提示使用createExperiment数据集不存在 → 列出可用数据集VoltOps 连接失败 → 降级为本地模式继续运行附带警告scorer 出错 → 记录日志但不会中断整个运行CtrlC→ 优雅退出并保留部分结果。6. 退出码| 码 | 说明 | | -- | ---- | | 0 | 成功——所有通过标准均满足 | | 1 | 失败——通过标准未满足 | | 2 | 错误——执行过程中出错 | | 130 | 中断——用户取消 |退出码让eval run可以无缝嵌入 CI/CD非零退出码尤其是 1直接让流水线失败从而在回归测试中自动拦截不合格的 Agent 版本。四、全局选项所有命令都支持以下全局选项选项说明--help显示命令帮助--version显示 CLI 版本--verbose开启调试日志--quiet抑制进度输出--no-color关闭彩色输出CLI 入口基于commander构建index.ts启动时会打印 VoltAgent CLI 的 ASCII 横幅并注册init、update、whoami、add、mcp、deploy、eval、tunnel、prompts、login、logout等命令--help会展示完整的命令树。五、配置指南1. VoltOps 认证通过环境变量提供认证信息export VOLTAGENT_PUBLIC_KEYpk_live_xxxxx export VOLTAGENT_SECRET_KEYsk_live_xxxxx也可以写入项目根目录的.env文件CLI 在运行时会自动加载见 config.ts 的 loadLocalEnvFileVOLTAGENT_PUBLIC_KEYpk_live_xxxxx VOLTAGENT_SECRET_KEYsk_live_xxxxx VOLTAGENT_API_URLhttps://api.voltagent.dev VOLTAGENT_CONSOLE_URLhttps://console.voltagent.dev认证解析顺序resolveAuthConfig加载项目根目录.env若存在若VOLTAGENT_API_URLVOLTAGENT_PUBLIC_KEYVOLTAGENT_SECRET_KEY三者齐全 → 直接使用否则若promptIfMissing为 true → 交互式输入缺失的公钥/私钥密码掩码输入并将输入写入.env文件以便复用若为 false → 直接抛出 VoltAgent credentials not found 错误。提示除环境变量认证外CLI 还提供voltagent login/voltagent logout/voltagent whoami命令管理 VoltOps 登录令牌令牌存储在~/.config/voltcli/config.json详见 config.ts 的 VoltOps Token Management适合以个人账号而非 API Key 方式使用 VoltOps 的场景。2. 项目配置创建.voltagent/config.json来存放项目级默认值{ defaultDataset: production-qa, defaultConcurrency: 4, experimentsPath: ./src/experiments, datasetsPath: ./.voltagent/datasets }这些默认值定义了实验文件与数据集文件的约定存放位置并让「不带参数运行」成为可能默认数据集、默认并发度都可以从配置中读取进一步简化命令行调用。六、故障排查常见问题认证失败Error: Authentication failed (401)核对VOLTAGENT_PUBLIC_KEY与VOLTAGENT_SECRET_KEY是否正确检查密钥在 VoltOps Console 中的权限确认密钥与目标环境生产/预发匹配。数据集不存在Error: Dataset test-data not found通过voltagent eval dataset pull交互模式列出可用数据集检查数据集名称拼写确认数据集存在于当前项目对应环境中。实验模块错误Error: Failed to load experiment module检查文件路径是否正确确保默认导出的是createExperiment(...)的结果使用.ts文件时确认 TypeScript 代码本身可编译CLI 通过bundleRequire加载语法错误会导致失败检查依赖是否完整安装。连接超时Error: Request timeout (ETIMEDOUT)检查网络连通性确认VOLTAGENT_API_URL可访问先使用--dry-run做本地测试检查防火墙/代理设置。调试模式开启详细日志以便定位问题# Unix/Linux DEBUGvoltagent:* voltagent eval run --experiment ./test.ts # Windows set DEBUGvoltagent:* voltagent eval run --experiment ./test.ts # 或使用 --verbose 标志 voltagent eval run --experiment ./test.ts --verbose提示对于云端链路问题--dry-run可以完全绕过 VoltOps帮助你区分「本地评估逻辑问题」与「云端连接问题」。七、总结与延伸阅读VoltAgent CLI 的eval命令族把「数据集管理」与「实验执行」两个环节标准化配合--tag、--experiment-name、--dry-run与退出码机制可以很自然地在本地开发调试、CI 回归检查、夜间定时评估等场景中复用同一套实验定义。其底层由 packages/cli 的 Commander 命令注册、dataset-push.ts / dataset-fetch.ts 的云端同步、以及 run-experiment.ts 与voltagent/evals的评估内核共同驱动。继续深入参考离线评估 — 以编程方式运行实验runExperimentAPI数据集 — 数据集结构与字段管理实验 — 实验配置全解runner / scorers / passCriteria / VoltOps 集成自定义 Scorer — 构建领域专属评分器内置 Scorer — 现有评分器清单赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐Phoenix 实验数据集 Python 全指南创建、管理与评估器接入实战Phoenix 实验数据集 Python 全指南创建、管理与评估器接入实战 本篇技术指南聚焦 Arize PhoenixAI Observability 可观测性AI 评测LLMOpsAI 应用人工智能距408考试60天基于cs-408题库的真题模拟题完整组合方案距408考试60天基于cs 408题库的真题模拟题完整组合方案 11月的某一天你翻开近五年的真题发现自己对树与图TCP握手这些必考内容依然靠死记文档教育教程goose CLI 命令全解从会话管理、任务执行到终端集成的实战指南goose CLI 命令全解从会话管理、任务执行到终端集成的实战指南 goose 是一款开源的、可扩展的 AI Agent其命令行界面CLI提供了管理会人工智能大模型AI AgentAI 应用本地部署MCP ClientsMCP 服务工具调用桌面应用CLI上一篇告别歌词不同步LrcHelper让SONY WALKMAN歌词显示效果提升300%的实战指南下一篇PHPStan argument.invalidConstant 错误详解向函数参数传入无效常量时的静态检测与修复创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考