Hermes Agent Loop 深度解析：一次请求如何变成可执行的多轮智能体

如果把 Hermes Agent 看成一个产品，它包含 CLI、TUI、Gateway、Cron、ACP、插件、Skills、Memory、MCP、浏览器和多平台消息接入。

但如果把它压缩到最小内核，真正决定“它是不是一个 Agent”的，是run_agent.py里的AIAgent.run_conversation()。

这个函数做的不是简单的“把用户输入发给模型，然后返回文本”。它负责把一个用户请求变成一个可中断、可调用工具、可恢复、可压缩、可切换模型、可持久化的多轮执行循环。

一句话概括：

Hermes 的 Agent Loop 是一个围绕 OpenAI-style message history 构建的执行状态机：每一轮先构造稳定 prompt 和 API request，再调用模型；如果模型返回 tool calls，就执行工具并把结果写回 messages；如果返回文本，就结束 turn、持久化、触发插件与后处理。

1. 入口：chat()只是薄封装，核心是run_conversation()

Hermes 对外可以暴露很多入口：

• CLI 里的普通对话
• Gateway 收到 Telegram、Slack、WeChat、WhatsApp 等消息
• Cron 定时任务
• ACP 编辑器集成
• 子 Agent delegation
• 程序化 API 调用

但进入核心执行时，都会收敛到AIAgent的会话循环。

chat()只是一个便利方法，真正返回完整结构的是run_conversation()：

python result = agent.run_conversation( user_message="Fix the bug in main.py", system_message=None, conversation_history=None, task_id="task_abc123", )

它返回的不是单纯字符串，而是一组执行元数据：

python { "final_response": "...", "last_reasoning": "...", "messages": [...], "api_calls": 3, "completed": True, "turn_exit_reason": "text_response(finish_reason=stop)", "model": "...", "provider": "...", "input_tokens": ..., "output_tokens": ..., }

这很关键。Hermes 把一次对话 turn 当成“可审计的执行过程”，而不是一次不可见的模型调用。

2. Turn 初始化：每次请求先重建运行时边界

run_conversation()一开始做了很多看似琐碎但非常关键的初始化。

它会：

• 安装安全 stdout/stderr 包装，避免 daemon/headless 模式下输出管道异常导致崩溃
• 确保 SQLite session 已创建
• 设置当前 provider/model 给 auxiliary client
• 给当前线程绑定 session id，方便日志过滤
• 绑定 skill 写入来源，区分前台用户 turn 和后台 self-improvement review
• 如果上一轮触发 fallback，下一轮先恢复 primary runtime
• 清理非法 surrogate 字符，避免 JSON 序列化或 SDK 编码崩溃
• 生成或继承task_id，用于隔离 terminal/browser 等工具环境
• 重置本 turn 的 retry counter、tool guardrail、stream scrubber、interrupt 状态

这一步的设计意图是：每个用户 turn 都是新的执行事务，但它复用 session 级别的上下文和 prompt cache。

所以 Hermes 在 turn 开始时既会清理“本轮执行状态”，也会保留“跨 turn 的长期状态”。

典型保留项包括：

• session id
• cached system prompt
• memory / skills nudge counters
• conversation history
• provider/model 配置
• SQLite session 记录

典型重置项包括：

• 本轮 retry 次数
• 本轮 tool guardrail 状态
• 本轮 stream buffer
• 本轮文件修改失败记录
• 本轮 interrupt 线程信号
• 本轮 API call counter

3. Message History：Hermes 内部统一使用 OpenAI 风格消息

Hermes 支持多种 provider 和 API mode：

但在 Agent Loop 内部，Hermes 尽量维持一种统一消息形态：

python {"role": "user", "content": "..."} {"role": "assistant", "content": "...", "tool_calls": [...]} {"role": "tool", "tool_call_id": "...", "name": "...", "content": "..."}

这带来两个好处。

第一，工具循环可以和 provider 解耦。模型是否来自 Anthropic、OpenAI、Gemini、Bedrock，并不改变 Hermes 内部“assistant tool_calls -> tool result -> next API call”的结构。

