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

• 人工智能
• AI Agent
• Agent 框架
• 后端
• 多智能体
• RAG
• 工具调用
• Agent 记忆

【免费下载链接】voltagent

AI 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.js：v18 及以上版本（推荐更高版本）；
• 包管理器：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-app@latest -- --example with-research-assistant

方式二：直接在仓库中运行，先安装依赖：

pnpm install # 或 npm install / yarn install

接着在examples/with-research-assistant目录下创建环境变量文件.env：

# .env OPENAI_API_KEY=your_openai_api_key_here EXA_API_KEY=your_exa_api_key_here

其中EXA_API_KEY会被src/index.ts中的 MCP 配置通过process.env.EXA_API_KEY自动读取（详见下文"Exa MCP 接入"小节），无需额外手工配置。

启动开发模式：

npm run dev # 或 pnpm dev / yarn dev

package.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 user's instructions.", model: "openai/gpt-4o", tools: await mcpConfig.getTools(), markdown: true, maxSteps: 50, });

几个值得注意的配置项：

• instructions：系统提示词，决定了 Agent 的行为边界。助理 Agent 被要求"只输出纯文本查询、每行一条、不加任何格式"，这保证了后续数据能被稳定解析；
• model：不同任务使用不同模型——研究查询用轻量的 GPT-4o-mini，报告撰写用更强的 GPT-4o，这正是 README 提到的"为不同任务选择不同 LLM"；
• markdown: 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 的链式（fluent）APIcreateWorkflowChain定义输入/输出的类型契约，再用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( ` I'm 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 Schema，result定义最终输出类型）。本例中：

• 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 }返回，作为后续步骤的data；
• writing 步骤通过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注册两个 Agent，workflows将research-assistant工作流注册为assistant（README 中该工作流的展示名称为Research Assistant Workflow，即createWorkflowChain中name字段的值），server: honoServer()挂载来自 packages/server-hono 的 Hono HTTP 服务，createPinoLogger提供结构化日志。

在 VoltOps 控制台交互

运行npm run dev后，打开 VoltOps 平台（README 中提供的地址为 https://console.voltagent.dev），执行以下步骤：

1. 找到名为Research Assistant Workflow的工作流；
2. 点击进入，输入一个topic参数并运行；
3. 尝试以下研究主题进行验证：
   • "Latest developments in quantum computing"
   • "Impact of AI on healthcare in 2024"
   • "Sustainable energy storage solutions"
   • "Future of remote work technologies"

控制台中即可观察到工作流按"研究 → 写作"两阶段顺序执行，并最终返回带参考文献列表的报告文本。

工作原理总结

整个示例的运行链路可以概括为：

1. 用户在 VoltOps 控制台提交topic；
2. 工作流research-assistant校验输入（Zod）后进入research步骤，助理 Agent（GPT-4o-mini）在temperature: 1下生成 3 条多样化查询，通过 Exa MCP 工具检索资料，输出查询文本；
3. 工作流进入writing步骤，写作 Agent（GPT-4o，markdown: true）利用getStepData("research")取回的主题输入与当前步骤的检索文本，撰写两段式报告并在正文以[#]脚注标注引用、文末附 References URL 列表；
4. 工作流返回{ text }作为最终结果（符合resultSchema 校验）。

该示例集中展示了 VoltAgent 的四个核心能力：Agent 与工具解耦（Exa 经 MCP 注入，Agent 本身不感知网络细节）、顺序数据流（步骤间通过返回值与getStepData传递上下文）、类型安全的数据流动（Zod 双端校验 + TS 全链路类型推断），以及多模型分工（轻量模型做检索、强模型做写作）。以此为模板，你可以将任意外部工具（数据库、浏览器、自定义 API）通过 MCP 接入，并借助andWhen、andAll、andAgent等步骤原语构建更复杂的研究型 Agent 系统。

赞分享

• 人工智能
• AI Agent
• Agent 框架
• 后端
• 多智能体
• RAG
• 工具调用
• Agent 记忆

【免费下载链接】voltagent

AI 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个高效调试技巧