企业官网建设流程全解析

多智能体系统听起来很复杂，但真正上手之后，核心就一句话：用一个主控角色把任务拆开，分给几个专门负责不同工作的 Agent，最后再把结果收回来。这篇文章要拆解的，就是怎么从零搭建一条 Hermes Agent 多智能体链路，用 1 个主控调度 3 个 Agent，底层模型接 Qwen 通义千问。适合正在做 Agent 开发、想从单 Agent 往多 Agent 协作过渡的读者，也适合那些已经跑通 Demo 但不知道生产环境里怎么配置主控、任务队列和失败重试的人。

这里要提前说清楚：Hermes Agent 的配置项在不同版本里会有差异，文章里给的配置结构是通用示例。你落地的时候，先把版本和 API 方式确认好，再照着调。

1. 先搞清楚它解决的是多 Agent 协作，不是替代模型

很多人在学 Agent 开发时，第一个念头是“哪个框架更强大”。但多智能体系统真正的价值不是让单个模型推理能力变强，而是把任务的流程控制权从代码里拿出来，交给一个主控 Agent 去编排。Hermes Agent 这类框架解决的核心问题，是多个角色之间怎么通信、任务怎么分发、结果怎么汇总。

1.1 主控调度不是“更聪明的模型”

主控调度器一般不需要比工作 Agent 更强的模型能力，它更像一个项目管理者。它的职责是：理解用户输入，把目标拆成多个子任务，按顺序或并行分发给对应 Agent，最后把返回结果合并成最终答复。工作 Agent 则更专注：有的负责检索资料，有的负责分析文本，有的负责生成内容。这样做的好处是，每个 Agent 的提示词、工具和上下文都可以单独控制，不会因为任务类型混杂而互相干扰。

实测中的体会是，主控模型的选择会影响任务拆分的质量。如果主控模型本身理解能力不够，就会把任务拆错，导致下游 Agent 拿到错误指令。所以预算允许时，主控尽量用能力更强一点的模型，工作 Agent 可以根据任务难度搭配不同档位。

顺带说一句，多智能体系统的交互模式并不只有“主控派单”这一种。业内常见的还有流水线模式、协作模式和辩论模式。流水线模式适合步骤固定、前一步输出就是下一步输入的场景；协作模式适合多个 Agent 地位平等、共同完成一个目标的场景；辩论模式适合需要多角度审视的决策任务。本文用的“1 个主控调度 3 个 Agent”属于主控派单模式，也是上手最容易、问题最好定位的一种，先把这种跑明白，再研究其他模式会更稳。

1.2 为什么这里选 Qwen 通义千问

选 Qwen 作为底层模型，主要有几个原因。第一，Qwen 有 API 和本地部署两条路线，开发阶段用 API 最快，生产环境如果对数据有要求，可以再切本地模型。第二，Qwen 的通用能力、中文理解能力和工具调用能力都比较均衡，在 Agent 场景下不容易出现指令理解偏差。第三，它在很多框架里已经有现成的接入方式，配置量不大。

如果走 API 路线，一般就是申请 Key，然后在 Agent 配置里把 provider 指向 Qwen 对应的服务地址；如果走本地路线，需要先确认显存和内存。我的建议是：第一次学习用 API 最稳，等流程跑通了再考虑本地化，不要一开始就卡在模型部署上。

1.3 三个 Agent 的角色怎么分

标题里的“3 个 Agent”，实际落地时角色可以根据业务改，但一个比较稳妥的起步组合是：

• 检索 Agent：负责查知识库、查外部资料，把原始信息带回来。
• 分析 Agent：负责对检索结果做结构化处理，比如总结、提取要点、对比差异。
• 生成 Agent：负责把最终结果整理成完整、可读的回复。

这个分法最大的好处是职责边界清晰。主控只需要决定“哪个任务交给谁”，不需要关心每个 Agent 内部怎么实现。后面要加第 4 个、第 5 个 Agent 时，也不会影响已经跑通的链路。

2. 环境准备：先跑通最小可用环境，再谈调度

多智能体系统出问题，一半以上不是框架问题，而是环境问题。所以安装之前，先把运行条件确认一遍。

2.1 本地环境需要什么

Hermes Agent 如果走桌面端或本地服务方式，系统层面一般支持 Windows、macOS 和 Linux。我用 Mac 和 Linux 都跑过，Windows 上如果用 WSL 或原生终端也能跑，但要注意路径分隔符和权限问题。

依赖方面，至少要准备：