第二，session persistence 可以稳定。Hermes 可以把同一种消息结构写入 SQLite，再在下一轮按 provider 需要转换出去。

转换发生在 transport 层：

• agent/transports/chat_completions.py
• agent/transports/anthropic.py
• agent/transports/codex.py
• agent/transports/bedrock.py

ProviderTransport抽象了三件事：

python convert_messages() convert_tools() normalize_response()

也就是说，Agent Loop 不直接关心 Anthropic 的content blocks、Codex Responses 的input items或 Bedrock 的converseshape。它只需要拿到一个 normalized response。

4. System Prompt：会话内稳定，API call 时叠加临时层

Hermes 的 prompt 构造不是每次请求都重拼一遍。

_build_system_prompt()会调用_build_system_prompt_parts()，分成三层：

拼好以后，结果缓存在self._cached_system_prompt。

这意味着：

• 同一个 session 中不会因为 memory 写入而马上改变 system prompt
• Gateway 这种“每条消息新建 AIAgent”的路径，会优先从 session DB 读取上次保存的 system prompt
• 只有 context compression 这类会改变 session 边界的事件，才会重建 prompt

这背后的目标非常明确：保持 system prompt byte-stable，最大化上游 prompt cache / KV cache 命中。

同时，Hermes 又允许一些内容在 API call 时临时叠加：

• ephemeral_system_prompt
• prefill messages
• external memory provider 的 prefetch 结果
• pluginpre_llm_call注入的上下文

这里有一个重要边界：plugin 注入的上下文不会塞进 system prompt，而是附加到当前 turn 的 user message。

原因很直接：system prompt 是 Hermes 的稳定缓存前缀；插件上下文是 turn-scoped 信息，放进 user message 才不会破坏缓存。

5. API Request 构造：从 canonical messages 到 provider kwargs

进入主循环后，每一次 API call 都会从messages复制出一个api_messages。

这不是简单复制，而是一次“发送前修复”：

• 修复损坏的 tool call arguments
• 修复 role alternation 违规
• 给当前用户消息注入 external memory prefetch 和 plugin context
• 把 reasoning 字段复制成 provider 需要的reasoning_content
• 移除内部字段，例如finish_reason、_thinking_prefill
• 对 strict provider 清理 Codex Responses 专属字段
• 拼接 cached system prompt
• 插入 prefill messages
• 对 Anthropic 相关路径应用 prompt caching markers
• 清理 orphan tool result / missing tool result
• 删除 thinking-only assistant turn，避免 provider 拒绝
• 标准化 whitespace 和 tool arguments JSON
• 清理 surrogate 字符

这一段体现了 Agent Loop 的一个核心现实：很多模型 API 看起来都兼容 OpenAI schema，但实际容忍度完全不同。

Hermes 的策略不是在每个工具里适配 provider，而是在 API call 之前集中修复 message shape。

最终通过_build_api_kwargs(api_messages)生成 provider SDK 可接受的 kwargs。

6. 模型调用：默认走 streaming，但外部看起来还是一个普通 response

Hermes 有两个主要 API 调用路径：

• _interruptible_api_call()：非流式
• _interruptible_streaming_api_call()：流式

有意思的是，Hermes 现在倾向于默认使用 streaming，即使没有 UI/语音 consumer。

原因不是为了显示 token，而是为了健康检查。

非流式调用可能在 provider 卡住时长时间没有任何反馈；streaming 路径可以检测：

• 首个 chunk 是否迟迟不来
• SSE keep-alive 是否只有心跳没有有效数据
• 工具调用参数是否被截断
• provider 是否支持 streaming
• 用户是否中途 interrupt

流式路径内部会把 chunk 累积回一个模拟的非流式 response：

python SimpleNamespace( choices=[ SimpleNamespace( message=SimpleNamespace( role="assistant", content=full_content, tool_calls=mock_tool_calls, reasoning_content=full_reasoning, ), finish_reason=effective_finish_reason, ) ], usage=usage_obj, )

所以 Agent Loop 后续处理不用关心响应来自流式还是非流式。它只看 normalized response。

这是一个非常实用的工程设计：传输层可以复杂，但循环状态机必须稳定。

