长时间研究Agent框架的同行应该都有同感市面上叫Agent的项目不少但真正从系统架构层面把事情讲清楚的并不多。绝大多数项目文档要么停留在“能跑Demo”的层面要么堆了一堆概念名词却没有交代清楚一个请求到底是怎么流动起来的。最近我花了不少时间把Hermes Agent的整体架构从头到尾梳理了一遍越看越觉得这套设计的执行路径划分是有门道的。它不是那种“大而全”的一体化单体而是非常务实地把感知、决策、记忆、行动几大能力拆成了相对独立的子系统然后通过一条清晰的执行主线把它们串起来。这篇就把我梳理出来的子系统地图和执行路径拆开揉碎讲清楚希望对正在做Agent设计或者准备入坑Agent框架开发的朋友有点参考价值。1. 整体架构设计思路为什么Hermes不走“大而全”路线先把眼光拉高一点看整个系统长什么样。任何一个Agent系统只要真正投入到复杂任务里马上就会暴露两个核心矛盾第一多能力之间的调度冲突第二状态与上下文的污染问题。Hermes架构的高明之处在于它用“子系统边界”同时回应了这两大矛盾。1.1 核心需求解析要回答的四个问题从架构层面看Hermes Agent设计时首先要回答四个问题谁来决定下一步做什么这是决策中枢的职责。谁提供做决策所需要的上下文这是记忆子系统与感知子系统的接口。谁负责把决策变成现实世界的效果这是工具调用与执行模块的核心使命。如果中间出错了谁能发现、谁能纠正这是监控与自省机制的底线。整个Hermes的代码结构基本就是围绕这四个问题构建出来的。它不是先写一个巨大的循环而是先把几个能力模块定义清楚再用执行路径把它们串起来。这种方法的最大好处是开发时可以并行排查问题时也能按子系统隔离不至于一崩全崩。1.2 选型逻辑为什么采用“多进程隔离 消息驱动”结构我看过不少Agent项目最让人头疼的一个问题是模块之间直接函数调用、共享进程内存。随着功能增多模块间的隐性耦合指数级上涨到最后改A模块要担心牵连B状态甚至导致整个Agent“人格分裂”。Hermes则采用了更接近后端微服务的思路核心子系统以独立进程/协程组运行通过内部消息总线通信。这样有几个非常直接的好处任一子系统崩溃可以独立重启不至于让整个运行中的任务直接报废。上下文数据与工具执行状态分离避免“幻觉上下文”污染决策。可以针对不同子系统独立伸缩比如高频的工具调用进程可以多开协程而记忆子系统则保持单写多读。这里要插一句并不是说进程越碎越好。Hermes的拆分度把握得比较克制它没有把每个技能拆成微服务而是把“技能”作为一个注册项挂载在工具子系统里。这种“子系统独立 技能内聚”的模式既保证了隔离性又避免过度设计是我认为它在架构层面比较成熟的一点。2. 核心子系统逐一拆解Hermes Agent内部大致可以划分为六个核心子系统每个子系统都有清晰的边界和对外接口。我逐个说并且会备注哪些是架构层面的必然选择哪些是可以按需取舍的弹性设计。2.1 感知子系统输入的“翻译层”感知子系统负责所有外部输入的处理。不管输入是自然语言、结构化数据还是消息事件都要先经过这个子系统进行清洗、解析、标准化才能进入后续决策环节。在设计上这个子系统做的事情比“读入数据”要复杂得多。它需要完成输入格式识别与转换意图分类之前的安全检查上下文切分长对话切片、窗口管理基础安全过滤注入检测、权限预留判断我比较欣赏的是它把“输入到内部表示”的转换做了一个独立层。这意味着底层模型可以换外部的接入渠道可以换但系统的内部数据结构可以保持稳定。对于开发者来说你只需要关注感知层输出的标准事件对象不需要爬到各渠道的原始细节里去。2.2 决策子系统Agent的“大脑”决策子系统是整个架构里最核心、也最适合做文章的部分。它承载的任务不是“理解语义”而是“决定行为”。常见架构里决策往往是一段简单的ReAct循环但Hermes把决策过程拆得更细腻了一档任务规划器把复杂目标拆成子任务序列决定执行顺序。策略选择器为每个子任务选择合适的“技能”或“工具”。反馈衡量器根据执行结果判断当前计划是否要调整、要继续还是要切换策略。我注意到Hermes的决策子系统对外提供一个“计划快照”的数据结构它记录当前目标、已完成步骤、进行中步骤以及每一步的置信度。这个快照不仅是执行路径的核心中间产物同时也是记忆子系统用于保存“经验”的重要依据。2.3 记忆子系统短期工作台与长期档案库记忆是Agent区别于普通自动化脚本的关键能力。Hermes对记忆的管理非常讲究它没有把所有历史堆起来一股脑塞给模型而是做成了双层结构第一层是工作记忆对应单次任务的上下文窗口。它保存的是当前任务相关的目标、约束、中间产物与最近几步的操作记录。这一层要求快速读写、低延迟因此通常是常驻内存的。第二层是长期记忆对应跨任务的个人知识库与经验库。这里的数据会被压缩、摘要后入库需要时才被检索召回。召回策略直接影响Agent的质量Hermes把召回做成了“任务主题相似度 语义向量匹配”双通道方式先按任务主题过滤一遍再做语义排序这样既快又不太耗模型额度。这层的关键点在于记忆写入比记忆读取更难。什么时候该沉淀记忆、什么时候只保留工作记忆Hermes用了一套置信度阈值机制来判断。只有达到基础置信度且被任务结果验证过的经历才会被沉淀到长期记忆里这能够有效阻止“垃圾经验”污染长期记忆库。2.4 工具子系统能力底座与技能仓库没有工具调用能力的Agent只能聊聊天而Hermes的工具子系统是它真正能干活的保障。这个子系统维护一份“技能清单”每项技能包含技能名称与描述参数SchemaJSON Schema格式执行器实现权限与资源配额声明工具子系统最大的设计亮点是统一执行协议。不管底层是调API、执行本地脚本还是操作第三方软件对Agent决策层而言技能只是“输入参数、输出结果”的黑盒。协议统一的好处是极其明显的新增一个技能不需要改动决策层任何代码替换某个第三方服务也只是替换Executor实现。2.5 执行子系统干活的“双手”执行子系统有时会被忽视但实际它承担了最容易出问题的部分。它负责把决策层选定的技能调用转化成真正的外部操作并捕捉过程中的状态变化。这个子系统里最值得关注的是它的“确认-执行-确认”三步流程。在执行前先做一次参数校验确认所有依赖条件满足执行过程中持续捕获输出流执行结束后再对输出结果做格式校验确保结果符合后续决策所需的标准结构。这个设计看似冗余但在真实场景里发挥了非常大的作用。比如调用一个外部API时网络超时或返回格式异常是家常便饭如果执行层不做好校验直接往上抛决策层很容易被脏数据带偏进而形成一连串的错误决策。2.6 监控与自省子系统兜底的“小哨兵”最后这个子系统通常不被新手关注但真正跑过长时间任务的开发者一定会明白它多重要。Agent系统一旦进入自主多步执行外部环境的变化、工具的异常返回、模型输出的漂移都可能随时打断任务。Hermes的监控子系统不只在外部做“看门狗”它更深入了一层对Agent自身行为的自省。核心机制包括步骤执行时间监控超时触发终止或重试策略Token消耗与成本预算追踪防止单次任务跑穿额度决策一致性校验防止Agent在类似场景下做出互相矛盾的选择执行轨迹记录每一步的输入输出全部落盘便于回溯有了这套兜底系统Agent运行的不确定性才真正被约束住。这也是Hermes能在长期运行任务中保持相对稳定姿态的底气所在。3. 执行路径全流程拆解一个请求的完整旅程架构讲完终究要看运行时怎么流转。一个真实的请求进来在Hermes内部走过的路径是非常清晰的。我按阶段拆解顺便标注每个阶段的关键决策点。3.1 请求进入与意图分发第一步外部请求到达感知子系统。这个阶段感知层会生成StandardInputEvent对象它包含消息内容、渠道元信息、时间戳和必要的权限标识。分发逻辑上感知层会根据输入类型决定后续走向普通任务请求走“标准规划通道”而事件型输入比如定时触发、外部回调走“快速响应通道”。这两种通道后续路径不同前者重规划、后者重执行但都会合并到同一条决策主链上。3.2 规划与决策循环任务进入决策子系统后规划器先做任务分解。这一步的关键指标是子任务粒度拆得太大每一步执行时间长、容错率低拆得太小又会引入大量调度开销。Hermes权衡后采用的是“可行性优先拆解”策略优先拆成最小可执行单元同时对每个子任务指定候选技能列表。这个列表很重要它给执行层留出了“备选路径”一旦首选技能失败不必返回大脑重新规划直接在列表里换下一个即可。决策循环深度依赖工作记忆的上下文快照每次循环结束后快照都会被更新。这种“快照驱动循环”的方式比传统ReAct的纯文本反馈机制更稳定因为结构化的快照不容易丢失关键信息。3.3 工具定位与执行确认计划确定后决策层会向工具子系统发起调用请求。这时的请求带着技能偏好列表、参数输入和约束条件。工具子系统在响应之前会先做一次契约校验核心是参数验证和权限确认。这一步在架构层面很容易忽略但实际价值很大。比如工具子系统的技能清单里有一个“执行Shell命令”的技能如果参数校验不到位Agent可能把一个带有危险变量的命令直接传给执行器。Hermes通过契约校验把“不可执行的条件”挡在执行之前从架构层面降低了风险。3.4 执行反馈与上下文更新执行完成后结果会封装成ExecutionResult对象包含状态码、数据负载、耗时和执行元信息。这个结果一方面返回给决策循环作为下一步判断的依据另一方面也会被发送给记忆子系统用于更新工作记忆。这是整个执行路径中最关键的一个环节反馈质量决定决策质量。只传“执行成功”显然不够Hermes还会把执行过程中的异常片段、耗时和部分中间输出一并带回上下文让决策层能够基于更完整的信息判断下一步动作。3.5 循环出口与任务收尾决策循环何时退出Hermes设定了三类出口条件计划执行完毕所有子任务均达到验收条件正常收尾。达到最大重试次数或成本预算上限强制终止转入降级策略。监控子系统检测到策略冲突或安全风险主动中断。正常收尾时Hermes会做一次收尾处理将最终结果格式化输出同时把值得沉淀的经验写入长期记忆。非正常收尾则会触发告警和轨迹保存方便开发人员事后复盘。4. 子系统交互边界与数据流约定老话说“API即契约”在Agent架构里子系统之间的数据流约定同样重要。Hermes能把执行路径理得清楚很大程度上归功于它有严格的交互边界定义。4.1 事件模型与数据格式统一整个系统内部传递的都是标准化事件结构每个事件带唯一的TraceID一个任务从开始到结束的全链路靠TraceID串联。这在排查问题时太重要了没有TraceID多进程环境下你根本没法把某一步的输入输出对应起来。我建议所有做Agent框架设计的朋友第一步先定义好统一事件模型。字段设计上要兼顾可读性与可扩展性比如至少包含event_id、trace_id、source_subsystem、target_subsystem、payload和timestamp。有了底层的统一数据格式后续的监控、日志、审计都会轻松很多。4.2 同步回调与异步消息的结合Hermes的子系统通信不是铁板一块的“全同步”或“全异步”。决策这种需要即时结果的环节用的是同步调用而记忆沉淀、日志持久化这类可以往后放的操作则走了异步消息队列。这个混合模式很值得我们借鉴。全同步会导致整体链路延迟高全异步又会让反馈变得不可控。根据不同环节对延迟的容忍度来决定通信方式才是工程设计里真正成熟的做法。4.3 权限与安全边界安全不是一个独立功能而应该横切系统。Hermes的做法是在每个子系统交互入口都设了一道权限检查点统一由权限管理模块发放AccessToken子系统间调用必须携带对应凭据。在实际部署中这意味着Agent内部并不是“无条件信任”的。执行子系统在执行Shell命令或文件操作前会把权限校验结果拿来做最后一道闸口。这种处处设防的思维对于要长期运行、接触真实环境的Agent系统来说太必要了。5. 部署形态与扩展思考架构图永远是静态的部署起来才能发现问题的真实面貌。我结合实际部署经验聊一下Hermes这类Agent系统在落地时的一些考量。5.1 单机部署与任务队列如果是个人使用或小团队内部工具场景Hermes完全可以在单机上跑。关键是要分配好任务队列哪个进程负责监听外部输入哪个进程跑决策模型调用哪个进程处理技能执行。建议是感知与决策用独立进程执行子系统的协程池可以根据任务类型动态调大调小。Hermes Agent v0.21 (bot mode)这种形态本质上就是把整个执行路径收敛到一个常驻的机器人进程中对外提供统一消息入口。适合部署在个人工作流里日常跑一跑自动化任务、做做信息整理稳定性上我实测下来是够用的。5.2 多节点部署时的扩展路径当任务量上升或需要多Agent协作时单机版就会遇到瓶颈。这时按子系统的独立性来做水平扩展是一个顺理成章的路径感知子系统可以多开实例做负载均衡。决策子系统如果依赖云端模型关键在于管理并发请求配额而不是无脑开进程。工具子系统非常适合做分布式Worker池把耗时型任务比如文件处理、爬虫抓取丢到Worker上异步执行。记忆子系统需要保持数据一致性建议独立部署并接持久化存储向量库加关系库。多节点部署的主要挑战在于消息总线的高可用以及任务状态的分布式同步。这里要特别强调所有跨节点消息必须带上TraceID和状态版本号否则一旦网络抖动任务状态很容易错乱。5.3 与Harness模式的对比很多人会混淆Agent和Harness的概念特意说一下我的理解。Hermes这类Agent更像是一个有自主决策能力的执行体它会基于目标动态选择工具与策略而Harness更接近一个固定流程的调度壳它把一组确定的工具按固定顺序跑完输出结构固定。从这套架构也能看出来Decision Making部分的存在与否是两者的分水岭。Hermes把决策做成独立子系统所以它是Agent如果哪天把决策模块拿掉、变成一个纯技能编排器那它就退化成了Harness。搞清楚这个区别你自己设计系统时目标会明确很多。6. 落地实操部署要点与配置建议理论讲得再多不如真正跑一把。这一节给出我在部署和调优Hermes Agent时认为最有价值、也最容易被文档忽略的几个点。6.1 环境准备与基础依赖部署前先把基础环境打理好。我习惯的底座是Ubuntu 22.04或Debian 12Python环境建议用uv管理依赖比裸装到系统里干净很多。如果你是Windows环境建议用WSL2跑服务层文件共享和进程管理都会省心不少。拉取代码后第一步永远不是急着配模型而是先跑一遍内置的体检命令确认所有子系统的可导入性和基础依赖都正常。然后确认消息总线Redis或者RabitMQ看你选哪种连通再做单测路径验证。走到这一步才算是“环境就绪”而非“看起来就绪”。6.2 关键配置文件项说明Hermes的配置可以拆成几大块我列一下我在落地时觉得最重要的配置项附上推荐值配置块关键配置项推荐值 / 说明模型接入推理服务地址与Key建议先连本地模型做联调避免额度浪费决策参数最大规划深度3~5太深会导致单次任务时间不可控记忆模块长期记忆召回TopK5~8取太多容易分散决策注意力工具执行最大并发工具数3~5并发太高容易触发外部平台限流监控模块单步超时阈值30~60秒视具体工具而定持久化轨迹日志保留天数14天以上方便复盘这些配置不是拍脑袋定的都是要用实际运行数据做调节的。建议初期保守一点并发低、超时短、深度浅跑稳定了再逐步放开。6.3 配置逐项说明表既然提到配置多一些注意事项。有几个坑我踩过值得单独说一说最大规划深度不是越大越好深度过大意味着决策模型要在一个很长的计划树上做选择Token消耗高且容易在后期产生计划漂移。我更推荐两层设计主规划器只做粗粒度阶段划分阶段内部再用子规划器做细粒度拆解。长期记忆TopK要在召回精准度和上下文污染之间找平衡。我也曾迷信“多召回一点总有好处”结果模型被多个相似但无关的旧任务干扰回答质量反而下降。单步超时阈值不要全局一个值。Shell命令和HTTP请求的超时性格完全不一样建议按技能类型拆分超时配置不然一个慢请求卡住整个调度队列。7. 常见问题与排查技巧实录这部分是全篇最有“烟火气”的地方。我整理了几个在运行Hermes Agent过程中遇到过的高频问题以及我的排查思路和解决办法希望对各位有直接参考价值。7.1 执行路径卡住不动任务超时排查现象是任务跑到某一步后就一直不返回没有报错也没有超时退出。排查路径如下。第一步看监控面板里的当前活动步骤定位卡在哪一个子系统。第二步去查执行子系统的日志看是否某个工具调用还挂着没返回。第三步检查外部服务是否限流很多API的限流是静默等待而不是直接报错表现为请求一直不返回。解决方式一般有几种给外部调用加独立的超时控制既不影响其他技能的超时设置也可以把长时间无响应的调用切换为异步任务让Agent先干别的事回头再查结果。7.2 决策结果“左右横跳”上下文混乱排查有时候Agent在同一类场景下做出的决策前后矛盾今天选方案A明天同样的条件偏偏选方案B而且看起来还没理由。我大概率会去查记忆子系统召回的内容是不是出了问题。重点看两个地方第一长期记忆里是不是混入了低质量经验第二召回结果是不是有多条相近内容互相干扰。解决方法是调低召回TopK或者收紧记忆写入的置信度阈值只让高质量经验进入召回候选。7.3 工具调用频繁失败契约校验排查工具调用失败且日志显示的是“契约校验未通过”这种问题大概率不是执行器本身的问题而是决策层生成参数时就错了。常见原因是模型没有真正理解这个技能的参数Schema尤其是那些可选参数很多的技能。我建议给这类技能增加“示例查询”描述在技能描述里附带1-2个典型参数组合示例。模型的遵循能力会明显提升远比你在Schema里写再多字段说明都有效。7.4 内存占用持续上涨长期运行泄漏排查Agent长期运行最怕内存一点一点涨上去。排查工具是先看进程RSS走势然后逐一关闭子系统做内存对比测试。实测下来记忆子系统的召回缓存和工具子系统的临时文件句柄最容易成为泄漏源头。简单的优化方案是给召回缓存设置最大条目数和LRU淘汰策略同时执行子系统每个任务结束后强制清理临时资源双管齐下后内存曲线基本能压平。7.5 一些杂项小经验汇总再分享几个零碎但实用的小经验日志级别初期用INFO就行别一上来DEBUG日志量太大反而掩盖关键信息。每次修改配置后热加载不见得都生效保险起见重启决策子系统否则你会纠结“为什么改了没反应”。多Agent协作场景下给不同Agent分配不同的技能白名单权限克制能避免很多互相踩踏的问题。定期做轨迹复盘别嫌麻烦每跑完一个复杂任务后翻一下执行路径你会发现Agent的决策习惯逐步形成这对调优帮助特别大。8. 写在最后的一点个人体会把Hermes Agent的这份架构地图梳理完我自己最大的收获不是记住了哪个子系统负责什么事情而是看清了“把复杂度隔离在子系统内部”这句话的分量。以前我自己写过一版“单体Agent”所有模块塞在一起跑看起来简单但一旦任务复杂度上来问题定位成本和扩展成本就陡增。Hermes这套“按能力边界拆子系统靠清晰协议串联”的思路我在后续自己的项目里也在逐步沿用。首先是统一事件模型一定要先定义好其次决策与执行的边界要划清这两件事做好了Agent的复杂度是可控的。如果你正在为Agent系统经常莫名其妙出错、功能越加越乱而头疼建议也按这个思路梳理一遍自己的架构。不用照搬任何一个框架核心是找到你自己的子系统边界和执行路径。先保证一条请求路径能完整跑通再谈功能的丰富路径干净了很多问题自然就消失了。最后再分享一个小技巧给执行路径里的每一步都加上一个简短的语义标签比如“规划-子任务拆分”、“工具-准备候选技能”、“执行-确认结果格式”。排查的时候按标签过滤日志比在无结构日志里捞针高效十倍。这是我在踩过多次坑之后总结的最实用的一招。