Hermes v0.10.0 工具网关：Agent 工具调用从写代码变成做配置

如果你最近在搞 Agent 应用，一定对“工具调用”这四个字不陌生。模型再聪明，不接上真实的业务系统，也只是个会聊天的玩具。但工具接多了之后，问题就来了：每个工具散落在不同的服务里，有的走 HTTP，有的走内部 SDK，有的是外部 SaaS，权限、限流、审计各搞一套，Agent 进程里塞满了工具调用逻辑，改一次工具要动一轮代码，上线前谁也说不清到底暴露了多少接口给模型。

Hermes v0.10.0 这次发布的 Tool Gateway，就是把“模型调工具”这件事从 Agent 内部彻底拆出来，变成一个独立的工具网关组件。所有工具统一注册、统一路由、统一鉴权，模型只跟网关打交道，工具方只需要按规范把能力挂上来。这个版本最大的价值不是多了一堆接口，而是把工具接入从“写代码”变成了“做配置”。如果你正在做 Agent 平台，或者要给现有业务系统接模型能力，这篇内容值得看完。我会从为什么需要工具网关讲起，再把 v0.10.0 的核心能力、配置方法、迁移注意事项逐个拆开。

1. Tool Gateway 到底是什么，为什么 Agent 需要它

1.1 单体 Agent 时代的工具调用痛点

先说个我自己的经历。早期做一个内部客服助手，Agent 要调订单查询、物流轨迹、退款状态三个系统。最开始实现很简单：在 Agent 代码里直接写 Python 函数，每个函数对应一个业务查询，模型按 function calling 的格式解析参数，然后调用本地函数。

跑了一个月，痛点全暴露了。第一个问题是耦合，每加一个工具就要改 Agent 的代码，业务方想接入自己的系统，得排队等开发排期；第二个是权限，当时所有工具共用同一个数据库账号，模型只要被诱导调了某个工具，就能看到不该看的数据；第三个是稳定性，有个第三方物流接口偶尔超时，结果整个 Agent 响应都被拖慢，因为没有独立的超时和重试策略；第四个是审计，每次工具调用到底传了什么参数、返回了什么结果、花了多少钱，完全靠日志里大海捞针。

这些问题不是靠 Agent 框架本身能解决的。你可以在代码里做封装，但每个团队封装方式不一样，有的用装饰器，有的直接 try-except，有的干脆不处理。当工具数量从 3 个涨到 30 个的时候，整个代码库就变成一个巨大的工具调用泥潭。

1.2 工具网关和 API 网关的本质区别

很多人一听“网关”就觉得跟 API 网关差不多。实际上两者解决的问题完全不同。API 网关管的是“客户端到服务端”的流量，重点是路由、认证、限流，面向的是人和程序之间的 HTTP 请求；工具网关管的是“模型到工具”的调用，重点是 Schema 校验、参数抽取、协议转换，面向的是大模型和业务系统之间的 function calling 交互。

举个例子。API 网关转发的是已经定好的 HTTP 请求，URL、Header、Body 都是明确的。但模型调用工具的时候，它给出的参数是自然语言推理出来的 JSON，字段类型可能错、字段可能缺失、枚举值可能根本不在范围内。工具网关要做的第一件事就是把模型输出的参数“翻译”成工具真正能接受的参数，然后决定调哪个后端。

协议上也不同。同一套工具，模型侧可能是 OpenAI 风格的 function calling，也可能走 MCP（Model Context Protocol），而工具端可能是 gRPC、HTTP、内部 SDK 甚至本地脚本。工具网关需要把所有这些统一成一套内部表示，再分发给后端。v0.10.0 的 Tool Gateway 正是围绕这套逻辑设计的。

2. v0.10.0 工具网关的核心能力拆解

2.1 工具的注册与 Schema 管理：让接入从写代码变成做配置

v0.10.0 里，工具注册只需要向网关发送一个包含工具元数据的请求。每个工具由三部分组成：工具描述、参数 Schema、路由目标。描述是给模型“看”的，决定模型在什么场景下会选用这个工具；参数 Schema 是给参数解析用的，决定怎么校验和转换模型传来的 JSON；路由目标则告诉网关这个工具实际的后端地址和调用方式。

注册接口大致长这样：

