Hermes Agent Tools 架构深度解析

一、先说结论：Tools 才是 Agent 从“会说”到“会做”的关键

很多人第一次看 AI Agent，会把注意力全部放在模型上：模型多大、推理多强、上下文多长。但真正落到工程里，一个 Agent 能不能完成任务，核心不只在模型，而在它能不能安全、稳定、可控地调用工具。

Hermes Agent 的 Tools 系统，可以理解成一套“行动中台”：模型负责判断下一步要做什么，Tools 负责把这一步变成真实动作，比如搜索网页、读取文件、修改代码、运行命令、打开浏览器、写入记忆、创建技能、委派子 Agent、发送消息、接入 MCP 外部系统。

所以本文的主线很简单：不要把 Tools 看成几个函数列表，而要看成一个完整运行系统：工具注册、工具发现、工具集过滤、模型可见 schema、运行时调度、handler 执行、错误包装、安全审批、外部 MCP 扩展。

二、Hermes Tools 的一句话架构

用一句话概括：Hermes Tools 是一组自注册函数，按 Toolsets 分组，由中央 Registry 统一管理，并通过 model_tools.py 暴露给模型，再由 run_agent.py 在 Agent Loop 中接收 tool_call、派发执行、回填结果。

这句话里有五个关键词：

三、工具注册：一个工具如何进入 Hermes 系统

Hermes 的工具不是散落在代码里的普通函数，而是带有元信息的“可调度动作”。官方 Tools Runtime 文档里提到，工具文件会在模块级别调用 registry.register()，把工具名、所属 toolset、schema、handler、check_fn、是否异步等信息注册进去。

这一步的意义很大：模型不会直接看 Python 函数，它只会看到工具 schema。schema 就像说明书，告诉模型这个工具叫什么、能做什么、需要哪些参数、参数是什么类型。handler 才是真正执行动作的函数。

举个通俗例子：如果一个工具叫 read_file，schema 会告诉模型“你可以通过这个工具读取文件，需要传 path 参数”；handler 会真的去文件系统读取内容；check_fn 则可以判断当前环境是否满足使用条件。

四、工具发现：为什么新增工具不需要到处改清单

在传统系统里，新加一个能力经常要改很多地方：工具列表、路由表、前端展示、后端调用。Hermes 的设计更偏插件式。model_tools.py 导入时，会触发内置工具发现逻辑；工具发现会扫描 tools 目录下包含顶层 registry.register() 调用的文件，然后导入这些模块。模块一导入，注册动作就完成。

这样做有两个好处：第一，工具模块自己声明自己，降低集中配置文件的维护压力；第二，某些可选工具即使依赖缺失，也不会拖垮整个工具系统，失败会被记录，其他工具仍然可以加载。

五、Toolsets：Hermes 如何控制 Agent 能做什么

工具越多，能力越强，但风险也越大。一个智能体如果同时能删文件、跑命令、发消息、操作浏览器、调用企业系统，那就必须有权限边界。Hermes 用 Toolsets 来解决这个问题。

Toolsets 是工具包。每个工具属于一个工具集；启用工具集，就会把里面的工具暴露给 Agent。官方 Toolsets Reference 把工具集分成三类：Core、Composite、Platform。此外，MCP 和插件还能动态生成工具集。

六、模型看到的不是全部工具，而是“过滤后的工具 schema”

这是理解 Hermes Tools 的关键：工具注册进系统，不代表模型一定能用。一次会话启动时，Hermes 会根据 enabled_toolsets、disabled_toolsets、平台预设、MCP 动态工具集、单个工具禁用配置、check_fn 可用性检查等条件，生成本次模型真正可见的工具 schema。

这就像给模型发一张“本次可操作菜单”。如果本次只启用 safe 工具集，模型就不应该看到危险的终端写入能力；如果浏览器 CDP 没连上，相关工具也不应该被暴露。这样可以减少幻觉调用，也能降低误操作风险。

七、一次工具调用是怎么跑起来的

当模型决定需要行动时，它不会自己去操作系统，而是返回一个 tool_call。这个 tool_call 通常包含两个东西：工具名和参数。接下来进入 Hermes 的 Agent Loop 和工具调度链路。

通俗拆解一下：模型说“我要调用 read_file，参数是某个路径”；run_agent.py 捕获这个 tool_call；model_tools.handle_function_call() 接手参数解析；如果不是特殊的 Agent-loop 工具，就进入 registry.dispatch()；注册表按名字找到 ToolEntry；再调用对应 handler；handler 返回结果；结果作为 tool message 回到对话上下文；模型再根据结果继续推理。

这里最像“人类工作流”的地方是：模型不是一次性输出最终答案，而是在“想一步、做一步、看结果、再想一步”的循环中推进任务。Tools 就是每一次“做一步”的执行器。

八、Hermes 内置工具：不是几个函数，而是一张能力版图

官方 Tools & Toolsets 文档提到，Hermes 内置工具覆盖 web search、browser automation、terminal execution、file editing、memory、delegation、messaging delivery、Home Assistant 等方向。Built-in Tools Reference 还说明内置工具会按工具集分组，具体可用性受平台、凭证和启用工具集影响。

可以把这些工具分成四大类：

九、Agent-loop 特殊工具：为什么有些工具不直接 dispatch