• Python 环境，建议用 3.10 以上，很多 Agent 项目的新特性只在新版本里支持。
• Node.js 环境，部分前端界面和工具包依赖它。
• 一个可用的模型访问凭据，也就是 Qwen API Key，或者本地模型的访问地址。
• 磁盘空间，尽量留出 5GB 以上。如果还要装本地模型，那要按模型体积单独评估。

安装前先检查这三个命令能不能正常输出版本信息：python --version、node --version、git --version。任何一个报错，都先解决掉再往下走。

2.2 安装 Hermes Agent 与依赖

安装这类框架，最常见的坑是依赖版本冲突。我的建议是新建一个独立的虚拟环境，不要直接装到系统 Python 里。这样后面升级依赖、重装环境都不会影响其他项目。

安装完成后，先执行一个最基础的健康检查，比如查看版本号或帮助命令，确认主程序能正常启动。

注意：如果工具在安装或首次使用时提示需要登录官网、注册账号，这是正常现象。很多 Agent 工具的第一道认证不是模型 API Key，而是工具平台本身的账号体系。不要急着跳过，先看提示要的是工具平台账号还是模型服务账号，两者通常不一样。

Mac 和 Linux 的主要差异在依赖安装方式上。Linux 环境经常缺系统级编译工具，遇到本地包编译报错时，先安装 build-essential 这类基础工具；Mac 上则要注意是不是用了 Homebrew 的 Python 和系统自带 Python 混在一起，容易把依赖装乱。如果不想处理这些，直接先跑官方推荐的安装脚本或容器方式，能省不少时间。

CLI 交互界面里常见的返回上一级、回到主页面这类命令，不同版本差异很大。不要靠记忆硬敲，启动后先看 help 命令列出来的选项，每个版本的快捷键和子命令命名都不一定一样。

2.3 确认 Qwen 模型可以正常响应

在接入多智能体调度之前，先单独验证模型能不能通。最直接的方法，是写一个最小请求脚本，调用一次 Qwen API，传入一段简单文本，确认返回值结构完整。

这一步很重要。如果模型调用本身就不通，后面配置主控和三个 Agent 时，你会分不清报错到底来自框架还是模型。实测时我一般先做一次 curl 或脚本调用，确认三件事：

• API Key 是否有效。
• 请求地址和模型名称是否匹配。
• 返回内容里是否包含正常的结果字段。

把这三点确认好，再进入 Hermes Agent 配置，排错范围会小很多。

这里给一段类似的请求示例，字段以你的服务商文档为准：

curl -X POST "https://your-qwen-endpoint/v1/chat/completions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-max", "messages": [ {"role": "user", "content": "你好，请回复一句话确认模型服务正常"} ] }'

如果返回里有 choices 字段，并且 message.content 是正常文本，说明模型服务没问题。接下来就可以放心配置 Hermes Agent。

3. 配置主控与三个 Agent：核心是职责和上下文的边界

多智能体配置和单 Agent 最大的区别是：你要同时管理多个提示词、多个模型参数、多个任务通道。如果所有 Agent 都共用同一套配置，那多 Agent 架构就失去了意义。

3.1 配置文件里需要确认哪些内容

一份典型的多 Agent 配置，通常包含这几块：

• 主控 Agent：模型、系统提示词、最大迭代次数、任务拆分规则。
• 工作 Agent：各自独立模型或共用模型、专属系统提示词、可调用工具。
• 调度规则：任务类型到 Agent 的映射关系。
• 全局配置：API Key、超时时间、日志目录、输出目录。

主控的 system prompt 是最重要的。它要让主控知道：自己不是直接回答问题的专家，而是任务分发者。建议在提示词里明确写清楚“遇到任务时，先判断需要调用哪个 Agent，不要自己越权完成所有工作”。

3.2 一个主控加三个 Agent 的示例配置

下面是一个通用结构示例，具体字段名需要按你安装的版本调整，但思路是通用的：

orchestrator: name: main_controller model: provider: qwen model_name: qwen-max system_prompt: | 你是整个多智能体系统的主控调度器。 请将用户任务拆解为子任务，并分配给对应的 worker agent。 不要直接替 worker 完成全部工作。 workers: - name: retriever_agent model: provider: qwen model_name: qwen-plus system_prompt: | 你是资料检索 Agent，负责查找和返回原始资料。 返回结果时保留来源和关键段落。 - name: analyzer_agent model: provider: qwen model_name: qwen-plus system_prompt: | 你是分析 Agent，负责对资料做总结、归纳和对比。 输出必须结构化，使用要点列表。 - name: generator_agent model: provider: qwen model_name: qwen-max system_prompt: | 你是内容生成 Agent，负责把分析结果整理成最终回复。 语言要清晰、完整、可读性强。 routing: - task_type: search target: retriever_agent - task_type: analyze target: analyzer_agent - task_type: generate target: generator_agent global: timeout_seconds: 120 max_iterations: 5 log_dir: ./logs output_dir: ./output