7. Tool Call 分支：assistant 消息先入历史，再执行工具

当模型返回tool_calls时，Hermes 会先构造一个 assistant message：

python { "role": "assistant", "content": "...", "reasoning": "...", "finish_reason": "tool_calls", "tool_calls": [...] }

然后把它 append 到messages。

这一点不能省。因为 OpenAI-style 工具协议要求 tool result 必须跟在对应的 assistant tool_calls 后面：

text assistant(tool_calls=[call_1, call_2]) tool(tool_call_id=call_1) tool(tool_call_id=call_2) assistant(final answer)

如果工具执行前不先写 assistant tool_call 消息，后续 replay 给 provider 时就会缺少父调用。

Hermes 在_execute_tool_calls()里决定执行方式：

• 如果只有一个工具，顺序执行
• 如果有多个工具，先判断是否可以并发
• clarify这类交互工具永远不并发
• read_file、search_files、skills_list、skill_view等只读工具可以并发
• write_file、patch这类路径相关工具，只有目标路径不重叠才可以并发
• MCP 工具只有在 server 显式 opt-in parallel 时才并发

并发路径会用ThreadPoolExecutor执行，但结果会按原始 tool_call 顺序写回 messages。

这个细节很重要：工具可以并行跑，但消息历史仍然保持 provider 期待的顺序。

8. Tool Dispatch：Agent-level tools 和 Registry tools 分层

Hermes 的工具不是直接在run_agent.py里硬编码一堆 if/else。

常规工具通过tools/registry.py自注册：

python registry.register( name="terminal", toolset="terminal", schema={...}, handler=handle_terminal, check_fn=check_terminal, )

