讲真的整理 Agent 框架的架构资料这段时间我最大的感触是市面上聊 Agent 的文章不少但大多数都停在“什么是 Agent”“怎么调工具”这个层面真正把子系统边界、执行链路、数据流向掰开揉碎讲清楚的内容太少了。正好最近在部署和研究 Hermes Agent顺手把它整个架构拆了一遍发现这套系统在分层设计和执行路径上有很多值得借鉴的地方。这篇不聊虚的直接画地图——从你输入一句话到 Agent 完成整个任务中间到底经历了哪些子系统控制权怎么移交数据怎么流转每一步为什么要这么设计。想搞懂 Agent 架构、准备自己搭 Agent 框架的朋友这篇可以当个参考坐标。1. 项目定位Hermes Agent 到底解决什么问题1.1 从单点工具到智能体框架的转变先交代背景。早期的 LLM 应用基本都是“问答式”的用户发一句话模型回一段话顶多中间调用一两次函数。这种模式在简单场景下够用但一旦任务变成“查完数据库→分析异常→生成报告→定时发送到指定邮箱”这种多步骤、有依赖关系、需要中途根据结果调整策略的活单靠 prompt 堆砌和函数调用就撑不住了。原因很简单没有状态、没有规划、没有反馈闭环。模型生成完一个工具调用就“失忆”了下一步怎么走完全依赖外部代码硬编码改一个环节就得改整个流程。Hermes Agent 这类框架的出发点就是把“智能决策”和“工具执行”从代码里拆出来做成一个可演进的系统。它不替你做业务而是提供一个容器模型在里面思考、调用工具观察结果、再思考、再行动一直到任务完成。这个循环一旦跑通Agent 能干的活就不再局限于你预先写死的流程而是可以根据实时反馈调整计划。我实际跑下来最明显的感觉是以前写自动化脚本每加一个新需求就要改代码现在换成 Agent大部分改动只是新增工具描述和调整授权策略主流程基本不动。1.2 Hermes 的整体架构分层Hermes 的架构如果概括成一句话就是“一个内核、两层边界、多个可插拔子系统”。内核负责决策理解用户意图、拆解目标、编排执行计划、根据中间结果修正方向。这是整个系统的大脑也是最难替换的部分——因为所有子系统都是为了辅助这个大脑做更好的决策而存在的。两层边界值得单独说。第一层是内核与工具之间的边界也就是热词里常提到的 Harness 和 Agent 的区分这个我后面专门用一章展开。简单说Agent 是大脑Harness 是身体大脑只负责想身体负责动。第二层是内部与外部之间的边界所有外部资源文件、数据库、网络服务、第三方 API都必须通过统一的工具接口进入系统不允许模型或子模块直接越界访问。这两层边界画清楚了系统才谈得上安全、可测试、可移植。子系统方面Hermes 把职责切得非常细输入感知、规划决策、工具执行、记忆管理、安全审计、编排通信每个子系统只干一件事通过定义良好的接口互相通信。这种“高内聚、低耦合”的好处你在改其中一个模块的时候体会最深。比如我换过记忆后端从默认的 SQLite 换成了独立的向量库业务逻辑和规划层完全没动只是适配了一下存储接口。1.3 适合谁来参考这份架构如果你属于下面几类人这篇架构拆解应该能直接对你有用正在从零搭建 Agent 平台的开发者可以参考它的子系统划分思路避免一上来就把所有逻辑堆在一个模块里。做 Agent 框架选型的技术负责人可以通过这篇了解这类系统内部的运作机制判断它能否满足你的场景要求。想深入理解 Agent 执行原理的爱好者执行路径地图那部分就是一份详细的流程图解跟着走一遍就知道 Agent 内部发生了什么。2. 子系统全景拆解2.1 输入感知子系统一切任务的第一站输入子系统承担的是“翻译”工作。用户的语言可能是自然语言、也可能是命令、文件、图片等富媒体但进入规划器之前必须统一转换成内部标准格式。Hermes 的做法是先把原始输入包成一个规范的事件结构包含会话标识、用户标识、输入内容、元数据然后按顺序做两件事规范化和意图初步分类。规范化的目的是消除输入差异比如把语音转写结果里的口头禅清理掉、把 Markdown 格式的输入转成纯文本、识别出用户贴过来的文件路径并解析成实际内容引用。意图初步分类则是粗粒度打标这是个问答请求还是任务执行请求还是系统管理请求这一步不涉及具体任务拆解但决定了后续走哪条处理管线。实际做的时候我建议在这层就保留完整的原始输入追踪 ID因为一旦后面出了问题排查要靠它串起整个链路。另外输入层有一个容易被忽略的设计长度阈值和内容截断策略。超长输入不能一股脑丢给模型也不是简单截断而是要先做摘要压缩或分段索引保留关键上下文。如果你在自己的框架里实现这层一定把压缩规则做成可配置的不同场景差异很大——代码仓库分析需要保留代码细节而聊天摘要则可以压缩得很激进。2.2 规划与决策子系统Agent 的决策中枢这是 Hermes 的核心。规划器接收来自输入层的标准化任务然后执行三个动作目标解析、任务分解、计划编排。目标解析是把模糊的自然语言请求提炼成可执行目标。比如用户说“帮我看看最近的流量异常并写个报告”规划器要识别出隐含目标“分析流量数据→识别异常→生成报告”同时明确约束条件时间范围、报告格式、是否需要建议。这个环节非常依赖模型在 prompt 里对自身能力的认知Hermes 的做法是预先注入当前可用的工具列表和系统提示让模型在分解任务时就知道“我有哪些牌可以打”。任务分解就是把大目标拆成子任务序列。这里有一个关键设计不追求一次性生成完美的完整计划而是先生成一个粗粒度的计划执行中逐步细化。原因很实际——真实环境的不确定性太高工具可能失败、数据可能不符合预期、用户可能中途改需求一次性计划越精致执行时碎得越彻底。Hermes 采用的策略是“计划-执行-观察-再计划”的循环每一步只往前走一小段但每一步都带着最新的环境反馈。规划器的输出是一个结构化的执行计划包含步骤列表、依赖关系、预期产出。这个计划既是执行的蓝图也是审计的依据——你每一步做了什么、为什么要做这件事都能追溯。我在部署过程中强烈建议开着这个日志看一圈很多 Agent 表现“智障”的时刻其实从计划阶段就能看出端倪要么工具清单没描述清楚要么分解粒度太粗要么顺序有明显问题。2.3 工具与执行子系统能力的外延如果规划器是大脑工具执行层就是手脚。Hermes 的工具层有一个核心设计——统一工具注册中心。任何能力想要被 Agent 使用必须先在注册中心登记声明工具名称、功能描述、输入输出 schema。这听起来像增加工作量但带来的收益在纯代码实现里体现不出来只有在 Agent 面对多个工具做选择时才明显模型的规划能力再强如果工具描述写得含糊它照样选错工具。我踩过的坑是工具描述里用了太多抽象名词模型经常把一个查询工具当成更新工具调用后来把描述改成“仅用于读取数据不会修改任何内容”准确率立刻上来了。工具执行本身要解决一个安全问题Agent 的模型输出从本质上是不可信的它生成的一个工具调用参数可能包含恶意路径、越权指令或资源耗尽请求。Hermes 在工具调用进入执行器之前会经过一层参数校验检查类型合法性、路径是否在授权范围、资源配额是否超限。执行阶段则强调隔离文件类操作用统一封装外部命令默认不直接透传 shell而是走受限执行器。这些在单机体验时好像“过度设计”一旦你打算把 Agent 暴露给多个用户使用才知道这层防护有多重要。工具执行的另一个设计点是“可观察性”。工具调用要记录完整的输入参数、执行耗时、返回结果可能要截断、错误信息。这不是为了写日志而写日志而是因为这些记录会回传给模型作为下一步决策的依据。工具返回的错误信息如果太笼统模型无法判断是重试还是换方案如果太长又会占用上下文空间。Hermes 的做法是执行器返回“结构化结果 简短摘要”让模型拿摘要做决策需要时再取详细内容。2.4 记忆子系统让 Agent 不“失忆”Agent 最大的痛点之一是上下文窗口有限无法在大任务中长期保持关键信息。Hermes 的记忆子系统分了三层来解决这个问题工作记忆短期存放在当前任务执行期间产生的临时状态比如上一步工具的返回结果、当前正在执行的分步计划。它存活于一次任务的执行周期任务结束就回收。会话记忆中期跨任务但限定在同一个会话内的历史信息比如用户之前表达过的偏好、之前已经确认过的事实。长期记忆持久跨会话的知识沉淀可以来源于是任务执行中提炼出的经验、用户主动保存的偏好、或系统从历史任务中自动摘要得到的结论。这里想重点说长期记忆的写入机制。至少在我接触到的配置里Hermes 不是每执行完一步就往长期记忆里塞内容那样只会塞满垃圾。它会在任务结束时做一次“提炼”把当前任务中值得长期记忆的信息抽成结构化条目比如“用户偏好周报邮件在周一上午发送”“数据库 schema 中订单表有一个 region 字段”然后才写入存储。这个提炼过程本身也是由一次模型调用完成的所以存储的质量取决于提炼策略设得好不好。我自己调过提炼 prompt核心是告诉模型“只保存以后可能复用的稳定事实不要保存临时性结论”。记忆的召回也是一个值得单独提醒的点召回不是把历史记录全倒给模型而是检索出最相关的部分做成压缩摘要。我之前遇到过一个现象Agent 在任务执行中突然“跑题”把很早以前某次对话的内容当成了当前指令后来排查发现是召回策略太激进把低相关度的记忆也拼进了上下文。记忆召回要有相关性阈值宁可少召回不要乱召回因为错误记忆对决策的破坏力远大于没有记忆。2.5 安全与审计子系统信任的边界安全子系统在 Hermes 架构里不是附加组件而是贯穿所有链路的一层横切能力。每次模型输出要落成一个可观察的动作时安全层都会介入做三件事检查权限、检查合规、记录痕迹。权限检查的粒度很关键。最小权限原则在 Agent 场景下不是一句空话某个工具可能本身支持删除操作但当前会话的授权级别只允许查询那安全层在工具调用发出前就把删除类参数直接毙掉。另一个是凭证管理工具访问外部服务需要的 API Key 和令牌不能出现在模型可见的上下文里。Hermes 的做法是凭证统一放在独立的密钥服务中工具执行时通过环境变量或临时凭证注入模型那边只能收到“权限已具备”的确认信号看不到具体的密钥内容。审计日志要求完整但不过度敏感。每条工具调用、每条外部通信、每次权限拒绝都应该有记录字段至少包含时间、会话、操作者、工具名称、参数摘要、结果状态、关联的追踪 ID。这套日志做起来不难真正难的是形成习惯——很多 Agent 项目前期跑得欢上线出问题才想起来没用日志串链路到时候翻遍系统也定位不到问题出在哪一步。我个人的习惯是第一天就给所有工具执行挂上追踪 ID 日志前期多花半小时后期省一整晚。2.6 编排与通信子系统多部件之间的总线当你的 Agent 不止一个实例或一个任务被拆成多个 Agent 协作时编排层就是整个系统的消息骨架。Hermes 的编排子系统采用类似事件总线的模式子系统之间不直接互相调用而是通过发布/订阅的方式通信。这样做的好处是模块之间彻底解耦新增一个日志组件、加一个监控组件完全不用改原有代码只要订阅对应的事件流就行。编排层要处理的另一个现实问题是任务优先级和队列。多用户同时使用 Agent 时可能出现资源竞争——两个任务同时想调用同一个写工具或者某个任务占用了大量模型配额导致其他任务排队。任务队列需要支持优先级标记和动态调整至少要有暂停、恢复、取消这三种操作。我实际运行的时候发现没有取消操作会非常痛苦一个失控的 Agent 任务会一直循环调用工具直到配额耗尽。编排层加上“最大循环次数”和“人工中断开关”都是必须的保命设计。3. 执行路径地图一次任务的生命周期3.1 请求从进入到落地的第一站我把一条完整执行路径一步步拆开用一个实际任务来演示这样比空讲抽象流程好理解得多。假设用户通过 Hermes 桌面端发起了一条请求“帮我查一下最近的销售数据跟上周对比然后把变化趋势写到一份日报里。”请求进入系统的第一步是接入层把数据包解析成标准事件。不管用户是通过桌面 GUI、命令行还是 HTTP API 发起的请求接入层都会统一封装成一个任务事件包含用户标识、输入文本、会话上下文、以及新生成的追踪 ID。追踪 ID 从这里诞生之后每一条日志、每一次工具调用、每一次模型请求都会带上它。紧接着编排层会把这个事件放到任务队列里并给它分配一个执行环境。执行环境包括可用的工具列表根据用户权限过滤后的、初始上下文目录、超时限制、资源配额。这一步在配置里被称为环境装载相当于给即将醒来工作的 Agent 准备办公桌和工具包。3.2 一条完整任务的控制流与数据流继续上面的销售日报任务。任务被调度器激活后执行路径基本是这样的第一步上下文组装与意图识别。记忆子系统先召回该用户最近的偏好和与本任务相关的历史信息比如上次日报的格式、用户是否提过要看哪些指标输入感知子系统完成意图粗分类——这是一个“数据分析生成报告”的综合任务然后整个会话上下文被压缩成一个装载包发给规划器。第二步规划器生成初始计划。规划器结合当前工具清单和装载包生成粗粒度计划内容大致是查询销售数据库→与上周数据对比→整理变化趋势→生成报告文件。此时计划只是骨架还不涉及具体的 SQL 查询语句或文档格式。这步的输出会写回工作记忆同时给编排层一个“计划已生成”的信号。第三步工具调用循环。执行器从计划中取出第一个动作“查询销售数据库”将工具名和参数发送到工具注册中心注册中心验证权限后调用数据库查询服务。返回结果被写入工作记忆同时一份带截断摘要的观察结果回传规划器。规划器看到数据后判断“数据正常可以继续”于是取出下一步动作向执行器发起第二次工具调用。依次循环直到生成报告文件这一步也执行完。第四步输出与记忆沉淀。最终结果报告文件的路径和摘要经由输出层包装返回给桌面端用户。同时记忆子系统触发提炼把“用户常用于存储日报的目录格式”“用户关注的销售指标集合”这类稳定偏好写入长期记忆。数据流和控制流在这里是分离的控制流沿着“规划器→执行器→观察→规划器”的闭环走数据流则沿着“输入层→工作记忆→工具参数→工具结果→工作记忆→输出层”的管线走。理解这个分离非常关键你可以把控制流理解成指挥官在传令数据流是后勤在送弹药两者互不阻塞。后续做并发优化、做监控时都是基于这种分离来定位瓶颈的。3.3 并行分支与资源竞争的处理并不是所有任务都像上面的例子一样线性跑完。实际中任务计划经常拆出多个可并行的子任务。比如还是销售日报可能规划器把“查询本周销售数据”和“查询上周销售数据”拆成两个独立动作这两个查询并没有先后依赖关系完全可以并行执行。否则如果按顺序跑用户只是要一份对比日报硬生生要多等一整轮工具往返的延迟。这里需要引入 DAG 式的计划表达就是给每个计划步骤声明依赖项。只有依赖项全部完成步骤才能进入执行候选池。Hermes 的调度器会不停地扫描候选池把可执行节点分发给空闲的工作线程或并行的工具执行器。资源竞争在并行场景下会集中爆发。我遇到过一个典型问题两个并行的工具调用都指向同一个文件写入路径结果后一个覆盖了前一个的产出导致最终报告数据不完整。解决方案是给工具注册中心加资源锁声明机制工具在注册时声明自己会读写哪些类型的资源执行器在发起并行调用前做一次冲突检测发现有重叠就串行化有依赖关系的任务自动排队。这类问题在单线程演示时永远不会触发一上真实负载就全冒出来了提前做资源冲突检测比事后修数据靠谱得多。3.4 失败回退与重试路径真实环境中没有哪种工具调用是百分百成功的。Hermes 的失败处理分三个层级工具级重试、计划级调整、任务级放弃。工具级重试发生在最底层。数据库查询偶尔超时、网络请求偶发抖动这些瞬时故障直接重跑一次工具调用就行。重试要设置次数上限和退避策略不要死磕同一参数同样姿势的直连重试比如第一次是连接超时第二次可以换一个端点或使用备用数据源。计划级调整发生在工具重试仍然失败的场景。比如数据库查询工具报了“权限不足”错误这不是重试能解决的事。此时执行器把错误信息返回规划器规划器做出判断——换一个只读的副本数据库还是改用另一个汇总表格工具这就是观察-再计划的循环在发挥作用一次失败不是任务的终点而是下一步决策的输入。我在调这个环节时发现规划器能否做出正确调整很大程度取决于工具返回的错误描述质量。如果你的工具只返回“执行失败”四个字模型就算想调整也不知道怎么调整。任务级放弃是最后的安全网。当规划器经过多轮调整仍然无法完成目标或者错误信息显示是永久性不可修复的问题比如检索的数据库根本不存在Agent 应该放弃执行并向用户明确汇报失败原因和已完成的工作。这里有一个体验上的关键点放弃不等于甩手不管好的 Agent 会输出一份“尝试了哪些方案、卡在哪个环节、用户可能怎么修正”的失败报告。让用户自己从头排查一个黑盒和让用户带着半成品问题去问体验差别是巨大的。4. 关键概念澄清Harness 与 Agent 的边界4.1 Harness 的本质与作用“Harness 和 Agent 有什么区别”这个问题在热词里出现频率很高也是不少新手理解 Agent 架构时最容易卡住的地方。用大白话说Agent 是大脑负责想“做什么、怎么做”Harness 是身体负责稳定承接这些想法把它安全地落到现实环境里。Harness 这个英文词本身的意思是“挽具”就是套在牲口身上用来拉车的装备。这个词其实很形象——它不决定去哪个方向、拉什么东西但它决定了拉车的动作是否稳定、是否受控、是否不伤到牲口本身。Hermes 里 Harness 承担的工作管理模型上下文、调度工具调用循环、处理模型输出解析、控制任务的生命周期状态机、处理部分意外的错误恢复。所有 Agent 决策之外的技术性脏活都是 Harness 在扛。为什么要单独拆出这一层因为 Agent 的核心只有一件事——基于当前状态产生决策文本。其余全都是通用工程调用模型、解析输出、执行工具、处理异常、管理内存。如果这些杂活跟决策逻辑混在一起写最后的结果就是换一个模型时重写一遍执行循环换一种协议时重写一遍消息处理。把 Harness 抽象出来之后决策逻辑和运行环境彻底解耦你甚至可以在同一个 Harness 上服务多个不同的 Agent 模型。4.2 边界划分的实践价值边界画清楚的价值在可测试性上体现得最明显。如果你想测试“Agent 面对工具失败时能否正确调整计划”没有 Harness 的架构里你必须真的造一个失败工具然后跑完整流程过程麻烦且不稳定。有 Harness 之后你可以 mock 工具执行层的返回结果让 Harness 以为工具调用失败了然后在受控条件下观察 Agent 的反应。这个能力意味着你可以系统性地验证 Agent 的决策能力——批量跑各种故障注入用例不比在生产环境里裸奔香得多边界带来的另一个价值是安全升级。模型迭代特别快今天用这个模型明天可能想换个更强的。如果模型只在 Agent 层流转而不直接触碰系统资源替换模型就变成了纯配置变更。我实际测试过只改一个模型配置项整个系统感知不到切换工具调用、上下文管理、记忆写入全都照常工作。同理如果你想在 Harness 层加一个全局的监控拦截器或请求缓存不需要动任何 Agent 逻辑。这点对于想长期演进 Agent 系统的团队来说是前期架构最值得投入的部分。5. 部署配置与实操避坑5.1 不同平台的部署观察架构跑起来需要能落地。我在 Windows 桌面端、Ubuntu 服务端、以及 Windows 下借助 Linux 子系统环境各跑过 Hermes三个环境遇到的问题完全不一样。Windows 桌面版整体引导做得算顺手但有一步容易坑到人——安装向导在检测基础环境时经常“提前结束”画面上既不提示缺了哪个组件也没有日志面板看起来像死掉了。后来我排查发现绝大多数情况是它依赖的 Linux 运行时子系统没有就位。Windows 下装这类系统的运行环境最常见的问题就是启用向导明明点了开始十几秒后却提示失败。那个时候优先去确认系统版本是否过旧、内核组件是否已启用。给 Windows 用户一个建议先手动把这些底层环境准备好再回来跑 Hermes 的安装向导能省掉大半的黑盒报错。Ubuntu 下部署相对干净需要注意的点集中在依赖版本上。Hermes 某些组件对 Python 版本有明确要求新装的系统默认可能已经带到更高版本的 Python反而不兼容。我用的方案是给 Hermes 单独建一个虚拟环境避免跟系统 Python 打架。另外工具执行层依赖的编译工具链也要提前装好否则部分插件在首次导入时才现编译失败报错信息相当不友好。桌面版和 Server 版的选择应该看场景桌面版适合个人调试方便可视化观察状态Server 版适合挂服务、接 API跑定时任务。一个提醒桌面版在长期运行任务时不要开启自动休眠否则任务跑到一半系统睡过去了醒来要么超时要么状态错乱。5.2 关键配置项与参数建议Hermes 的具体配置项名称在不同版本里有一些差异我这边用的是当前自己手上的版本不一定完全对得上你拿到的版本但思路是通用的。核心配置就几块值得花时间调好的就几个参数。模型相关参数不要太信任默认值。任务复杂程度高、需要多轮思考时把最大输出 Token 适当调大否则计划到一半被截断。温度参数建议任务执行类场景调到 0 到 0.2 之间生成的文章结语、方案建议这种场景可以放宽到 0.7。不要试图让一个参数适配所有任务如果系统支持按任务类型配不同参数尽量分开配。工具列表和白名单这是安全性的核心。我会在配置文件里区分“全局禁用工具”“默认可用工具”“按会话授权工具”三类宁可少一个工具让 Agent 多绕一步也不要给一个危险工具放到默认可用列表里。另外工具描述写得好不好直接决定执行路径绕不绕这块值得花时间逐步打磨。并发与超时并发参数要从保守值开始先 1 并发跑通整个流程逐步往上加观察系统稳定性和响应延迟再最终确定。超时参数分两类模型请求超时、工具执行超时两者要分开配置。我遇到过工具执行非常慢但确实在正常工作的情况超时设短了就会误杀好任务建议工具超时尽量宽重点控制循环次数上限而不是单次超时。5.3 常见问题与排查记录我把实际运行中遇到的典型问题整理成一张速查表按子系统分布做个索引方便排查时对照。问题现象涉及子系统排查方向处理建议安装向导中途失败环境依赖检查系统基础运行时组件版本先手动安装依赖再重跑向导模型请求超时或频繁无响应决策子系统检查模型服务端负载和超时参数降低并发加大模型请求超时Agent 反复调用同一工具停不下来规划/编排层检查最大循环次数限制设置循环上限与人工中断开关多个并行任务互相覆盖文件工具执行/调度层检查资源冲突检测日志启用资源锁声明串行化冲突操作记忆召回内容导致跑题记忆子系统检查召回相关性阈值调高阈值限制低相关度记忆注入工具执行返回权限错误安全/工具层检查当前会话授权级别按最小权限原则调整授权配置排查过程中的最核心方法就一条从追踪 ID 串起全部日志。只要链路里的每个子系统都正确打上了同一个追踪 ID拿着它过滤日志执行路径会一目了然哪个环节卡了、哪个环节绕了、哪个环节失败了全都能按图索骥。拴不住追踪 ID 的系统遇到问题只能靠猜猜问题最耗时间。6. 架构演进的一些经验体会跑了一段时间 Hermes 之后我对这套架构设计的理解也从最初的“看热闹”变成了“看门道”。最想分享的一点体会是这套子系统拆分的价值不会在第一天体现而是在你开始给 Agent 加奇怪的新能力时才会爆发。比如我给它加了一套图表生成工具这个改动只涉及工具注册中心的新增和一个新执行器适配规划层、记忆层、安全层完全无感知。这种扩展成本才是一个好架构最直接的回报。给正准备搭 Agent 系统的朋友一个建议先别急着上复杂的分布式方案就用 Hermes 这类框架默认的单机部署把主路径跑通亲手画一张执行路径图标注出每一步控制和数据在哪里交接。这张图比任何文档都更能帮你建立对这个系统的直觉。等主路径稳了再逐步往里面加并发、加多 Agent 编排、加更细粒度的安全控制——那时候你会发现前期拆清楚的边界全都会加倍回报给你。最后再分享一个小技巧架构总览这类内容如果只看不画理解深度会差很多。我建议你把博文里的执行路径地图自己重画一遍不用拘泥形式哪怕手写一个方框箭头流程图都行。画的过程里你会注意到很多读文章时忽略掉的细节比如哪些环节有返回环路、哪些环节是单向传递。这些细节才是吃透一套架构的真正钥匙。
讲真的整理 Agent 框架的架构资料这段时间我最大的感触是市面上聊 Agent 的文章不少但大多数都停在“什么是 Agent”“怎么调工具”这个层面真正把子系统边界、执行链路、数据流向掰开揉碎讲清楚的内容太少了。正好最近在部署和研究 Hermes Agent顺手把它整个架构拆了一遍发现这套系统在分层设计和执行路径上有很多值得借鉴的地方。这篇不聊虚的直接画地图——从你输入一句话到 Agent 完成整个任务中间到底经历了哪些子系统控制权怎么移交数据怎么流转每一步为什么要这么设计。想搞懂 Agent 架构、准备自己搭 Agent 框架的朋友这篇可以当个参考坐标。1. 项目定位Hermes Agent 到底解决什么问题1.1 从单点工具到智能体框架的转变先交代背景。早期的 LLM 应用基本都是“问答式”的用户发一句话模型回一段话顶多中间调用一两次函数。这种模式在简单场景下够用但一旦任务变成“查完数据库→分析异常→生成报告→定时发送到指定邮箱”这种多步骤、有依赖关系、需要中途根据结果调整策略的活单靠 prompt 堆砌和函数调用就撑不住了。原因很简单没有状态、没有规划、没有反馈闭环。模型生成完一个工具调用就“失忆”了下一步怎么走完全依赖外部代码硬编码改一个环节就得改整个流程。Hermes Agent 这类框架的出发点就是把“智能决策”和“工具执行”从代码里拆出来做成一个可演进的系统。它不替你做业务而是提供一个容器模型在里面思考、调用工具观察结果、再思考、再行动一直到任务完成。这个循环一旦跑通Agent 能干的活就不再局限于你预先写死的流程而是可以根据实时反馈调整计划。我实际跑下来最明显的感觉是以前写自动化脚本每加一个新需求就要改代码现在换成 Agent大部分改动只是新增工具描述和调整授权策略主流程基本不动。1.2 Hermes 的整体架构分层Hermes 的架构如果概括成一句话就是“一个内核、两层边界、多个可插拔子系统”。内核负责决策理解用户意图、拆解目标、编排执行计划、根据中间结果修正方向。这是整个系统的大脑也是最难替换的部分——因为所有子系统都是为了辅助这个大脑做更好的决策而存在的。两层边界值得单独说。第一层是内核与工具之间的边界也就是热词里常提到的 Harness 和 Agent 的区分这个我后面专门用一章展开。简单说Agent 是大脑Harness 是身体大脑只负责想身体负责动。第二层是内部与外部之间的边界所有外部资源文件、数据库、网络服务、第三方 API都必须通过统一的工具接口进入系统不允许模型或子模块直接越界访问。这两层边界画清楚了系统才谈得上安全、可测试、可移植。子系统方面Hermes 把职责切得非常细输入感知、规划决策、工具执行、记忆管理、安全审计、编排通信每个子系统只干一件事通过定义良好的接口互相通信。这种“高内聚、低耦合”的好处你在改其中一个模块的时候体会最深。比如我换过记忆后端从默认的 SQLite 换成了独立的向量库业务逻辑和规划层完全没动只是适配了一下存储接口。1.3 适合谁来参考这份架构如果你属于下面几类人这篇架构拆解应该能直接对你有用正在从零搭建 Agent 平台的开发者可以参考它的子系统划分思路避免一上来就把所有逻辑堆在一个模块里。做 Agent 框架选型的技术负责人可以通过这篇了解这类系统内部的运作机制判断它能否满足你的场景要求。想深入理解 Agent 执行原理的爱好者执行路径地图那部分就是一份详细的流程图解跟着走一遍就知道 Agent 内部发生了什么。2. 子系统全景拆解2.1 输入感知子系统一切任务的第一站输入子系统承担的是“翻译”工作。用户的语言可能是自然语言、也可能是命令、文件、图片等富媒体但进入规划器之前必须统一转换成内部标准格式。Hermes 的做法是先把原始输入包成一个规范的事件结构包含会话标识、用户标识、输入内容、元数据然后按顺序做两件事规范化和意图初步分类。规范化的目的是消除输入差异比如把语音转写结果里的口头禅清理掉、把 Markdown 格式的输入转成纯文本、识别出用户贴过来的文件路径并解析成实际内容引用。意图初步分类则是粗粒度打标这是个问答请求还是任务执行请求还是系统管理请求这一步不涉及具体任务拆解但决定了后续走哪条处理管线。实际做的时候我建议在这层就保留完整的原始输入追踪 ID因为一旦后面出了问题排查要靠它串起整个链路。另外输入层有一个容易被忽略的设计长度阈值和内容截断策略。超长输入不能一股脑丢给模型也不是简单截断而是要先做摘要压缩或分段索引保留关键上下文。如果你在自己的框架里实现这层一定把压缩规则做成可配置的不同场景差异很大——代码仓库分析需要保留代码细节而聊天摘要则可以压缩得很激进。2.2 规划与决策子系统Agent 的决策中枢这是 Hermes 的核心。规划器接收来自输入层的标准化任务然后执行三个动作目标解析、任务分解、计划编排。目标解析是把模糊的自然语言请求提炼成可执行目标。比如用户说“帮我看看最近的流量异常并写个报告”规划器要识别出隐含目标“分析流量数据→识别异常→生成报告”同时明确约束条件时间范围、报告格式、是否需要建议。这个环节非常依赖模型在 prompt 里对自身能力的认知Hermes 的做法是预先注入当前可用的工具列表和系统提示让模型在分解任务时就知道“我有哪些牌可以打”。任务分解就是把大目标拆成子任务序列。这里有一个关键设计不追求一次性生成完美的完整计划而是先生成一个粗粒度的计划执行中逐步细化。原因很实际——真实环境的不确定性太高工具可能失败、数据可能不符合预期、用户可能中途改需求一次性计划越精致执行时碎得越彻底。Hermes 采用的策略是“计划-执行-观察-再计划”的循环每一步只往前走一小段但每一步都带着最新的环境反馈。规划器的输出是一个结构化的执行计划包含步骤列表、依赖关系、预期产出。这个计划既是执行的蓝图也是审计的依据——你每一步做了什么、为什么要做这件事都能追溯。我在部署过程中强烈建议开着这个日志看一圈很多 Agent 表现“智障”的时刻其实从计划阶段就能看出端倪要么工具清单没描述清楚要么分解粒度太粗要么顺序有明显问题。2.3 工具与执行子系统能力的外延如果规划器是大脑工具执行层就是手脚。Hermes 的工具层有一个核心设计——统一工具注册中心。任何能力想要被 Agent 使用必须先在注册中心登记声明工具名称、功能描述、输入输出 schema。这听起来像增加工作量但带来的收益在纯代码实现里体现不出来只有在 Agent 面对多个工具做选择时才明显模型的规划能力再强如果工具描述写得含糊它照样选错工具。我踩过的坑是工具描述里用了太多抽象名词模型经常把一个查询工具当成更新工具调用后来把描述改成“仅用于读取数据不会修改任何内容”准确率立刻上来了。工具执行本身要解决一个安全问题Agent 的模型输出从本质上是不可信的它生成的一个工具调用参数可能包含恶意路径、越权指令或资源耗尽请求。Hermes 在工具调用进入执行器之前会经过一层参数校验检查类型合法性、路径是否在授权范围、资源配额是否超限。执行阶段则强调隔离文件类操作用统一封装外部命令默认不直接透传 shell而是走受限执行器。这些在单机体验时好像“过度设计”一旦你打算把 Agent 暴露给多个用户使用才知道这层防护有多重要。工具执行的另一个设计点是“可观察性”。工具调用要记录完整的输入参数、执行耗时、返回结果可能要截断、错误信息。这不是为了写日志而写日志而是因为这些记录会回传给模型作为下一步决策的依据。工具返回的错误信息如果太笼统模型无法判断是重试还是换方案如果太长又会占用上下文空间。Hermes 的做法是执行器返回“结构化结果 简短摘要”让模型拿摘要做决策需要时再取详细内容。2.4 记忆子系统让 Agent 不“失忆”Agent 最大的痛点之一是上下文窗口有限无法在大任务中长期保持关键信息。Hermes 的记忆子系统分了三层来解决这个问题工作记忆短期存放在当前任务执行期间产生的临时状态比如上一步工具的返回结果、当前正在执行的分步计划。它存活于一次任务的执行周期任务结束就回收。会话记忆中期跨任务但限定在同一个会话内的历史信息比如用户之前表达过的偏好、之前已经确认过的事实。长期记忆持久跨会话的知识沉淀可以来源于是任务执行中提炼出的经验、用户主动保存的偏好、或系统从历史任务中自动摘要得到的结论。这里想重点说长期记忆的写入机制。至少在我接触到的配置里Hermes 不是每执行完一步就往长期记忆里塞内容那样只会塞满垃圾。它会在任务结束时做一次“提炼”把当前任务中值得长期记忆的信息抽成结构化条目比如“用户偏好周报邮件在周一上午发送”“数据库 schema 中订单表有一个 region 字段”然后才写入存储。这个提炼过程本身也是由一次模型调用完成的所以存储的质量取决于提炼策略设得好不好。我自己调过提炼 prompt核心是告诉模型“只保存以后可能复用的稳定事实不要保存临时性结论”。记忆的召回也是一个值得单独提醒的点召回不是把历史记录全倒给模型而是检索出最相关的部分做成压缩摘要。我之前遇到过一个现象Agent 在任务执行中突然“跑题”把很早以前某次对话的内容当成了当前指令后来排查发现是召回策略太激进把低相关度的记忆也拼进了上下文。记忆召回要有相关性阈值宁可少召回不要乱召回因为错误记忆对决策的破坏力远大于没有记忆。2.5 安全与审计子系统信任的边界安全子系统在 Hermes 架构里不是附加组件而是贯穿所有链路的一层横切能力。每次模型输出要落成一个可观察的动作时安全层都会介入做三件事检查权限、检查合规、记录痕迹。权限检查的粒度很关键。最小权限原则在 Agent 场景下不是一句空话某个工具可能本身支持删除操作但当前会话的授权级别只允许查询那安全层在工具调用发出前就把删除类参数直接毙掉。另一个是凭证管理工具访问外部服务需要的 API Key 和令牌不能出现在模型可见的上下文里。Hermes 的做法是凭证统一放在独立的密钥服务中工具执行时通过环境变量或临时凭证注入模型那边只能收到“权限已具备”的确认信号看不到具体的密钥内容。审计日志要求完整但不过度敏感。每条工具调用、每条外部通信、每次权限拒绝都应该有记录字段至少包含时间、会话、操作者、工具名称、参数摘要、结果状态、关联的追踪 ID。这套日志做起来不难真正难的是形成习惯——很多 Agent 项目前期跑得欢上线出问题才想起来没用日志串链路到时候翻遍系统也定位不到问题出在哪一步。我个人的习惯是第一天就给所有工具执行挂上追踪 ID 日志前期多花半小时后期省一整晚。2.6 编排与通信子系统多部件之间的总线当你的 Agent 不止一个实例或一个任务被拆成多个 Agent 协作时编排层就是整个系统的消息骨架。Hermes 的编排子系统采用类似事件总线的模式子系统之间不直接互相调用而是通过发布/订阅的方式通信。这样做的好处是模块之间彻底解耦新增一个日志组件、加一个监控组件完全不用改原有代码只要订阅对应的事件流就行。编排层要处理的另一个现实问题是任务优先级和队列。多用户同时使用 Agent 时可能出现资源竞争——两个任务同时想调用同一个写工具或者某个任务占用了大量模型配额导致其他任务排队。任务队列需要支持优先级标记和动态调整至少要有暂停、恢复、取消这三种操作。我实际运行的时候发现没有取消操作会非常痛苦一个失控的 Agent 任务会一直循环调用工具直到配额耗尽。编排层加上“最大循环次数”和“人工中断开关”都是必须的保命设计。3. 执行路径地图一次任务的生命周期3.1 请求从进入到落地的第一站我把一条完整执行路径一步步拆开用一个实际任务来演示这样比空讲抽象流程好理解得多。假设用户通过 Hermes 桌面端发起了一条请求“帮我查一下最近的销售数据跟上周对比然后把变化趋势写到一份日报里。”请求进入系统的第一步是接入层把数据包解析成标准事件。不管用户是通过桌面 GUI、命令行还是 HTTP API 发起的请求接入层都会统一封装成一个任务事件包含用户标识、输入文本、会话上下文、以及新生成的追踪 ID。追踪 ID 从这里诞生之后每一条日志、每一次工具调用、每一次模型请求都会带上它。紧接着编排层会把这个事件放到任务队列里并给它分配一个执行环境。执行环境包括可用的工具列表根据用户权限过滤后的、初始上下文目录、超时限制、资源配额。这一步在配置里被称为环境装载相当于给即将醒来工作的 Agent 准备办公桌和工具包。3.2 一条完整任务的控制流与数据流继续上面的销售日报任务。任务被调度器激活后执行路径基本是这样的第一步上下文组装与意图识别。记忆子系统先召回该用户最近的偏好和与本任务相关的历史信息比如上次日报的格式、用户是否提过要看哪些指标输入感知子系统完成意图粗分类——这是一个“数据分析生成报告”的综合任务然后整个会话上下文被压缩成一个装载包发给规划器。第二步规划器生成初始计划。规划器结合当前工具清单和装载包生成粗粒度计划内容大致是查询销售数据库→与上周数据对比→整理变化趋势→生成报告文件。此时计划只是骨架还不涉及具体的 SQL 查询语句或文档格式。这步的输出会写回工作记忆同时给编排层一个“计划已生成”的信号。第三步工具调用循环。执行器从计划中取出第一个动作“查询销售数据库”将工具名和参数发送到工具注册中心注册中心验证权限后调用数据库查询服务。返回结果被写入工作记忆同时一份带截断摘要的观察结果回传规划器。规划器看到数据后判断“数据正常可以继续”于是取出下一步动作向执行器发起第二次工具调用。依次循环直到生成报告文件这一步也执行完。第四步输出与记忆沉淀。最终结果报告文件的路径和摘要经由输出层包装返回给桌面端用户。同时记忆子系统触发提炼把“用户常用于存储日报的目录格式”“用户关注的销售指标集合”这类稳定偏好写入长期记忆。数据流和控制流在这里是分离的控制流沿着“规划器→执行器→观察→规划器”的闭环走数据流则沿着“输入层→工作记忆→工具参数→工具结果→工作记忆→输出层”的管线走。理解这个分离非常关键你可以把控制流理解成指挥官在传令数据流是后勤在送弹药两者互不阻塞。后续做并发优化、做监控时都是基于这种分离来定位瓶颈的。3.3 并行分支与资源竞争的处理并不是所有任务都像上面的例子一样线性跑完。实际中任务计划经常拆出多个可并行的子任务。比如还是销售日报可能规划器把“查询本周销售数据”和“查询上周销售数据”拆成两个独立动作这两个查询并没有先后依赖关系完全可以并行执行。否则如果按顺序跑用户只是要一份对比日报硬生生要多等一整轮工具往返的延迟。这里需要引入 DAG 式的计划表达就是给每个计划步骤声明依赖项。只有依赖项全部完成步骤才能进入执行候选池。Hermes 的调度器会不停地扫描候选池把可执行节点分发给空闲的工作线程或并行的工具执行器。资源竞争在并行场景下会集中爆发。我遇到过一个典型问题两个并行的工具调用都指向同一个文件写入路径结果后一个覆盖了前一个的产出导致最终报告数据不完整。解决方案是给工具注册中心加资源锁声明机制工具在注册时声明自己会读写哪些类型的资源执行器在发起并行调用前做一次冲突检测发现有重叠就串行化有依赖关系的任务自动排队。这类问题在单线程演示时永远不会触发一上真实负载就全冒出来了提前做资源冲突检测比事后修数据靠谱得多。3.4 失败回退与重试路径真实环境中没有哪种工具调用是百分百成功的。Hermes 的失败处理分三个层级工具级重试、计划级调整、任务级放弃。工具级重试发生在最底层。数据库查询偶尔超时、网络请求偶发抖动这些瞬时故障直接重跑一次工具调用就行。重试要设置次数上限和退避策略不要死磕同一参数同样姿势的直连重试比如第一次是连接超时第二次可以换一个端点或使用备用数据源。计划级调整发生在工具重试仍然失败的场景。比如数据库查询工具报了“权限不足”错误这不是重试能解决的事。此时执行器把错误信息返回规划器规划器做出判断——换一个只读的副本数据库还是改用另一个汇总表格工具这就是观察-再计划的循环在发挥作用一次失败不是任务的终点而是下一步决策的输入。我在调这个环节时发现规划器能否做出正确调整很大程度取决于工具返回的错误描述质量。如果你的工具只返回“执行失败”四个字模型就算想调整也不知道怎么调整。任务级放弃是最后的安全网。当规划器经过多轮调整仍然无法完成目标或者错误信息显示是永久性不可修复的问题比如检索的数据库根本不存在Agent 应该放弃执行并向用户明确汇报失败原因和已完成的工作。这里有一个体验上的关键点放弃不等于甩手不管好的 Agent 会输出一份“尝试了哪些方案、卡在哪个环节、用户可能怎么修正”的失败报告。让用户自己从头排查一个黑盒和让用户带着半成品问题去问体验差别是巨大的。4. 关键概念澄清Harness 与 Agent 的边界4.1 Harness 的本质与作用“Harness 和 Agent 有什么区别”这个问题在热词里出现频率很高也是不少新手理解 Agent 架构时最容易卡住的地方。用大白话说Agent 是大脑负责想“做什么、怎么做”Harness 是身体负责稳定承接这些想法把它安全地落到现实环境里。Harness 这个英文词本身的意思是“挽具”就是套在牲口身上用来拉车的装备。这个词其实很形象——它不决定去哪个方向、拉什么东西但它决定了拉车的动作是否稳定、是否受控、是否不伤到牲口本身。Hermes 里 Harness 承担的工作管理模型上下文、调度工具调用循环、处理模型输出解析、控制任务的生命周期状态机、处理部分意外的错误恢复。所有 Agent 决策之外的技术性脏活都是 Harness 在扛。为什么要单独拆出这一层因为 Agent 的核心只有一件事——基于当前状态产生决策文本。其余全都是通用工程调用模型、解析输出、执行工具、处理异常、管理内存。如果这些杂活跟决策逻辑混在一起写最后的结果就是换一个模型时重写一遍执行循环换一种协议时重写一遍消息处理。把 Harness 抽象出来之后决策逻辑和运行环境彻底解耦你甚至可以在同一个 Harness 上服务多个不同的 Agent 模型。4.2 边界划分的实践价值边界画清楚的价值在可测试性上体现得最明显。如果你想测试“Agent 面对工具失败时能否正确调整计划”没有 Harness 的架构里你必须真的造一个失败工具然后跑完整流程过程麻烦且不稳定。有 Harness 之后你可以 mock 工具执行层的返回结果让 Harness 以为工具调用失败了然后在受控条件下观察 Agent 的反应。这个能力意味着你可以系统性地验证 Agent 的决策能力——批量跑各种故障注入用例不比在生产环境里裸奔香得多边界带来的另一个价值是安全升级。模型迭代特别快今天用这个模型明天可能想换个更强的。如果模型只在 Agent 层流转而不直接触碰系统资源替换模型就变成了纯配置变更。我实际测试过只改一个模型配置项整个系统感知不到切换工具调用、上下文管理、记忆写入全都照常工作。同理如果你想在 Harness 层加一个全局的监控拦截器或请求缓存不需要动任何 Agent 逻辑。这点对于想长期演进 Agent 系统的团队来说是前期架构最值得投入的部分。5. 部署配置与实操避坑5.1 不同平台的部署观察架构跑起来需要能落地。我在 Windows 桌面端、Ubuntu 服务端、以及 Windows 下借助 Linux 子系统环境各跑过 Hermes三个环境遇到的问题完全不一样。Windows 桌面版整体引导做得算顺手但有一步容易坑到人——安装向导在检测基础环境时经常“提前结束”画面上既不提示缺了哪个组件也没有日志面板看起来像死掉了。后来我排查发现绝大多数情况是它依赖的 Linux 运行时子系统没有就位。Windows 下装这类系统的运行环境最常见的问题就是启用向导明明点了开始十几秒后却提示失败。那个时候优先去确认系统版本是否过旧、内核组件是否已启用。给 Windows 用户一个建议先手动把这些底层环境准备好再回来跑 Hermes 的安装向导能省掉大半的黑盒报错。Ubuntu 下部署相对干净需要注意的点集中在依赖版本上。Hermes 某些组件对 Python 版本有明确要求新装的系统默认可能已经带到更高版本的 Python反而不兼容。我用的方案是给 Hermes 单独建一个虚拟环境避免跟系统 Python 打架。另外工具执行层依赖的编译工具链也要提前装好否则部分插件在首次导入时才现编译失败报错信息相当不友好。桌面版和 Server 版的选择应该看场景桌面版适合个人调试方便可视化观察状态Server 版适合挂服务、接 API跑定时任务。一个提醒桌面版在长期运行任务时不要开启自动休眠否则任务跑到一半系统睡过去了醒来要么超时要么状态错乱。5.2 关键配置项与参数建议Hermes 的具体配置项名称在不同版本里有一些差异我这边用的是当前自己手上的版本不一定完全对得上你拿到的版本但思路是通用的。核心配置就几块值得花时间调好的就几个参数。模型相关参数不要太信任默认值。任务复杂程度高、需要多轮思考时把最大输出 Token 适当调大否则计划到一半被截断。温度参数建议任务执行类场景调到 0 到 0.2 之间生成的文章结语、方案建议这种场景可以放宽到 0.7。不要试图让一个参数适配所有任务如果系统支持按任务类型配不同参数尽量分开配。工具列表和白名单这是安全性的核心。我会在配置文件里区分“全局禁用工具”“默认可用工具”“按会话授权工具”三类宁可少一个工具让 Agent 多绕一步也不要给一个危险工具放到默认可用列表里。另外工具描述写得好不好直接决定执行路径绕不绕这块值得花时间逐步打磨。并发与超时并发参数要从保守值开始先 1 并发跑通整个流程逐步往上加观察系统稳定性和响应延迟再最终确定。超时参数分两类模型请求超时、工具执行超时两者要分开配置。我遇到过工具执行非常慢但确实在正常工作的情况超时设短了就会误杀好任务建议工具超时尽量宽重点控制循环次数上限而不是单次超时。5.3 常见问题与排查记录我把实际运行中遇到的典型问题整理成一张速查表按子系统分布做个索引方便排查时对照。问题现象涉及子系统排查方向处理建议安装向导中途失败环境依赖检查系统基础运行时组件版本先手动安装依赖再重跑向导模型请求超时或频繁无响应决策子系统检查模型服务端负载和超时参数降低并发加大模型请求超时Agent 反复调用同一工具停不下来规划/编排层检查最大循环次数限制设置循环上限与人工中断开关多个并行任务互相覆盖文件工具执行/调度层检查资源冲突检测日志启用资源锁声明串行化冲突操作记忆召回内容导致跑题记忆子系统检查召回相关性阈值调高阈值限制低相关度记忆注入工具执行返回权限错误安全/工具层检查当前会话授权级别按最小权限原则调整授权配置排查过程中的最核心方法就一条从追踪 ID 串起全部日志。只要链路里的每个子系统都正确打上了同一个追踪 ID拿着它过滤日志执行路径会一目了然哪个环节卡了、哪个环节绕了、哪个环节失败了全都能按图索骥。拴不住追踪 ID 的系统遇到问题只能靠猜猜问题最耗时间。6. 架构演进的一些经验体会跑了一段时间 Hermes 之后我对这套架构设计的理解也从最初的“看热闹”变成了“看门道”。最想分享的一点体会是这套子系统拆分的价值不会在第一天体现而是在你开始给 Agent 加奇怪的新能力时才会爆发。比如我给它加了一套图表生成工具这个改动只涉及工具注册中心的新增和一个新执行器适配规划层、记忆层、安全层完全无感知。这种扩展成本才是一个好架构最直接的回报。给正准备搭 Agent 系统的朋友一个建议先别急着上复杂的分布式方案就用 Hermes 这类框架默认的单机部署把主路径跑通亲手画一张执行路径图标注出每一步控制和数据在哪里交接。这张图比任何文档都更能帮你建立对这个系统的直觉。等主路径稳了再逐步往里面加并发、加多 Agent 编排、加更细粒度的安全控制——那时候你会发现前期拆清楚的边界全都会加倍回报给你。最后再分享一个小技巧架构总览这类内容如果只看不画理解深度会差很多。我建议你把博文里的执行路径地图自己重画一遍不用拘泥形式哪怕手写一个方框箭头流程图都行。画的过程里你会注意到很多读文章时忽略掉的细节比如哪些环节有返回环路、哪些环节是单向传递。这些细节才是吃透一套架构的真正钥匙。
技术详解与实践)