POST /api/v1/tools Content-Type: application/json { "name": "order_query", "description": "根据订单号查询订单状态和物流信息", "version": "1.2.0", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单号" }, "include_detail": { "type": "boolean", "default": false } }, "required": ["order_id"] }, "backend": { "type": "http", "url": "https://internal.example.com/api/order/query", "method": "POST", "timeout_ms": 3000, "auth": { "type": "service_token", "token_ref": "order-svc-token" } } }

这里有个很容易忽略的点：description不是给人看的注释，而是给模型看的提示词，直接影响模型选工具的正确率。我见过很多人随便写一句“查询订单”，结果模型在需要查询物流的时候也调了这个工具。好的描述应该包含触发条件、参数字段说明、返回内容概述，甚至典型调用示例。比如写成“当用户询问订单当前状态或物流轨迹时，使用此工具。传入订单号。返回字段包括 status、logistics、预计送达时间”，选中的准确率会明显提升。

Schema 管理方面，v0.10.0 加入了版本概念。工具更新不影响正在跑的 Agent，只有显式指定新版本或未指定版本（默认最新）时才生效。这个设计类似于接口的兼容性保障，工具方可以放心迭代，不用担心改了一个字段导致所有历史会话崩溃。

2.2 路由与多协议适配：HTTP、gRPC、SDK 和 MCP 一网打尽

工具网关最核心的工程价值在协议适配层。v0.10.0 内置了三类后端适配器：HTTP/REST 适配器、gRPC 适配器、进程内 SDK 适配器。另外通过 MCP Bridge 可以接入任意符合 MCP 规范的工具服务器。

HTTP 适配器处理最多的情况。它需要做三件额外的事：参数映射、认证注入、响应规整。参数映射解决的是模型叫order_id，后端接口要orderNo这种字段名不一致的问题；认证注入解决的是后端要求内部 Token，而模型侧不应该感知 Token 的问题；响应规整则是把后端返回的任意 JSON 结构转换成工具调用结果的标准格式。这三步都很容易踩坑，尤其是响应规整，后端返回{code:0, data:{...}}这种工业标准格式和返回裸数组的格式，处理逻辑完全不同。

gRPC 适配器稍微复杂一点，需要网关持有后端的.proto文件描述或反射信息，才能把 JSON 参数转成 protobuf 消息。v0.10.0 的做法是注册工具时允许上传 proto 描述符，网关在启动时解析一次，后续调用直接做二进制转换。

进程内 SDK 适配器适合工具跟网关部署在同一个进程的情况，比如一些轻量级脚本工具、内部函数工具。它通过 Python 或 Go 的 SDK 注册回调函数，网关调用时直接发起进程内调用，省掉一次网络跳转。延迟确实低，但代价是工具崩溃可能拖垮网关本身，所以我一般只在低风险工具上用这个模式。

MCP 是目前比较受关注的接入方式。v0.10.0 的 Tool Gateway 可以作为一个 MCP Client，连接外部的 MCP Server，自动把 MCP Server 暴露的工具列表同步到网关，并统一转换成模型侧的 function schema。效果上，你接入一个 MCP Server 就像批量注册了一组工具，不需要手动维护 Schema。后面实操部分我会给一个具体配置。

2.3 执行策略：超时、重试、限流与熔断的默认值

工具调用最让人头疼的不确定性，都发生在执行阶段。v0.10.0 把执行策略做成了可配置项，并给了相对保守的默认值。

超时方面，网关级默认 5 秒，工具级可以覆盖。这个值不是拍脑袋定的。大模型生成 tool call 之后，整个链路如果超过 5 秒，用户感知就会明显变差。而且工具调用往往不是单次，Agent 可能连续调用两三个工具才能回答一个问题，单个工具 3 到 5 秒的上限比较合理。实时性要求高的查询类工具建议设置 2 到 3 秒，跑批类的工具可以放宽到 30 秒以上。

重试策略要分场景。幂等的查询接口可以放心重试，默认 2 次退避重试，间隔 200 毫秒起步，指数递增；非幂等的创建类操作，比如下订单、发消息，默认不重试，避免重复执行造成业务事故。这算是我用了好几个版本后觉得最该坚持的设计，宁可结果失败返回给模型让它换招，也不能在不确定状态下乱重试。

限流和熔断是网关版新增的重点。可以按工具维度限制每秒调用次数，也可以按来源 Agent 维度限制，还可以结合 token 消耗做预算控制。熔断则采用滑动窗口，连续失败率达到 50% 且最小请求数超过 10 次，就熔断该工具 30 秒，后续请求直接返回失败，不再打到后端，让下游喘息。配置片段如下：

execution: default: timeout_ms: 5000 retry: max_attempts: 2 backoff_ms: 200 multiplier: 2.0 conditions: [timeout, 5xx, connection_error] tools: order_query: timeout_ms: 3000 retry: max_attempts: 3 order_create: retry: max_attempts: 0

3. 实操：用 v0.10.0 把真实工具接入网关

3.1 部署与初始化：从 Docker 到第一个工具

v0.10.0 提供了 Docker 镜像，推荐的方式是用 Compose 跑起来网关加一个默认的演示工具服务。我在一台 4C8G 的机器上实测，网关本身占用资源很小，空闲时内存大概 300MB 左右，主要是启动时的 Schema 解析和路由表加载占一点 CPU。

一个最小部署配置：

services: hermes-gateway: image: hermes/tool-gateway:v0.10.0 ports: - "8080:8080" - "9090:9090" environment: HERMES_DATA_DIR: /data HERMES_ADMIN_TOKEN: admin-token-xxx volumes: - ./data:/data

启动后用管理接口创建一个命名空间，命名空间用来隔离不同业务团队的 Agent。然后注册第一个工具。我把一个内部天气接口接进去测试，前后花了不到十分钟，包括写描述、调参数、试调用三个步骤。

初始化完成后，健康检查接口在GET /healthz，管理接口在GET /api/v1/tools可以列出所有工具。试调用接口是POST /api/v1/tools/{name}/invoke，传入参数 JSON，网关会直接调用后端并返回标准结果。这一步很重要，可以在不经过模型的情况下单独验证工具链路。

3.2 把现有 OpenAPI 定义批量转成工具

很多团队不是没有工具，而是有一堆现成的 HTTP API。逐个手写工具注册信息太累，v0.10.0 提供了一个导入转换器，可以直接读取 OpenAPI 3.0 定义，把每个 operation 自动生成工具。

我试过一个包含 20 多个接口的订单服务，用了官方的转换命令行，过程大致是：

hermes-tools import openapi \ --spec ./order-service.json \ --namespace order-svc \ --base-url https://internal.example.com \ --auth-ref order-token

转换完成后网关打印了生成的工具清单，包括路径、方法、参数映射。有几个注意点值得说下。OpenAPI 里的operationId默认作为工具名，如果你的接口没有写 operationId，网关会从路径和方法名组合生成，这种名字通常很难读，建议先统一补 operationId。另一个是 OpenAPI 中的 query 参数会被转成工具参数，但嵌套的 body 对象在某些写法下会变成扁平的字段，嵌套层级较深时会丢失结构，需要手工调一下 Schema。

批量转换并不意味着万事大吉，自动生成的描述往往就是接口摘要那几句话，对模型选工具帮助不大。我的习惯是导入后先跑一遍测试集，看工具选择召回率，再针对选错的工具手工优化描述。

3.3 接入 MCP Server 的完整路径

MCP 是最近绕不开的话题。v0.10.0 的 MCP Bridge 支持以 SSE 方式连接远程 MCP Server，也支持本地进程以 stdio 方式启动。

先看远程 MCP 的配置，比如一个部署在内部的知识库工具服务器：

mcp_servers: - name: knowledge-base transport: sse url: https://mcp-internal.example.com/sse auth: type: bearer token_ref: mcp-kb-token

网关启动后会向 MCP Server 请求工具列表，自动生成对应的网关工具。完成之后列工具接口就能看到一批knowledge-base_*前缀的工具。这个前缀很重要，可以避免不同 MCP Server 之间工具重名冲突。

本地 MCP 用 stdio 方式时，配置稍有不同，需要指定启动命令和工作目录：

mcp_servers: - name: local-code-runner transport: stdio command: /opt/hermes-tools/code-runner args: ["--port", "0"] cwd: /opt/hermes-tools

实测中 ssh 远程 MCP 调试还算顺利，但 stdio 方式需要保证网关进程对命令有可执行权限，且子进程日志没有接入 stdin 造成阻塞，否则网关可能一直等待子进程输出。遇到 MCP 工具丢失的情况，优先检查网关日志里有没有mcp handshake failed，多半是 MCP Server 地址不通或者认证过期。

4. 安全与可观测性：工具网关最容易忽略的两件事

4.1 权限模型：谁可以让模型调用什么

工具暴露给模型之后，权限控制就不是“这个接口要不要登录”这种级别了，而是“模型在什么条件下可以调用哪些工具”。v0.10.0 的权限模型设计了三个维度：

第一个维度是 Agent 来源维度。每个 Agent 调用网关时携带自身的 Client ID，网关据此判断该 Agent 能访问哪些命名空间和工具。比如客服 Agent 只能调订单查询、退款查询，不能调内部员工信息查询。

第二个维度是字段级脱敏。工具返回的数据经常包含敏感信息，模型拿到之后可能无意间透露给用户。网关允许配置返回字段的脱敏规则，例如订单对象的buyer_phone字段在返回前自动替换成138****1234。这一步是在后端返回和模型接收之间插入的，工具方不需要配合修改。

第三个维度是人工审批触发条件。某些高风险操作，比如转账、删除数据，可以配置为“需要管理员审批后才真正执行”。网关支持两类：一类是调用前审批，Agent 请求先挂起并发送审批通知，审批通过才真正调后端；另一类是事后审计，调用直接放行但标记为高风险。我的建议是创建类操作一律事前审批，查询类操作做好脱敏加审计就够了，事前审批加太多会把整个 Agent 的交互体验拖垮。

4.2 审计日志与全链路追踪

工具调用的日志跟普通 API 日志最大的不同，在于必须建立“会话—消息—工具调用”三层关联。用户问一句话，可能触发模型连着调三个工具，每个工具调用成功还是失败、耗时多久、返回值多大，这些最终要归到同一个会话里。

v0.10.0 在审计日志中默认记录：调用时间、Agent ID、工具名称、工具版本、入参摘要、出参摘要、状态码、耗时、重试次数、熔断标记、费用预估。入参摘要和出参摘要默认只保留前 200 个字符，避免大字段把日志打爆。这个设计很实用，否则一个向量检索工具返回的 10 万字符内容直接写进日志，一周就能把磁盘吃完。

追踪方面，网关集成了 OpenTelemetry，可以导出 trace 到 Jaeger 或 Grafana Tempo。每个工具调用会生成一个独立 span，包含从模型发起请求到后端响应全过程的耗时分解。我排查过一次“工具偶尔变慢”的问题，靠 trace 立刻定位到是后端连接池配置过小，而不是网关的问题。

可观测性还有一个实用功能是成本归集。每个工具调用可以配置对应的成本单价，按 token 消耗和后端调用次数估算费用。月底对账的时候，管理员面板可以直接按命名空间、按工具维度导出消耗报表，不确定费用归属的时候很有用。

5. v0.10.0 升级避坑与常见问题排查

5.1 从旧版本迁过来的 Breaking Changes

如果你已经在用旧版本的 Hermes，直接升到 v0.10.0 需要注意几个破坏性变更，我升级第一轮就踩了两个。

第一个是配置文件格式调整。旧版里工具定义和策略配置分散在两个文件，v0.10.0 统一收敛到config.yaml下单块结构。启动时会做兼容解析，但日志里会打出 deprecated 警告，如果使用了旧字段，建议按警告信息逐步迁移，而不是直接静默忽略。

第二个是默认路由策略变了。旧版对 HTTP 工具默认使用 GET 请求，新版改为 POST，并且会把工具参数放在 JSON Body 里。如果你的后端接口只支持 GET 且改动成本高，需要在工具定义里显式声明method: GET。这个变更思路其实是让网关适配更复杂的参数结构，但确实对存量工具不友好。

第三个是管理 API 的鉴权变严格了。旧版管理接口裸奔也能访问，新版默认要求配置HERMES_ADMIN_TOKEN，没配置的时候启动直接失败，而不是给一个警告继续跑。这对安全是好事，但自动化脚本里如果漏了环境变量，升级后会发现一连串部署失败。

5.2 高频问题排查速查表

结合这段时间的实际使用，我把常见问题整理成一张表，方便后面遇到时直接定位。

还有一个小技巧：网关保存了每次工具调用的原始请求和响应。排查参数类问题时，不要只看模型侧日志，直接查网关里的原始记录，比任何猜测都有效。

5.3 我个人的使用体会

这个版本改下来，我最大的感受是“工具网关”这个抽象是对的。以前每接一个工具，就要说服业务方接受一堆 Agent 框架的约束，现在他们只需要提供一个接口，后面的认证、限流、日志都不是他们操心的事。接入速度明显变快，权限也集中收口了。

如果你也要上工具网关，我的建议是第一批先接查询类、幂等类的低风险工具，跑通链路、验证权限模型和审计日志，再逐步扩大范围。工具描述多花点心思打磨，后面能省下大量调 prompt 的时间。MCP 适配器值得尽早试用，现在生态里已经有很多现成 MCP Server，接进来就能用，比自己造接口省事得多。

最后分享一个配置小细节：网关有个request_body_limit参数，默认 4MB。之前接入一个文档分析工具，返回内容一大就报 413，排查半天才发现是默认请求体上限卡住了。如果你也接了大返回的工具，记得先把这个值调大，别等线上出问题再翻文档。