model_tools.py在导入时会扫描tools/*.py，用 AST 找到顶层registry.register()，然后 import 对应模块。模块 import 时完成注册。

模型侧看到的 tool schema 来自：

python get_tool_definitions(enabled_toolsets, disabled_toolsets)

它会做：

• toolset 展开
• disabled toolset 扣除
• check_fn可用性过滤
• dynamic schema override
• execute_code/browser_navigate的 schema patch

工具执行则经过：

python handle_function_call(name, args, task_id, ...)

它会：

1. 根据 schema 做参数类型 coercion
2. 触发 pluginpre_tool_call，允许拦截
3. 对非 read/search 工具重置 read-loop tracker
4. 调用registry.dispatch()
5. 触发 pluginpost_tool_call
6. 触发 plugintransform_tool_result
7. 返回字符串化结果

但是有几类工具必须由 Agent Loop 直接处理：

所以AIAgent._invoke_tool()先处理 agent-level tools，再把普通工具交给handle_function_call()。

这是一种典型的分层：工具注册是开放生态，Agent-level 工具是 loop 内部状态操作。

9. 工具结果回灌：结果不是给用户看的，而是给下一次模型调用看的

工具执行完成后，Hermes 会追加：

python { "role": "tool", "name": function_name, "content": tool_result, "tool_call_id": tool_call.id, }

这条消息的第一读者不是用户，而是模型。

所以 Hermes 对 tool result 还会做一系列处理：

• 大结果可能通过maybe_persist_tool_result()落盘，只把摘要/引用放回上下文
• 多模态工具结果会转换成当前模型能接受的内容结构
• 子目录 context hints 会追加到工具结果中，提醒模型相关目录有新的上下文文件
• 每个 tool result 后可以注入/steer用户指导
• 文件修改类工具失败会被记录，最后在 assistant response 里追加提醒，防止模型过度宣称“已完成”

工具结果写入后，Agent Loop 不结束，而是continue。

下一次 API call 会把新的messages发给模型。模型读到 tool result 后，可能继续调用工具，也可能生成最终答案。

这就是 Agent Loop 的核心循环：

text LLM -> tool_calls -> execute tools -> append tool results -> LLM -> ...

10. Final Response 分支：没有工具调用才是真正结束

如果模型返回的是普通文本，没有 tool calls，Hermes 才进入 final response 分支。

但这个分支也不是简单返回。它会处理很多边缘情况：

• 如果流式输出已经发给用户但连接中断，使用已交付内容作为 final response
• 如果工具之后模型返回空内容，追加 synthetic user nudge，让模型继续处理工具结果
• 如果是 thinking-only response，append 这个 assistant message 再请求继续
• 如果连续空响应，尝试 fallback provider
• 如果 response 被截断，最多请求 continuation
• 如果工具调用参数被截断，拒绝执行不完整参数
• 如果 Codex 返回中间确认文本但还没做事，追加“继续执行工具”的系统级 user nudge

这说明 Hermes 没有把模型当成总是可靠的状态机。

它假设模型可能：

• 只输出 thinking，不输出可见文本
• 工具后沉默
• 工具 JSON 写一半
• 提前说“我会做”，但没有真正调用工具
• 因 context 劣化返回空
• 因 provider 问题返回 malformed response

Agent Loop 的职责就是把这些不稳定输出修正成可继续推进的执行过程。

11. Iteration Budget：限制循环，但不是粗暴中止

Hermes 默认给每个 agent 一个IterationBudget。

它的作用是限制一次 turn 内最多消耗多少模型迭代，避免工具循环无限跑下去。

关键点：

• parent agent 有自己的预算
• subagent 有独立预算
• execute_code这种程序化工具调用可以 refund，不消耗主 agent 预算
• 如果预算耗尽，Hermes 不会直接丢一个错误，而是再发一次无工具 summary request

预算耗尽时，它会追加一条用户消息：

text You've reached the maximum number of tool-calling iterations allowed. Please provide a final response summarizing what you've found and accomplished so far, without calling any more tools.

然后移除工具，让模型总结已有工作。

这比“直接失败”更适合用户体验，也更适合 Gateway/Cron 这类后台执行场景：即使没完成，也要给出当前状态。

12. Context Compression：循环过程中动态压缩，而不是等报错

Hermes 的压缩有两个触发点。

第一是 preflight compression。

当加载已有 conversation history 后，Hermes 会估算：

python estimate_request_tokens_rough( messages, system_prompt=active_system_prompt, tools=self.tools, )

如果超过 context threshold，就在第一次 API call 前先压缩。

第二是工具执行后的在线压缩。

每次工具执行完，Hermes 会根据 provider 返回的 usage 或粗略估算判断是否超过阈值。如果超过，就调用_compress_context()。

压缩做几件事：

• 先 flush memory，避免上下文丢失前遗漏 durable facts
• 保留前 N 条和后 N 条消息
• 中间内容总结成 compact summary
• 工具调用和工具结果成对保留，避免拆坏协议
• 生成新的 session lineage
• 清理缓存并重建 prompt

这跟普通聊天机器人的“超过 token 就截断历史”完全不同。

Hermes 要维护的是一个可恢复的执行轨迹，因此 compression 必须保留协议合法性。

13. Interrupt：中断不是杀进程，而是让 loop 在安全点退出

Hermes 支持用户中途发新消息、/stop或平台侧 interrupt。

在模型调用阶段：

• _interruptible_api_call()把真正 HTTP request 放到后台线程
• 主线程每 0.3 秒检查一次 interrupt
• 如果 interrupt 到来，关闭当前 request-local client
• 抛出InterruptedError
• 不把半截 response 写入 history

在工具执行阶段：

• 主线程会把 interrupt signal fan out 到 worker thread
• 未启动的工具会追加 synthetic skipped result
• 已启动的工具依赖工具内部轮询 interrupt
• 并发工具 worker 结束后会清理 thread-local approval/sudo callback 和 interrupt bit

这样做的目标不是“强杀所有操作”，而是保持 messages 合法：

text assistant(tool_calls) tool(cancelled/skipped result)

即使被中断，下一轮也不会因为 orphan tool_call 破坏 provider 协议。

14. Recovery：Hermes 的 Agent Loop 是带恢复策略的状态机

Agent Loop 里有大量 retry 和 recovery 逻辑，主要分几类。

14.1 Provider response 为空或 malformed

如果 response 没有 choices、content invalid、output empty，Hermes 会：

• 记录 provider/model/error context
• 优先尝试 fallback provider
• 否则 exponential backoff retry
• 超过次数后返回结构化失败

14.2 输出被截断

如果finish_reason == "length"：

• 文本截断：追加 continuation user message，最多继续 3 次
• 工具参数截断：最多重试一次，同样拒绝执行半截参数
• thinking budget 耗尽：给用户明确提示降低 reasoning effort 或增大 max tokens

14.3 图像被 text-only provider 拒绝

如果 provider 返回“只支持 text content”，Hermes 会：

• 标记本 session vision unsupported
• 从 messages / api_messages 里移除 image_url
• 以 text-only mode 重试

14.4 编码异常

如果遇到 surrogate 或 ASCII codec 问题：

• 清理 messages
• 清理 api_messages
• 清理 prefill
• 清理 tools schema
• 必要时清理 credential 里的非 ASCII 字符
• 重新发起请求

14.5 Provider 认证或限流

对 401、403、429、5xx 等错误，Hermes 会结合：

• credential pool
• provider-specific refresh
• fallback provider chain
• error classifier
• context compression

这些恢复策略都在主循环中完成，外部入口不需要理解每种 provider 的失败模式。

异常恢复与可观测性

15. Session Persistence：只有清理完内部脚手架才落库

一次 turn 结束时，Hermes 会做几件持久化操作：

• 保存 trajectory，如果启用
• 清理 terminal/browser 等 task resources
• 删除 thinking prefill、empty response recovery 这类内部 synthetic scaffolding
• 把 messages 写入 session DB
• 更新 token usage、cost、billing provider、api_call_count
• 保存 system prompt snapshot
• 触发 session title / session search 相关索引

Hermes 使用 SQLite~/.hermes/state.db，核心表包括：

• sessions
• messages
• messages_fts
• messages_fts_trigram

messages 表里不只存 content，还存：

• tool_call_id
• tool_calls
• tool_name
• finish_reason
• reasoning
• reasoning_content
• reasoning_details
• codex_reasoning_items
• codex_message_items

也就是说，Hermes 存的不是“聊天记录”，而是“可 replay 的 agent execution transcript”。

这也是为什么它非常重视 role alternation、tool_call/tool_result 配对和 provider-specific reasoning fields。

16. Plugin Hooks：Agent Loop 留了多个可扩展切点

Hermes 的插件不是只在 UI 层装饰，它可以插入 Agent Loop 的关键节点。

典型 hook 包括：

关键设计是：hook 可以扩展，但不能随意破坏 loop 的协议。

例如pre_llm_call返回的上下文会注入 user message，而不是 system prompt；transform_tool_result必须返回 string；pre_tool_call只能通过明确 block directive 阻止工具。

这保证了插件生态不会把核心消息状态机搞乱。

17. Callback Surfaces：CLI、Gateway、ACP 都靠它实时展示进度

AIAgent构造函数接收很多 callback：

• tool_progress_callback
• thinking_callback
• reasoning_callback
• clarify_callback
• step_callback
• stream_delta_callback
• tool_gen_callback
• status_callback

这些 callback 让同一个 Agent Loop 能跑在不同外壳里。

CLI 可以显示 spinner 和 streaming token。

Gateway 可以把“正在调用工具”“等待用户确认”“当前步骤”等状态发到消息平台。

ACP 可以把 status update 映射成编辑器里的进度事件。

这也是 Hermes 和很多简单 agent demo 的分界：核心 loop 不直接绑定 UI，但它暴露足够细的执行事件，让 UI 能实时表达状态。

18. 这个 Agent Loop 的核心不变量

Hermes 的实现非常复杂，但核心不变量其实清晰。

不变量一：system prompt 在 session 内稳定

稳定 prompt 带来缓存收益，也避免 memory mid-turn 写入导致模型上下文自相矛盾。

不变量二：内部消息格式尽量统一

无论外部 provider 是 Anthropic、OpenAI、Codex、Bedrock，Agent Loop 都围绕 canonical message history 运转。

不变量三：tool call 必须配对 tool result

即使工具失败、中断、跳过，也要写回合法 tool result，避免下一次 API call 协议损坏。

不变量四：工具结果进入上下文前必须可控

大结果要落盘，失败要标记，多模态要降级，插件可以 transform，文件修改失败要在最终回答里提示。

不变量五：模型不是可信状态机

Agent Loop 必须处理空响应、截断、半截 JSON、thinking-only、provider 断流、认证失败、限流和上下文过载。

不变量六：turn 结束必须可审计

Hermes 会记录 turn exit reason、token usage、cost、tool turns、messages、trajectory 和 session DB。

19. 和“简单 Tool Loop”的差异

一个最小 tool loop 可能长这样：

python while True: response = llm(messages, tools) if response.tool_calls: results = run_tools(response.tool_calls) messages.extend(results) continue return response.content

Hermes 的真实 loop 多了至少十层工程约束：

Hermes 的复杂性不是为了显得复杂，而是因为它要在真实环境里长期运行：CLI、Gateway、Cron、ACP、多 provider、多工具、多平台、多 session 同时存在。

20. 读源码时最应该抓住的主线

如果要深入读 Hermes Agent Loop，不建议从 1.5 万行的run_agent.py第一行读到最后。

更高效的路径是：

1. AIAgent.run_conversation()：看 turn 生命周期
2. _build_system_prompt_parts()/_build_system_prompt()：看 prompt 稳定边界
3. _build_api_kwargs()：看 provider request 如何生成
4. _interruptible_streaming_api_call()：看 streaming 如何被归一化
5. _build_assistant_message()：看 provider response 如何变回 canonical message
6. _execute_tool_calls()/_execute_tool_calls_sequential()/_execute_tool_calls_concurrent()：看工具执行
7. _invoke_tool()和model_tools.handle_function_call()：看 agent-level tools 与 registry tools 的分界
8. _compress_context()：看上下文压缩和 session lineage
9. _persist_session()：看 messages 如何真正落库
10. plugin hook 相关调用：看扩展点如何插入 loop

理解这条主线之后，再看 Gateway、Cron、ACP、Skills、MCP，就会清楚很多：它们不是替代 Agent Loop，而是在不同入口和扩展点上复用同一个 loop。

结语

Hermes Agent Loop 的价值，不在于它会调用工具。会调用工具只是起点。

真正有工程含量的是：它把模型调用、工具执行、上下文管理、错误恢复、并发、持久化、插件、跨 provider 兼容，全部收束到一个可审计的状态机里。

这也是为什么 Agent Runtime 的核心不是“写一个 while loop”，而是定义一组稳定的不变量：

• prompt 什么时候能变
• messages 什么时候能写
• tool result 如何回灌
• provider 差异在哪里被吸收
• 失败时怎么恢复
• 中断后怎么保持协议合法
• turn 结束后怎么可追溯

Hermes 的答案是：让AIAgent.run_conversation()成为唯一的执行真相，其它入口都围绕它适配。

这就是 Hermes Agent Loop 的核心设计。

学AI大模型的正确顺序，千万不要搞错了

🤔2026年AI风口已来！各行各业的AI渗透肉眼可见，超多公司要么转型做AI相关产品，要么高薪挖AI技术人才，机遇直接摆在眼前！

有往AI方向发展，或者本身有后端编程基础的朋友，直接冲AI大模型应用开发转岗超合适！

就算暂时不打算转岗，了解大模型、RAG、Prompt、Agent这些热门概念，能上手做简单项目，也绝对是求职加分王🔋

📝给大家整理了超全最新的AI大模型应用开发学习清单和资料，手把手帮你快速入门！👇👇

学习路线:

✅大模型基础认知—大模型核心原理、发展历程、主流模型（GPT、文心一言等）特点解析
✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑
✅开发基础能力—Python进阶、API接口调用、大模型开发框架（LangChain等）实操
✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用
✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代
✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经

以上6大模块，看似清晰好上手，实则每个部分都有扎实的核心内容需要吃透！

我把大模型的学习全流程已经整理📚好了！抓住AI时代风口，轻松解锁职业新可能，希望大家都能把握机遇，实现薪资/职业跃迁～

这份完整版的大模型 AI 学习资料已经上传CSDN，朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】