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、派发执行、回填结果。这句话里有五个关键词关键词通俗理解自注册函数每个工具模块通过 registry.register() 声明自己不需要维护一份手工工具清单。Toolsets工具不是全部暴露给模型而是按场景、平台、任务分组启用或禁用。Registry所有工具进入统一注册表调度时按工具名查找 ToolEntry。Schema模型看到的不是 Python 函数而是 OpenAI function-calling 风格的工具定义。Dispatch模型返回 tool_call 后Hermes 根据工具名和参数调用真实 handler。三、工具注册一个工具如何进入 Hermes 系统Hermes 的工具不是散落在代码里的普通函数而是带有元信息的“可调度动作”。官方 Tools Runtime 文档里提到工具文件会在模块级别调用 registry.register()把工具名、所属 toolset、schema、handler、check_fn、是否异步等信息注册进去。这一步的意义很大模型不会直接看 Python 函数它只会看到工具 schema。schema 就像说明书告诉模型这个工具叫什么、能做什么、需要哪些参数、参数是什么类型。handler 才是真正执行动作的函数。举个通俗例子如果一个工具叫 read_fileschema 会告诉模型“你可以通过这个工具读取文件需要传 path 参数”handler 会真的去文件系统读取内容check_fn 则可以判断当前环境是否满足使用条件。四、工具发现为什么新增工具不需要到处改清单在传统系统里新加一个能力经常要改很多地方工具列表、路由表、前端展示、后端调用。Hermes 的设计更偏插件式。model_tools.py 导入时会触发内置工具发现逻辑工具发现会扫描 tools 目录下包含顶层 registry.register() 调用的文件然后导入这些模块。模块一导入注册动作就完成。这样做有两个好处第一工具模块自己声明自己降低集中配置文件的维护压力第二某些可选工具即使依赖缺失也不会拖垮整个工具系统失败会被记录其他工具仍然可以加载。五、ToolsetsHermes 如何控制 Agent 能做什么工具越多能力越强但风险也越大。一个智能体如果同时能删文件、跑命令、发消息、操作浏览器、调用企业系统那就必须有权限边界。Hermes 用 Toolsets 来解决这个问题。Toolsets 是工具包。每个工具属于一个工具集启用工具集就会把里面的工具暴露给 Agent。官方 Toolsets Reference 把工具集分成三类Core、Composite、Platform。此外MCP 和插件还能动态生成工具集。类型例子作用Core 工具集file、terminal、web、browser、memory 等单一能力域比如文件、终端、网页。Composite 工具集debugging file terminal web把多个基础工具组合成一个常见场景。Platform 工具集hermes-cli、hermes-api-server、hermes-discord不同运行入口下暴露不同工具。Dynamic 工具集mcp-github、plugin toolsets、custom toolsets运行时由 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_callmodel_tools.handle_function_call() 接手参数解析如果不是特殊的 Agent-loop 工具就进入 registry.dispatch()注册表按名字找到 ToolEntry再调用对应 handlerhandler 返回结果结果作为 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 还说明内置工具会按工具集分组具体可用性受平台、凭证和启用工具集影响。可以把这些工具分成四大类能力方向代表工具价值看世界web_search、web_extract、browser_snapshot、browser_vision让 Agent 能查资料、读网页、理解浏览器页面。改项目read_file、write_file、patch、terminal、process让 Agent 能读写文件、打补丁、跑测试、管理后台进程。记经验memory、session_search、skills_list、skill_view、skill_manage让 Agent 能把事实、历史和流程沉淀下来。接系统MCP、Discord、Feishu、Spotify、Home Assistant、send_message让 Agent 能接外部服务、企业系统和消息平台。九、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 ServerHermes 也不会盲目传递完整 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 的工具层至少要包含以下能力设计点工程意义工具注册表所有工具统一注册工具名、schema、handler、可用性检查都结构化管理。权限分组用 toolsets 或类似机制控制不同场景暴露哪些工具。统一调度模型 tool_call 不直接执行而是通过调度层统一处理。安全审批危险动作要识别、审批、记录、可回滚。运行隔离命令最好跑在容器、沙箱、远程 workspace 或最小权限环境。错误回填失败也要作为结果返回给模型支持重试和自我修正。外部扩展通过 MCP 或插件机制接企业系统而不是把所有接口写死。十六、结尾总结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 从“会回答问题”进化到“能在真实环境里安全做事”。