★ FEATURED ARTICLE 人工智能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 官方脚手架create-voltagent-app的变更记录为主线系统梳理该 CLI 工具从 AI 供应商选择、包管理器检测含 Bun 支持、模型注册表provider/model字符串、LibSQL 持久化可观测性到 VoltAgent 2.xAI SDK v6迁移的完整能力脉络。读者将掌握如何用一条命令创建生产就绪的 VoltAgent 项目、理解生成模板中每个默认组件的用途并了解 1.x 到 2.x 升级的关键步骤。一、工具定位一条命令生成 VoltAgent 应用create-voltagent-app是 VoltAgent 生态中的官方项目脚手架其作用与create-next-app、create-vite类似通过交互式问答把「选服务器框架 → 选 AI 供应商 → 配 API Key → 选 IDE → 装依赖」这条完整链路自动化。它也是 VoltAgent 开发者生态README 中提到的 Developer Ecosystem的重要组成部分与voltagent/cli、VoltOps 可观测平台共同构成从初始化到监控调试的闭环。入口代码见 packages/create-voltagent-app/src/index.ts它直接调用runCLI()cli.ts。使用方式即官方 README 中的快速开始命令npm create voltagent-applatest也可以直接指定项目目录npm create voltagent-applatest my-agent-app从cli.ts的实现可以看到CLI 基于commander构建还支持一个特殊选项--example name用于从 VoltAgent 仓库的examples目录直接下载某个示例如with-nextjs、with-rag-chatbot走的是「检查仓库 → 下载 → 解压」的独立流程utils/github.ts。二、交互式初始化流程0.2.0 现代化改造CHANGELOG 0.2.0 记录了一次里程碑式的 CLI 现代化重构奠定了如今交互流程的骨架。对照 cli.ts 的源码完整流程如下项目命名未传目录参数时用inquirer询问项目名默认my-voltagent-app并校验目录是否已存在cli.ts。选择 REST 服务器框架Hono推荐或 Elysia。两者分别对应voltagent/server-hono与voltagent/server-elysia包版本要求均为^2.0.0工厂函数分别为honoServer()与elysiaServer()见 types.ts。选择包管理器见下一节详述。选择 AI 供应商OpenAI、Anthropic、Google、Groq、Mistral、Ollama本地。可选 API Key 输入支持跳过跳过时.env中会写入占位符。选择 IDE用于自动配置 MCP Docs ServerCursor / Windsurf / VS Code / 暂不配置。自动安装依赖基座依赖在提问阶段就已异步安装见下。每次创建都会上报匿名分析事件captureProjectCreation/captureError见 utils/analytics.ts这解释了为什么测试文件 cli.integration.spec.ts 中会 mock 掉 analytics 与 inquirer。值得注意的是「边问边装」的并行设计选定包管理器后createBaseDependencyInstaller立即开始安装基础依赖用户继续回答 AI 供应商等问题时安装已在后台进行waitForCompletion()会在后续提问前等待其完成cli.ts。基座依赖清单见 dependency-installer.ts包括voltagent/core、voltagent/libsql、ai、voltagent/cli、voltagent/logger、dotenv、zod以及所选服务器包Node 版本要求20.19.00.1.26 起放弃 Node.js v18。三、包管理器检测与 Bun 支持0.2.190.2.19 为 CLI 引入了包管理器选择能力CLI 现在会检测可用的包管理器pnpm、bun、yarn、npm并让用户在项目初始化过程中选择使用哪一个所选包管理器会用于依赖安装和创建后的运行指引若未检测到任何包管理器则回退到 npm 并给出明确警告。实现细节在 utils/package-manager.ts跨平台检测通过execSync执行whereWindows或whichUnix-like判断命令是否存在package-manager.ts。只展示已安装项getInstalledPackageManagers()遍历PACKAGE_MANAGER_CONFIG的键仅把 PATH 中真实存在的包管理器作为选择项package-manager.ts。默认优先级pnpm bun yarn npm全部缺失时兜底 npmtypes.ts。安静安装参数每个包管理器配置了各自的静默安装参数如pnpm install --loglevelerror、bun install --silent、npm install --loglevelerrortypes.ts。依赖安装本身通过spawn异步执行捕获 stderr 输出仅在 Windows 下使用 shelldependency-installer.ts——这正对应 0.2.0 中「完整的 Windows 支持与跨平台命令」的改进。四、模型注册表用provider/model字符串零导入选模型0.2.180.2.18 引入「模型注册表 路由器」这是对开发者体验影响最直接的变化之一新增模型注册表与路由器让你可以直接使用provider/model字符串而无需导入对应的 provider 包。import { Agent } from voltagent/core; const openaiAgent new Agent({ name: openai-agent, instructions: Summarize the report in 3 bullets., model: openai/gpt-4o-mini, }); const anthropicAgent new Agent({ name: anthropic-agent, instructions: Turn notes into action items., model: anthropic/claude-3-5-sonnet, }); const geminiAgent new Agent({ name: gemini-agent, instructions: Translate to Turkish., model: google/gemini-2.0-flash, });在脚手架语境下这套机制与AI_PROVIDER_CONFIG一一对应每种供应商都配置了默认模型 ID、环境变量名与 Key 申请地址types.ts供应商默认模型 ID环境变量是否需 API KeyOpenAIopenai/gpt-4o-miniOPENAI_API_KEY是Anthropicanthropic/claude-3-5-sonnetANTHROPIC_API_KEY是Googlegoogle/gemini-2.0-flashGOOGLE_GENERATIVE_AI_API_KEY是Groqgroq/llama-3.3-70b-versatileGROQ_API_KEY是Mistralmistral/mistral-large-latestMISTRAL_API_KEY是Ollama本地ollama/llama3.2无本地服务否生成代码时模板中的{{modelId}}占位符会被替换为所选供应商的模型 IDutils/templates.ts。这意味着生成的项目天然就是「零 provider 导入」的写法agent 的model字段直接使用provider/model字符串见 templates/base/index.ts.template。五、生成项目的默认骨架与动态模板创建后的项目目录结构由 utils/templates.ts 中的模板清单决定同时由 project-creator.ts 完成.gitignore写入、MCP 配置与git init初始提交my-agent-app/ ├── .env # 由所选供应商动态生成 ├── .gitignore ├── Dockerfile ├── tsconfig.json ├── tsdown.config.ts # 0.2.10 起用 tsdown 打包 └── src/ ├── index.ts # 主入口动态注入服务器/模型/供应商 ├── workflows/ │ └── index.ts # comprehensive-workflow 示例 └── tools/ ├── index.ts └── weather.ts # 天气工具示例模板在源目录src/与构建目录dist/之间做了路径解析resolveTemplatesDir测试环境优先读取源码模板以避免依赖构建产物templates.ts。5.1 自带完整工作流示例0.1.330.1.33 起新项目内置了一个综合性工作流示例覆盖 VoltAgent 工作流引擎的核心组合子andThen、andAgent、andAll、andRace、andWhen并独立出一个sentimentAgent以避免与主 agent 混淆。项目因此拥有模块化的src/workflows目录结构模板中的{{projectName}}会被替换为项目名templates.ts。生成的主入口src/index.ts会将expenseApprovalWorkflow注册进VoltAgentindex.ts.template用户可立即在 VoltOps 控制台的工作流页面运行「Expense Approval Workflow」体验多步编排。5.2 Agent 定义规范instructions取代description0.1.180.1.18 把示例与模板中的 Agent 定义统一迁移到instructions字段为最终弃用description做准备const agent new Agent({ name: My Assistant, - description: A helpful assistant., instructions: A helpful assistant., llm: new VercelAIProvider(), model: openai(gpt-4o-mini), });生成模板同样遵循该约定instructions: A helpful assistant that can check weather and help with various tasksindex.ts.template。六、开箱即用的可观测性可观测性是脚手架模板反复强化的方向经历了三个阶段演进6.1 默认接入 VoltOpsClient0.2.70.2.7 让基座模板始终包含VoltOpsClient从 VoltOps 控制台一键开启生产级可观测性import { VoltAgent, VoltOpsClient, Agent } from voltagent/core; // ... agent configuration ... new VoltAgent({ agents: { agent }, workflows: { expenseApprovalWorkflow }, logger, voltOpsClient: new VoltOpsClient({ publicKey: process.env.VOLTAGENT_PUBLIC_KEY || , secretKey: process.env.VOLTAGENT_SECRET_KEY || , }), });密钥通过VOLTAGENT_PUBLIC_KEY与VOLTAGENT_SECRET_KEY环境变量注入这一配置至今仍保留在生成模板中index.ts.template且 README 模板会把这两个变量以注释形式写入.env预览templates.ts。6.2 LibSQL 持久化观测数据0.2.130.2.13 修复了一个关键缺陷此前模板使用内存观测存储重启后 trace 与 span 全部丢失。现在模板改用LibSQLObservabilityAdapter把可观测数据持久化到.voltagent/observability.db与已有的持久化记忆.voltagent/memory.db保持一致const observability new VoltAgentObservability({ storage: new LibSQLObservabilityAdapter({ url: file:./.voltagent/observability.db, }), });该配置同样沉淀在 index.ts.template。记忆与观测两条数据链路都落在本地 SQLite 文件上开发期重启不丢数据调试与监控体验显著改善。七、默认日志方案voltagent/logger0.2.30.2.3 为模板引入voltagent/logger用createPinoLogger取代默认的 ConsoleLoggerimport { createPinoLogger } from voltagent/logger; const logger createPinoLogger({ level: info, name: my-voltagent-app, }); const voltAgent new VoltAgent({ agents: [agent], logger, });其核心收益是环境自适应开发环境输出漂亮的彩色格式化日志生产环境输出 JSON。生成的模板中name取项目名、level为info并配合logger.child({ component: libsql })为存储适配器划分子日志index.ts.template。八、VoltAgent 2.x 迁移指南0.2.140.2.14 将脚手架对齐到 VoltAgent 2.x底层为 AI SDK v6。CHANGELOG 给出了明确的 1.x → 2.x 迁移摘要升级 VoltAgent 包npm run volt update若 CLI 缺失先执行npx voltagent/cli init再npm run volt update。对齐 AI SDK 依赖pnpm add ai^6 ai-sdk/provider^3 ai-sdk/provider-utils^4 ai-sdk/openai^3若使用 UI hooks需将ai-sdk/react升级到^3。结构化输出generateObject与streamObject在 VoltAgent 2.x 中已弃用改用generateText/streamText搭配Output.object(...)。CHANGELOG 特别提示VoltAgent 自身 API 保持兼容但如果直接调用 AI SDK需要遵循上游 v6 迁移指南。这一版本对齐也反映在基座依赖上——模板直接声明ai: ^6.0.0、voltagent/core: ^2.0.0、voltagent/libsql: ^2.0.0、voltagent/logger: ^2.0.0dependency-installer.ts。九、供应商自定义工具透传0.2.110.2.11 为模板与框架增加了对 provider 自定义工具的支持例如 OpenAI 的openai.tools.webSearch()支持将 provider 自定义工具作为独立 tool 使用也支持放进 toolkit工具归一化逻辑会原样透传 provider 工具的元数据依赖ai升级到^5.0.76该版本处于 VoltAgent 1.x 末期2.x 已进一步对齐到ai^6。这为生成项目中使用厂商专属能力如联网搜索扫清了障碍。十、IDE 集成MCP Docs Server0.1.280.1.28 引入了voltagent/docs-mcp包与volt mcp命令族让 AI 编程助手在 IDE 内直接查询 VoltAgent 文档volt mcp setup # 交互式配置 Cursor、Windsurf 或 VS Code volt mcp test # 测试 MCP 连接并给出用法示例 volt mcp status # 查看当前 MCP 配置状态 volt mcp remove # 移除 MCP 配置脚手架侧与之联动在 CLI 中选择 IDE 后project-creator会调用configureMcpForIde为目标 IDE 生成配置目录如.cursor/、.vscode/并在完成后打印 MCP 配置摘要project-creator.ts、cli.ts。配置完成后开发者可以直接在 IDE 中向 AI 助手提问「How do I create an agent in VoltAgent?」「How do I use voice features?」等由 MCP 服务器实时返回文档、示例与最佳实践。十一、工程化与依赖卫生CHANGELOG 中有大量条目反映脚手架背后的工程质量投入也值得了解0.2.6Biome 与发包校验全 monorepo 修复 Biome lint 问题为所有包增加publint脚本严格校验package.json修复voltagent/internal的typesVersions结构启用attwAre The Types Wrong检查保证类型导出正确。0.2.10tsdown 打包应用模板改用 tsdown 打包使生产构建在 Node ESM 下直接运行无需手工补.js扩展名或定制 import 映射器。0.2.8 / 0.1.21 / 0.1.16Zod 版本管理为兼容 Vercel AI5 将 Zod 升级到^3.25.0同时保留与zod-from-json-schema0.0.5的兼容此前多次通过固定 Zod 版本3.24.2规避「Type instantiation is excessively deep and possibly infinite」的 TS 编译错误根因是多个包使用不同 patch 版本的 Zod。0.1.26 / 0.1.21运行时与目标平台放弃 Node.js v18tsconfig.json的target升级到ES2022。0.1.11模块解析package.json增加显式exports字段files数组移除src目录优化模块解析与发布体积。十二、小结从脚手架看 VoltAgent 的最佳实践基线纵观整个 CHANGELOGcreate-voltagent-app的演进方向非常清晰默认即生产可用。从 0.2.0 的多供应商交互式选择到 0.2.18 的provider/model模型注册表再到 0.2.3/0.2.7/0.2.13 连续落地的 Pino 日志、VoltOpsClient 与 LibSQL 持久化观测脚手架不断把「日志、可观测、持久化记忆」这三件基础设施内建到生成模板中。同时0.2.19 的包管理器检测与 Bun 支持、0.2.10 的 tsdown ESM 构建、0.1.28 的 MCP IDE 集成则持续降低新用户的上手摩擦。对开发者而言理解这份 CHANGELOG 就等于掌握了 VoltAgent 推荐的项目基线provider/model字符串选模型、LibSQL 记忆与观测、Pino 日志、VoltOps 可观测、instructions字段定义 agent、内置工作流示例。若要从 1.x 升级直接套用 0.2.14 给出的三步迁移清单即可想深入学习生成的模板细节可在仓库中对照 templates/base 目录与 src 下的 CLI 实现继续探索。赞分享人工智能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/sandbox-e2b 演进解析为 VoltAgent Workspace 接入 E2B 云沙箱voltagent/sandbox e2b 演进解析为 VoltAgent Workspace 接入 E2B 云沙箱 本篇技术指南以 packages/sa人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音使用 create-voltagent-app 快速搭建 VoltAgent AI Agent 应用从一行命令到 Agent 与工作流实战使用 create voltagent app 快速搭建 VoltAgent AI Agent 应用从一行命令到 Agent 与工作流实战 本文以 creat人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音VoltAgent × Vercel AI SDKvoltagent/vercel-ai Provider 从 0.1.1 到 1.0.0 的演进与实现解析VoltAgent × Vercel AI SDK voltagent/vercel ai Provider 从 0.1.1 到 1.0.0 的演进与实现解人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音上一篇VuelidateVue.js轻量级模型验证库全面解析下一篇PatternFly 3无障碍访问(A11y)构建符合WCAG标准的界面终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
