Hermes Agent 架构研读笔记

这个仓库用于整理我对 hermes-agent 项目的源码研读、架构拆解与设计分析。内容不是官方文档翻译，而是基于实际代码结构做出的主题化研究，重点关注这个项目如何把一个功能完整的 Agent 系统组织成可运行、可扩展、可治理的工程。

仓库定位

这份笔记主要回答几个问题：

• hermes-agent 为什么值得研究
• 它的核心架构是如何分层和协作的
• 一个生产级 Agent 系统通常需要哪些关键模块
• 如果将来用 Go 或其他语言重构，可以复用哪些设计思路

整体上，这组文档不是“按目录扫源码”，而是按架构主线来理解系统。

研究方法

本仓库采用“五条主线拆解法”来分析 hermes-agent：

1. Agent Loop：核心调度与推理执行循环
2. Tool Registry：工具注册、暴露与调用系统
3. SessionDB / Memory：会话状态与长期记忆系统
4. Gateway：多平台接入与消息标准化系统
5. Security / Approval：安全控制、审批与执行隔离系统

这种拆法的目标，是把一个复杂的 Agent 工程拆成职责相对清晰、边界相对稳定的几个核心模块，便于阅读、复盘和后续重构。

文档导航

• 主线拆解思路
• 主线一：Agent Loop 主循环
• 主线二：Tool Registry 工具系统
• 主线三：SessionDB / Memory 记忆系统
• 主线四：Gateway 多平台接入系统
• 主线五：Security / Approval 安全治理系统
• 项目研讨笔记

核心结论

基于当前文档分析，我对 hermes-agent 的总体判断是：

• 它不是一个演示型 Agent 项目，而是明显面向真实使用场景的工程化实现。
• 它的核心价值不只在“会不会调模型”，而在于把 Agent Runtime、Tools、Memory、Gateway 和 Security 串成了完整闭环。
• 它比较适合用来学习“生产级 Agent 系统需要哪些横切能力”，尤其是多平台接入、审批机制、会话持久化和工具治理。
• 它的很多设计都具有可迁移性，后续如果做 Go 重构、平台化改造或企业内部 Agent 框架抽象，都有较高参考价值。

适合谁阅读

这份笔记适合以下读者：

• 想系统理解 Agent 工程架构的开发者
• 想从开源项目中提炼可复用设计模式的工程师
• 准备做 Agent 平台、工具编排或多渠道接入的团队
• 想把现有 Python Agent 系统迁移或重构到 Go / Java / Rust 等语言的人

阅读建议

推荐阅读顺序：

1. 先看 主线拆解思路，建立整体分析框架
2. 再看五条主线文档，理解各模块职责与交互边界
3. 最后看 项目研讨笔记，作为整体总结与架构判断

后续计划

后续我会继续在这份笔记上补充：

• 更细的源码入口索引
• 模块之间的调用链与时序关系
• 与 OpenAI Agents SDK、Anthropic、Google ADK 等方案的对比
• 如果用 Go 重构时的模块划分建议与实现思路

English Version

For English readers, see README_EN.md.