Hermes Agent实战：从零搭建大模型工具调用智能体

1. Hermes Agent是什么为什么值得折腾第一次看到“hermes-agent”这个名字可能有人以为这是个快递物流项目毕竟Hermes在国外也是家快递公司的名字。但在AI开源社区里Hermes这个词在圈内人眼里基本就指向一件事——Nous Research出品的Hermes系列模型。这个系列从Hermes 1一路迭代到Hermes 4主打的就是function calling函数调用和agent能力。所以当你看到一个叫hermes-agent的项目时大概率它不是一个单纯的聊天机器人而是一个围绕“让大模型真正动手干活”这个目标搭建的智能体框架。我最早接触Hermes系列模型是在做工具调用评测的时候当时对比了几个开源模型发现Hermes在结构化输出和工具调用的稳定性上确实有两把刷子。后来社区里出现了各种基于Hermes模型封装的agent项目hermes-agent就是其中比较有代表性的一个。它做的事情其实可以概括成一句话把大模型当成一个“会思考的大脑”再给它接上各种“手脚”——也就是工具、API、数据库查询能力让它能自主完成从理解用户意图、拆解任务、调用工具、汇总结果到最终回复的完整闭环。这个项目适合谁我觉得有三类人最值得关注。第一类是后端开发者想把LLM能力接进现有业务系统里但不想从零去写提示词工程、工具调用协议和上下文管理这一大套东西第二类是独立开发者和产品原型验证者想快速搭一个能真正干活的AI助手而不是只会聊天的demo第三类是对多智能体编排、agent架构感兴趣的研究者想在一个相对干净的代码基础上做二次开发。如果你只是想要一个开箱即用的聊天机器人那这个项目对你的价值不大但如果你想理解agent内部的运行逻辑或者想在一个可靠的基础上做自己的agent产品那它值得你花点时间研究。我在实际用的过程中最大的感受是这个项目把“模型能力”和“落地执行”之间的粘合层做得比较扎实。很多agent项目要么过度包装、代码绕来绕去要么太简陋、连基本的对话记忆都做不好。hermes-agent属于那种“工具痕迹很明显但确实能跑通”的项目你改起来不费劲跑起来也不容易崩这在开源agent项目里已经算很难得了。2. 核心架构拆解一个Agent到底由哪些零件组成2.1 模型层Agent的“大脑”选型不管是hermes-agent还是其他agent框架最底层一定是模型层。这里的模型不仅仅是“能聊天”的模型而是“能理解工具调用协议”的模型。为什么这么说因为agent和普通聊天机器人最大的区别在于普通聊天只要求模型生成自然语言而agent要求模型在合适的时候输出一个结构化的“工具调用指令”比如{name: get_weather, arguments: {city: 上海}}然后系统拿着这个指令去执行真实代码再把执行结果喂回给模型让模型继续推理。这就非常考验模型的“指令跟随”和“结构化输出”能力。如果你用一个不擅长function calling的模型你会发现它要么该调用工具的时候不调用要么生成了一个格式乱七八糟的参数导致解析直接报错。Hermes系列模型在这块的调教是下了功夫的它专门用了大量工具调用的数据做微调所以在hermes-agent项目里模型层默认接Hermes系列或者兼容OpenAI function calling协议的其他模型用起来会比较顺。在实际部署时我建议把模型层做成可配置的不要把模型写死在代码里。因为你本地测试可能用Hermes 3的小版本部署到服务器可能换成更大的参数版本甚至可能接一个商业API。hermes-agent这类项目通常会提供一个模型配置文件你只需要改接口地址、API key、模型名称这几个字段就能切换底层模型这个设计对于实际开发来说非常重要省去了每次换模型就要改业务代码的麻烦。2.2 编排层理解、规划、行动的循环模型的上一层是编排层也就是agent的大脑中枢。这一层负责的事情包括接收用户的初始输入把输入组装成系统提示词和对话历史调用模型判断模型输出是“普通回复”还是“工具调用”如果是工具调用解析出工具名和参数执行对应的Python函数把执行结果作为新的上下文消息追加进对话再次调用模型让模型基于工具结果继续生成回复重复这个循环直到模型认为任务完成输出最终答案这个循环看起来简单但实现起来有很多细节。比如循环的最大次数设多少如果工具一直返回错误是让模型重试还是直接放弃上下文里工具结果占用的token怎么控制这些都是在编排层需要考虑的问题。hermes-agent在这块的处理算是比较成熟的它会在循环里做一个最大迭代次数的限制防止模型陷入死循环同时会维护一个消息列表来管理对话状态。有一点我要特别提醒编排层是整个agent系统的核心也是最容易出bug的地方。很多人觉得agent不就是“调模型、调工具”嘛但真到了生产环境模型返回慢、工具超时、结果格式不对、用户中途取消等等情况都会冒出来。如果你用现成的hermes-agent框架这些基础问题它已经帮你处理掉了大部分你只需要关注业务逻辑但如果你是自己从零写建议把编排层的健壮性放在第一位。2.3 记忆与持久化对话不能“失忆”一个让我印象深刻的点是hermes-agent对记忆和持久化的处理。很多入门级的agent项目对话历史只存在内存里服务一重启就什么都没了。但真实的应用场景比如客服机器人、个人助理用户昨天聊到一半的事情今天打开应该还能接上。这就需要一个持久化层来存对话历史和Agent状态。hermes-agent在记忆这块采用了一种分级策略。短期记忆直接放在请求上下文里也就是每次调用模型时把最近的几轮对话发给模型保证模型“记得”当前正在聊的事长期记忆则落到数据库里可以按会话ID来管理下次用户再来的时候把之前的对话摘要或完整记录加载回来。这种方案的好处是既保证了模型在上下文窗口内的效率又不会让系统彻底“失忆”。我自己在实际项目里还会在此基础上加一个“记忆摘要”的机制。因为如果对话轮次太多全部塞进上下文会超出token限制这时候可以用一个轻量模型把前面的对话压缩成摘要再作为系统消息的一部分传给主模型。这个技巧在我处理长会话时效果非常好也是hermes-agent这种框架留给你二次发挥的空间。2.4 工具调用Agent与外部世界的接口工具调用层是agent真正“干活”的地方。在hermes-agent里一个工具的定义通常包含三部分工具名称、工具描述、工具参数的JSON Schema。拿查天气举例工具名称get_weather工具描述获取指定城市的当前天气情况参数city为城市名称如北京参数Schema{type: object, properties: {city: {type: string}}, required: [city]}模型看到这个定义之后如果用户问“上海今天冷吗”它就会判断这需要调用get_weather工具然后按Schema生成{city: 上海}。系统拿到这个参数之后把它传给Python函数get_weather(city上海)来执行再把返回值回传。这里有一个关键点工具描述写得越清晰模型调用工具的准确率越高。很多人用不好agent不是模型不行是工具描述写得太含糊。比如你写“查询天气”模型可能不确定是要查实时天气还是预报也不知道参数该传什么但如果你写“获取指定城市的当前实时天气和24小时预报参数city为城市中文名称例如北京”那模型基本不会调用错。这个经验我在调hermes-agent时反复验证过值得你重视。3. 从零搭建一个Hermes Agent实操记录3.1 技术选型与准备工作实战环节我以自己的一个真实项目为例来演示怎么把一个Hermes Agent跑起来。这个项目的需求是做一个能查天气、能做加减乘除、能查本地知识库的智能助理。技术栈我选了Python FastAPI模型端用一个兼容OpenAI function calling接口的服务。选FastAPI的原因很简单异步性能好、自带API文档、写起来干净。如果你不熟悉FastAPI也没关系换成Flask甚至直接写个Python脚本跑命令行业能理解整个逻辑只是FastAPI更适合后面接Web服务。环境准备分几步安装Python 3.10以上版本建议用虚拟环境隔离依赖安装openai SDK和FastAPI相关库准备一个能用的模型推理服务本地跑vLLM也行接OpenAI官方API也行关键是这个服务要支持function calling我用的是本地部署的一个Hermes量化模型通过vLLM提供OpenAI兼容的接口。这样做的考虑是本地部署不需要把对话数据发给第三方隐私上更可控而且断网也能跑适合开发调试。如果你机器配置不够直接用一个支持function calling的云端API也能跑通整个流程。3.2 核心代码定义工具和Agent循环先定义两个工具一个是天气查询一个是计算器import json import random from typing import Any, Callable def get_weather(city: str) - str: # 这里只做演示真实场景应该调用天气API mock_temps {北京: 12, 上海: 18, 广州: 25, 深圳: 26} temp mock_temps.get(city, random.randint(10, 28)) return json.dumps({city: city, temperature_celsius: temp, condition: 多云}, ensure_asciiFalse) def calculator(expression: str) - str: # 安全起见这里只允许数字和四则运算符号 allowed_chars set(0123456789-*/(). ) if not all(c in allowed_chars for c in expression): return json.dumps({error: 包含非法字符仅支持数字和四则运算}) try: result eval(expression, {__builtins__: {}}, {}) return json.dumps({expression: expression, result: result}, ensure_asciiFalse) except Exception as e: return json.dumps({error: f计算失败: {str(e)}}, ensure_asciiFalse)然后定义工具的元信息这个信息在调用模型时会被发送给它让模型知道“有哪些工具可以用、每个工具的输入输出长什么样”tools_meta [ { type: function, function: { name: get_weather, description: 获取指定城市的当前天气情况城市请使用中文名称, parameters: { type: object, properties: { city: {type: string, description: 城市中文名称例如北京、上海} }, required: [city] } } }, { type: function, function: { name: calculator, description: 执行四则运算传入一个包含数字和、-、*、/运算符的表达式字符串, parameters: { type: object, properties: { expression: {type: string, description: 数学表达式例如 (123)*4} }, required: [expression] } } } ] tool_functions: dict[str, Callable] { get_weather: get_weather, calculator: calculator, }接下来是Agent的核心循环。我用openai SDK来调用兼容接口from openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_keyEMPTY ) def run_agent(user_input: str, max_iterations: int 5): messages [{role: user, content: user_input}] for step in range(max_iterations): response client.chat.completions.create( modelhermes-3-llama-3.1-8b, messagesmessages, toolstools_meta, tool_choiceauto, temperature0.2, ) assistant_msg response.choices[0].message if not assistant_msg.tool_calls: # 模型没有要求调用工具说明任务完成直接返回内容 return assistant_msg.content # 模型要求调用工具执行并拼接结果 messages.append(assistant_msg.model_dump()) for tool_call in assistant_msg.tool_calls: func_name tool_call.function.name func_args json.loads(tool_call.function.arguments) if func_name in tool_functions: func_result tool_functions[func_name](**func_args) else: func_result json.dumps({error: f未知工具: {func_name}}) messages.append({ role: tool, tool_call_id: tool_call.id, content: func_result, }) print(f--- 第{step 1}轮工具调用: {func_name}({func_args}) - {func_result}) return 已达到最大迭代次数任务未能在预期内完成请简化你的输入后重试。这段代码的核心逻辑就是我在前面说的编排循环调模型、看是否返回工具调用、执行工具、把结果回填、再调模型直到模型不再要求调用工具。我加了一个max_iterations参数默认5次防止模型陷入无休止的工具调用循环这是我在生产环境踩过坑之后养成的习惯。最后用FastAPI把它包成一个API接口from fastapi import FastAPI from pydantic import BaseModel app FastAPI(titleHermes Agent Demo) class ChatRequest(BaseModel): message: str app.post(/chat) def chat(req: ChatRequest): result run_agent(req.message) return {reply: result}启动服务后用curl测试curl -X POST http://localhost:8000/chat \ -H Content-Type: application/json \ -d {message: 上海今天多少度另外帮我算一下 (2517)*3 等于多少}在模型正常的情况下请求会先触发get_weather和calculator两个工具的调用最终返回类似这样的结果{reply: 上海今天18摄氏度多云。你说的算式 (2517)*3 计算结果等于126。}整个链路就算跑通了。3.3 关键参数的选择依据这一段讲的参数是我在反复调试中总结出来的每一个都有它存在的道理。temperature0.2工具调用场景下温度越低越好。温度高意味着模型输出更随机有可能在生成JSON参数时出现格式漂移比如用了中文引号、多了个逗号解析直接崩。0.2是我试过比较稳妥的值既保留了少量随机性又保证了结构化输出的稳定。如果你对稳定性要求极高甚至可以设成0。max_iterations5这个值根据你任务的复杂度来定。如果你的工具链条很长比如需要查数据库、调API、再根据结果查另一个API那5次可能不够我跑复杂任务时会放宽到8到10次。但如果你发现模型经常把迭代次数跑满还没完成任务大概率不是次数不够而是工具描述写得有歧义或者模型对任务的理解有问题。tool_choiceauto让模型自己决定什么时候调用工具。还有一种写法是tool_choicerequired强制模型必须调用工具才能回复适合那种“每次请求都必须查一下数据库”的场景。但在通用场景下auto最合适因为不是每个问题都需要调用工具比如用户说“你好”你没必要让它去查天气。max_tokens这其实是我在配API的时候总会额外设置的参数。如果模型回复的最大token数太小工具结果很长时会被截断模型看到不完整的工具返回值就会开始胡编乱造。我一般把它设为模型最大上下文的一半以上给工具结果留足空间。另外如果你在调试时发现模型迟迟不调用工具可以在系统提示词里加一句“当用户的问题涉及查询或计算时请使用提供的工具来获取信息”这个引导性提示对中小模型尤其有效。4. 工具调用的边界与安全别让Agent乱跑4.1 工具白名单与参数校验Agent能干活也意味着它有“闯祸”的能力。如果给模型接了一个能执行任意Python代码的工具那用户就可以绕过业务逻辑直接让模型跑系统命令这是一个非常现实的安全隐患。我在给hermes-agent做工具扩展时一直坚持“最小权限”原则只给模型提供完成任务必需的工具绝不提供它不该碰的能力。以计算器工具为例我故意在代码里做了一个字符白名单校验只允许数字和四则运算符号直接把潜在的注入风险挡在门外。很多人觉得麻烦但这是必要的。你想想如果不做校验用户传一个__import__(os).system(rm -rf /)之类的表达式被eval执行出来是什么后果虽然在沙箱环境下可能不至于真的删库但这种风险完全不该冒。对于更复杂的工具比如数据库查询或API调用我建议在工具函数内部再做一层权限检查。比如管理员用户才能调用的工具工具执行前先校验会话身份写操作类的工具需要二次确认涉及外部API的调用要设超时和重试限制。这些细节看着琐碎但能帮你在生产环境少踩很多坑。4.2 调用次数限制与环路控制除了安全边界工具的“失控循环”也是一个典型问题。我在调试一个数据分析Agent的时候遇到过一个情况模型问“帮我查一下A表的数据”工具返回了数据但模型发现数据格式不对又调用工具去查B表B表结果还是不对又查A表……来来回回查了五六次最后才意识到是模型自己把查询条件理解错了。这种循环不仅消耗token还会让接口响应变得非常慢。所以除了max_iterations之外我还会给整个Agent调用加一个总超时时间比如30秒超过就强制终止。另外对单个工具的执行也要设超时特别是那些调用第三方API的工具网络抖动可能导致线程卡死从而拖垮整个服务。还有一个小技巧当工具连续返回错误或相同结果时可以在回填给模型的内容里附加一句提醒比如“工具返回结果与前一次完全一致请检查你的查询参数是否正确”。这个提示能有效打断模型的重复行为让它换个思路。4.3 敏感操作的人审机制在真实业务里有些操作不适合让Agent全自动完成比如发送邮件、转账、删除数据。我个人的做法是把这类型操作设计成“待审批”状态。Agent只负责生成一个执行提案包括操作内容、影响范围、预计后果然后提交给用户确认用户点确认后系统才真正执行。在hermes-agent这类框架里实现人审也不算复杂。最简单的方法是在工具回调里加一个needs_confirmation标记工具执行前先返回一个“该操作需要用户确认”的状态Agent收到这个状态后不再继续执行而是把确认请求展示给用户。这种模式虽然让Agent“不那么自动”但它在涉及钱、隐私、数据删除等敏感场景下是最稳妥的方案。你别嫌麻烦很多Agent翻车的案例都是因为让模型在无约束条件下执行了敏感操作。工具能力边界一定要心里有数该上锁的地方必须上锁。5. 常见问题与排查技巧实录5.1 上下文越长回复越飘怎么解这是我被问得最多的问题之一。随着对话轮数增加模型开始“忘记”用户最初的意图或者被中间的工具结果带偏。原因很简单上下文太长注意力被稀释了。我的解决方案是三管齐下。第一限制传入模型的历史消息数量只保留最近N轮更早的内容做摘要第二把用户的“原始目标”在系统提示词里重复一遍让模型始终记得自己本来要干嘛第三工具结果尽量精简不要让工具返回一大段噪声数据工具端可以先做过滤和汇总再回传。比如天气查询工具如果API返回的是一个包含几十个字段的JSON我先在工具内部把它压缩成“城市、温度、天气、建议”四个字段再传给模型。这样既节省token也让模型更容易提取关键信息。5.2 工具调用格式报错如果你在日志里看到类似JSONDecodeError或者Failed to parse tool call说明模型生成的内容不是一个合法的JSON。这个问题在用小模型或者弱模型时尤其常见。我摸索出来的几个排查思路先检查模型是否真的支持function calling有些模型只是“宣称”支持实际效果惨不忍睹再看一下模型服务的推理参数temperature设置是不是太高最后检查系统提示词里有没有让模型“不要输出除了JSON之外任何内容”这种明确指令。如果模型还是经常输出非标准JSON可以加一个后处理步骤用正则把模型输出里的JSON片段提取出来再用json.loads去解析。这个方法不能根治问题但能让服务先跑起来。5.3 并发请求互相干扰默认情况下如果你用一个全局的消息列表存对话状态那多个用户同时访问时就会互相串线。A用户说的话可能被B用户的Agent看到这在生产环境是绝对不能接受的。解决办法是给每个会话一个独立的session_id消息列表按会话隔离。简单做法是用一个字典key是session_idvalue是消息数组复杂一点的可以上Redis。我在hermes-agent里的实践是直接用字典加锁因为单机场景下够用但如果你要水平扩展建议把会话状态放到Redis或者其他分布式存储里。另外要注意多线程环境下操作共享消息列表要加锁不然并发写会导致消息顺序错乱或者丢失。Python的threading.Lock就能解决代码量不大但很多人容易忽略。5.4 模型输出被截断如果你发现模型回复到一半突然断了像说了一句话没说完一样大概率是max_tokens设置得太小。这个问题在Agent场景里会引发连锁反应如果模型正准备输出工具调用指令但指令写到一半就被截断你拿到手的是一段残缺的JSON解析直接失败。我会习惯在配置文件里把max_tokens设成一个相对大的值而不是用默认值。另外如果模型服务支持“流式输出”用流式方式接收结果也能在一定程度上缓解截断问题因为你可以实时发现输出异常提前做处理。5.5 常见问题速查表现象可能原因解决方案模型从不调用工具系统提示词没引导 / 模型不支持function calling加引导提示、换支持工具调用的模型、检查tools参数工具调用参数缺失或错误工具描述不清晰 / 温度太高重写工具description、降低temperature到0.2以下模型陷入重复调用同一工具工具结果不满足模型预期 / 上下文被噪声干扰精简工具返回结果、增加结果异常提示、限制最大迭代次数并发对话内容串线消息列表全局共享按session_id隔离会话状态工具执行超时第三方API慢 / 死锁为每个工具设置单独超时时间回复突然中断max_tokens不足调大max_tokens、开启流式输出工具结果太大导致上下文溢出工具返回未做裁剪在工具端做字段过滤和摘要6. 我的实操心得与后续扩展方向最后分享一点我个人在实际操作中的体会。hermes-agent这个项目技术上不算特别复杂但它把一个Agent系统最关键的几个环节都串起来了模型选择、工具定义、调用循环、记忆管理。如果你能把这个框架真正跑通一遍对Agent整体运作方式的理解会比只看文档深刻得多。我的建议是不要停留在“能跑通demo”就收手而是试着往里面加一个自己的工具亲手走一遍从定义工具到调试排错的全流程这个过程中学到的经验是看多少篇文章都换不来的。我在实际使用中还发现一个值得优化的点现成的框架往往默认Agent单线程工作但在一些场景下把一个复杂任务拆解成多个子任务并行处理会快得多。后续你可以尝试在这个Agent基础上扩展一个“任务分发器”把用户问题分解成几个独立的部分分别交给不同的Agent子实例去处理再汇总结果。这种多Agent协作的模式是当前整个行业都在探索的方向也是hermes-agent这类项目留给开发者最大的想象空间。另外流式输出也值得投入时间改造。现在的实现是等Agent全部跑完才返回结果用户体验上有点迟钝。如果能把工具调用的过程实时推送给用户比如先显示“正在查询天气...”再显示“天气查到了正在计算...”用户会感觉系统更智能。这块技术上不算难就是要把异步生成器和API响应的生命周期管理好。想清楚这些事之后再回头看hermes-agent你会发现它不只是一个项目更像一张地图把你带进了Agent开发的门往里走的路需要你自己去探索。希望这篇文章能让你少走一些我走过的弯路。