Hermes Agent自主执行循环：工具调用、上下文与熔断

装完 Hermes Agent 的第一件事我一般不会是跑官方 demo而是先把它的循环日志打开看一次完整任务里它到底调了几次工具、每次拿到什么返回值。这个习惯是被坑出来的——早期我以为它只是个套了壳的对话命令行结果它自作主张地改了三个文件、重跑了两次同一个命令最后给我一份看起来像模像样但事实全错的总结。从那以后我明白Hermes Agent 本质是一个「带预算的自主执行循环」模型只负责决策真正决定成败的是工具描述、上下文管理和熔断策略这三件脏活。这篇内容就是围绕这三件脏活展开的。它面向的是已经把 Hermes Agent 拉起来、但跑复杂任务时经常翻车的同学也适合还在犹豫要不要把它接进自己工作流的从业者。下面我会把项目结构、配置项、工具注册、任务循环、上下文压缩、失败重试、排查套路全部拆开讲每一处都尽量给到可以直接抄的参数和代码并且说明我为什么这么选。1. 先把 Hermes Agent 拆开看它到底在管什么1.1 三层结构模型、工具、循环缺一层都跑不起来很多人上手 Hermes Agent 时把它当成更聪明的命令行于是把所有期待压在模型身上配置里只改一个模型名就开始跑长任务。跑两天就会发现两个极端简单任务它绕远路复杂任务它提前收工。根子在于没看清它其实是三层结构而且能力上限由最弱的那层决定。第一层是决策层也就是背后那个支持结构化函数调用的模型。它只输出下一步该调用哪个工具、参数是什么不直接接触文件系统和网络。第二层是工具层你自己注册的那些函数读文件、查数据库、发请求、跑脚本都算它们是智能体唯一能真正改变世界的手。第三层是循环层负责把模型的决策翻译成真实的函数调用、把返回值塞回上下文、判断是否该继续、是否超预算、是否该熔断。我见过最多的错误是把三层混在一起在提示词里写一大堆你可以读文件、可以查询、可以修改却没有注册对应的工具。模型会一本正经地在回复里模拟执行过程输出一段我已读取配置文件发现第 12 行有问题——而实际上它什么也没读。这种幻觉在 Hermes Agent 上尤其常见因为它对工具调用的服从度很高你给它描述却忘了给实现它就会用语言把缺口补上。反过来也有一类问题工具注册了十几个但循环层的max_steps设成了 50模型又缺少任务已完成的明确信号它会在工具之间来回试探把预算烧光。所以我的做法是先把三层各自的边界在配置里写死再谈优化。循环层管预算和终止工具层管能力边界决策层只管在当前可见的上下文里挑下一步。提示判断一个 Hermes Agent 配置是否健康最快的办法是看一次任务的日志里模型决策次数和工具实际执行次数是否接近。如果前者远大于后者说明提示词里的工具描述和真实注册的工具对不上。1.2 为什么走工具调用优先而不是堆提示词早期做类似功能常见路径是把所有能力写进一段超长提示词让模型输出特定格式的文本再用正则去解析。这套办法能跑但维护成本极高你改一个字模型输出的格式就可能跟着变解析失败时你拿不到结构化错误只能靠肉眼比对更麻烦的是没法做参数校验模型给你一个不存在的文件路径程序照样执行。Hermes Agent 走的是结构化函数调用这条路工具以 schema 的形式声明模型返回的是带参数名的结构化结果。这条路的好处有三个我在实际项目里都吃到过红利。第一个是可校验。参数在进入你的函数之前就能被 schema 拦一道类型不对、必填缺失、枚举越界直接返回错误给模型它会自己纠正。我在一个批量配置检查任务里统计过加了 schema 校验之后因为参数格式错误导致的失败从 23% 降到 4% 左右。第二个是可观测。每次调用都有明确的工具名和参数对象日志里一眼能看出它想干什么。排查问题时不用再猜这段自然语言到底对应哪个动作。第三个是可收敛。工具集合是有限的模型的选择空间被压缩行为方差明显变小。这点在做需要重复执行的定时任务时特别关键——你需要它每次都走同一条路而不是今天用方法 A、明天用方法 B。代价也有你得写 schema得维护工具描述得处理工具返回值的序列化。但这部分工作量是一次性的而提示词解析的维护是持续的。我的判断标准很简单——如果这个任务你需要跑超过十次就值得走工具调用如果只是一次性实验随手写个脚本更快。1.3 部署形态怎么选一次性脚本、常驻服务还是容器Hermes Agent 本身不限制部署形态但不同形态对配置的要求差别很大。我按实际使用场景整理了一张对照表这张表帮我省了不少返工。形态适合场景关键配置差异主要风险一次性命令行脚本单次批处理、离线整理、临时分析max_steps可设小8~15日志直接打到终端中断后无断点长任务重跑成本高常驻后台服务定时巡检、消息触发、多用户共用必须限制单任务预算和并发数工具白名单要收窄一个失控任务拖垮整个进程容器化运行需要文件隔离、需要可复现环境沙箱根目录挂载、工具只暴露容器内路径挂载点写错导致读到宿主机敏感目录我自己的主力形态是容器化的常驻服务加一个命令行入口。容器负责隔离命令行入口负责调试。这里有个细节值得说容器里跑的时候工具层拿到的路径必须是容器内路径而你在提示词或配置里写的往往是宿主机路径两者不一致会导致文件明明存在却读不到的怪问题。我的处理办法是在配置里统一用一个sandbox_root变量所有工具内部都先做一次路径归一化把外部传入的路径强制拼到这个根目录下再判断是否存在。另外常驻形态下一定要给单任务加时间预算。我吃过一次亏一个任务因为工具一直返回文件不存在模型不断换路径重试循环层没有时间上限硬是跑了四十多分钟把并发槽位全占了。后来我加了step_budget_seconds超时直接把当前上下文打包落盘并终止第二天再人工看。2. 环境准备与首次跑通把地基打平2.1 依赖与目录约定先定规矩再写代码Hermes Agent 的依赖本身不复杂一个能跑模型的推理端、一份 Python 环境、几个常用的序列化库就够。真正容易出问题的是目录约定——如果你让工具随意读写当前工作目录跑上几次之后你就分不清哪个文件是原始输入、哪个是中间产物、哪个是被改坏的版本。我固定的目录结构是这样几乎每个项目都照抄hermes-agent/ ├── config/ │ └── agent.yaml # 主配置模型、预算、白名单 ├── prompts/ │ └── system.md # 系统提示词单独文件便于版本管理 ├── tools/ │ ├── __init__.py # 工具注册入口 │ ├── fs_tools.py # 文件类工具 │ └── report_tools.py # 业务类工具 ├── runs/ │ └── 20250101-093000/ # 每次运行一个时间戳目录 │ ├── trace.jsonl # 逐步决策与工具调用记录 │ ├── artifacts/ # 中间产物 │ └── result.md # 最终输出 └── logs/ └── agent.log # 进程级日志为什么强调runs按时间戳分目录因为 Hermes Agent 的调试几乎全靠回溯。出了问题你要能拿到那一次运行的完整轨迹模型在什么上下文下做了什么决策、工具返回了什么、下一步为什么那么走。如果所有运行都往同一个日志文件里写几百次之后这份日志就没法看了。按时间戳切分之后排查就变成找到那次运行、打开 trace、从后往前看最后三步这么简单。prompts/system.md单独拆出来也是同样道理。系统提示词是智能体行为的最大变量改一个字可能整个行为就变了。放在配置文件里内联你很难做版本对比单独成文件配合版本管理工具你可以清楚地看到上周三改了什么导致任务完成率掉了。2.2 配置文件逐项说明每个参数都说清为什么下面这份配置是我在多个项目里收敛出来的版本字段不多但每一项都有明确用途。model: endpoint: http://127.0.0.1:8000/v1 # 本地推理端地址 name: hermes-agent-default temperature: 0.2 # 决策类任务压低随机性 max_tokens: 2048 loop: max_steps: 20 # 单任务最多决策轮数 step_budget_seconds: 180 # 单任务墙钟上限 max_tool_calls_per_step: 3 # 一轮内允许并行调用的工具数 repeated_action_limit: 2 # 同一动作重复上限超过即熔断 tools: whitelist: - read_file - list_dir - grep_text - write_report sandbox_root: /workspace/sandbox allow_write_paths: - /workspace/sandbox/output memory: mode: summary # 上下文压缩策略 max_context_tokens: 24000 keep_recent_steps: 4 # 保留最近几步原文不压缩 logging: level: info trace_path: ./runs几个参数值得单独解释。temperature我一般压到 0.2 甚至 0.1因为智能体任务的核心是稳定复现不是创意。你要的是它每次都选对工具而不是偶尔灵光一现。有人担心温度太低会让模型钻牛角尖反复走同一条错路——这个问题靠repeated_action_limit解决不靠提高温度。max_steps的设定有讲究。太小任务做不完太大一旦模型陷入循环你要等很久才发现。我的经验值是按任务复杂度分档单文件分析 8~12多文件汇总 15~20需要多轮验证的流程 25~30。超过 30 步还没收敛基本可以判断是提示词或工具描述有问题加预算没用。repeated_action_limit是我后加的效果立竿见影。实现方式很简单把工具名 规范化参数做一次哈希同一个哈希连续出现超过阈值就直接终止并报告。这项机制拦住过一次事故——模型因为一个路径拼写错误连续七次用同样的参数调read_file如果没有这层限制它会一直试到预算耗尽。注意allow_write_paths是白名单不是黑名单只写你要允许的目录。用黑名单模式排除某些路径在实际项目里非常危险因为模型会构造出你没预料到的路径变体。2.3 最小可运行示例先跑通再谈优化跑通 Hermes Agent 的最小闭环代码量其实很少。核心就是注册一个工具、构造一次对话、拿到函数调用、执行、把结果塞回去、再问一轮。import json from hermes_agent import Agent, tool tool( nameread_file, description读取沙箱内指定文本文件的内容返回前 4000 字符。路径必须是相对沙箱根目录的相对路径。, parameters{ type: object, properties: { path: {type: string, description: 相对沙箱根目录的文件路径例如 notes/a.md}, max_chars: {type: integer, default: 4000, minimum: 200, maximum: 8000} }, required: [path] } ) def read_file(path: str, max_chars: int 4000) - dict: import os root /workspace/sandbox real os.path.realpath(os.path.join(root, path)) if not real.startswith(os.path.realpath(root)): return {ok: False, error: path_out_of_sandbox, hint: 请使用沙箱内相对路径} if not os.path.isfile(real): return {ok: False, error: file_not_found, hint: 先用 list_dir 确认文件是否存在} with open(real, r, encodingutf-8) as f: content f.read(max_chars) return {ok: True, path: path, content: content, truncated: len(content) max_chars} agent Agent(config./config/agent.yaml, tools[read_file]) trace agent.run(读一下 notes 目录下最新的笔记总结三条要点) print(json.dumps(trace.steps, ensure_asciiFalse, indent2))这段代码里最值钱的不是那几行读取逻辑而是两个错误返回。path_out_of_sandbox和file_not_found都带了hint字段这个字段是给模型看的不是给你看的。带上提示之后模型在下一步大概率会去调list_dir而不是继续瞎猜路径。我做过对比加上hint之后路径类问题导致的无效步数减少了六成左右。还有一个细节返回值统一用{ok: bool, ...}结构。不要让有的工具返回字符串、有的返回对象、有的直接抛异常。统一的返回结构让模型更容易判断成功与失败也让你的日志可以被程序化统计。2.4 首次运行的自检清单五件事全部过一遍第一次跑通之后别急着上复杂任务先把这五项过一遍。这张清单帮我省过很多后续的糊涂账。检查项怎么验证不通过的典型表现工具是否真的被调用在工具函数里打一行日志模型说我已读取但日志无记录沙箱路径是否生效故意传../etc/hosts试一次返回了内容而不是拒绝循环是否有上限给一个不可能完成的任务跑了几十步还在继续轨迹是否落盘去runs/时间戳/看文件目录为空或只有一行上下文是否会超限连续做十轮长对话中途报错或输出变成乱码第三项特别值得单独试一次。给 Hermes Agent 一个它绝对完不成的任务比如把不存在的文件 a.md 改写成 b.md然后观察它会不会在预算内干净地停下来并报告失败。一个健康的配置应该在三到五步内放弃并给出原因而不是无限重试。这项测试我每次都做因为它直接暴露循环层的熔断是否生效。3. 工具注册与函数描述整个系统最容易翻车的地方3.1 工具描述怎么写模型才不选错同样一个读取文件的工具描述写得好不好使用准确率能差出三倍。我做过一组对照实验用同一批二十个任务只改描述结果差别非常明显。描述写法任务成功率典型误用读取文件62%传给目录路径、传绝对路径、读二进制文件读取沙箱内指定文本文件的内容返回前 4000 字符。路径必须是相对沙箱根目录的相对路径。89%偶尔传超长路径差距来自哪里来自描述里把边界和返回形态都写清楚了。读取文件这四个字没有告诉模型任何约束它只能猜。而第二版明确说了三件事读的是文本不是二进制、路径是相对的、返回有长度限制。模型在决策时就有了判断依据。我的描述模板固定为四段一句话用途、明确的输入边界、返回内容说明、失败时的建议动作。这四段加起来通常不超过一百字但能覆盖绝大多数误用。{ name: grep_text, description: 在沙箱内按关键词搜索文本文件返回匹配行的文件路径与行号最多返回 50 条。适合在不确定文件位置时先定位再读取。, parameters: { type: object, properties: { keyword: {type: string, description: 要搜索的关键词区分大小写不支持正则}, scope: {type: string, description: 搜索范围相对沙箱根目录的目录路径例如 notes留空表示整个沙箱}, limit: {type: integer, default: 50, minimum: 1, maximum: 200} }, required: [keyword] } }注意我在描述里强调了适合在不确定文件位置时先定位再读取。这句话是在引导模型的工作顺序先搜后读而不是一上来就猜路径。类似的行为引导写进工具描述比写在系统提示词里更有效因为它在模型最需要做选择的那一刻出现在上下文里。3.2 参数校验与返回值设计把错误挡在业务逻辑之外Hermes Agent 把工具参数交到你手上时schema 层面能挡掉一部分问题但业务层面的校验还是得自己做。我把校验分成三道防线。第一道是 schema 层。类型、必填、枚举、数值范围都在这里声明。这一层能拦住大部分格式错误而且拦截后模型能拿到结构化的错误信息通常会自己改正。第二道是路径与权限校验。所有涉及文件系统的工具第一件事都是路径归一化加白名单比对。这段代码我写成了一个公共函数每个工具开头调一次绝不省略。实现要点是用真实路径解析掉符号链接之后做前缀比对而不是简单字符串匹配否则output/../secret这类路径会绕过去。第三道是业务语义校验。比如写入报告这个工具要求目标文件必须在output目录下且扩展名必须是.md内容长度不能为 0。这类校验看起来琐碎但它把模型可能做出的荒唐决定压缩到了一个可接受的范围里。返回值的设计同样重要。我坚持三条规矩永远返回对象不返回裸字符串失败时给机器可读的错误码加人类可读的提示成功时也给出足够的上下文让模型判断下一步。举个例子list_dir成功时不只返回文件名列表还返回文件大小和修改时间的简要信息。这些信息能让模型在下一步直接决定读哪个文件省掉一次额外的查询。提示工具返回值里不要塞超过必要的信息。我见过有人在工具里把整个文件内容返回一次就把上下文撑爆了。返回内容要有限额超长的部分截断并标记truncated: true让模型自己决定要不要分段读。3.3 危险操作的隔离与白名单先假设它会出错写工具的默认心态应该是模型一定会用最离谱的方式调用它。基于这个假设我给所有工具做了分级。只读类读文件、列目录、搜索、查询数据库的只读视图。这类工具放开一点没关系出问题顶多是读了不该读的东西用沙箱兜住就行。写入类写文件、追加内容、生成报告。这类必须限定目标目录而且我倾向于让它写新文件而不是改旧文件。改旧文件的风险在于一旦改错原始内容就没了。如果确实需要修改我会让工具先写一个.bak副本。执行类跑脚本、执行命令。这类我原则上不在通用智能体里开放。真有需要也是包装成跑某个固定脚本、参数只能是白名单里的枚举值而不是开放任意命令执行。这个决定不是过度谨慎而是因为一个开放的命令执行工具等于把整个环境交给了模型的判断而模型是会犯错的。外部请求类调用接口、抓取数据。这类要限制目标地址范围并且设置超时和响应体大小上限。没有超时的请求工具一旦对方不响应整个任务就卡在那里白白烧掉时间预算。这套分级的实际价值在于它让你在配置里可以按任务类型动态调整工具集。做只读分析任务时白名单里只有只读工具模型就算想写也写不了。这种能力按需开放的思路比事后审查可靠得多。3.4 一个可复用的工具模板照抄改改就能用把前面这些规矩落到代码上我形成了一个固定模板。新加工具时直接复制把中间的业务逻辑换掉其余部分基本不动。import os from hermes_agent import tool SANDBOX os.path.realpath(/workspace/sandbox) ALLOW_WRITE [os.path.realpath(/workspace/sandbox/output)] def _resolve(path: str): 把外部路径归一化到沙箱内越界直接返回 None real os.path.realpath(os.path.join(SANDBOX, path)) if not real.startswith(SANDBOX os.sep) and real ! SANDBOX: return None return real tool( namewrite_report, description把整理好的内容写入 output 目录下的 Markdown 报告。目标文件不存在时新建已存在时覆盖。内容为空会拒绝写入。, parameters{ type: object, properties: { filename: {type: string, description: 文件名必须以 .md 结尾例如 weekly.md}, content: {type: string, description: 报告正文Markdown 格式长度 1 到 20000 字符} }, required: [filename, content] } ) def write_report(filename: str, content: str) - dict: if not filename.endswith(.md): return {ok: False, error: bad_extension, hint: 文件名必须以 .md 结尾} if not content or len(content) 20000: return {ok: False, error: bad_length, hint: 内容长度需在 1 到 20000 字符之间} target _resolve(os.path.join(output, filename)) if target is None: return {ok: False, error: path_out_of_sandbox, hint: 只能写入 output 目录} if not any(target.startswith(p os.sep) for p in ALLOW_WRITE): return {ok: False, error: write_not_allowed, hint: 目标目录不在写入白名单内} os.makedirs(os.path.dirname(target), exist_okTrue) with open(target, w, encodingutf-8) as f: f.write(content) return {ok: True, path: os.path.relpath(target, SANDBOX), bytes: len(content.encode(utf-8))}这个模板里我特意保留了三个设计路径解析函数独立出来方便复用、所有失败都返回带hint的结构、成功时返回写入字节数。最后这个细节是为了让模型能校验自己的操作结果——如果它写了但返回的字节数是 0它就知道出了问题。4. 任务循环与上下文管理决定它能跑多远4.1 单轮与多轮之间怎么判断该让它自己决定步数Hermes Agent 支持两种典型使用方式。一种是你把任务拆好一次只让它做一步下一轮由你的程序决定。另一种是给它一个目标让它自己在循环里决定走多少步。前者可控后者省事选择标准在于任务的可预测性。任务路径明确时用单轮。比如把这三个文件的内容合并成一份——步骤是固定的你自己写循环比让模型决定更省 token 也更可靠。这种情况下 Hermes Agent 的价值在于每一步的语言理解和格式转换不在于路径规划。任务路径不确定时用多轮自主循环。比如检查这批配置有没有问题能修的直接修不能修的列出来。模型可能先列目录、再逐个读、发现问题后改写、最后汇总。路径是它在过程中逐步确定的你事先写不出来。多轮模式下最关键的参数不是max_steps而是终止信号的清晰度。我给每个任务都会在提示词里写明什么情况下算完成。比如当你已经写出报告并且报告里包含三个小节时任务结束不要再调用任何工具。这句话能显著减少做完了还继续折腾的情况。还有一个实用技巧在多轮循环里给模型一个显式的finish工具。它的作用就是我干完了这是结论。相比让模型用自然语言说任务完成一个专门的终止工具让循环层的判断变成确定性的——看到这个工具被调用就停不用去解析文本。这个改动看似微小但在我实测中把平均步数压低了约 15%。4.2 上下文压缩与记忆落盘别让历史把窗口撑爆Hermes Agent 跑长任务时上下文增长得非常快。一个工具返回值动辄上千字符十几步之后窗口就满了。撑爆的表现不是报错而是更隐蔽的——模型开始忘记前面的约束重复做已经做过的事或者把两次不同文件的内容混在一起。我的压缩策略是分级处理不同内容用不同方式对待。内容类型处理方式理由系统提示词与约束永不压缩放最前约束一旦丢失行为立刻跑偏最近 3~5 步的完整交互保留原文模型需要精确的近期上下文做决策更早的工具返回值摘要为一句结论 引用路径具体内容可以重新读结论不能丢用户的原始目标永不压缩周期性重述防止模型跑偏到自己发明的新目标上具体的压缩动作我在达到窗口的 70% 时触发而不是等到 95%。留出 30% 的余量很关键因为压缩本身也需要消耗 token而且压缩之后紧接着的那次工具调用可能返回一个很大的结果需要缓冲空间。压缩时我会把被压掉的内容落盘。runs/时间戳/artifacts/目录下存一个context-archive.jsonl每条记录包含步数、工具名、完整返回值。然后在压缩后的上下文里保留一行引用第 6 步读取 notes/a.md 的完整内容已归档可用 read_file 重新获取。这样模型如果真的需要细节它知道去哪里拿而不是凭空瞎编。注意压缩摘要尽量用抽取式而不是生成式。让模型总结一下刚才读了什么很容易引入事实错误一旦错误结论进入上下文后续所有决策都建立在错误基础上。我倾向于用固定模板截取关键字段宁可粗糙也不虚构。4.3 失败重试与熔断把失控变成一个可检测的状态Hermes Agent 的失败模式其实不多但每一种都很耗时间。我总结了四类对应四种处理。参数错误型工具返回bad_parameter之类。这类重试是有意义的模型看到提示通常会改。我允许重试两次第三次还是同样的参数就直接终止。资源不存在型文件不存在、目录为空。这类重试意义不大但模型往往会换个路径再试。我给这类错误配了明确的hint先用 list_dir 确认并且在配置里限制同一工具的连续失败次数为 3。工具内部异常型你的工具代码抛异常了。这类绝不能让它自动重试因为问题在你这边重试只会重复报错。我的处理是把异常捕获后返回internal_error并立刻终止当前任务把 trace 落盘待查。循环型同一个动作重复出现。这是最隐蔽的因为它不报错只是在原地打转。用前面提到的哈希去重法可以检测出来阈值设 2 次。熔断的触发条件我设了三层任意一层命中就停步数超限、时间超限、连续重复超限。停止时不是静默退出而是生成一份未完成报告写清楚它做到哪了、卡在哪里、最后三次动作是什么。这份报告的价值在于你第二天来看的时候不需要重跑就能判断问题所在。5. 实操做一个能跑完整流程的小项目5.1 需求拆解配置巡检助手拿一个我实际做过的模拟项目来说一批散落在notes/目录下的 Markdown 配置文件格式是键: 值的简单文本需要检查几个问题——必填项是否缺失、数值是否超范围、有没有重复键。检查完之后生成一份报告能自动修的比如去掉多余空格直接修好写回不能修的列进报告。选这个题目是因为它同时包含只读操作、判断逻辑和受控写入能覆盖 Hermes Agent 的大部分典型用法而且不需要外部依赖。拆解下来是三个工具list_dir列文件、read_file读内容、write_report写报告。修改文件这一步我没做成独立工具而是让write_report支持写回指定文件名因为原始的配置文件也放在output目录下的副本里。这样做的原因是永远不要让智能体直接改原始数据。所有修改都发生在副本上人工确认后再同步回去。5.2 分步实现从工具到提示词先注册工具代码沿用前面的模板。list_dir的返回值我做的稍微丰富一点带上文件大小和行数这样模型在决定读哪个文件时能有个初筛。tool( namelist_dir, description列出沙箱内某个目录下的文件返回文件名、字节数和行数最多 100 个。用于在读取前确认有哪些文件可用。, parameters{ type: object, properties: { path: {type: string, description: 相对沙箱根目录的目录路径例如 notes} }, required: [path] } ) def list_dir(path: str) - dict: real _resolve(path) if real is None or not os.path.isdir(real): return {ok: False, error: dir_not_found, hint: 确认目录名是否正确} items [] for name in sorted(os.listdir(real))[:100]: full os.path.join(real, name) if not os.path.isfile(full): continue with open(full, r, encodingutf-8, errorsignore) as f: line_count sum(1 for _ in f) items.append({ name: name, bytes: os.path.getsize(full), lines: line_count }) return {ok: True, path: path, count: len(items), items: items}然后是系统提示词。这部分是决定行为的关键我写得比较具体把检查规则逐条列出来而不是让模型自由发挥。你是一个配置巡检助手。工作流程固定为三步 1. 用 list_dir 列出 notes 目录下的全部 .md 文件 2. 逐个用 read_file 读取按以下规则检查 - 必填键缺失timeout、retries、endpoint 三个键必须存在 - 数值越界timeout 必须在 1 到 300 之间retries 必须在 0 到 5 之间 - 重复键同一个文件内同一个键出现两次及以上 3. 用 write_report 写两份文件 - fixed/ 目录下写修复后的副本只修复多余空格这一个问题 - report.md 写检查结果按文件分组列出问题 规则不要修改原始文件只在 fixed/ 下生成副本。 所有文件检查完毕后调用 finish不要在中间停下来询问。这段提示词里有几个刻意的设计。工作流程写成固定三步减少它在路径规划上的消耗。检查规则写死具体数值避免它自己发明标准。最后一条不要停下来询问很重要因为 Hermes Agent 在没有明确指令时倾向于在中间步骤输出一段我发现了问题是否继续然后停下等回复这在批处理场景里是致命的。5.3 效果验证用四个指标判断它值不值得用跑完之后我统计了四个指标这四个指标也是我评价任何 Hermes Agent 任务的通用标准。指标含义我的及格线任务完成率完整跑完并产出可用结果的比例85% 以上平均决策步数一次任务的平均循环轮数低于预估步数的 1.5 倍工具错误率工具返回失败的比例低于 10%人工干预率需要人工修正结果的比例低于 20%第一轮跑下来完成率是 78%主要失败原因是它在某个文件里遇到格式不规范的行缺冒号卡在那里反复读同一个文件。工具错误率 12%集中在read_file的路径问题上。针对性改了两处一是给read_file的file_not_found提示里加上如果多次找不到说明该文件可能不在 notes 目录请跳过并在报告中记录二是在提示词里补了一条遇到无法解析的行记录为格式错误并继续处理下一个文件不要重试。改完第二轮完成率到了 91%工具错误率降到 6%。这个迭代过程本身就是我想强调的Hermes Agent 的调优不是改模型是改约束。你不需要换更大的模型你需要把遇到这种情况怎么办写清楚。6. 常见问题与排查实录6.1 症状对照表先定位再动手跑了这么多轮我把最常见的问题整理成了对照表。出问题时先在这里找症状能省掉大量盲猜。症状最可能的原因处理动作模型说做了但日志无记录工具没注册成功或名字对不上检查注册入口打印已注册工具列表反复读同一个文件提示里没有读不到就跳过的指令在错误返回的 hint 里加跳过建议任务做到一半停下等回复缺少不要询问、直接完成的约束系统提示词补一句明确的连续执行要求报告内容张冠李戴上下文压缩时把不同文件的信息混在一起改用抽取式压缩按文件分块归档跑到一半输出变成乱码或截断上下文超限未被检测降低触发压缩的阈值加窗口监控明明文件存在却说找不到沙箱路径与外部路径不一致检查 sandbox_root 配置统一用相对路径同样参数连续调用七八次没有重复动作熔断加哈希去重阈值设 2写入的文件是空的内容超长被截断或写入前没校验长度工具里加长度校验并返回明确错误码表格里第五行值得展开说。上下文超限最麻烦的地方在于它不报错只是让输出质量慢慢变差。我的做法是在循环层加一个监控每次调用模型前估算当前 token 数超过窗口 70% 就打一条警告日志。这条日志在排查为什么后面几步变笨了时非常有用。6.2 日志怎么读从后往前看三步Hermes Agent 的trace.jsonl是排查的核心素材每一行是一条记录模型决策、工具调用、工具返回。我的阅读顺序固定是从后往前看三步。先看最后一步。如果最后一步是模型输出了一段自然语言而不是工具调用说明它认为任务结束了——那就要判断这个结束对不对。如果最后一步是工具调用说明它是被熔断打断的去看熔断原因。再看倒数第二步和第三步。这三步连起来看基本能还原它当时在想什么。我遇到的大部分问题在这三步里就能看出来要么是它拿到的工具返回值里有误导信息要么是它连续两次做了同一件事。这里有个经验不要读完整的 trace。一份跑了二十步的 trace 可能有几万字从头读会迷失。定位问题永远是最后几步 出问题那一步这两个点中间的过程可以跳过。6.3 几条踩出来的避坑心得第一条先跑只读版本再开放写入。任何新任务我都会先用只读工具集跑一遍确认它的判断逻辑是对的再把写入工具加进白名单。这个习惯让我避免了好几次它自信地改错文件的事故。第二条给每个任务准备一组失败样本。我手里有一批故意做坏的输入缺字段的、格式乱的、空文件的、超长的。每次改完配置先用这批样本跑一遍。一个健康的配置应该能在这些输入上干净地失败并报告原因而不是卡死或瞎编。第三条温度不要为了灵活而调高。有人觉得温度低会让智能体僵化实际上智能体的灵活性应该来自工具集合和提示词的覆盖度不是来自随机性。我所有生产配置的温度都在 0.3 以下。第四条接受它做不完。这是心态问题但很实际。我现在给每个任务都设了明确的未完成也算合格的判定——只要它能准确报告卡在哪里这份输出就是有价值的。相反一个把所有任务都成功完成但结论可疑的配置才是真正危险的。第五条把提示词当代码管理。每次改系统提示词我都记一笔改了什么、为什么改、之后哪项指标变了。这条记录在三个月后回看时价值极高因为智能体的行为变化往往是缓慢的没有记录你根本察觉不到是哪次改动引入的退化。最后分享一个我最近常用的小技巧在系统提示词末尾加一句如果你不确定某个判断把不确定性明确写进输出不要猜。这句话让输出里多了一些此处不确定的标注看起来不够漂亮但人工复核的效率提高了很多——我可以直接跳到那几处去看而不是通读全文。这个内容后续还能往几个方向扩一是把工具集做成插件式的按任务类型动态加载二是给循环层加一个预算预估机制在任务开始前先估算需要多少步超预估就提前警告三是把 trace 做成可视化回放那样排查效率还能再上一个台阶。这几个我都还在试等有稳定结论了再拿出来聊。