Hermes v0.10.0 发版之后我第一时间把 Tool Gateway 模块拉下来过了一遍顺手在一台 Ubuntu 测试机上从零部署跑通了链路。这个版本的核心不是加了几个新工具而是把工具从“硬编码”升级成“网关化”——Agent 的所有外部能力统一收敛到 Tool Gateway由它负责注册、路由、鉴权、重试和可观测性。如果你正在做 AI Agent 相关项目或者想把手里的 API、脚本、内外网服务统一暴露给智能体这篇拆解应该能帮你省不少时间。内容按我实际部署的顺序走先说设计思路再拆核心能力给配置示例最后把我在现场踩过的坑列出来。1. 这次发布到底改了什么Tool Gateway 在整个体系里扮演的角色1.1 从“单机脚本”到“网关化”我最早接触 Hermes 的 Agent 框架时工具调用还是比较原始的做法在 Agent 代码里定义一个个函数模型输出参数后直接调用本地 Python 函数或者用 LangChain 那样的 Tool 列表硬挂上去。这种方式在 demo 阶段很爽代码一写就能跑但一旦工具数量超过十几个问题就来了——每个工具都要单独处理鉴权、超时、错误重试Agent 的 prompt 也会因为工具清单太长而开始丢三落四路由准确率直线下降。v0.10.0 把这块重新做了一遍。Tool Gateway 单独成了一个服务模块它不负责具体业务逻辑只做工具描述、请求路由、权限校验和调用兜底。Agent 侧不再直接知道“工具在哪、怎么连、用什么凭据”它只对接网关说一句“帮我查北京天气”网关自己根据工具注册表把请求转发到对应的 HTTP 接口或本地进程。这个思路类似我们平时用的反向代理Nginx 不关心上游是 Java 还是 Go只负责按路径把请求转过去。Tool Gateway 也一样它让 Agent 和工具实现彻底解耦。我从部署观察来看这个版本最大的变化是心智模型变了以前你是在“写工具”现在你是在“注册并暴露工具”。1.2 三个核心设计目标通读发行说明和默认配置后我理解 Tool Gateway 主要围绕三个目标展开第一统一入口。所有工具调用走同一个地址、同一套鉴权逻辑Agent 不再散装对接多个服务。你可以在网关层做统一的审计日志记录哪个 Agent、哪个会话、调用了什么工具、传入了什么参数、结果是否成功。多智能体场景下这几乎是刚需。第二协议适配。网关对外暴露稳定的调用接口对内支持 HTTP、gRPC、本地进程、标准输入输出等不同协议。工具本身不需要被迫改造只要注册时描述清楚“怎么调用”网关负责协议转换。我有几个内部服务还是老旧的 CLI 脚本按 v0.10.0 的写法注册成command类型工具Agent 也能正常调起来这一步省了很多迁移成本。第三安全边界。网关能统一做参数校验、敏感操作鉴权、频控和结果脱敏。以前工具散落在 Agent 代码里权限判断经常写得七零八落现在至少在网关上有一个集中审查点。说实话这几个目标单拆开看都不新鲜但 Hermes 把它们收敛进一个独立网关并且绑定到了 Agent 的工具调用主链路上这个组合在同类 Agent 项目里算是比较完整的方案。对刚上手的人来说你不需要立刻理解全部设计只要记住一条以后工具相关的配置、权限、监控都在网关这一层处理。2. 工具网关的核心能力拆解2.1 工具注册与描述文件网关第一步要解决的是“工具怎么被知道”。v0.10.0 里每个工具对应一份描述文件可以是 YAML也可以是 JSON。我建议用 YAML可读性好很多。描述文件里最核心的几部分工具名、描述、输入参数结构、调用方式、超时和重试策略。我实际使用的工具描述长这样name: weather_query description: 查询指定城市的实时天气返回温度、天气状况和风力级别。 version: 1.0.0 input_schema: type: object properties: city: type: string description: 城市名称例如北京、上海、广州 required: true unit: type: string enum: [celsius, fahrenheit] default: celsius handler: type: http endpoint: http://127.0.0.1:8081/weather method: GET auth: type: api_key key_env: WEATHER_API_KEY timeout_ms: 3000 retry: max_attempts: 2 backoff_ms: 500这里有几个容易忽略的点description要写得像“给另一个工程师看的需求说明”不能被模型误解。我第一版写的是“天气接口”结果路由频繁跑到别的工具上改成“查询指定城市的实时天气返回温度、天气状况和风力级别”之后准确率明显提升。模型做意图识别时靠的就是这段描述不能吝啬文字。input_schema要尽量严格。网关在把请求转发给业务服务之前会先按照这层 schema 做 JSON Schema 校验。字段类型不对、缺必填项网关会直接返回参数错误不会把脏数据打到你的服务上。我最初图省事没写required字段结果模型偶尔漏传城市名业务侧报了很奇怪的空指针异常排查了半天才发现是网关层就该拦下来的。handler的endpoint支持环境变量覆盖。这样同一份描述文件可以同时用于测试环境和生产环境部署时只要改环境变量不用改文件。key_env推荐用环境变量而不是明文写在文件里否则一份工具描述文件传出去等于把密钥也送出去了。2.2 路由策略语义优先精确兜底网关注册了一堆工具之后接下来要解决的是“模型这次想调哪个工具”。v0.10.0 的路由方式我理解是两层第一层是语义匹配。把用户请求和工具描述分别做向量化然后算相似度得分最高的工具作为候选。这一层的好处是容错性好用户说“今天上海冷不冷”也能匹配到天气查询工具而不是必须一字不差地说“调用 weather_query”。第二层是精确匹配。如果语义匹配的置信度低于阈值网关会切换到一个更严谨的阶段直接在候选工具集合里做关键词和 schema 匹配必要时还能把候选列表塞回给 Agent让大模型自己做最终选择。我测试下来这套“先语义、后精确”的设计在生产环境里比较实用。纯语义匹配容易把“删除文件”和“清理缓存”搞混纯精确匹配又会让用户请求变得很死板。混合策略相当于给路由上了双保险。唯一要注意的是语义阈值要调整好阈值设太高请求经常落到“不确定”状态设太低又会出现张冠李戴。我目前的经验是从 0.65 开始往上调观察一周的路由错误日志再微调。2.3 鉴权与权限隔离不少 Agent 项目把工具鉴权做在 Agent 层但 v0.10.0 把它下沉到了网关。这个设计的好处是不管哪个 Agent 在调工具只要经过网关就必须遵循同一套权限规则。网关支持按工具维度配置授权策略。比如permissions: - tools: - weather_query - calendar__* allow: - role: user - role: assistant - tools: - admin__* - database__* allow: - role: admin deny: - role: guest我理解这里是把工具名作为一个资源维度后面可以挂角色、用户、租户等主体维度。对个人本地使用来说鉴权看似多余但一旦接入到桌面版或网页版多个角色同时访问权限隔离就是底线了。我遇到过因为权限配置不当普通用户能够触发管理类脚本的事故所以这块建议在一开始就配好而不是等出了问题再补。还有一个细节鉴权信息从哪来如果 Agent 侧传过来的身份令牌是主账号网关就不知道该以哪个用户身份去调用工具。v0.10.0 支持在请求头里带X-Hermes-User这类身份标识网关再结合令牌做映射。实际部署时我建议把它放在网关前面的反向代理层统一注入不要让 Agent 自己随便传用户身份否则伪造成本太低。2.4 熔断、重试与超时工具调用的稳定性往往决定了 Agent 体验的上限。模型等了十秒钟还没拿到工具结果就算后文生成得再好用户也会觉得“卡”。v0.10.0 在网关注入了一套失败处理机制超时控制默认 3000 毫秒可以按工具单独配置重试策略支持最大尝试次数和指数退避熔断状态连续失败次数超过阈值后网关直接快速失败不再把流量打到已经挂掉的服务上我在配置里经常这样组合读类工具超时 2 秒重试 1 次写类工具超时 5 秒不重试。为什么要区分因为写操作重试容易产生重复提交比如支付回调这种场景超时后盲目重试可能造成业务端重复扣款。Agent 侧最多把网关注入的错误提示反馈给模型让模型重新调整参数而不是网关默默再打一次。这个取舍最好在业务上线前跟团队明确好。熔断这块我观察到默认参数比较保守适用于普通个人项目。如果你有高并发场景建议把熔断统计窗口调短一些。我测试时为了验证效果故意把上游服务停掉观察网关在熔断打开后的响应变化大概连续失败六次左右就进入快速失败状态恢复探测频率也还算合理。这种细节如果你不在压测环境里模拟线上出问题时往往只能靠猜。3. Skill、MCP 与 CUA网关如何把外部能力变成内部工具3.1 Skill 是模板不是工具很多人初看 Hermes 文档时会把 Skill 和 Tool 搞混。我在本地把两个模块都跑了一遍索性别急下结论先看了两者的角色定位Skill 是一段可复用的工作流模板它可以编排多个工具调用也可以包含提示词、前置条件、后处理逻辑Tool 是单次原子操作比如“查询天气”“写入文件”“调用某个 API”。换句话说Tool 是积木Skill 是搭积木的图纸。v0.10.0 里 Skill 可以直接访问 Tool Gateway 吗可以。而且实际写起来很方便name: daily_review description: 每天早上汇总天气、待办事项和最新消息。 steps: - tool: weather_query input: city: {user.city} - tool: todo__list - tool: rss__latest网关在分发请求时可以把 Skill 拆成多个工具调用串行执行也可以让 Agent 按 Skill 定义的步骤逐步触发。我个人建议把 Skill 当作业务模板收敛不要放太多动态逻辑进去。一旦 Skill 里的步骤太多且互相依赖出问题时的排查链路会变得很长可观测性压力也大。3.2 MCP 接入让网关变成协议中立层MCPModel Context Protocol最近在 Agent 生态里热度很高Hermes 的热词里也有一条“hermes接入mcp”。v0.10.0 的工具网关对 MCP 的接入方式是让我比较惊喜的一部分网关本身不关心工具是从本地注册表来的还是从 MCP Server 来的。你只需要在网关配置里声明一个 MCP 类型的源网关会自动把远端 MCP Server 暴露的工具同步到本地路由表里。这意味着什么意味着你不再需要为每个 MCP Server 单独写适配器。有一个团队在内部维护了很多按 MCP 协议暴露的服务以前每个服务都要在 Agent 侧单独接入现在只要在网关配置里加一段mcp_servers: - name: internal_services url: http://192.168.1.20:3000/mcp sync_interval: 60网关会定期拉取这些服务的工具列表刷新进路由表。我测试时覆盖了三种常见 MCP Server纯数据查询型、文件操作型、带回调通知型。前两种很顺利第三种需要回调到网关网络链路要确保是双向通的。如果你在企业内网部署记得检查防火墙是否放行 MCP Server 到网关方向的连接原因你懂的——单向白名单能挡住很多奇怪的问题。这个“协议中立”的思路我认为是 v0.10.0 最值得关注的技术方向。以后工具生态大概率会越来越分散与其让 Agent 直接对接所有协议不如让网关做中间翻译。你的 Agent 只需要认识一种语言剩下的事交给网关。3.3 CUA 场景下的工具调用差异搜索热词里还有一条“hermes agent cua”这里 CUA 指的是 Computer Use Agent也就是让 Agent 去操作图形界面的场景。Tool Gateway 在这类场景里角色有点特殊它不仅要决定“调用哪个工具”还要决定“这个动作是不是允许执行”。在普通工具调用里模型输出的参数相对结构化在 CUA 场景里模型可能直接输出鼠标坐标、键盘按键、屏幕截图分析结果。这类操作没法用简单的 JSON Schema 完全约束。我看到的处理方式是网关保留一层额外的动作白名单比如“允许打开应用”“允许点击指定区域”“允许输入文字”但“允许下载任意文件”“允许修改系统设置”这类高危操作必须走到人工确认。我在本地做了个简单模拟让 Agent 登录桌面版的 Hermes然后尝试通过 CUA 工具去操作一个文本编辑器。第一次配置时我把“点击”“输入”两类动作都放开结果 Agent 因为屏幕坐标偏移差点点到删除按钮。加上坐标范围校验和二次确认之后情况才稳定下来。这个点提醒我网关的权限模型要能区分“工具级别”和“动作级别”不能因为一个工具可以调用就放宽到底层操作。MCP、CUA、Skill 这些能力基本都是围绕“让 Agent 更接近真实操作环境”展开的但越接近真实环境网关的边界控制就越重要。这也是为什么我觉得 v0.10.0 把 Tool Gateway 单独拎出来而不是继续堆在 Agent 核心进程里是走对了方向。4. 实操记录从 Ubuntu 部署到跑通第一个路由4.1 安装与初始化如果你和我一样在 Ubuntu 上部署最顺滑的路径是直接用官方安装脚本。我这边用的还是 22.04 LTS依赖这块只遇到一个 Python 版本问题后面会讲。先看安装步骤curl -fsSL https://install.hermes.example/v0.10.0.sh | sh脚本执行完二进制会被放到/usr/local/bin/hermes。然后初始化网关配置hermes gateway init --dir /etc/hermes这一步会在/etc/hermes/下生成gateway.yaml、tools/目录和logs/目录。Windows 用户如果用的是桌面版可以在安装目录下找到hermes-gateway.exe本地没跑起来的话建议优先检查是不是被安全软件拦了端口监听。启动网关hermes gateway start --port 9009看到类似gateway started, listening on 0.0.0.0:9009的输出就说明正常了。我的习惯是不用 root 跑单独开一个hermes用户再把/etc/hermes权限收窄。工具描述文件里如果有密钥也会因为权限不对而无法读取这在本地单机上是加分项。4.2 注册一个自定义工具我在测试机上注册的第一个工具还是天气查询目的是把整个链路走通。做法很简单在/etc/hermes/tools/下新建weather_query.yaml内容就用前面那段示例。然后执行hermes gateway tool list如果这个工具被正确识别tool list里会看到weather_query和它的版本号。如果没看到大概率是 YAML 格式问题。这里有一个坑input_schema里的required字段必须和properties里的键对应否则网关会认为描述文件非法。我第一版忘了把unit放进properties校验直接失败日志只会提示 reactive 错误不看的话根本不知道少了字段。工具注册后即便没人调用网关也可以做连通性检测hermes gateway tool test weather_query --input {city:北京}它会直接绕过 Agent用工具描述里的 endpoint 发一次真实请求并把结果原样打出来。这个命令我强烈建议在生产环境发布前跑一次能提前暴露很多“配置看起来对、实际链路不通”的问题。4.3 配置路由与权限网关默认的路由模式是“语义优先 精确兜底”。我在配置里显式把它写出来便于后面调参gateway: listen: 0.0.0.0:9009 registry: provider: file path: /etc/hermes/tools/ route: mode: semantic semantic_model: hermes-embedding-v1 threshold: 0.65 fallback: exact这里semantic_model指向的是 Hermes 自带的嵌入模型。实际部署时不需要额外下载大模型文件初始化过程会把它装到一个本地模型目录。如果你有其他向量化服务也可以通过semantic_endpoint把它指到外部模型服务。权限配置我放在了gateway.yaml里。个人本地跑可以先不设置复杂的策略直接把default_allow设成true专心调通链路。但如果你想接桌面版、网页版或者多人共用网关建议立刻改成false并加上角色维度policy: default_allow: false roles: - name: user allow_tools: [weather_query, todo__*] - name: admin allow_tools: [*]改完配置后记得重启网关。v0.10.0 这部分配置是启动时加载的不提供热更新。虽然可以在运行中手动hermes gateway reload但权限这类敏感配置重启一次成本不高没必要省。4.4 手工触发一次调用配置完成后我直接用 curl 模拟 Agent 发起一次工具调用curl -X POST http://127.0.0.1:9009/v1/route \ -H Authorization: Bearer $HERMES_TOKEN \ -H Content-Type: application/json \ -d {query:北京天气怎么样,session_id:test-001}网关返回的结果大致长这样{ matched_tool: weather_query, confidence: 0.87, arguments: { city: 北京 }, result: { temperature: 26, condition: 多云, wind: 3级 } }这里我特意验证了两件事第一网关是否把“北京天气怎么样”正确路由到了weather_query而不是别的工具第二返回的arguments是否按照input_schema补齐了默认值。两个都没问题说明从“文本请求”到“结构化工具调用”的链路基本可靠。接着我又测了一个不在工具清单里的请求比如“帮我写一首诗”网关返回的是no_tool_matched并且把这个结果返回到 Agent 侧由模型直接用语言回答而不是强行走工具调用流程。这个行为很重要网关不是拦截一切未知请求它只负责“工具这块”的路由其他请求还是还给模型处理。5. 常见问题与排查技巧实录5.1 症状与排查对照表我整理了一份我自己生产环境里遇到过的、以及社区里高频出现的问题对照表。你可以直接按症状查原因。现象可能原因排查方向工具调用总是超时上游服务响应慢或网络不通用gateway tool test绕过网关直连上游看是否也超时路由匹配到错误的工具工具描述不够具体或语义阈值过低先看confidence低于 0.6 就优化描述不要急着降阈值请求没到网关监听地址配置成了 127.0.0.1外部访问不到检查listen配置和防火墙规则鉴权一直失败环境变量没注入网关进程确认auth.key_env对应的变量存在且服务已重启更新桌面版后无法更新本地缓存未清理或旧进程还占着端口退出旧进程清掉缓存目录再重新启动工具显示为unavailable注册表同步失败或 MCP Server 不在线查看 MCP 同步日志确认远端服务存活网关 CPU 飙高语义路由模型频繁加载检查是否每次请求都在重新加载模型改成预加载模式其中“桌面版无法更新”这个现象我见得最多很多情况下不是版本有问题而是旧进程没有完全退出更新脚本覆盖不了正在运行的二进制文件。Windows 上尤其明显建议在任务管理器里把所有hermes*进程先结束再把安装目录里除用户配置和工具描述文件外的旧文件清掉重新跑安装脚本基本都能解决。5.2 几个容易踩的坑第一个坑是“工具描述文件里写了密钥”。我有一个同事图省事直接把 API Key 写进weather_query.yaml然后把这个文件复制到了配置仓库里。结果仓库刚好是公开的密钥就泄露了。别这么干用key_env引用环境变量文件本身可以入版本库密钥永远只放在环境变量或密钥管理服务里。第二个坑是“重试导致重复执行”。我在测一个“发送消息”工具时给它的重试策略配了两次。网关第一次调用超时后重试成功但上游服务其实已经收到过第一次请求并执行了发送动作用户收到了两条相同消息。排查到后来发现不是业务代码的问题是网关重试策略没有考虑幂等。建议写操作类工具要么实现幂等键要么直接关掉重试。第三个坑是“语义路由把本地工具暴露给外部会话”。如果你把网关监听在0.0.0.0且没有权限策略同一局域网内的其他设备可以直接调你的工具。我在测试机上验证过结果不小心把家里的智能家居服务暴露到了一个非常危险的路径上。后来养成了习惯任何工具网关都必须配default_allow: false至少把匿名访问挡在外面。第四个坑是“工具描述文件的服务重启后丢失”。如果你把工具目录放在临时目录里比如/tmp/hermes_tools系统重启后就什么都没了。这个看起来很低级但我在 fast 调试时真的吃过一次亏最后所有工具描述文件都迁到了/etc/hermes/tools/保存好设备重启验证一遍。这类“小而不易察觉”的问题往往比复杂故障更耗时间。6. 我的一些观察下一步该往哪走6.1 工具描述质量决定上网体验工具网关的路由、参数映射、权限控制都做得比较完善但我看下来决定整体效果能不能发挥出来的往往是最不起眼的工具描述文件。描述写得模糊语义路由就会飘参数 schema 设计得粗糙即使路由对了也会频繁报参数错误鉴权配置不清网关就会在安全边界上漏风。我个人的一个习惯是为每个新增工具写一段“用户请求示例”放在描述文件的备注里比如“示例北京明天几点日出”。这不仅仅是给人看的文档充其量也是给模型和路由模块看的“正样本”。调试路由时可以直接拿这些示例请求做回归测试看路由结果是否稳定。工具多了以后只靠肉眼 review 描述质量是不够的把请求示例沉淀成测试集是性价比很高的一步。6.2 建议优先尝试的扩展方向我用了几天 v0.10.0 之后如果让我给一个团队建议接下来可以优先试这几个方向一是把所有“危险工具”都挂到人工确认流程。网关本身提供了权限控制但人工确认需要额外的工作流。你可以基于网关的 webhook 事件做一个简单确认接口工具触发前先发一条通知用户点通过再放行。CUA 场景里尤其要用这一步能在最大程度上避免 Agent 误操作。二是把网关的访问日志接入现有的日志分析体系。v0.10.0 的网关日志格式相对规整每一条工具调用都会记录会话 ID、工具名、参数、耗时、状态码。把这些字段映射到日志平台里后续做成本分析、异常告警、工具使用画像都很方便。我在本地把它接进了 Loki一周后就能看出哪些工具被频繁调用、哪些工具基本没人用、哪些工具经常失败优化方向一下就清楚了。三是把 Skill 拆得再细一点。刚开始写 Skill 时很容易把流程写成一个“大接口”步骤之间耦合很重。我后来借鉴了模块化的思路每个 Skill 只封装一类明确目标比如“生成周报”而不是“处理每日所有事务”这样网关路由时更从容后续维护也更省力。提示工具网关不是万能的保险丝它的价值在于给 Agent 一个稳定、清晰、可控的工具边界。边界画得好不好取决于你是否愿意在描述文件、路由阈值、权限策略这些“辅助工作”上多花时间。最后分享一个我亲测有效的习惯每次升级 Hermes 版本前不要急着看新功能先把当前的工具描述文件和网关配置备份一份然后在测试环境里跑一遍hermes gateway tool test把所有常用工具的连通性过一遍。版本升级往往伴随着配置格式的微调提前发现问题比上线后让用户帮你发现问题要省心得多。v0.10.0 的 Tool Gateway 做到了这一代该做的事接下来就看你在上面怎么组合自己的工具生态了。