Hermes Agent 实战：循环控制、工具契约与上下文预算

很多人第一次接触 Hermes Agent第一反应是不就是包了一层模型接口吗于是花半小时照着示例把 demo 跑通然后直接接进真实业务结果第二天就开始崩任务跑一半停了、工具被同一个参数反复调用十几轮、结构化输出解析报错、账单比预算高出一个数量级。这些问题几乎都不是模型能力问题而是对 Hermes Agent 这套运行模型的理解深度不够——它真正难啃的部分从来不是调用一次模型而是循环怎么控、工具契约怎么定、上下文预算怎么花。这篇教程面向已经能把基础 demo 跑起来、准备把 Hermes Agent 往真实场景推进的人我会按运行模型拆解 → 最小工程搭建 → 工具注册 → 上下文管理 → 故障排查 → 成本与可观测性的顺序讲中间穿插我自己踩过的坑和实测参数。新手也能看懂前半部分但后半部分的排错链路建议你至少跑过一个多步任务之后再回来读感受会完全不一样。1. 先看清 Hermes Agent 到底在循环什么动手写代码之前这一个小时值得花在理解运行模型上。我见过太多人跳过这一步后面所有痛苦都源自这里。1.1 一次任务从进入到返回实际经过四层把 Hermes Agent 想象成一个项目经理带一个执行团队。项目经理模型不做具体活只负责判断现在该干什么然后把活派给执行团队工具拿到结果再判断下一步。围绕这个比喻一次任务实际穿过四层层级职责出问题时的典型症状编排层控制循环次数、超时、终止条件任务无限循环、提前中断决策层模型判断下一步动作该调工具时不调、乱调工具执行层工具运行时含参数校验与结果回传参数类型错、异常吞掉、返回值过大状态层上下文、会话记忆、长期知识忘掉前文、上下文爆掉、答非所问新手最容易只关注决策层觉得换个更强的模型就好了但实际排查下来七成问题出在执行层和状态层。一个工具返回了 3 万字的原始数据直接把上下文挤爆模型再强也只能在垃圾信息里瞎猜。编排层的核心是一个 while 循环逻辑大致是把当前上下文送给模型 → 模型返回动作要么调用工具要么给最终答案→ 如果调用工具执行并把结果追加进上下文 → 回到开头。这个循环必须有两个硬刹车最大迭代次数和总耗时上限。我的经验是迭代次数默认给 15复杂任务给到 30超过这个数还没收敛基本说明任务分解本身有问题继续加次数只是烧钱。1.2 工具描述不是注释是模型唯一能看到的接口契约这是 Hermes Agent 和普通函数库最大的区别。你写一个普通 Python 函数调用方是人类程序员他会去读源码。但在 Agent 场景下调用方是模型它看不到你的函数实现只能看到你提供的那段工具描述和参数 schema。描述写得含糊模型就会猜猜就必然出错。我做过一组对比测试同一个查询订单的工具描述分别写成查询订单信息和根据订单号查询订单详情返回金额、状态、创建时间三个字段订单号必须是 16 位纯数字不要传用户 ID。后者的参数正确率从大概六成提升到九成以上。差别就是几十个字的描述。所以写工具描述时我固定包含四件事这个工具做什么一句话说清不用可用于这类模糊词参数的确切格式含位数、取值范围、枚举值返回什么字段名和含义尤其要说明哪些字段可能为空什么时候不该用它这条最容易被忽略但效果最好1.3 三种启动形态选错了后面全是返工Hermes Agent 通常提供三种使用形态适用场景差别很大选之前先想清楚你的落地位置命令行单次执行适合验证工具链通不通、调试单步行为。跑一条命令看一次完整轨迹最快定位问题。SDK 嵌入到业务代码适合把 Agent 能力塞进已有服务比如工单系统里加一个自动分诊。灵活性最高但进程生命周期、异常处理要自己管。常驻服务形态适合多客户端调用、需要会话保持的场景。好处是上下文可以跨请求维持坏处是状态管理和并发控制一下子复杂起来。我个人的建议是任何新项目都从命令行形态开始先把工具跑顺确认单步行为符合预期再往上换成 SDK 或服务形态。反过来做的人出问题时根本分不清是工具写错了还是框架集成错了。2. 搭一个能跑的最小工程别一上来就堆功能最小工程的意义不是能跑就行而是建立一条可重复的验证路径。后面每加一个功能都能回到这条路径上确认没把地基弄塌。2.1 目录结构和依赖安装里的取舍我习惯的目录结构是这样的简单但够用hermes-demo/ ├── .env # 环境变量不进版本库 ├── config/ │ └── agent.yaml # 模型、迭代上限、超时配置 ├── tools/ │ ├── __init__.py # 工具注册入口 │ ├── search.py │ └── calc.py ├── prompts/ │ └── system.md # 系统提示词单独放便于版本对比 └── run.py # 入口脚本依赖安装上有一个坑值得单独说Agent 框架往往和某些 HTTP 客户端库、序列化库有版本耦合。我遇到过一次本地环境里某个库是较新的大版本框架用的是旧版接口表现是工具调用一切正常但流式返回时偶尔截断排查了大半天。所以我的做法是新建独立虚拟环境装完之后立刻冻结一份依赖清单后面所有调试都在这个环境里做不跟其他项目共用。python -m venv .venv source .venv/bin/activate pip install -r requirements.txt pip freeze requirements.lock注意不要把环境问题当成框架 bug。遇到行为诡异时第一步永远是换一个干净环境复现一次这一步能省掉大量无效排查。2.2 模型接入与环境变量管理模型接入这块配置文件里我只放非敏感项密钥一律走环境变量。配置文件长这样model: name: your-model-name temperature: 0.2 max_tokens: 2048 loop: max_iterations: 15 timeout_seconds: 120 tools: enabled: - search - calctemperature这个参数在 Agent 场景下尤其要压低。有人喜欢调到 0.7 追求创造力结果同一个任务跑五次给出五种不同的工具调用序列根本没法排查。Agent 场景下 0.1 到 0.3 是比较稳的区间需要创意的环节应该放在最终文本生成那一步而不是决策那一步。环境变量加载用标准做法即可重点是别把密钥写进配置文件再提交上去import os from pathlib import Path def load_env(path: str .env) - None: p Path(path) if not p.exists(): return for line in p.read_text(encodingutf-8).splitlines(): line line.strip() if not line or line.startswith(#) or not in line: continue key, _, value line.partition() os.environ.setdefault(key.strip(), value.strip())这段代码很简单但setdefault这个细节很重要——它保证已经存在的环境变量优先方便在容器里覆盖配置而不改文件。2.3 第一个可复现的任务脚本最小验证脚本我一般这么写重点是把完整轨迹打出来from hermes_agent import Agent, tool # 包名以你本地实际安装为准 tool( namecalc, description执行四则运算。expression 必须是仅含数字和 -*/() 的字符串例如 (128)*3。, ) def calc(expression: str) - str: if not set(expression) set(0123456789-*/(). ): return 错误表达式包含非法字符 try: return str(eval(expression, {__builtins__: {}}, {})) except Exception as e: return f错误{type(e).__name__}调用侧的关键是拿到每一步的中间状态而不是只看最终字符串agent Agent.from_config(config/agent.yaml) result agent.run(计算 (128)*3 的结果再把结果乘以 1.5) for step in result.trace: print(f[{step.index}] action{step.action} args{step.arguments}) print(f observation{str(step.observation)[:200]}) print(最终答案:, result.output)注意eval那里我加了{__builtins__: {}}因为模型完全可能生成出人意料的表达式把内置函数禁掉是必要的兜底。这类用户输入来自模型的地方全部要按不可信输入处理后面第 3 章还会展开。2.4 跑通之后先读日志别急着加功能脚本跑通那一刻大多数人会立刻开始加下一个工具。我建议反过来先在日志上停留一会儿确认三件事第一模型第一次调用工具时参数是否符合你预期的格式还是它猜对了。第二工具返回的内容长度是否合理有没有把整页原文塞进去。第三循环用了多少轮如果一个问题用了 8 轮才收敛说明提示词或工具粒度有问题。这三件事如果在只有两个工具的简单场景下就有毛病等你加到十个工具问题会成倍放大。先修地基再盖楼这是我做过十几个 Agent 项目后最想告诉新人的一句话。3. 工具注册是整套系统最容易翻车的地方工具写得好不好直接决定 Agent 的稳定上限。模型的能力是给定的但工具契约是你完全可控的部分。3.1 函数签名的三条硬约束我给团队定的规矩是三条没有例外参数只用基础类型。字符串、数字、布尔、以及它们的列表。不要传自定义对象、不要传嵌套三层的字典。模型的参数生成能力在扁平结构上最稳嵌套一深错误率陡增。返回必须是字符串或可直接序列化的结构。返回内容会被写进上下文任何无法序列化的对象都会在这一步炸掉。一个工具只做一件事。叫handle_order的工具模型永远不知道该传什么拆成query_order、cancel_order、refund_order每个的触发场景一目了然。这三条听起来很基础但违反率极高。我最常见到的反例是把整个业务服务的十几个方法包成一个工具用action参数区分——模型的action值填错率能到三成以上。3.2 参数校验和错误回传决定模型能不能自我纠错工具执行失败时有两种回传方式抛异常或者返回一段描述错误的字符串。在 Agent 场景下后者几乎总是更好的选择。原因是这样的抛异常会让整个循环中断模型失去了看到错误并修正的机会返回错误字符串则相当于给模型一个反馈信号它下一轮很可能就改对了。我实测过一个场景参数格式错误时返回明确提示模型在第二轮自我修正成功的比例超过七成。tool(namequery_user, description按用户 ID 查询用户基础信息。user_id 必须是 8 位纯数字字符串。) def query_user(user_id: str) - str: if not (isinstance(user_id, str) and user_id.isdigit() and len(user_id) 8): return 参数错误user_id 必须是 8 位纯数字字符串例如 00123456。请重新生成参数后重试。 data fetch_from_store(user_id) if data is None: return f未找到 user_id{user_id} 对应的用户请确认 ID 是否正确或改用其他查询方式。 return format_brief(data)注意错误信息里的三个要素说清错在哪、给出正确格式示例、提示下一步怎么做。只写参数错误四个字模型的修正成功率会低很多。3.3 工具数量膨胀之后分组和懒加载怎么落地工具从 3 个涨到 30 个时你会遇到一个很典型的现象模型开始选错工具。不是它笨是候选太多、描述之间边界模糊。我的处理办法分两步。第一步是按场景分组比如查询类操作类计算类每组只暴露给对应的子任务。第二步是懒加载主循环只挂载少量高频工具其余工具通过一个检索工具按需取用tool(namefind_tool, description当现有工具无法完成任务时用一句话描述你需要的能力返回可用工具列表。) def find_tool(need: str) - str: matched registry.search(need, top_k3) if not matched: return 没有找到匹配的工具请尝试换个说法描述你的需求。 return \n.join(f- {t.name}: {t.description} for t in matched)这套做法的代价是多一轮调用但换来的是选择准确率明显提升。工具数超过 15 个时我基本都会上这个方案。3.4 危险操作必须加人工确认闸门只要工具有写操作——发消息、改数据、下单、删文件——就必须有确认环节。这不是最好有是必须。我见过一个内部工具Agent 在调试时把测试环境的配置批量改了一遍虽然可以回滚但那半天时间全废了。实现上有两种粒度。轻量做法是在工具内做二次判断把待执行动作返回给上层等人工确认后再真正执行tool(nameupdate_status, description修改工单状态。调用前会返回确认信息需人工确认后才真正生效。) def update_status(ticket_id: str, status: str) - str: if status not in {open, processing, closed}: return 参数错误status 只能是 open / processing / closed 之一。 return f[待确认] 将工单 {ticket_id} 状态改为 {status}。请人工确认后调用 confirm_action 执行。重量做法是在编排层拦截任何标记为dangerous的工具调用都先挂起走审批流再恢复。项目初期用轻量做法就够等真正上生产再上审批流。4. 上下文和记忆预算没管住后面全是白干上下文是 Agent 最稀缺的资源比 token 费用更值得关注。预算失控的表现往往不是报错而是回答质量缓慢下降——模型开始忽略中间的信息或者反复询问已经提供过的内容。4.1 上下文窗口的分配策略与实测比例我习惯把上下文按用途切成四块并给每块一个预算上限用途建议占比说明系统提示词10%角色、规则、输出格式要求工具描述15%工具越多占比越高超过 25% 要考虑懒加载历史轨迹50%每轮的动作和观察结果最容易失控留给输出25%预留给最终答案和中间推理历史轨迹这一块是重灾区。一个工具返回了 5000 字的原始数据十轮之后就积累成 5 万字直接吃掉全部预算。所以我对所有工具的返回值都做截断处理MAX_OBSERVATION_CHARS 1500 def truncate(text: str, limit: int MAX_OBSERVATION_CHARS) - str: if len(text) limit: return text head text[: int(limit * 0.7)] tail text[-int(limit * 0.2):] return f{head}\n...[中间省略 {len(text) - limit} 字]...\n{tail}保留头尾、掐掉中间是因为关键信息往往出现在开头结构说明和结尾结论。这个截断策略我用了很久实测对最终答案质量的影响很小但上下文占用能压到原来的三分之一。4.2 短期会话记忆和长期知识的分工很多人把这两件事混为一谈结果两头都不好用。我的划分标准很简单短期记忆管理这次任务进行到哪一步了。包括已完成动作、已确认事实、待办事项。它是结构化的、有界的、随任务结束而丢弃。长期知识管理这个领域有哪些稳定事实。比如产品参数、制度条款、历史案例。它通过检索按需注入不进主上下文。短期记忆我倾向于用一个显式的状态对象维护而不是靠模型从长对话里自己回忆{ confirmed: {order_id: 20240115001, amount: 328.5}, pending: [确认收货地址, 生成对账单], done: [查询订单, 核对金额] }每轮把这个状态序列化后放进上下文模型对现在该干什么的判断会稳定得多。我做过对比同样是十轮任务有显式状态的完成率明显高于纯对话历史。4.3 裁剪、摘要、检索三种压缩手段怎么选上下文快满时的处理方式有三种适用场景完全不同裁剪最简单直接丢掉最早的几轮对话。适合任务步骤之间弱相关的场景比如批量处理一批独立条目。缺点是会丢掉早期确认的关键约束。摘要是把早期轨迹用模型压缩成一段话。适合长流程但信息密度不均的任务。缺点是摘要本身要花一次调用而且有信息损耗。我的经验是每积累 8 到 10 轮做一次摘要把结果写回轨迹开头。检索是把完整轨迹存到外部只在需要时按关键词取回相关片段。适合超长任务或需要回溯历史的情况。实现成本最高但信息保留最完整。我的默认组合是优先裁剪任务涉及多轮依赖时切成摘要单次任务超过 40 轮再上检索。不要一上来就上最复杂的那套维护成本会压垮你。5. 多步任务跑不稳按这条链路往下查Agent 出问题时最忌讳的是一上来就改提示词。改提示词属于盲调改十次有九次是碰运气。下面这条排查链路是我反复用过、能稳定定位问题的方法。5.1 循环停不下来和反复调用特征其实很好认死循环有两种典型表现看轨迹就能区分第一种是同一个工具、同样的参数被调用多轮。这几乎一定是工具返回值让模型误以为没成功。比如工具返回了空字符串模型会以为调用失败于是重试。解决办法是让工具的返回永远有明确语义哪怕是查询结果为空也要写成一句完整的话。第二种是在两个工具之间来回跳A 的结果触发 BB 的结果又触发 A。这通常是任务分解逻辑有歧义或者两个工具的职责边界重叠。解决办法是把其中一个合并或删掉然后用提示词明确拿到 X 之后不要再调用 Y。第三种更隐蔽每轮参数都有微小变化永远不收敛。常见于带分页或时间范围的工具模型不断缩小范围试图查全。这类问题要在工具层面加限制比如明确告诉它一次最多返回 20 条不需要翻页。5.2 从执行轨迹里定位失败节点定位失败节点有个笨办法但极其有效从后往前找第一个看起来不对的观察结果。具体操作是把轨迹按轮次打印出来只显示动作名、参数摘要、观察结果前 200 字。然后从最终答案开始往前扫找到第一个这一步的结果和预期不符的位置。它后面的所有内容基本都可以忽略因为都是基于错误信息推出来的。我通常会在排查脚本里加一段辅助输出def dump_trace(trace, max_obs: int 200): for step in trace: args str(step.arguments) obs str(step.observation) flag 关注 if obs.startswith(错误) or len(obs) 10 else print(f[{step.index:02d}] {step.action} {args[:120]}) print(f - {obs[:max_obs]}{flag})先把所有以错误开头、或者短得异常的观察结果高亮出来八成问题就在这几行里。5.3 结构化输出解析失败四种原因按概率排让 Agent 输出 JSON 是常见需求解析失败也极其常见。按我遇到的频率排序第一位模型在 JSON 外面包了一层说明文字。比如好的结果如下{...}。这不是模型的错是提示词没写死。解决办法是在系统提示里明确只输出 JSON不要任何解释、不要代码块标记。第二位字段缺失或拼写不一致。模型可能把user_id写成userId。解决办法是在提示词里给出完整的字段清单和示例并在解析前做一次键名标准化。第三位数值类型变成了字符串。比如金额328.5变成328.5。这个在解析后做一次类型转换就能兜住。第四位JSON 本身语法错误。长输出时偶发通常表现为尾部截断。解决办法是留足输出 token 预算或者改用更小的输出结构分步生成。import json, re def parse_json_safely(text: str): text text.strip() text re.sub(r^(?:json)?|$, , text, flagsre.MULTILINE).strip() start, end text.find({), text.rfind(}) if start -1 or end -1: return None try: return json.loads(text[start : end 1]) except json.JSONDecodeError: return None这个函数不优雅但能兜住绝大多数脏输出。解析失败时一定要让上层知道而不是返回空字典假装成功——静默失败是 Agent 系统里最难查的 bug 类型。5.4 给自己留一个最小复现用例每次修完一个 bug我都会把触发它的那条输入存成一个固定用例跑在回归脚本里。Agent 系统有个讨厌的特性修 A 场景可能把 B 场景弄坏因为两者共享同一段提示词或同一个工具。我的回归集现在有二十来条每条只包含输入 期望的关键行为不比对完整输出因为模型输出有波动只检查三件事是否调用了预期工具、是否在预期轮数内收敛、最终答案是否包含关键字段。跑一遍不到两分钟能拦掉大部分回归问题。6. 成本、延迟和可观测性上生产前的最后一道关本地跑得欢一上量就发现账单失控或者响应慢到没法用这是 Agent 项目最常见的翻车姿势。6.1 记一本 token 账按阶段拆开看总 token 数没什么参考价值关键是要拆开看系统提示词占多少、工具描述占多少、历史轨迹占多少、输出占多少。我见过一个案例工具描述占了总消耗的四成——因为有人给每个工具写了三百字描述挂了二十个工具。简单的记账方式是在每轮调用后记录一次import time class TokenLedger: def __init__(self): self.records [] def add(self, stage: str, prompt_tokens: int, completion_tokens: int, cost: float): self.records.append({ stage: stage, prompt: prompt_tokens, completion: completion_tokens, cost: cost, ts: time.time(), }) def summary(self): agg {} for r in self.records: s agg.setdefault(r[stage], {prompt: 0, completion: 0, cost: 0.0}) s[prompt] r[prompt] s[completion] r[completion] s[cost] r[cost] return agg跑几十个真实任务之后看这份汇总你会清楚地知道钱花在哪。我的经验是历史轨迹通常是最大头其次是工具描述这两个也恰好是最容易优化的两块。6.2 并发和超时的参数怎么定超时设置要分两层单次模型调用超时和整个任务超时。前者的经验值是 30 到 60 秒后者按任务复杂度给 120 到 300 秒。只设单次超时是不够的因为一个任务可能由十次正常调用组成加起来早就超了业务能忍的时长。并发方面Agent 任务大多是 IO 密集型的适度并发能显著提升吞吐但要注意两点一是模型服务方通常有速率限制并发数设太高会大量触发限流重试反而更慢二是工具如果有共享资源数据库连接、外部接口配额并发会放大冲突。我一般从并发 5 开始压测逐步往上加观察两个指标平均任务耗时和限流重试比例。重试比例超过 5% 就说明并发给高了。import asyncio sem asyncio.Semaphore(5) async def run_one(task_input: str): async with sem: try: return await asyncio.wait_for(agent.run_async(task_input), timeout180) except asyncio.TimeoutError: return {status: timeout, input: task_input}Semaphore加在任务粒度而不是调用粒度这样单个任务内部的多次模型调用不会互相抢名额。6.3 上生产前必须补齐的埋点本地调试靠 print上生产必须靠结构化埋点。我认为最低限度要有这四类埋点用途关键字段任务级统计成功率、耗时分布task_id、状态、总轮数、总耗时轮次级定位哪一步开始偏step_index、动作、参数、观察长度工具级发现哪个工具最不稳工具名、调用次数、错误率、平均返回长度成本级控制预算分阶段 token、单任务成本有一个字段特别容易被忽略观察结果的长度。它和上下文爆掉高度相关一旦某个工具的平均返回长度突然从 500 涨到 5000说明上游数据格式变了上下文预算很快会出问题。这个指标比错误率更早发出预警。再补一个实践中的小技巧给每个任务生成一个短的追踪 ID把它写进所有日志和工具调用的元信息里。出问题时用这一个 ID 就能串起整条链路比按时间戳去猜要快得多。这个习惯我在第三个 Agent 项目才开始养成之后每次排查故障的时间至少缩短一半。最后分享一个我觉得最值钱的体会Agent 的稳定性不是调出来的是设计出来的。工具契约清晰、状态显式维护、预算提前切好这三件事做到位你会发现需要调提示词的场景少了一大半。反过来如果地基没打好再怎么在提示词里加请仔细思考务必检查效果都很有限——模型看不到你的函数实现它能依靠的只有你给它的那点信息。