做 Agent 类系统的人应该都有同感第一版 Demo 跑通并不难难的是进了生产环境之后链路还能不能稳定、边界还清不清晰、新需求加进来时改哪里不炸哪儿。Hermes Agent 在我眼里是一个很适合拿来当“架构标本”的代理框架因为它不是把提示词和工具调用揉成一团的玩具而是把输入、规划、记忆、执行、工具连接、观测拆成了明确的子系统。这篇文章不打算复读官方文档而是把 Hermes Agent 整体架构里到底有哪些子系统、它们怎么协作、一条用户请求从进来到最终产出会走过哪些执行路径一层层完整画出来。我正在用 Hermes Agent 做自动化编排的开发者以及想系统理解现代 Agent 框架设计思路的架构师都可以对照着看。1. 先给整个系统画一张子系统地图1.1 为什么必须分层而不是堆功能很多 Agent 项目翻车并不是某一个环节技术多难而是所有能力都堆在一个“上帝循环”里读消息、调模型、执行工具、返回结果全写在一起。前期很爽后期任何一个工具报错都会把整条链路拖死想加一个新能力又不敢动老逻辑。Hermes Agent 给我的最大启发是它把“大脑”和“手脚”彻底分开中间还插了一层“记忆”和“管控”。换句话说模型负责思考和规划工具连接器负责执行具体动作记忆库负责暂存和沉淀上下文而沙箱和观测层负责保证这个过程不会失控。这种分层的收益是实打实的你可以随时换模型而不影响工具层也可以只新增一个连接器而不碰规划逻辑。1.2 六个核心子系统全景表我做架构梳理的时候习惯先把整个系统画成一个表这样比看代码更直观。Hermes Agent 按职责可以拆成六块子系统核心职责典型载体/形态输入编排层接收不同渠道消息做格式统一和会话封装通道适配器、消息队列意图与规划引擎判断用户要什么拆解任务步骤制定执行计划规则路由 大模型规划器记忆系统管理短期上下文、长期知识库、向量检索内存缓存、向量数据库、KV存储工具连接器对接外部 API、命令、文件系统、浏览器等能力插件式连接器、工具注册表执行沙箱控制工具调用权限、限制资源消耗、拦截高危操作进程沙箱、权限校验、超时熔断可观测与追踪记录日志、链路 ID、指标复现每一步输入输出结构化日志、链路追踪、监控面板我最早看这个表的时候以为“执行沙箱”和“工具连接器”可以合并后来踩了坑才发现连接器解决的是“能不能调用”沙箱解决的是“允不允许调用、调用了会有什么后果”。这俩必须分开否则安全策略很快就会变成一团乱麻。1.3 子系统之间的解耦原则与数据契约子系统拆开之后最重要的就是它们之间怎么说话。Hermes Agent 的核心数据契约是一个统一的“执行上下文”对象无论是输入编排、规划器还是工具调用产出的数据都会以标准格式写进上下文。这意味着上游不需要关心下游用什么模型、怎么实现的只需要保证输出满足契约格式。比如规划引擎产出的不是一句自然语言而是一组结构化的步骤节点每个节点包含目标、依赖、超时时间、期望输出。工具连接器拿到这个节点之后才知道该执行什么、返回什么格式。提示判断一个 Agent 架构是不是成熟看它两个地方就够了——工具调用的输入输出有没有规范化以及上下文对象是不是贯穿全链路。如果每个环节都各传各的私有结构后面链路追踪和故障复现会非常痛苦。2. 核心子系统逐个拆开看2.1 输入编排与意图感知子系统输入编排层是用户请求的第一个落点但它容易被低估。它要处理的不只是“收到一条消息”而是要解决三个问题渠道异构、会话归一、上下文续接。渠道异构很好理解同样的请求可能来自命令行、桌面端、WebHook 或者定时任务触发不同渠道的消息格式完全不同。Hermes Agent 的做法是为每种渠道写一个适配器统一转换成内部 Message 结构。消息进来之后下一步是会话归一这一步会做“要不要开新会话”的判断如果一个新的请求和最近上下文没有关联就初始化一个独立会话避免记忆污染。我实际用下来有个很深的体会意图感知不要一上来就丢给大模型。轻量级的意图可以做规则预判比如“查天气”“调用某接口”这类高频且明确的指令直接用关键词和时间规则就能落地响应快还不烧 Token。只有规则判不了的情况才升级到模型做语义分类。这种“短路径优先”的思路对性能和成本都友好得多。2.2 任务规划引擎规划引擎是整个 Agent 的“大脑”但它不是单纯的大模型问答而是混合了一组确定性策略。Hermes Agent 的规划器最常见的是两层结构第一层是任务分类器决定当前任务是单步任务还是多步任务。回答一个简单问题属于单步任务规划器可以直接把请求映射到“检索 - 总结 - 回答”的固定流水线但像“帮我整理这周所有邮件里的待办并按优先级发到群里”这种就是典型的多步任务需要动态拆解。第二层才是动态规划器。它会基于当前可用的工具列表和用户目标生成一个带顺序依赖的 DAG有向无环图。规划器生成的不只是步骤还有每个步骤的输入从哪里来、输出给谁用。这一步最考验架构设计的细节如果步骤之间没有显式的依赖声明后面做并发优化时会无从下手。很多人第一次看 Hermes Agent 时都会问为什么不把所有步骤都交给大模型一个提示词搞定我的答案是动态规划拆出来的步骤可以单独重试、单独缓存、单独观测。如果整个任务是一坨提示词任何一步失败都要全量重跑而拆成步骤节点之后失败只需要从失败的节点续跑效率和稳定性是量级差异。2.3 记忆系统短期上下文与长期知识库记忆系统的设计直接决定 Agent 是“每次都像失忆”还是“越用越懂你”。Hermes Agent 把记忆分了三层第一层是会话级短期记忆存当前会话的上下文消息和最近几轮的执行结果用内存环形缓冲超出窗口就做摘要压缩把旧对话浓缩成一段摘要丢回上下文。第二层是长期事实记忆存用户的偏好、高频指令、已知约束条件用 KV 存储做持久化。这层记忆更新的时机很关键——不能每轮对话都写通常是在一次任务成功完结后抽取“用户偏好”和“环境事实”回写。第三层是知识库式记忆面向的是“过往处理过类似任务的经验”比如之前的相似故障处理记录用向量化存储加文本检索实现。我踩过一个坑短期记忆和长期记忆没有做“写入策略隔离”导致短期上下文里的临时噪声被写进长期库知识越用越浑浊。后来改成“只有经过成功闭环且明确包含可沉淀信息的任务才允许写长期库”效果立刻改善了很多。记忆系统的架构核心不在于存得多不多而在于什么该忘、什么该留、什么时候触发写入。2.4 工具连接器与外部资源适配层工具连接器是 Agent 能力的边界。Hermes Agent 的每个工具都遵循同一个规范从输入参数到输出结果都需要声明 JSON Schema并注册到工具注册表。规划器只能看到注册表里已声明的能力看不到任何未注册的代码。连接器内部有两个关键设计。一个是超时隔离每个工具调用都有独立的超时上限避免某个上游接口卡死拖垮整条链路。另一个是失败分类连接器会对错误做标准化归类比如“网络错误”“鉴权失败”“业务规则拒绝”“参数不合法”不同错误类型触发不同的重试策略。这里特别想提醒一点工具不是越底层越好。连接器暴露给规划器的能力粒度应该是业务语义级的。比如你有一个“发送邮件”的底层接口同时想支持“给指定列表群发邮件”就把“群发”做成一整个工具而不是让规划器自己去循环调用底层接口。粒度太粗会不灵活但粒度太细会让规划器陷入大量的编排步骤模型更容易出错。2.5 执行沙箱与安全管控执行沙箱是 Hermes Agent 里最容易被忽略、却最容易出事故的子系统。它管的是三件事权限边界、资源额度、操作审计。权限边界解决的是“工具可用但这个场景能不能用”。比如一个文件读写工具在普通对话场景中可能被允许但一旦上下文里出现了“删除”“覆盖整个目录”这类高风险意图沙箱就会要求二次确认或直接拒绝。资源额度解决的是“防止失控”。每个任务能调用多少次工具、累计执行多久、单次返回体多大、并发跑多少个步骤都要有配额。配额不是用来限制正常使用的而是用来防止 Agent 在异常场景下把事情无限放大。我有一次亲眼看到一个逻辑不严谨的规划器在循环里反复调用同一接口好在配额把它截停了。现在我把“每任务最大工具调用次数”和“单工具最大耗时”全部设成显式参数宁可配额设置过严导致偶尔要人工提额也比任其失控强得多。2.6 可观测性与运行追踪执行链路一旦变长排障就变成了“考古”。Hermes Agent 在可观测性上的核心设计是给每个会话分配一个全局 TraceID从输入编排到每一个工具调用都记录同一个 ID并且输出结构化日志。结构化日志和普通日志最大的区别在于它把“参数”“耗时”“状态”“错误码”拆成了独立字段而不是拼在一行字符串里。这样排查时可以按 TraceID 直接拉出整条链路也能通过指标面板看到“哪个工具平均耗时最高”“哪种错误类型占比最大”。我还建议在关键节点打“快照”比如规划完成时、每次工具调用前后、最终响应前把当时的上下文截取一部分存下来。这个东西在调试复杂任务时几乎是救命用的——你可以直接回放每一步而不是对着最终结果猜过程。3. 一条请求完整走完的执行路径3.1 入口与会话封装现在把视角从静态架构切到动态流程看一条请求在 Hermes Agent 里是怎么走完的。第一步永远是输入编排层接收原始消息做渠道适配同时做会话查找或创建。会话封装这一步比看起来更重要。它决定了两件事当前请求属于哪个会话、这个会话已经积累了哪些上下文。如果是新会话编排层会做一次“零状态初始化”把系统提示词、用户偏好、可用工具列表组装成初始上下文。这个上下文会被打上一个唯一 ID作为整条链路的追踪根。这一步我还要特别强调“请求去重”。如果输入编排层没有做请求 ID 去重网络重试或者用户手滑重复提交时同一个请求就可能被执行两次。幂等控制必须从前端就做起不能等执行引擎去判断。3.2 意图分类与规划器裁决会话封装完成后请求进入意图分类器。这一步产出一个结构化意图对象包含任务类型、优先级、是否多步、是否涉及外部副作用。意图对象会直接影响后面的路由简单问答走快速检索路径多步任务走规划器路径高风险操作走安全审查路径。规划器拿到意图和目标之后会结合工具注册表生成一份执行计划。生成计划不是只输出一串步骤名而是要输出步骤之间的依赖关系和每个步骤的输入数据来源。比如“整理邮件待办并推送”这个任务规划器可能生成“读取邮件 - 抽取待办 - 生成摘要 - 发送到群”并且显式声明第四步依赖第三步的结果。规划完成之后执行引擎会做一次“可执行性预检”看计划里的每个步骤是否都有对应的工具、是否存在循环依赖、预估耗时是否超限。预检不通过的任务会在规划阶段就拒绝而不是执行到一半才失败。这一步能省掉非常多无效调用。3.3 工具调用与中间结果回填执行引擎拿到计划后就开始按依赖顺序调度步骤。有依赖关系的步骤串行执行无依赖的步骤尽可并发执行。每个步骤执行前执行引擎都会读取该步骤的输入引用从上下文中取出对应数据执行后把返回值统一写回上下文的“中间结果区”。中间结果回填是整个执行路径里最容易被忽略的环节。Hermes Agent 的每个输出都会带上 schema 版本和返回时间后续步骤读取时可以根据版本判断数据是否过期。比如邮件列表读取之后如果任务拖了很久才执行到“给用户发摘要”执行引擎可以重新校验邮件数据是不是已经过时。工具调用的失败处理也发生在这里。一般工具连接器会先做一次自动重试重试策略区分“可重试错误”和“不可重试错误”网络超时可以重试鉴权失败重试多少次都一样直接跳过。重试仍然失败时步骤会标记为“失败”并触发规划器的“补偿路由”——规划器会尝试找替代工具或者在有充足信息的情况下进入降级模式。3.4 结果组装全自动输出与 Bot Mode所有步骤完成后执行引擎把上下文里的最终结果交给生成层做结果组装。这个环节要做两件事一是把内部的结构化数据转成用户可读的自然语言二是对结果做合规检查确保没有输出敏感内容或未经验证的信息。这里就不得不提 Hermes Agent 的交互模式差异了。默认的交互模式是全自动输出Agent 把结果直接返回给用户但还有一个很有价值的模式叫 Bot Mode也就是无人值守模式适合定时任务、告警触发、批处理场景。Bot Mode 下Agent 不会等用户追问而是按预设的交付方式把结果路由到指定频道、推送接口或者归档存储。Bot Mode 让我在项目里获得了很大的收益比如每天早上的数据巡检、每周的日志聚合报告全部用 Bot Mode 定时跑完全不需要人参与。它的执行路径和普通交互模式唯一的区别在“结果交付”这一段前面从意图分类到工具调用完全复用同一套机制。3.5 并发、超时与异常路径前面说的是一条请求的“理想路径”真实的系统里每秒可能同时进来几十条请求所以还要看并发和异常路径怎么控制。Hermes Agent 的做法是引入执行配额和信号量机制给每个会话分配最大并发数全局再设一个总并发上限。超时策略也要区分维度全局任务有总超时单步骤有单步骤超时工具调用有连接和读超时。我个人的配置习惯是“总超时最长、单步骤次之、工具调用最短”这样预留了重试和补偿的空间。如果单步骤超时就等于全局超时那重试和兜底根本来不及执行。异常路径里最容易被忽略的是“优雅降级”。当一个核心工具不可用时Agent 是否能明确地告诉用户“我现在只能用部分能力处理”我见过太多系统在工具故障时输出一大段“似乎有点问题”的废响应。好的做法是结果组装层在输出前检查每个关键步骤的状态只要有任何一步未完成就必须在回复里显式声明处理范围而不是装成一切正常。4. 生产环境常见故障与排查清单4.1 三个典型故障场景重现场景一任务永远卡在“规划中”。这种情况大多是工具注册表里没有匹配的可用工具规划器生成不了可执行的步骤一直在循环尝试。排查时先看日志里是否出现“no_tool_found”之类的标记然后检查工具注册表里各工具的描述和参数声明是不是写得太笼统导致语义匹配失败。场景二工具调用成功但结果“答非所问”。这个问题的根源通常不在工具层而在上下文回填环节。某个中间结果被后续步骤覆盖了或者读取时取错了字段。排查思路是追踪中间结果区的每一次写入记录比对当前节点的输入引用是否和规划时的定义一致。场景三响应超时但日志里一切正常。优先检查并发配额是不是被占满了。有些长任务的工具调用没有正确释放信号量导致后续请求全部排队。这种情况要在执行引擎的资源池监控里看“活跃数”和“等待数”如果活跃数恒等于上限且长时间不降大概率是信号量泄漏。故障现象优先怀疑环节首要排查依据卡在规划中工具注册表、意图路由日志中 no_tool_found 标记答非所问中间结果回填、上下文引用追踪中间结果区写入记录全链路超时并发配额、信号量释放资源池活跃数监控记忆串味长期记忆写入策略检查成功闭环过滤条件重复执行输入编排层幂等控制请求 ID 去重日志4.2 日志链路追踪排查法排障成本最大的部分是链路长、环节多。如果日志是散落在各个子系统里的独立文本排查一条失败任务要来回切换好几处效率极低。我强烈建议把 Hermes Agent 的每个子系统都强制落在同一套 TraceID 上并且让日志带上“层级字段”比如编排层标记为 layerinput规划层标记为 layerplanner。有了链路 ID 之后排障就变成了一条流水线先按 TraceID 拉出所有日志按时间排序再看最后一个成功节点是哪个失败节点的错误类型是什么最后沿着依赖关系往前查输入数据通常很快就能定位。我还习惯在每次工具调用前后各打一条“进入/返回”日志内容包含入参摘要、耗时、返回状态码。这个习惯让很多看起来诡异的问题变得非常直接——有一次工具明明超时了但因为重试成功上层日志显示成功只有看了带耗时的进入返回记录才发现第一次调用已经超了 20 秒重试才正常。4.3 配置级调优重试、缓存、超时和配额把几个核心配置项单独拿出来说因为它们的调整逻辑跟直觉不完全一致。重试策略上指数退避要配但要限制最大重试次数一般三次以内。连续第三次失败还继续重试基本说明问题是结构性的重试只会放大负载。缓存策略上对“确定性工具”的结果做缓存收益最大。比如读取某份静态配置、查询固定维度报表这些结果在一定时间窗口内不会变规划器动态使用缓存能省大量外部调用。但凡是带副作用的写操作一律不缓存。一个比较实用的 YAML 配置示例可以直接参考engine: global_timeout_sec: 300 max_concurrency: 32 max_retries: 3 retry_backoff_base_sec: 1 retry_backoff_factor: 2 tools: default_timeout_sec: 15 cache_enabled: true cache_ttl_sec: 300 deny_high_risk: true memory: short_term_window: 20 long_term_write_policy: on_success_only vector_top_k: 5 trace: log_level: structured snapshot_on_plan: true snapshot_on_tool_call: true超时配置上我个人的经验是“宁可早失败不要晚成功”。一个工具调用如果已经超过默认时限继续等下去成功率很低不如及早标记失败走补偿路径。全局任务超时也要设得比预估耗时长一些给重试留余地但又不能长到让用户无限等待——超过一个心理阈值之后先返回部分结果都比继续挂着强。配额配置的底层逻辑是“保住核心业务牺牲边缘任务”。全局并发数、单任务最大工具调用次数、Bot Mode 的最大并发任务数这些参数在生产环境里要结合监控数据逐步压测调整不能一上来就开满。我见过太多系统把配额全部开到最大结果一个异常任务就把整台机器的资源吃完正常流量反而被拖死。5. 架构演进中的个人经验5.1 从单体脚本长成子系统的路径说回晚上我最早用 Hermes Agent 时并没有一口气把六个子系统全搭出来而是从一个单体脚本起步读消息调模型执行工具返回。是后来跑了一段时间才慢慢长成前面讲的结构。第一条路径是从工具调用失败开始痛的当时任何工具报错都会导致整个脚本异常退出于是先拆出了工具连接器加了超时和错误分类。第二条是记忆串味多个会话上下文互相污染于是拆出了会话隔离和记忆层级。第三条是并发任务互相抢占资源于是拆出了执行引擎和配额控制。回头看架构并不是一开始设计出来的而是被生产环境一次次教育出来的。但关键区别是 Hermes Agent 给了足够清晰的边界让每个“教育时刻”都能落进对应的子系统里而不是把补丁打在同一个地方。5.2 我给团队定下的三条架构纪律第一条纪律每个子系统只能和它直接相邻的子系统通信。输入编排不能直接调用工具连接器工具连接器也不能直接改记忆所有交互都必须经过执行引擎的调度。这条纪律带来的是“改造点单一”换工具不影响规划调记忆策略不影响编排。第二条纪律所有跨子系统数据必须用标准结构。任何工具产出自定义格式、任何规划器不走标准上下文都要在代码审查时被拦下来。宁可前期多写一点转换代码也不让私有结构悄悄长进链路里。第三条纪律每条执行路径都要有“兜底出口”。无论是异常超时、工具全挂、还是上下文溢出都必须有一条明确的路让请求安全结束并且把状态如实告诉用户。我最怕的架构问题是“链路断了但进程没报错”用户和一个失灵但假装正常的系统对话这种情况比直接失败更隐蔽、更危险。最后分享一个实操时我反复验证过的心得把执行路径图当作系统的一等资产来维护。代码可以重构工具可以增减但那条“输入 - 编排 - 规划 - 执行 - 输出”的主路径要始终清晰。每次排障、每次评审、每次新增能力先回到这张路径图上确认改动落在哪一段整个系统就乱不了。画图不见得要多精细但边界和顺序必须人人心中有数。这也是我写这篇文章最想传达的一点架构总览的价值不止于好看它是团队所有人对齐语言的那张地图。