这份配置里，主控和生成 Agent 用了更强一点的模型，检索和分析用了低一档的模型。这样做的目的是控制成本，同时保证关键环节的生成质量。如果你的任务比较简单，全部用同一型号也可以，但最好让每个 Agent 的系统提示词保持独立。

3.3 任务分发和上下文传递

配置好之后，还要想清楚任务是怎么流转的。常见的方式有两种：

• 顺序流转：主控先调检索 Agent，拿回资料，再调分析 Agent，最后调生成 Agent。
• 条件流转：主控根据用户问题的类型，直接决定调哪个 Agent，可以跳步。

这两种方式在代码实现上差别不大，但主控提示词和调度规则要写清楚。顺序流转适合处理链路固定的任务，比如“查资料、做分析、出报告”；条件流转适合开放式问题，比如“用户问天气就直接回，不用启动检索”。

上下文传递是另一个容易踩坑的点。每个 Agent 的输入，不能把上一轮的完整对话全部塞进去，否则上下文会越来越长，带来两个问题：一是 token 消耗变大，二是模型容易被无关信息干扰。建议只传递“当前子任务的输入 + 必要的中间结果摘要”，并在主控里做结果压缩。

4. 从单任务验证到批量任务：先跑通再开并发

配置完成后，最忌讳直接跑一个复杂的真实任务。一定要先做最小验证。

4.1 先跑一条简单任务

我建议用一条边界非常明显的问题来测试，例如“请分析一下这段文本的核心观点，输出三段总结”。这个任务需要检索、分析和生成三个环节，但输入很短，方便定位问题。

第一轮跑的时候，重点看四件事：

• 主控是否成功启动，日志里能看到模型调用记录。
• 主控是否把任务分发给了正确的 Agent。
• 每个 Agent 是否返回了内容。
• 最终输出是否把三个环节的结果汇总起来。

如果第一轮就报错，先不要调参数。去看日志里的完整报错信息，尤其是发生错误的环节。是多 Agent 配置没加载，还是模型调用失败，还是某个 Agent 的提示词格式有问题。大部分问题在这一步就能定位。

4.2 批量任务和并发控制

单任务跑通后，再考虑批量。批量任务的核心不是“一次能跑多少条”，而是“跑挂之后能不能恢复”。所以批量前，先确认三个能力：

• 输入列表是否支持从文件读取。
• 每条任务是否有独立 ID 或独立输出文件。
• 失败任务是否会重试，重试次数和间隔是否能配置。

并发数不要一上来就拉满。先开 2 到 3 个并发，观察资源占用和响应时间，再逐步往上加。很多框架默认并发数看起来很高，但实际受 API 限流和本地资源限制，过高的并发只会让失败率上升。

如果跑的是长任务，建议给每条任务设置合理超时时间，并在输出目录里保留日志。这样即使任务失败，也能根据日志恢复，而不是整套流程重新跑一遍。

4.3 输出结果怎么验证

输出不是“有内容”就算成功。多 Agent 系统里，要验证结果是否符合预期，至少看三层。

第一层，完整性。最终回复是否包含所有必要部分，有没有因为某个 Agent 结果为空导致整体内容缺失。第二层，一致性。三个 Agent 的输出是否在结论上互相矛盾，特别是检索结果和分析结果之间。第三层，可重复性。同一输入跑两次，结果是否有明显波动。如果模型参数固定、输入固定，结果应该相对稳定。如果每次输出差异很大，说明提示词约束不够，需要把输出格式要求写得更细。

5. 常见故障和排查顺序：从日志到输入再到参数

多 Agent 系统故障排查，最怕的就是凭感觉改参数。正确做法是固定一套排查顺序，一层层缩小范围。

5.1 API Key、模型名称与网络问题

这一类问题通常在日志里会直接报 401、403、404 或超时。先确认三件事：

• API Key 有没有复制完整，有没有空格或换行。
• 模型名称是不是服务商支持的准确名称，比如 qwen-max、qwen-plus 这类写法。
• 网络能不能正常访问模型服务地址，公司内网或有防火墙时经常在这里卡住。

注意，模型名称写错是最常见的低级别错误。很多人在本地跑通了，换到服务端时模型名没改，导致请求直接失败。

5.2 任务卡住、超时和“输出死循环”

