Hermes Agent 运行时：AIAgent、模型协议与工具执行
内容提要
本文介绍Hermes Agent运行时架构，聚焦模型—工具循环。核心组件包括：AIAgent作为会话组合根，Provider Transport隔离模型协议差异，Tool Registry管理工具注册与执行管线。工具通过Toolset按会话过滤，Tool Search渐进披露MCP工具Schema以节省上下文。工具调用经参数修正、钩子、审批、分派等流程，最终由Environment决定执行位置。
延伸解读
工具执行位置由环境决定
同一工具名在不同模式下执行位置不同：本地模式在用户机器，SSH/云模式在远端沙箱。UI能力（窗口、剪贴板）留在本机，而终端、文件、代码工具在远端。理解这一点有助于排查路径、权限和网络问题，避免误以为工具行为一致。
Tool Search 的渐进披露机制
当MCP工具过多时，完整Schema常驻会占用大量上下文。Tool Search通过桥接工具（tool_search、tool_describe、tool_call）按需披露，模型先看到名称和描述，再按需获取详细Schema。这平衡了上下文效率与能力可见性，但模型需学会使用这些桥接工具，可能影响交互效率。
工具注册的完整契约
工具注册不仅包含handler，还声明Schema、可用性检查、环境依赖等。check_fn决定工具是否出现在模型视野中，并缓存结果以应对服务抖动。这提醒开发者：工具不仅是函数，还需考虑参数校验、审批、审计等，确保安全与稳定。
Q&A
Hermes Agent 运行时中 AIAgent 的核心职责是什么？
AIAgent 是会话运行时的组合根，保存模型客户端、工具快照、上下文引擎、记忆管理器、SessionDB、迭代预算、回调、中断状态和会话级计数，并负责协调对话循环、工具执行和上下文压缩等模块。
Provider Transport 在 Hermes Agent 中起什么作用？
Provider Transport 负责隔离不同模型协议的差异，核心接口包括 convert_messages、convert_tools、build_kwargs 和 normalize_response，将内部消息转换为供应商格式，并将响应归一化回内部对象，避免主循环直接处理各家供应商的原始结构。
Hermes Agent 中 Tool Registry 为什么不仅仅是函数表？
Tool Registry 除了注册 handler，还管理工具的名称、toolset、JSON Schema、可用性检查、环境依赖、异步标记、结果大小限制和动态 Schema 覆盖，并集中处理参数契约、作用域、审批、插件决策、错误封装和审计，因此是一个小型应用服务器。
Tool Search 如何节省上下文？
Tool Search 通过渐进披露机制，只将 Hermes 核心工具的完整 Schema 直接发送给模型，而 MCP 工具和非核心 Plugin 工具则延迟披露，模型仅常驻看到 tool_search、tool_describe、tool_call 三个桥接 Schema，并根据目录预算选择 Tier 1 或 Tier 2 策略，从而减少每轮请求的固定输入。
Hermes Agent 中工具最终在哪里执行？
工具执行位置由 Environment Backend 决定，可以落在 local、Docker、Singularity、Modal、Daytona、Vercel Sandbox 或 SSH 等环境。在远程模式下，Terminal、文件和代码工具在远端项目环境执行，而窗口、剪贴板、通知等 UI 能力留在本机。
Hermes Agent 中 Toolset 的作用是什么？
Toolset 将 file、terminal、browser、memory、web 等能力组合起来，并根据入口、平台、Profile 和用户配置求出本会话的工具快照，从而决定模型本轮可见的工具，实现能力属于会话而非进程。
Hermes Agent 中一次工具调用经过哪些流程？
一次工具调用依次经过参数修正与作用域检查、请求中间件、工具调用前钩子、人工审批（如果需要）、注册表分派、结果规范化、post Hook 与结果变换，最后写回 Tool Message。
Hermes Agent 中 check_fn 的作用是什么？
check_fn 用于检查工具依赖、凭据或外部服务是否可用，如果不可用，该工具就不会出现在模型的 Schema 中。当前实现会短时缓存检查结果，并保留最近一次成功判断来吸收瞬时抖动。
