Agent | 有志者事竟成

工具系统：从注册到调度

Wed, 01 Jul 2026 14:00:00 +0800

系列：通过 Hermes 探秘 Agent 工程 | 第 2 篇 上一篇：Agent Loop：Agent 的核心执行循环

工具系统解决了什么问题？

一个 Agent 再聪明，如果只能"说话"不能"做事"，就只是一个聊天机器人。工具系统就是 Agent 的手脚——让模型能读写文件、执行命令、搜索网络、操作浏览器、管理定时任务……

但工具越多，管理越复杂：

怎么让新增的工具被 Agent 感知又不改核心代码？
怎么让不同平台（CLI vs 网关 vs 子代理）看到不同的工具集？
怎么让工具调用安全可控？

Hermes 用三个机制解决这些问题：自注册、toolset 分层、capabilities 检查。

机制一：模块级自注册

最精巧的设计是——每个工具文件自己注册自己。

Hermes 规定：任何放在 tools/ 目录下的 Python 文件，只要在模块顶层调用 registry.register()，就会被系统自动发现。你不需要在一个"总清单"里添加新工具的引用。

# 以文件工具为例
registry.register(
 name="read_file",
 toolset="file",
 schema=READ_FILE_SCHEMA,
 handler=_handle_read_file,
 check_fn=_check_file_reqs,
 emoji="📖",
 max_result_size_chars=100_000
)

这行代码做了什么？

参数	含义
`name`	工具名，模型用这个名称调用工具
`toolset`	工具归属的分组，用于批量启用/禁用
`schema`	OpenAI function calling 格式的参数描述
`handler`	实际执行函数
`check_fn`	可用性检查函数（比如检查 Docker 是否可用）
`emoji`	显示用图标
`max_result_size_chars`	输出结果的最大字符数

发现过程：AST 扫描

你可能会问：系统怎么知道 tools/ 下哪些文件调用了 registry.register？

答案很巧妙——不用运行代码就能发现。Harmes 的 discover_builtin_tools() 函数在导入模块之前，先对文件做 AST（抽象语法树）扫描，寻找模块顶层的 registry.register() 调用。只有被 AST 判定为"会注册工具"的模块，才会被真正导入。

