使用 VoltAgent 构建多智能体研究助手：Workflow Chain 与 Exa MCP 集成实战

人工智能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 是一个开源的 TypeScript AI Agent 框架本篇指南以with-research-assistant示例为骨架完整演示如何用它搭建一个研究 写作两阶段的多智能体工作流研究助理 Agent 借助 Exa 搜索经 MCP 接入生成检索查询并搜集素材写作 Agent 再将素材组织成带引用的分析报告。读完本文你将掌握 VoltAgent 的 Agent 定义、MCP 配置、createWorkflowChain链式编排、跨步骤数据访问getStepData以及如何接入 VoltOps 控制台交互运行并能直接复制出可运行的完整项目。示例速览一个真实可运行的 AI 研究助手该示例位于仓库 examples/with-research-assistant核心入口是 src/index.ts。它演示了 VoltAgent 工作流系统中一个典型的多智能体协作场景研究阶段Research Phase助理 Agent 接收用户给定主题生成多条多样化的搜索查询并通过 Exa MCP 工具检索网络资料写作阶段Writing Phase写作 Agent 分析研究材料产出结构化的两段式分析报告并在文末以脚注引用形式列出所有来源 URL。官方 README 总结的五大特性构成了这个示例的骨架见 examples/with-research-assistant/README.md多智能体工作流编排多个 Agent 协作完成复杂研究任务Exa MCP 集成通过 Model Context Protocol 接入 Exa 的搜索能力采集研究数据智能查询生成助理 Agent 为研究主题构思覆盖面广的有效检索词专业报告撰写写作 Agent 将研究发现组织成结构清晰的分析报告类型安全数据流使用 Zod Schema 做运行时校验并打通 TypeScript 类型推断。环境准备与前置依赖运行本示例前需要准备以下环境以仓库实际依赖为准Node.jsv18 及以上版本推荐更高版本包管理器pnpm、npm 或 yarn 均可OpenAI API Key示例默认使用openai/gpt-4o-mini与openai/gpt-4o两个模型Exa API Key在 https://exa.ai/ 注册账号后从控制台 Dashboard 获取。查看 package.json 可知本示例依赖的核心包版本为voltagent/core^2.9.2、voltagent/logger^2.0.2、voltagent/server-hono^2.0.14、voltagent/libsql^2.1.2、voltagent/cli^0.1.21以及zod^3.25.76开发期使用tsx直接运行 TypeScript。快速启动创建项目并运行有两种方式拿到这个示例方式一通过脚手架创建推荐官方 README 提供了一条命令npm create voltagent-applatest -- --example with-research-assistant方式二直接在仓库中运行先安装依赖pnpm install # 或 npm install / yarn install接着在examples/with-research-assistant目录下创建环境变量文件.env# .env OPENAI_API_KEYyour_openai_api_key_here EXA_API_KEYyour_exa_api_key_here其中EXA_API_KEY会被src/index.ts中的 MCP 配置通过process.env.EXA_API_KEY自动读取详见下文Exa MCP 接入小节无需额外手工配置。启动开发模式npm run dev # 或 pnpm dev / yarn devpackage.json中dev脚本为tsx watch --env-file.env ./src它会自动加载.env并以 watch 模式运行源码目录。启动成功后日志中会出现 MCP 连接与工具拉取的信息随后是 VoltAgent 的标准启动消息说明两个 Agent 与工作流已成功注册。Exa MCP 接入把外部搜索能力注入 Agent示例通过MCPConfiguration以stdio 子进程方式启动一个远程 MCP 服务器mcp-remote将 Exa 搜索服务暴露为 Agent 可直接调用的工具import { Agent, MCPConfiguration, VoltAgent, createWorkflowChain } from voltagent/core; import { createPinoLogger } from voltagent/logger; import { honoServer } from voltagent/server-hono; import { z } from zod; const mcpConfig new MCPConfiguration({ servers: { exa: { type: stdio, command: npx, args: [-y, mcp-remote, https://mcp.exa.ai/mcp?exaApiKey${process.env.EXA_API_KEY}], }, }, });从源码看MCPConfiguration定义于 packages/core/src/mcp/registry/index.ts会为每个服务器维护独立的 MCP 客户端缓存mcpClientsById并支持可选的授权配置authorization用于工具级访问控制它还提供disconnect()方法用于优雅断开所有已连接的 MCP 客户端。示例中通过await mcpConfig.getTools()将 Exa 暴露的工具取回并同时注入两个 Agent。定义两个各司其职的 Agent示例构建了查询生成与报告撰写两个 Agent职责边界非常清晰const assistantAgent new Agent({ id: assistant, name: Assistant, instructions: The user will ask you to help generate some search queries. Respond with only the suggested queries in plain text with no extra formatting, each on its own line. Use exa tools., model: openai/gpt-4o-mini, tools: await mcpConfig.getTools(), }); const writerAgent new Agent({ id: writer, name: Writer, instructions: Write a report according to the users instructions., model: openai/gpt-4o, tools: await mcpConfig.getTools(), markdown: true, maxSteps: 50, });几个值得注意的配置项instructions系统提示词决定了 Agent 的行为边界。助理 Agent 被要求只输出纯文本查询、每行一条、不加任何格式这保证了后续数据能被稳定解析model不同任务使用不同模型——研究查询用轻量的 GPT-4o-mini报告撰写用更强的 GPT-4o这正是 README 提到的为不同任务选择不同 LLMmarkdown: true让写作 Agent 以 Markdown 格式输出markdown是 Agent 的公开配置属性见 packages/core/src/agent/agent.ts 中 AgentConfig 相关定义maxSteps: 50限制 Agent 单次任务的最大执行步数防止工具调用链失控或无限循环packages/core/src/agent/agent.ts 中maxSteps为可选配置并支持通过stopWhen覆盖默认的stepCountIs(maxSteps)停止条件。用 createWorkflowChain 编排两阶段工作流工作流是本示例的灵魂。它使用 VoltAgent 的链式fluentAPIcreateWorkflowChain定义输入/输出的类型契约再用andThen按顺序追加步骤const workflow createWorkflowChain({ id: research-assistant, name: Research Assistant Workflow, purpose: A simple workflow to assist with research on a given topic., input: z.object({ topic: z.string() }), result: z.object({ text: z.string() }), }) .andThen({ id: research, execute: async ({ data }) { const { topic } data; const result await assistantAgent.generateText( Im writing a research report on ${topic} and need help coming up with diverse search queries. Please generate a list of 3 search queries that would be useful for writing a research report on ${topic}. These queries can be in various formats, from simple keywords to more complex phrases. Do not add any formatting or numbering to the queries. , { provider: { temperature: 1 } }, ); return { text: result.text }; }, }) .andThen({ id: writing, execute: async ({ data, getStepData }) { const { text } data; const stepData getStepData(research); const result await writerAgent.generateText( Input Data: ${text} Write a two paragraph research report about ${stepData?.input} based on the provided information. Include as many sources as possible. Provide citations in the text using footnote notation ([#]). First provide the report, followed by a single References section that lists all the URLs used, in the format [#] url. , ); return { text: result.text }; }, });类型安全的输入/输出契约createWorkflowChain的input与result均使用 Zod Schema 定义在 packages/core/src/workflow/chain.ts 中WorkflowConfig的input接受 Zod Schemaresult定义最终输出类型。本例中input: z.object({ topic: z.string() })工作流只接收一个topic字符串result: z.object({ text: z.string() })工作流最终产出一段报告文本。这带来两个收益运行时校验——非法输入在工作流入口即被拦截编译期类型推断——每个步骤的data参数都能获得完整的 TypeScript 类型提示。andThen 步骤与跨步骤数据访问andThen用于追加一个函数步骤其execute回调接收{ data, getStepData, ... }上下文上下文类型WorkflowExecuteContext定义于 packages/core/src/workflow/chain.ts其中getStepData(stepId)返回指定步骤的WorkflowStepData可能是undefined。这正是本示例的关键技巧research 步骤从data解构出topic调用assistantAgent.generateText生成查询词并将结果以{ text: result.text }返回作为后续步骤的datawriting 步骤通过getStepData(research)读取任意前置步骤此处为 research的输入数据stepData?.input与当前步骤的data.text查询词列表一起拼进提示词要求写作 Agent基于提供的信息撰写两段研究报告正文使用脚注标注引用文末提供 References 引用列表。此外andThen的步骤配置还支持name、purpose、retries等可选字段generateText可传入{ provider: { temperature: 1 } }这类 provider 级参数research 步骤将温度调至 1以鼓励查询词的多样性与创造性。工作流链式 API 的更多可能从 packages/core/src/workflow/chain.ts 的类型定义看createWorkflowChain返回的链式对象除了andThen还内置了andAgent把某步任务直接委托给 Agent 执行、andWhen/andBranch条件分支、andForEach/andMap循环与映射、andAll/andRace并行、andGuardrail护栏校验、andSleep/andSleepUntil延时等丰富步骤原语。本示例展示的研究 → 写作顺序流水线只是最基础的一种组合读者可以在此基础上轻松扩展出更复杂的编排。注册到 VoltOps把工作流跑起来最后一步是将 Agent 与工作流注册进 VoltAgent 实例并挂上 Hono 服务器与日志const logger createPinoLogger({ name: with-mcp, level: info, }); new VoltAgent({ agents: { assistant: assistantAgent, writer: writerAgent, }, workflows: { assistant: workflow, }, server: honoServer(), logger, });new VoltAgent({ ... })会启动一个可交互的运行时agents注册两个 Agentworkflows将research-assistant工作流注册为assistantREADME 中该工作流的展示名称为Research Assistant Workflow即createWorkflowChain中name字段的值server: honoServer()挂载来自 packages/server-hono 的 Hono HTTP 服务createPinoLogger提供结构化日志。在 VoltOps 控制台交互运行npm run dev后打开 VoltOps 平台README 中提供的地址为 https://console.voltagent.dev执行以下步骤找到名为Research Assistant Workflow的工作流点击进入输入一个topic参数并运行尝试以下研究主题进行验证Latest developments in quantum computingImpact of AI on healthcare in 2024Sustainable energy storage solutionsFuture of remote work technologies控制台中即可观察到工作流按研究 → 写作两阶段顺序执行并最终返回带参考文献列表的报告文本。工作原理总结整个示例的运行链路可以概括为用户在 VoltOps 控制台提交topic工作流research-assistant校验输入Zod后进入research步骤助理 AgentGPT-4o-mini在temperature: 1下生成 3 条多样化查询通过 Exa MCP 工具检索资料输出查询文本工作流进入writing步骤写作 AgentGPT-4omarkdown: true利用getStepData(research)取回的主题输入与当前步骤的检索文本撰写两段式报告并在正文以[#]脚注标注引用、文末附 References URL 列表工作流返回{ text }作为最终结果符合resultSchema 校验。该示例集中展示了 VoltAgent 的四个核心能力Agent 与工具解耦Exa 经 MCP 注入Agent 本身不感知网络细节、顺序数据流步骤间通过返回值与getStepData传递上下文、类型安全的数据流动Zod 双端校验 TS 全链路类型推断以及多模型分工轻量模型做检索、强模型做写作。以此为模板你可以将任意外部工具数据库、浏览器、自定义 API通过 MCP 接入并借助andWhen、andAll、andAgent等步骤原语构建更复杂的研究型 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点击查看免费下载相关推荐用 VoltAgent 接入 Exa MCP 构建智能菜谱生成 Agent完整实战指南用 VoltAgent 接入 Exa MCP 构建智能菜谱生成 Agent完整实战指南 本指南基于 VoltAgent 官方示例 examples/with人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音Video2X面向低清素材的开源视频超分辨率与帧插值工具Video2X面向低清素材的开源视频超分辨率与帧插值工具 Video2X 是一个基于机器学习的视频超分辨率与帧插值开源框架整合了 Real ESRGAN、R音视频视频处理图像处理深度学习Ruflo 高级 Swarm 编排实战基于 MCP 工具与 CLI 构建研究、开发、测试多智能体集群Ruflo 高级 Swarm 编排实战基于 MCP 工具与 CLI 构建研究、开发、测试多智能体集群 本文基于 ruflo 仓库中的高级蜂群编排技能文档 .人工智能AI Agent多智能体Agent 编排Agent 记忆工具调用代码智能体MCP 服务AI 评测上一篇yuzu仿真平台实战指南5步掌握Switch游戏PC端部署与优化下一篇Vim日志文件分析终极指南10个高效调试技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考