公司动态
从零搭建Hermes Agent多智能体链路:1主控调度3Agent接Qwen
多智能体系统听起来很复杂但真正上手之后核心就一句话用一个主控角色把任务拆开分给几个专门负责不同工作的 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 型任务还要考虑服务商侧的限流不能只看本地资源。给一个大概的判断表现象优先排查次要排查请求返回 401/403API Key 是否正确账号是否有权限请求超时网络连通性模型上下文长度、服务商负载主控不派单主控提示词是否误配路由规则是否匹配任务类型Agent 返回为空该 Agent 的输入内容模型是否被安全策略拦截批量任务部分失败单条任务输入格式并发数和限流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。多智能体系统的复杂度是一点点堆出来的排查思路也得按层来跳步只会让问题更难定位。