hermes-agent：轻量级智能体运行内核的设计与实践

说实话看到 hermes-agent 这个名字我第一反应不是某个开源项目而是一个很具体的痛点当项目里同时跑着多个大模型、挂了十几套工具函数、还要管短期记忆和长期记忆的时候代码会变得像一团被猫玩过的毛线。每加一个能力就要回头改一遍调度逻辑每换一次模型就要重新调一遍工具描述格式。那段时间我一直在想能不能做一个轻量的执行内核把模型、工具、记忆、调度这几件事彻底拆开让 Agent 退回到它本来的样子——一个忠实传递消息并调度资源的信使。hermes-agent 就是从这个念头长出来的。它的定位很纯粹一个面向工具编排的智能体运行内核名字取自希腊神话里的信使神 Hermes因为整个系统最核心的行为就是接收消息、理解意图、转发给合适的工具、再把结果带回来。它不是一个全家桶式的低代码平台也不是一个绑定特定厂商 SDK 的框架而是一套足够薄、足够透明、可以嵌入任何 Python 项目的执行核心。这篇文章我会把项目的设计思路、核心机制、上手路径和真实调试中踩过的坑全部盘一遍希望能给打算自研 Agent 或正在对比框架选型的朋友提供一份参照。1. 从信使神到智能体内核hermes-agent 到底想解决什么1.1 为什么偏偏叫 Hermes在动手写第一行代码之前我先把项目的边界想清楚了市面上很多 Agent 产品把大模型聊天能力和工具调度能力混在一起其实并不利于稳定复用。Agent 本质上就是一个中间层——它不负责生成知识也不负责执行业务逻辑它只负责在正确的时间把请求送到正确的执行者手里再把执行结果翻译回模型能理解的语言。这正是 Hermes 这个神话角色干的活传达神谕、引导灵魂、穿针引线。所以 hermes-agent 的核心抽象就三样东西消息Message、工具Tool、执行循环Loop。模型看到的是一连串消息系统提供的是一组工具描述执行循环在两者之间不断斡旋直到模型认为任务完成或达到终止条件。这套设计和人类工作中的转包非常像你不需要自己会写 SQL但你知道有一个数据查询工具能查数据库Agent 要做的就是把你的意图准确翻译成一条工具调用请求。1.2 重型框架逼出来的自研决定最开始我也尝试过用现成的编排框架但用了几个星期就发现了几个绕不开的问题。第一是抽象层级太高。很多框架把 Agent 的每一步都封装成了可观测组件回调链勾子机制表面上看功能很全但一旦需要调试某个工具返回格式问题你就得在多层包装之间来回跳排查成本远大于自己写一个循环。第二是工具注册太重。为了兼容各种模型框架往往要求你写额外的装饰器、描述模板、参数校验规则。但我的需求很简单我有一批 Python 函数我想让模型能调用它们。多余的封装只会增加出错面。第三是升级依赖牵着走。大模型 API 的接口变动很频繁如果框架紧耦合某个 SDK升级一个 SDK 版本可能导致整个 Agent 行为变化。我就遇到过一次某个框架因为上游依赖调整导致工具描述里的required字段丢失最后模型产出的 JSON 格式全乱套了。所以 hermes-agent 的设计原则是尽量不约束模型尽量少包装代码所有链路都能在两三层以内看完。模型调用是一层工具执行是一层中间只有消息传递这一条线。1.3 它的定位与主流框架的差异为了说清楚她适合什么场景我拿几个大家熟悉的方向做了个对比对比维度hermes-agent其他重型编排框架纯自研脚本调用抽象层级极薄核心只有一个循环多层封装组件丰富无统一抽象工具接入成本函数描述字典即可需要装饰器/派生类写死 if-else模型切换成本改一个 Provider 配置依赖框架适配层每个调用点都改可调试性消息流转清晰日志直观回调链复杂逻辑分散适合项目中轻量 Agent、嵌入式能力大型复杂工作流一次性脚本如果你需要的是可视化编排、人机协同审批、多角色多智能体协作这类纯业务层面的大平台确实没必要用 hermes-agent但如果你想给自己现有的业务系统加一个会调用工具的智能层不想被框架绑架那这套轻内核的设计可能更贴合你的需要。2. 架构拆解四个可替换零件加一条消息总线2.1 LLM Provider模型只是消息的读写者hermes-agent 的模型层被我刻意做成了薄薄一层。它不关心你用的是哪家模型只要求实现两个能力接收消息列表返回文本或工具调用。换句话说Provider 就是一个翻译器——把系统内部的统一消息结构翻译成目标模型的 ChatCompletion 格式再把结果解析回来。这样做的好处非常实际。今天项目里可能用的是 A 厂模型明天业务方说想换成 B 厂开源的私有化模型我只需要换掉 Provider 的地址和鉴权参数工具描述、记忆策略、调度逻辑完全不用动。哪怕某个模型本身不支持原生的 function calling也可以降级成把工具描述拼进 system prompt让模型输出结构化 JSON的解析模式。模型能力的差异被限制在最外层核心循环保持稳定。2.2 Tool Registry工具本质上就是给模型看的说明书工具注册是 Agent 项目里最容易被低估的一环。一个工具要能被模型正确使用不只是提供函数实现还要满足三件事名字全局唯一、描述语义清晰、参数结构机器可读。hermes-agent 采用函数参数字典的方式注册工具。参数字典直接转成 JSON Schema模型根据 Schema 决定传什么参数。最开始我踩过一个很蠢的坑某个工具的入参名是user_id但函数内部用的是uid我直接把user_id填进描述模型照做之后函数抛 KeyError。后来我统一要求工具描述里的参数名必须和函数签名完全一致这种低级问题就再也没出现过。另外我强烈建议在描述里写清楚工具的使用边界。比如一个查询订单工具描述中最好写明当用户询问订单状态、物流信息、退款进度时使用当用户询问商品库存时不要使用。因为模型对工具的选择完全依赖描述语义描述写得越具体误调用越少。我在实际测试中对比过同样一组工具描述从一句话扩展到三句话之后工具选择准确率大概提升了十几个百分点。2.3 Memory Store短期与长期记忆必须分开管Agent 的记忆设计很容易掉进一个误区把所有历史消息和知识片段塞进同一个向量库觉得有了记忆就万事大吉。实际上短期记忆和长期记忆的读写策略完全不同。在 hermes-agent 里短期记忆就是当前会话的消息队列它是模型上下文的主要来源直接参与每次调用。长期记忆则分成两块一块是用户画像类的高频事实比如用户所在城市常用收货地址这类信息在每次请求时以精简摘要形式注入另一块是历史对话的知识片段按需通过相似度检索召回而不是全量塞进去。这个设计的核心是控制上下文成本。一个会话如果持续几百轮全量塞历史消息既费 token 又会干扰模型对当前任务的判断。我在实现里加入了一个简单的摘要策略会话超过 N 轮之后把前面的消息自动压缩成一段结构化摘要只有与当前问题相关的片段才会被重新拉出来。2.4 OrchestratorReAct 循环的最小实现整个 hermes-agent 最核心的部分是这个执行循环逻辑简单到可以用一句话概括把消息交给模型如果模型返回工具调用就执行工具并把结果追加回消息列表然后继续如果模型返回最终答复就结束循环。但简单不代表容易写对。这个循环里有三个关键约束我必须处理好终止条件。不能无限循环。我同时设置了最大迭代轮数和模型明确结束两种出口任何优先达成的条件都会终止。异常隔离。工具执行抛异常时不能让整个 Agent 直接崩溃而是把错误信息作为一条消息回传给模型让模型决定是换一种参数重试还是向用户解释。消息追溯。每一条工具调用和返回结果都要带有足够的元信息哪个工具、耗时、成功与否否则出问题的时候你只能瞎猜。这套循环看下来很像 React 论文里描述的 ReAct 范式但工程实现上做了很多防呆处理。这也是为什么我不建议直接手写在业务代码里——边界条件和异常处理看起来不起眼实际跑起来全是细节。3. 从零跑通30 分钟跑起你的第一个 hermes-agent 应用3.1 安装与环境准备hermes-agent 是一个纯 Python 库Python 3.10 以上直接装就行。安装好之后你需要准备一个可用的模型 API Key。如果你本地有 OpenAI 兼容协议的推理服务比如 vLLM、Ollama 的 OpenAI 兼容端点也可以直接配进去。pip install hermes-agent安装完之后我建议先跑一下项目自带的健康检查命令。它会自动检测 Python 版本、核心依赖完整性并模拟一次最小模型调用确保底子没问题再开始写业务逻辑。hermes-agent doctor3.2 配置文件里的核心选项hermes-agent 不搞一大堆配置文件一个 YAML 就能撑起整个项目的基础配置。核心就几个字段model: provider: openai_compatible base_url: https://your-api-endpoint api_key: ${API_KEY} model_name: gpt-4o-mini loop: max_iterations: 8 timeout_seconds: 60 memory: short_rounds: 20 long_term_store: local其中short_rounds表示短期记忆保留最近多少轮对话超过的会被摘要压缩max_iterations是执行循环的最大轮数。我的经验是这两个参数值得花时间调一调——轮数太少模型来不及调用工具太多则在极端情况下产生高昂 token 费用。起步阶段建议max_iterations设在 8后续根据具体任务复杂度调整。3.3 用代码定义一个工具并启动 Agent配置完成之后真正写业务代码的部分比我预想的还要朴素。下面这个例子定义了一个城市天气查询工具并把它注册进 Agentimport asyncio from hermes import Agent, Tool def get_weather(city: str, date: str 今天) - str: 查询指定城市当天或指定日期的天气情况。 参数说明 - city: 城市名称如“杭州”“上海” - date: 日期默认为今天 当用户询问天气、要不要带伞、适合穿什么衣服时使用。 # 这里替换成真实天气 API 调用 return f{city}{date}天气多云21-28℃微风 async def main(): agent Agent.load(config.yaml) agent.register_tool(Tool.from_function(get_weather)) reply await agent.run(明天杭州适合穿什么衣服) print(reply) asyncio.run(main())注意Tool.from_function会自动从函数的参数签名、默认值和 docstring 中生成 JSON Schema 描述。这意味着你不需要额外维护一份模型看到的工具描述函数本身就是唯一的事实来源。一开始我在这个设计上犹豫了很久——自动生成会不会丢失描述细节实际用下来发现只要 docstring 写得规矩自动生成的效果远比手工维护的描述准确因为它永远不会出现描述和代码不一致的问题。3.4 用一个真实任务验证链路光跑通不是目的你得看到 Agent 真的在循环。我在本地加了一行日志观察它的内部状态一个简单任务的完整轨迹大致是这样的[1] user : 明天杭州适合穿什么衣服 [2] agent : 调用工具 get_weather(city杭州, date明天) [3] tool : 杭州明天天气多云21-28℃微风 [4] agent : 明天杭州多云气温 21-28℃微风建议穿着短袖或薄长袖……这个过程看似平淡但它把整个核心链路完整验证了用户消息进来、模型识别意图、选择正确工具、生成合规参数、工具执行、结果回传、模型组织最终答复。如果日志里第 [2] 步就停了多半是工具描述写得不够清楚如果 [3] 之后模型没有正常组织回答多半是模型本身能力对长上下文的处理有问题。4. 调试实录Agent 循环里最容易翻车的四个地方4.1 上下文爆炸当对话历史变成一本越翻越厚的书第一次把 Agent 放到真实聊天场景里压测时我很快发现了一个让人头大的问题会话跑到三十轮之后请求体越来越大响应越来越慢费用肉眼可见地涨。更麻烦的是模型开始失忆——用户明明前面说过自己在上海后面问我那家店的情况模型完全不记得是哪家店。根因很简单上下文窗口是有限的而我对所有历史消息一视同仁地保留。后来我把消息按两条规则处理一是按轮次截断太老的消息直接进摘要二是按类型加权工具调用结果由于经常包含关键业务数据保留优先级高于闲聊内容。压缩策略上线之后同样的会话从 3.5 万 token 降到了 8 千 token而且关键事实反而是靠摘要注入保住了。4.2 工具返回格式不规范一次报错暴露了三个隐藏问题有一次 Agent 在执行一个数据库查询工具时频繁报错报错信息是JSON 解析失败。我把工具返回的内容打出来一看傻眼了函数返回的字符串里既有正常结果又夹带了一行日志输出结果整段内容作为 JSON 解析时直接炸掉。排查链路是这样的先怀疑工具函数内部发现没写日志语句再怀疑模型端解析逻辑发现它对非 JSON 内容的容错很差最后才定位到是工具链路里某个第三方客户端把警告信息打到了 stdout被一并当成了返回值。修了三处才算完工具返回值统一走序列化层非法输出强制过滤模型端解析失败时增加一次重新请求模型修正的重试第三方客户端日志重定向到独立文件绝不污染标准输出。4.3 死循环最大轮数只是最后的保险丝有一次测试一个自动归档文件的任务Agent 在归档工具和查询工具之间反复横跳了二十多次也没有停下来。查日志发现归档工具每次执行后返回的都是同一个状态模型认为任务没有完成于是继续调用归档工具而工具本身永远返回同样的结果——模型基于完全相同的上下文做决策自然得出完全相同的结论。光设max_iterations只是止损不是根治。我随后做了两个改进一是在工具结果里加入状态变化标识如果工具检测到没有任何文件需要归档就直接返回已完成无待处理文件这样的终结性描述引导模型结束任务二是在循环里加了一个简单的去重机制如果两轮出现的消息哈希完全相同就主动打断并把检测到重复动作请尝试新策略或结束任务写入上下文。这两个改动之后死循环问题基本绝迹。4.4 工具调用的副作用重试不是免费午餐这是一个让我后怕的坑。某次测试让 Agent 调用一个发送短信验证码工具由于上游 API 超时我的代码做了一次机械重试。结果上游其实已经收到了请求重试导致同一个用户在同一分钟里收到了两条验证码短信。如果场景换成支付退款,代价会更大。从那之后我把所有带副作用的工具单独标记为side_effecttrue只允许执行一次由编排层统一记录执行状态不再让模型或链路层的重试逻辑反复触发。Agent 工具调用的幂等问题真的只有在上生产环境时才会意识到有多重要。5. 落地经验把 hermes-agent 接进真实业务时我做的调整5.1 场景一内部知识库问答第一个落地场景是给团队内部接一个知识库问答机器人。起初想直接拿通用模型回答但内部文档涉及大量私域术语模型经常一本正经地胡编。后来我在 hermes-agent 里挂了个检索工具先把团队文档拆成片段进向量库Agent 收到提问后用检索工具拿回 top-k 相关片段再让模型基于这些片段组织回答。这里有个很关键的设计调整我不让模型直接接触原始文档库而是通过检索工具间接访问。好处是权限可以在工具层统一管控模型拿不到的东西就是拿不到坏处是如果检索质量不好Agent 会带着错误材料做推理。所以我把检索结果里加入相似度分数和来源文档 ID模型在看到低分结果时可以选择不采用并由我在回复里附上引用链接方便人工核对。5.2 场景二定时巡检自动化第二个场景是给运维同学做一个定时巡检助手。每天固定时间触发Agent 调用监控查询工具读取服务器指标如果发现异常再调用告警规则查询工具拉取对应规则最后生成一份包含处置建议的巡检报告。这个场景暴露出一个新的问题Agent 是异步的、非确定性的而巡检报告需要按固定格式输出。解决的思路是给 Agent 定义一个结构化输出工具——报告不是让模型自由发挥生成文本而是让模型调用一个write_report工具按规定字段传参由工具端渲染成标准格式。这样既保留了 Agent 的灵活性又保证了交付物的规范性。定式的东西交给代码灵动的部分交给模型这是我做完这个场景最大的体会。5.3 生产级使用前必须补齐的三件事从 Demo 走到生产我发现至少要补齐这三块基础设施否则线上出了问题就是抓瞎。第一是全链路日志。每条消息、每次工具调用、每次模型请求耗时和 token 消耗都要记录。我用的是 JSON Lines 格式按天落盘配合查询工具可以按会话 ID 拉出完整轨迹。没有这套日志你永远无法复现用户说了一句话之后 Agent 为什么做了那件事。第二是权限最小化。Agent 能调用的工具集必须按会话上下文裁剪。一个只查天气的机器人不应该持有删除数据库的工具引用。我在注册层做了一个allowed_tools白名单机制业务方每次创建会话时显式声明开放哪些工具。第三是成本度量。大模型 API 不像传统接口那么便宜模型一个顿悟可能就烧掉不少 token。我在每次请求返回时记录 prompt 和 completion 的 token 明细按会话累计。设置单会话成本阈值超过自动熔断并通知负责人。这套成本护栏在多人共用的场景下尤为重要。5.4 关于上下文窗口压缩的最终方案前面提到摘要压缩我再具体分享一下最终采用的策略。我压缩分两级硬截断距离当前超过short_rounds轮的消息直接移出上下文只保留统计信息比如工具调用次数、涉及实体。记忆提取每次会话结束时一个独立的记忆总结模型会把本段对话里的关键事实抽成简短条目存入长期记忆库。下次新会话启动时按相关性把记忆条目注入系统提示词。这套方案跑下来长会话的体验提升非常明显。用户隔几天回来Agent 依然记得上次聊到哪、用户的偏好是什么而上下文并不会因此无限膨胀。6. 选型复盘什么情况下我会推荐直接用 hermes-agent6.1 与通用编排框架的权衡项目走到现在经常有人问我跟 LangChain 这类成熟工具比你自研的意义在哪里我的回答是取决于你需要的是速度还是控制权。如果任务是快速堆一个多工具 Demo或者团队对 Python 生态不熟直接用重型编排框架完全没问题。但如果你需要对 Agent 每一条消息、每一笔 token、每一次工具副作用做精细控制又或者你使用的模型/工具链比较独特那一个透明轻量的内核会让你在生产环境里少踩很多莫名的坑。hermes-agent 不会试图覆盖所有场景它在你可以一眼看穿整个运行链路这件事上做到了极致。6.2 适用边界与后续规划目前 hermes-agent 更适合单 Agent、工具编排、可控并发这类场景。多 Agent 协作、复杂人工审批流、流式工作流这些方向它还在逐步完善中。我接下来的计划是补两块能力一是给工具调用加分布式追踪支持让链路可视化不再靠猜二是做一个更灵活的人机协作接口让 Agent 在遇到不确定场景时主动发起确认而不是自作主张。如果你正在给业务系统加智能能力又不想被笨重的框架拖着走我的建议是先去读一遍 hermes-agent 的实现源码。它不长但每一行都在回答一个基本问题Agent 到底是什么——一个忠实的信使仅此而已。把这一点想透了你写自己的 Agent 时就会少很多迷茫。