tools/*.py → AST 扫描 → 发现 registry.register() → 导入模块 → 执行注册

这个设计的好处是零配置扩展：丢一个新文件到 tools/，加一行 registry.register()，Agent 下次启动就能用。

机制二：Toolset 分层

光有注册还不够。50+ 个工具不能同时塞给所有场景——CLI 用户需要 terminal，Telegram bot 不需要；子代理可能只给 read_file 和 write_file；webhook 回调必须严格限制为只读工具。

Hermes 的办法是toolset（工具集）。

toolsets.py 定义了一组命名的工具集：

TOOLSETS = {
 "web": {
 "description": "Web research and content extraction tools",
 "tools": ["web_search", "web_extract"],
 "includes": []
 },
 "terminal": {
 "description": "Terminal/command execution and process management tools",
 "tools": ["terminal", "process"],
 "includes": []
 },
 "file": {
 "tools": ["read_file", "write_file", "patch", "search_files"],
 },
 "browser": {
 "tools": ["browser_navigate", "browser_snapshot", ...],
 },
 ...
}

每个 toolset 可以引用其他 toolset（includes 字段），形成组合。比如 CLI 默认可能启用 terminal + file + web + browser，而子代理可能只给 file + web。

三层过滤

最终给模型的工具列表，经过三层过滤：

启用集（enabled_toolsets）：用户配置启用了哪些 toolset，取并集
禁用集（disabled_toolsets）：从并集中减去这些
capabilities 检查：对每个工具调用 check_fn()，去掉当前环境不支持的

机制三：capabilities 检查与缓存

很多工具的可用性取决于外部环境。比如 terminal 工具在非 local 后端（比如 Docker 远程）可能不可用，browser 需要 Playwright 安装，ha_list_entities 需要 HASS_TOKEN 环境变量。

每个工具可以定义自己的 check_fn。但这个检查有个问题：外部环境（比如 Docker 守护进程的 socket 连接）可能瞬断，每次调用 LLM 前都检查一遍会增加延迟。

Hermes 用了两层优化：

TTL 缓存

check_fn 的结果缓存 30 秒，同一个会话里连续调用不重复检查。

瞬断抑制

更精妙的是"最近一次成功抑制“机制：如果某个 check_fn 最近成功过（证明功能确实可用），那么接下来 60 秒内的失败会被当作"瞬断"忽略掉——工具仍然可用，不报错。

为什么需要这个？想象一下：Docker daemon 的 Unix socket 偶尔超时（容器负载高时很常见），如果一刀切地"失败就禁用”，会导致 CLI 工具在你的会话中被随机移除。有了瞬断抑制，单次超时不影响使用，只有持续失败才会真正禁用。

分发：handle_function_call()

当模型返回工具调用时，Agent 通过 handle_function_call() 分发。这个函数是整个工具系统的"路由器"。

路由逻辑

模型输出 tool_calls
↓
handle_function_call(name, args, task_id, ...)
↓
参数类型强制转换（字符串 "42" → 整数 42）
↓
工具 Search bridge 特殊处理（让模型能"搜索工具目录"）
↓
查找 ToolEntry → 调用 handler(args) → 返回 JSON 结果

参数类型强制转换

不同模型的 function calling 实现有差异——有些模型会把数字参数传成字符串（"42" 而不是 42）。handle_function_call() 会自动根据 schema 做类型强制转换，确保 handler 收到正确类型的参数。

Tool Search Bridge

这是个有意思的工具：tool_search / tool_describe / tool_call，合称"工具搜索桥"。它让模型可以搜索当前会话可用的工具目录，而不需要在 system prompt 里塞进所有工具的定义。

启用场景：当工具数量太大（50+）会消耗大量上下文 token 时，模型可以先用 tool_search 找到需要的工具，再用 tool_describe 查看参数细节，最后用 tool_call 调用。相当于给工具系统加了一层"按需索引"。

并行执行

如果模型一次返回多个独立的工具调用，Hermes 支持并行执行。

模型返回：[tool_A(args_A), tool_B(args_B), tool_C(args_C)]
↓
并行分发到 ThreadPoolExecutor / asyncio
↓
等待所有结果
↓
合并到历史对话

并行执行的关键是每个工具 handler 要线程安全。大部分工具本质是无状态的（接收参数 → 执行 → 返回结果），天然支持并行；但有副作用的工具（比如写文件同一路径）需要开发者自己保证安全。

为什么这样设计？

回顾这三个机制，你会发现 Hermes 工具系统的设计哲学：

原则	对应机制	为什么
扩展不改核心	AST 自注册	新增工具加一行代码，零配置
平台差异化	toolset 分层	CLI 和 Telegram 看到不同工具
弹性可用	瞬断抑制	外部服务偶尔抖动不丢工具
按需加载	Tool Search Bridge	工具多时不爆上下文
类型安全	强制转换	不同模型输出的格式差异被抹平

工程启示

工具系统的好坏不取决于工具数量，而在于管理质量。

一些值得借鉴的设计决策：

**让工具自己说"我需要什么"**——通过 check_fn` 声明依赖，而不是让外部代码猜测工具是否可用
缓存有退路——30 秒 TTL + 60 秒瞬断抑制，既避免重复检查，又不会把抖动当死机
渐进式暴露——不是所有工具平铺给模型，而是通过 toolset + bridge 按需暴露，控制上下文开销

总结

工具系统是 Agent 可靠性的基础。Hermes 用自注册让扩展零成本，用 toolset 让多平台共享代码，用 capabilities 检查让工具可用性可感知，用并行分发让执行不阻塞。

下一篇，我们将深入 System Prompt 的组装——Hermes 是如何把工具定义、记忆快照、用户规则拼成一个既紧凑又完整的系统提示的。

Agent Loop：Agent 的核心执行循环

Wed, 01 Jul 2026 10:00:00 +0800

系列：通过 Hermes 探秘 Agent 工程 | 第 1 篇

为什么需要一个"循环"？

如果你用过 ChatGPT 或 Claude 的聊天界面，你会发现它们的工作方式是一次性的：你发一条消息，模型回一条消息，对话结束。

但 Agent 不同。Agent 的任务往往不是"问一句答一句"能解决的。一个典型的 Agent 请求可能是：

“帮我查一下今天 A 股涨幅前 10 的板块，把结果写成 CSV 文件，然后分析一下这些板块的共同特征。”

这个任务需要：

调用工具查询数据
把数据写入文件
读取文件内容进行分析
输出最终结论

每一步都依赖上一步的结果，模型需要"看到"工具执行的结果，才能决定下一步做什么。这就是 Agent Loop——一个让 LLM 和工具反复交互的 while 循环。

从入口开始

Hermes 的 Agent 入口是一个叫 run_conversation 的函数。从名字就能看出，它处理的是一轮"对话"（一个用户请求），但内部的轮数远不止一轮。

用户消息 → [循环开始] → 构建消息 → 调用 LLM → 有工具调用？→ 执行工具 → 结果回灌 → 再次调用
↓
[循环结束] ← 无工具调用 → 输出最终回复

整个循环可以分成三个阶段：初始化、迭代、终结。

阶段一：系统 Prompt 的构建

在循环开始之前，Agent 需要构建一个系统 Prompt。这个 Prompt 不是用户写的，是 Agent 自己"拼装"出来的，目的只有一个：告诉 LLM 你是谁、你能做什么、你现在处于什么环境。

Hermes 把它拆成三层：

Stable（稳定层）：身份声明、工具使用指南、环境信息、Skill 索引。这部分每个会话只构建一次，因为它是"不变的"。
Context（上下文层）：用户自定义的规则文件（比如项目根目录的 AGENTS.md），以及一些平台特有的提示。这部分是"半稳定"的——用户改了规则文件，下次会话会刷新。
Volatile（易变层）：记忆快照、用户画像、当前时间、会话 ID、当前模型。这部分每个会话都会不同，甚至有时会动态刷新。

这三层拼在一起，就是一个完整的系统 Prompt。比如它的典型结构可能是：

[身份] 你是一个运行在终端里的 AI Agent...
[工具使用] 你可以调用以下工具：terminal, read_file, write_file...
[环境] 操作系统 Linux，当前目录 /root，后端终端 local...
[技能] 已安装技能：akshare-data-fetcher, github-pr-workflow...
[记忆] 用户偏好：简洁高效，不喜欢废话...

阶段二：循环的"燃料"——迭代预算

进入循环之前，Agent 需要知道一件事：最多能循环多少次？

如果没有任何限制，Agent 可能陷入死循环：模型不断调用工具，工具结果不理想，模型再尝试，再失败，无限循环下去。

Hermes 用一个叫做 IterationBudget 的对象来管理这个预算。它有两个维度：

max_total：整个会话的总循环次数上限（默认 90 次）
单轮预算：每轮对话消耗 1 个预算

每次调用 LLM 之前，预算会被"消耗"一次。当预算耗尽时，循环强制终止。

但还有一个细节：execute_code 工具可以"退款"。因为 execute_code 本质上是一个程序化的调用（程序生成代码 → Agent 自动执行 → 返回结果），不算真正的"对话轮次"。所以调用这个工具时，预算会被退还。

调用 execute_code → 消耗预算 → 执行完毕 → 退还预算

这就是为什么你能用 Agent 跑很多代码，但不会快速耗尽预算。

阶段三：每次迭代内部发生了什么

每次循环内部，其实分成几个子步骤：

1. 中断检查

在调用 LLM 之前，先检查用户是否发来了新消息或 /stop 命令。如果有，立刻中断循环，返回迄今为止的结果。这种设计很实用——你可以在 Agent 执行到一半时喊停。

2. 调用 LLM

构建好消息列表（系统 Prompt + 历史对话 + 当前工具结果）后，Agent 调用 LLM 的 API。这一步可能失败（网络超时、限流、模型错误），所以有一套重试和退避机制。

3. 解析响应

LLM 返回的响应有两种可能：

纯文本：模型认为任务已经完成，不再需要调用工具
带工具调用：模型输出了工具调用指令（function call）

4. 工具调度的"三道安检"

如果模型要求调用工具，Agent 不会立即执行，而是经过三层验证：

名称校验：检查工具名是否存在。如果模型产生幻觉（叫了一个不存在的工具名），尝试自动修复（比如 fuzzy 匹配相似的工具名）。如果修不好，最多重试 3 次，然后终止。
参数校验：检查工具的参数是否是合法的 JSON。如果是空字符串，自动补成 {}（模型常见行为）。如果是损坏的 JSON，先尝试重试 3 次，还不行就注入一个"错误结果"让模型看到，让它自己修正。
去重与限制：检查并去除重复的调用（比如同一个工具被连续调两次相同的参数）。同时限制 delegate_task 子代理的调用数量，防止无限递归。

5. 执行与结果回灌

通过验证的工具调用会被分发执行。Hermes 支持并行执行（如果模型一次返回多个独立的工具调用），也支持串行。

执行结果会被格式化为统一的 tool role 消息，追加到历史对话中。下一次循环时，模型就能看到这些结果。

6. 压缩检查

每次工具执行完毕，Agent 会估算当前上下文（历史对话 + 工具结果）的 token 数。如果接近上下文窗口的阈值（默认 50%），就会触发压缩——用一个便宜的模型把早期的对话摘要替换掉，保留关键信息，释放空间。

这就是为什么你可以在一个会话里聊很久，而不会遇到"上下文太长"的错误。

什么时候循环结束？

循环终止的条件有四个：

模型返回纯文本（没有工具调用）→ 任务完成，返回最终回复
预算耗尽（达到 max_total）→ 强制停止，返回已完成的进度
用户中断（发送新消息或 /stop）→ 优雅退出，保留当前状态
工具护栏触发（检测到危险操作）→ 立即停止，输出安全警告

工程启示

从 Hermes 的实现中，我们可以看到几个 Agent 工程的设计原则：

1. 循环必须有预算

没有预算限制的 Agent 是不可靠的。预算不仅是"保护伞"，也是"进度表"——用户可以据此判断任务的复杂度。

2. 工具执行是"窗口"，不是"黑盒"

Agent 不是盲目信任模型的输出。名称校验、参数校验、去重、限流——这些"安检"步骤确保工具调用是安全、合理、可预测的。

3. 错误恢复是"对话式"的

当工具调用失败时，Agent 不是直接报错退出，而是把错误信息作为 tool result 喂回给模型，让它有机会自己修正。这种"容错对话"是 Agent 智能的核心体现。

4. 上下文是"有价商品"

Agent 的每一次 API 调用都在消耗 token，而上下文窗口是有限的。压缩机制把"长对话"变成"摘要 + 近期内容"，让 Agent 能处理远超窗口容量的任务。

总结

Agent Loop 不是一个高深的概念，它就是一个 while 循环。但这个循环内部的设计——迭代预算、中断处理、工具调度、错误恢复、上下文压缩——决定了 Agent 的可靠性、效率和智能程度。

下一个系列文章，我们将深入工具系统：Hermes 是如何让 50+ 个工具自动注册、发现、分发和执行的。