导读大多数 agent 教学项目教的是一个人在终端里和 AI 对话。但生产级 agent 要面对多平台并发、跨重启记忆、自我进化。本文从真实可运行的 Hermes 教学仓库出发拆解一个生产级自主 agent 的五层架构并带你走完一条消息从入口到持久化的完整旅程为整个系列画好全局地图。你学过的 agent 教程可能漏掉了最重要的事先问自己一个问题你见过的 agent 项目是不是长这样一个while True循环里面调模型、调工具、再调模型。看起来挺对但一旦你要把它部署到 Telegram 上同时服务 100 个用户再让它跨重启记住昨天聊了什么这个循环工具的架构就崩了。Hermes Agent 从一开始就没走这条路。它是一套跨平台的自主 agent同一套核心循环可以挂在 Telegram、Discord、微信、飞书等 15 平台命令可以在 Docker、SSH、云端执行对话持久化到 SQLite支持全文搜索。更特别的是agent 能自己创建编辑技能文件每 10 轮自动 fork 一个后台副本审视对话、更新记忆。模型接入走 OpenAI 兼容接口支持 200 家提供商。这套能力的背后是一张清晰的分层架构。五层架构从上到下每层只干一件事生产级 agent 由五层组成从上到下各司其职。第一层入口层——用户从哪里来CLI、Telegram、Discord、微信……每个入口的交互方式完全不同但它们都做同一件事把用户输入统一成同一种内部格式交给核心循环。第二层核心循环层——agent 的大脑模型思考 → 调工具 → 结果回写 → 继续。这是整个系统的心脏。注意一个细节核心循环是同步的异步工具通过事件循环桥接。第三层工具与智能层——能力目录工具自注册、记忆、技能、审批。这一层最大的特点是添加新工具不需要修改核心循环代码。工具文件被导入时自动登记到注册表核心循环只认注册表。第四层执行环境层——命令在哪里跑本地、Docker、SSH、云端。这一层是抽象接口对上层完全透明。上层只管说执行这条命令至于命令跑在哪由环境层决定。第五层持久化层——跨重启存活SQLite 会话、MEMORY.md、技能文件。对话记录、长期记忆、技能定义全部落盘。agent 重启后一切照旧。一条消息的完整旅程CLI 场景 8 步光看架构图不够我们跟着一条消息走一遍完整流程。假设你在终端输入了一句话接下来发生这些事用户在终端输入一句话CLI 创建 AIAgent 实例AIAgent 组装 system promptSOUL.md人设 MEMORY.md / USER.md记忆 HERMES.md 或 AGENTS.md项目配置 工具定义和技能清单messages system prompt tools 一起发给模型 APIOpenAI SDK所有提供商同一个接口模型返回纯文本 → 显示结束tool_calls → 继续对每个 tool_call查工具注册表 → 危险命令检测 → 执行 → 结果以 tool 角色写回回到第 4 步继续下一轮循环结束后整个会话持久化到 SQLite注意第 5 步里的危险命令检测生产级 agent 不会让你在终端里随便执行rm -rf /。Gateway 场景同一个核心不同入口那 Telegram 上的消息怎么走区别只在入口和出口。Gateway 场景下适配器收到消息 → 转统一格式 → Gateway 按 chat_id 找到或创建会话 → 创建 AIAgent 实例 → 后面和 CLI 完全一样 → 回复经适配器发回。区别只在入口和出口核心循环完全一样。这正是分层的价值核心逻辑写一遍就能挂到所有平台。五个关键设计决策为什么这样做1. OpenAI SDK 作为唯一 API 客户端不同提供商只是不同的 base_url。从 OpenRouter 切到 Anthropic 或本地端点不改一行代码只改配置。所有消息统一用 OpenAI 格式role / tool_calls / tool_call_id。2. 核心循环是同步的大部分工具文件读写、终端命令本身是同步的。同步循环错误处理和调试简单。少量异步工具通过持久化事件循环桥接。模式可以概括为同步主体 异步桥接。3. 工具用自注册而非中心配置工具文件被导入时自动调用注册表 register() 登记。导入链注册表不依赖工具 → 工具依赖注册表 → 编排层导入所有工具触发注册 → 核心循环使用编排层。加新工具只写一个文件什么都不用改。4. SQLite 而非文件系统Gateway 场景下多平台消息可能同时到达。WAL 模式支持并发读写FTS5 支持全文搜索历史会话。5. agent 能改自己这是区别于 LangChain / AutoGen 的核心。三个机制Background Review每 N 轮 fork 后台副本审视对话自动更新 MEMORY.md / USER.md 或创建 skillSkill 创作闭环skill_manager_tool 创建、编辑、补丁自己的 skillTrajectory RL 流水线对话轨迹压缩成训练数据运行时生效学习 离线生效进化 用 → 记 → 抽象 → 训练 → 更好地用。关键状态存在哪里理解 agent 架构最重要的是知道每个状态存在哪。messages→ 当前对话运行时session→ 对话持久化SQLitememory→ 跨会话知识文件 MEMORY.md / USER.mdconfig→ 运行配置YAML 环境变量工具注册表→ 能力目录工具名 → 处理函数映射SOUL.md / MEMORY.md / HERMES.md→ 长期上下文人设 / 记忆 / 项目配置执行环境→ 命令在哪跑抽象接口对上层透明把这四层分清就不会把当前对话和长期记忆混为一谈。五阶段学习路径从能跑的单 agent 到自我进化这个仓库把整个学习过程拆成五个阶段共 27 章s01~s27其中 26 章配有可运行的 Python 参考实现s24 插件架构仅有文档可独立阅读。阶段章节目标1s01-s06做出能跑的单 agent对话循环、工具注册、SQLite 持久化、提示词组装、上下文压缩、错误恢复2s07-s11补智能和安全记忆、技能管理、危险命令审批、子 agent 委派、配置系统3s12-s15接入多平台Gateway 架构、平台适配器、终端后端抽象、定时任务4s16-s19高级能力MCP、浏览器自动化、语音视觉、CLI 与 Web 界面5s20-s24自我进化与生产化后台审视、技能创作闭环、Hook 系统、trajectory 与 RL、Plugin 架构怎么读这个仓库关键在累进式快照agents/sXX.py是完整可运行的每章都包含前面所有章节的代码。你不用翻前面的文件直接看最新的即可。learn-hermes-agent/ ├── agents/ # 每章一个可运行的 Python 参考实现s01~s27 ├── docs/zh/ # 中文主线文档 ├── docs/en/ # 英文文档 ├── illustrations/ # 每章配套黑板风格概念插图 ├── tests/ # 冒烟测试 ├── web/ # Web 教学平台可选 ├── .env.example └── requirements.txt # 仅 4 个依赖openai / PyYAML / fastapi / uvicorn依赖只有 4 个跑起来不会有什么环境噩梦。避坑三个最容易卡住的地方Gateway 和 CLI 是竞争关系吗不是。它们是同一个核心循环的两个不同入口这一点想通了分层架构的核心价值也就理解了。工具、技能、MCP 有什么区别工具硬编码在代码里的能力技能agent 运行时可创建编辑的能力文件MCP通过外部协议接入的第三方能力三者是不同层级的扩展机制不是一回事。为什么这么多配置来源不同场景需要不同配置CLI 开发、Telegram 生产、Docker 隔离。用优先级链合并而不是硬编码。小结架构的价值在于应对复杂性回到开头的问题。为什么不是一个循环一堆工具因为生产环境是复杂的多平台并发、跨重启记忆、自我进化、安全审批都不是一个循环能解决的。五层架构让每一层只关心自己的事层与层之间通过清晰的接口协作。下一篇逐行拆解百行的 Agent Looprun_conversation 同步循环看看核心循环到底是怎么写的。如果你正在从零搭建自己的 agent或者想理解 LangChain 这类框架底层到底封装了什么欢迎在评论区聊聊你目前卡在哪一步。参考文献Hermes Agent 教学仓库docs/zh/s00-architecture-overview.md架构总览本文主要素材Hermes Agent 教学仓库README-zh.md学习路径与章节索引Hermes Agent 教学仓库docs/zh/data-structures.mdmessages / session / memory / config 四层状态需要源码在如下链接下载https://gitcode.com/ganxin7932508/learn-hermes-agent.git 【系列：手搓自主 AI Agent：Hermes 架构原理剖析 · 第 1 篇】
导读大多数 agent 教学项目教的是一个人在终端里和 AI 对话。但生产级 agent 要面对多平台并发、跨重启记忆、自我进化。本文从真实可运行的 Hermes 教学仓库出发拆解一个生产级自主 agent 的五层架构并带你走完一条消息从入口到持久化的完整旅程为整个系列画好全局地图。你学过的 agent 教程可能漏掉了最重要的事先问自己一个问题你见过的 agent 项目是不是长这样一个while True循环里面调模型、调工具、再调模型。看起来挺对但一旦你要把它部署到 Telegram 上同时服务 100 个用户再让它跨重启记住昨天聊了什么这个循环工具的架构就崩了。Hermes Agent 从一开始就没走这条路。它是一套跨平台的自主 agent同一套核心循环可以挂在 Telegram、Discord、微信、飞书等 15 平台命令可以在 Docker、SSH、云端执行对话持久化到 SQLite支持全文搜索。更特别的是agent 能自己创建编辑技能文件每 10 轮自动 fork 一个后台副本审视对话、更新记忆。模型接入走 OpenAI 兼容接口支持 200 家提供商。这套能力的背后是一张清晰的分层架构。五层架构从上到下每层只干一件事生产级 agent 由五层组成从上到下各司其职。第一层入口层——用户从哪里来CLI、Telegram、Discord、微信……每个入口的交互方式完全不同但它们都做同一件事把用户输入统一成同一种内部格式交给核心循环。第二层核心循环层——agent 的大脑模型思考 → 调工具 → 结果回写 → 继续。这是整个系统的心脏。注意一个细节核心循环是同步的异步工具通过事件循环桥接。第三层工具与智能层——能力目录工具自注册、记忆、技能、审批。这一层最大的特点是添加新工具不需要修改核心循环代码。工具文件被导入时自动登记到注册表核心循环只认注册表。第四层执行环境层——命令在哪里跑本地、Docker、SSH、云端。这一层是抽象接口对上层完全透明。上层只管说执行这条命令至于命令跑在哪由环境层决定。第五层持久化层——跨重启存活SQLite 会话、MEMORY.md、技能文件。对话记录、长期记忆、技能定义全部落盘。agent 重启后一切照旧。一条消息的完整旅程CLI 场景 8 步光看架构图不够我们跟着一条消息走一遍完整流程。假设你在终端输入了一句话接下来发生这些事用户在终端输入一句话CLI 创建 AIAgent 实例AIAgent 组装 system promptSOUL.md人设 MEMORY.md / USER.md记忆 HERMES.md 或 AGENTS.md项目配置 工具定义和技能清单messages system prompt tools 一起发给模型 APIOpenAI SDK所有提供商同一个接口模型返回纯文本 → 显示结束tool_calls → 继续对每个 tool_call查工具注册表 → 危险命令检测 → 执行 → 结果以 tool 角色写回回到第 4 步继续下一轮循环结束后整个会话持久化到 SQLite注意第 5 步里的危险命令检测生产级 agent 不会让你在终端里随便执行rm -rf /。Gateway 场景同一个核心不同入口那 Telegram 上的消息怎么走区别只在入口和出口。Gateway 场景下适配器收到消息 → 转统一格式 → Gateway 按 chat_id 找到或创建会话 → 创建 AIAgent 实例 → 后面和 CLI 完全一样 → 回复经适配器发回。区别只在入口和出口核心循环完全一样。这正是分层的价值核心逻辑写一遍就能挂到所有平台。五个关键设计决策为什么这样做1. OpenAI SDK 作为唯一 API 客户端不同提供商只是不同的 base_url。从 OpenRouter 切到 Anthropic 或本地端点不改一行代码只改配置。所有消息统一用 OpenAI 格式role / tool_calls / tool_call_id。2. 核心循环是同步的大部分工具文件读写、终端命令本身是同步的。同步循环错误处理和调试简单。少量异步工具通过持久化事件循环桥接。模式可以概括为同步主体 异步桥接。3. 工具用自注册而非中心配置工具文件被导入时自动调用注册表 register() 登记。导入链注册表不依赖工具 → 工具依赖注册表 → 编排层导入所有工具触发注册 → 核心循环使用编排层。加新工具只写一个文件什么都不用改。4. SQLite 而非文件系统Gateway 场景下多平台消息可能同时到达。WAL 模式支持并发读写FTS5 支持全文搜索历史会话。5. agent 能改自己这是区别于 LangChain / AutoGen 的核心。三个机制Background Review每 N 轮 fork 后台副本审视对话自动更新 MEMORY.md / USER.md 或创建 skillSkill 创作闭环skill_manager_tool 创建、编辑、补丁自己的 skillTrajectory RL 流水线对话轨迹压缩成训练数据运行时生效学习 离线生效进化 用 → 记 → 抽象 → 训练 → 更好地用。关键状态存在哪里理解 agent 架构最重要的是知道每个状态存在哪。messages→ 当前对话运行时session→ 对话持久化SQLitememory→ 跨会话知识文件 MEMORY.md / USER.mdconfig→ 运行配置YAML 环境变量工具注册表→ 能力目录工具名 → 处理函数映射SOUL.md / MEMORY.md / HERMES.md→ 长期上下文人设 / 记忆 / 项目配置执行环境→ 命令在哪跑抽象接口对上层透明把这四层分清就不会把当前对话和长期记忆混为一谈。五阶段学习路径从能跑的单 agent 到自我进化这个仓库把整个学习过程拆成五个阶段共 27 章s01~s27其中 26 章配有可运行的 Python 参考实现s24 插件架构仅有文档可独立阅读。阶段章节目标1s01-s06做出能跑的单 agent对话循环、工具注册、SQLite 持久化、提示词组装、上下文压缩、错误恢复2s07-s11补智能和安全记忆、技能管理、危险命令审批、子 agent 委派、配置系统3s12-s15接入多平台Gateway 架构、平台适配器、终端后端抽象、定时任务4s16-s19高级能力MCP、浏览器自动化、语音视觉、CLI 与 Web 界面5s20-s24自我进化与生产化后台审视、技能创作闭环、Hook 系统、trajectory 与 RL、Plugin 架构怎么读这个仓库关键在累进式快照agents/sXX.py是完整可运行的每章都包含前面所有章节的代码。你不用翻前面的文件直接看最新的即可。learn-hermes-agent/ ├── agents/ # 每章一个可运行的 Python 参考实现s01~s27 ├── docs/zh/ # 中文主线文档 ├── docs/en/ # 英文文档 ├── illustrations/ # 每章配套黑板风格概念插图 ├── tests/ # 冒烟测试 ├── web/ # Web 教学平台可选 ├── .env.example └── requirements.txt # 仅 4 个依赖openai / PyYAML / fastapi / uvicorn依赖只有 4 个跑起来不会有什么环境噩梦。避坑三个最容易卡住的地方Gateway 和 CLI 是竞争关系吗不是。它们是同一个核心循环的两个不同入口这一点想通了分层架构的核心价值也就理解了。工具、技能、MCP 有什么区别工具硬编码在代码里的能力技能agent 运行时可创建编辑的能力文件MCP通过外部协议接入的第三方能力三者是不同层级的扩展机制不是一回事。为什么这么多配置来源不同场景需要不同配置CLI 开发、Telegram 生产、Docker 隔离。用优先级链合并而不是硬编码。小结架构的价值在于应对复杂性回到开头的问题。为什么不是一个循环一堆工具因为生产环境是复杂的多平台并发、跨重启记忆、自我进化、安全审批都不是一个循环能解决的。五层架构让每一层只关心自己的事层与层之间通过清晰的接口协作。下一篇逐行拆解百行的 Agent Looprun_conversation 同步循环看看核心循环到底是怎么写的。如果你正在从零搭建自己的 agent或者想理解 LangChain 这类框架底层到底封装了什么欢迎在评论区聊聊你目前卡在哪一步。参考文献Hermes Agent 教学仓库docs/zh/s00-architecture-overview.md架构总览本文主要素材Hermes Agent 教学仓库README-zh.md学习路径与章节索引Hermes Agent 教学仓库docs/zh/data-structures.mdmessages / session / memory / config 四层状态需要源码在如下链接下载https://gitcode.com/ganxin7932508/learn-hermes-agent.git