并不是所有工具都只是普通函数调用。官方 Tools Runtime 文档明确提到，todo、memory、session_search、delegate_task 这些工具会在 registry.dispatch 前被 Agent Loop 拦截，因为它们需要访问 Agent 级状态，比如 TodoStore、MemoryStore、历史 session 或子 Agent。

这其实很好理解：read_file 只需要文件路径，terminal 只需要命令；但 memory 要改长期记忆，session_search 要搜历史会话，delegate_task 要启动子 Agent，这些都不是单纯函数能独立完成的，需要 Agent Loop 提供上下文和状态。

十、MCP：把外部系统变成 Hermes 可调用工具

MCP 是 Hermes Tools 扩展外部能力的重要入口。官方 MCP 文档说明，Hermes 会在启动时发现配置的 MCP Server，并把 MCP Server 提供的工具注册到普通工具注册表；当 MCP Server 发出 tools/list_changed 通知时，Hermes 还能重新拉取工具列表并更新注册表。

也就是说，MCP 不是另起一套工具系统，而是把外部系统的能力纳入 Hermes 的统一工具体系。比如 GitHub MCP Server 可以暴露 list_issues、create_issue 等工具；数据库 MCP Server 可以暴露查询能力；企业内部系统可以把工单、CRM、知识库等包装成工具。

MCP 的另一个重点是安全过滤。Hermes 的 MCP 配置支持 include、exclude、resources、prompts 等策略，可以只暴露最小必要工具。对于 stdio MCP Server，Hermes 也不会盲目传递完整 shell 环境，而是只传配置过的 env 和安全基线，减少密钥泄露风险。

十一、Terminal / Runtime：命令到底在哪里执行

Agent 能跑命令是一件很强的事，也是一件很危险的事。所以 Hermes 把终端执行抽象成 runtime/backend。官方 Tools Runtime 文档提到，终端系统支持 local、docker、ssh、singularity、modal、daytona、vercel_sandbox 等后端，并支持 per-task cwd、后台进程管理、PTY 模式和危险命令审批回调。

尤其值得注意的是 Docker backend。官方配置文档强调，Hermes 不是每条命令新建一个容器，而是在首次使用时启动一个长期容器，后续 terminal、file、execute_code 等调用通过 docker exec 进入同一容器。这样做让安装的包、工作目录、/workspace 文件能在多个工具调用之间保持一致，更接近真实开发环境。

十二、安全审批：能行动，也要能刹车

Tools 系统越强，安全越不能省。Hermes 的危险命令审批机制会在执行终端命令前检查 DANGEROUS_PATTERNS，覆盖递归删除、磁盘格式化、危险 SQL、系统配置覆盖、服务停止、curl | sh、进程杀伤等典型危险模式。

审批模式可以配置为 manual、smart 或 off。manual 是默认模式，遇到危险命令需要人工审批；smart 会用辅助模型评估风险，低风险命令自动通过，高风险自动拒绝，不确定时再让用户确认；off 等价于 --yolo，会跳过审批，这种模式只适合隔离环境或明确知道风险的场景。

十三、错误处理、异步桥接与并发：工具系统的稳定性设计

真实工具调用一定会失败：网页打不开、命令报错、依赖缺失、API 限流、参数不合法。Hermes 的做法不是让异常直接炸穿 Agent，而是把异常包装成结构化错误结果返回给模型。官方 Tools Runtime 文档提到，registry.dispatch() 和 handle_function_call() 都有错误包装，保证模型拿到的是良构 JSON 字符串，而不是未处理异常。

另外，工具 handler 可能是同步函数，也可能是异步协程。Hermes 通过 _run_async() 把异步 handler 桥接到同步调度路径里：CLI 没有运行中的事件循环时使用持久事件循环，Gateway 有运行循环时使用线程里的 asyncio.run()，并行 worker 线程则使用线程本地事件循环。

并发方面，Hermes 会根据工具组合和交互需求顺序或并发执行。对普通用户来说，这意味着多个不互相依赖的工具调用可以更快完成；对工程师来说，这意味着工具必须考虑并发安全、状态隔离和日志可追踪。

十四、从源码看 Tools：建议按这条路线读

如果你想真正理解 Hermes Tools，不建议一上来全仓库乱翻。更高效的阅读路线是从模型能看到的工具定义开始，再看注册表，再看调度，再看具体执行环境和安全审批。

十五、对自研 Agent 系统的启发

Hermes Tools 系统给自研 Agent 最大的启发，不是“工具越多越好”，而是“工具要被治理”。一个成熟 Agent 的工具层至少要包含以下能力：

十六、结尾总结：Hermes Tools 的本质是“可控行动系统”

Hermes Agent 的 Tools 不是简单的工具列表，而是一套完整的可控行动系统。它让模型不再只是生成文字，而是能围绕任务一步步搜索、读取、修改、执行、记忆、委派和自动化。

从工程角度看，Hermes Tools 最值得学习的是这条主线：工具先注册到 Registry，再由 Toolsets 控制可见范围，模型只看到过滤后的 schema；模型产生 tool_call 后，Agent Loop 接管，经过 handle_function_call 和 registry.dispatch 调用 handler；执行结果回填给模型；过程中再由审批、沙箱、错误包装、MCP 过滤和插件钩子保障安全与扩展性。

真正成熟的 Agent，不是“会调一个搜索 API”，而是拥有一套能够长期运行、可审计、可扩展、可限制、可恢复的工具执行体系。Hermes Tools 的价值就在这里：它让 AI Agent 从“会回答问题”进化到“能在真实环境里安全做事”。