任务卡住，不要直接杀进程。先看日志停在哪一步，判断是主控还在等 Agent，还是某个 Agent 在等待模型返回。如果日志长时间没有新内容，大概率是模型调用超时，或者上下文过长导致响应变慢。

如果你在日志里看到类似 “the agent execution provider did not respond in time” 的报错，先不用怀疑框架坏了。这类提示本质上就是执行组件没有按时返回，常见原因包括模型服务端响应慢、网络超时、上下文太长、并发数超过了服务商限流。处理顺序是：先降低并发，再缩短单次输入，最后适当调大超时时间。三者都试过还没解决，再回头查网络稳定性。

搜索热词里常提到的“qwen 输出死循环”，本质上是 Agent 在多次迭代中反复调用同一个工具或输出同一段内容。解决办法有两个方向：一是限制最大迭代轮数，比如全局配置里把 max_iterations 调小；二是检查系统提示词是否给 Agent 留下了“重复操作”的空间。比如“如果分析失败，重试一次”这种指令，在没写重试上限时，就可能变成无限重试。

5.3 资源占用和并发下的稳定性

批量跑任务时，如果出现内存飙升、响应变慢、任务互相挤占资源，就需要看资源占用。先用系统监控工具查看 CPU、内存、磁盘读写。如果内存占用持续升高，可能是中间结果没有释放，或者是上下文对象没有清理。此时先降低并发数，再检查日志输出和临时文件。

低配置机器能跑通 Demo，不代表能跑批量任务。我的建议是：内存小于 8GB 的环境，把并发控制在 1 到 2；内存 16GB 以上，再考虑开更高的并发。API 型任务还要考虑服务商侧的限流，不能只看本地资源。

给一个大概的判断表：

6. 从 Demo 到生产落地：知识库、MCP 和 Agent 安全边界

把多 Agent 系统跑通之后，下一步通常就是往生产环境靠。这里有几个方向值得关注。

6.1 给 Agent 外挂知识库

搜索热词里反复出现“hermes agent 外挂知识库”，说明这是很多人刚跑通 Demo 后就遇到的问题。外挂知识库的本质，是把检索环节从“让模型凭记忆回答”变成“先查资料再回答”。常见做法是：将文档切片后存入向量数据库，比如 Milvus，检索 Agent 根据用户问题做向量检索，再把命中片段交给分析 Agent。这样做的好处是回答有依据，缺点是系统复杂度明显上升。落地时建议先确保持一种清晰的文档切片和检索召回策略，再逐步加。

向量数据库不是必须的。如果知识库文档很少，直接用关键词检索也能顶一段时间。我的建议是：文档量少、业务简单时，不要为了用 Milvus 而引入 Milvus，先跑通链路最重要。

6.2 MCP 与 Skill 的区别

很多 Agent 框架现在都支持 MCP 和 Skill。MCP 是模型上下文协议，解决的是 Agent 与外部工具连接的标准问题，比如通过 MCP 让 Agent 调用数据库、访问 API、读写文件。Skill 更像一个内置的专用技能包，通常封装了提示词、工具调用流程和参数模板。

两者的区别，我的理解是：MCP 偏协议层，解决“能不能接”的问题；Skill 偏应用层，解决“接上后怎么用得更好”的问题。实际使用时，一个 Skill 内部可能调用了多个 MCP 工具。所以不要把两者对立起来，而是看你的 Agent 需要什么能力，再决定从哪一层扩展。

6.3 Agent 安全边界

多 Agent 系统在安全上比单 Agent 更需要注意，因为任务会经过多个角色，风险面更大。至少要做四件事：

• 每个 Agent 的权限最小化，检索 Agent 不能同时拥有写文件权限。
• 对 Agent 可调用的工具做白名单，不要开放任意命令执行。
• 日志脱敏，避免 API Key 和用户敏感信息落到普通日志里。
• 外层再加一道请求审核，确认用户输入不会被用于恶意指令注入。

这些点看起来不起眼，但在生产环境里是最容易出问题的。多智能体系统一旦上线，被调用的就不只是模型能力，还有你暴露给 Agent 的数据库、文件系统和外部服务。权限边界不控制好，出事的概率会大幅上升。

最后再说一点。这个方案真正落地时，最该盯住的不是功能列表，而是输入格式、资源占用和失败重试。先把单任务跑稳，再开并发；先验证模型连通性，再配置复杂调度；先把输出目录和日志规划好，再谈知识库和 MCP。多智能体系统的复杂度是一点点堆出来的，排查思路也得按层来，跳步只会让问题更难定位。