从零手写 AI Agent：Learn Hermes Agent 深度解析

一、痛点切入：当市面上的 Agent 教程都在「Hello World」

如果你是 AI 开发者，有没有被这样的教程困扰过——学完了能跟 AI 聊两句天，却不知道怎么做真正能用的 Agent？大多数开源教程止步于「给模型发送一条消息，收到回复」，而真实场景中你需要：对话持久化、工具系统、记忆管理、权限控制、跨平台接入、自我进化……

Learn Hermes Agent 正是为了解决这个认知断层而生的教学项目。它不走「演示 Demo」路线，而是带你从 0 到 1 手写一个生产级自主 AI Agent 的全部核心机制。

二、项目背景与作者

该项目由 GitHub 用户 longyunfeigu 创建，2025-2028 年持续维护，积累 183 Stars，MIT 许可证，完全开源。项目以 Hermes Agent 为蓝本进行教学重构——不追求逐行复制源码，而是抓住真正决定 Agent 能力的核心设计决策。

项目特点鲜明：27 个可独立运行的章节脚本（agents/s01_*.py ~ s27_*.py），每个章节配套中英双语文档（docs/en/ + docs/zh/），边读边跑，边跑边改。

三、技术架构：五层分层设计

这是本项目区别于一般 Agent 教程的核心所在。作者将 Hermes Agent 提炼为五层架构，每层职责清晰，层与层之间通过接口通信，新增能力不需要修改核心循环：

层级	职责	代表组件
Entry Layer	统一消息入口	CLI / Telegram / Discord / Slack / WeChat 等 15+ 平台适配器
Core Loop Layer	核心对话循环	s01_agent_loop.py — 同步循环 + 事件桥接异步工具
Tool & Intelligence Layer	工具注册与智能	ToolRegistry / Memory / Skills / Permission
Execution Environment Layer	执行环境抽象	Local / Docker / SSH / Modal / Daytona
Persistence Layer	状态持久化	SQLite + FTS5 / MEMORY.md / Skills 文件

关键洞察：无论消息来自 Telegram 还是终端，核心循环完全一样。跨平台的秘密在于：只替换 Entry Layer 的适配器，Core Loop Layer 不变。

五层架构图 图1：Hermes Agent 五层架构（来源：项目文档）

消息流程图 图2：消息在系统中的完整流转路径（来源：项目文档）

四、核心机制详解

4.1 Agent Loop（s01）

最简单的 Agent 循环：调用模型 → 接收 tool_calls → 执行工具 → 回填结果 → 继续迭代。s01 用约 100 行代码实现了这个最小版本：

client = OpenAI(base_url=BASE_URL, api_key=API_KEY)
# 1. 发送消息给模型
response = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS)
# 2. 提取工具调用
if response.usage.tool_calls:
    for tool_call in response.usage.tool_calls:
        result = run_tool(tool_call.function.name, tool_call.function.arguments)
        messages.append({"role": "tool", "tool_call_id": tool_call.id, "content": result})
# 3. 循环直到模型停止请求工具

4.2 Tool System（s02）

工具系统采用自注册模式——每个工具文件在 import 时自动调用 registry.register()，新增工具不需要修改循环代码：

# 工具定义：OpenAI Function Calling 格式
TOOLS = [{"type": "function", "function": {
    "name": "terminal",
    "description": "Run a shell command",
    "parameters": {"type": "object", "properties": {"command": {"type": "string"}}}
}}]

# 注册表：name -> (schema, handler)
registry = ToolRegistry()
registry.register(name="terminal", toolset="system", schema=TOOLS[0], handler=run_terminal)

4.3 Session Store（s03）

对话历史存入 SQLite + FTS5 全文检索，支持 WAL 模式并发读写，重启不丢失。这解决了 Gateway 场景下多平台同时发消息的并发写入问题。

4.4 Skill System（s08）

Skills 采用了按需加载策略：系统提示词中只放 name + description（成本低），模型判定需要某个 Skill 时再通过 skill_view 读取完整内容。Skill 文件遵循 Hermes 规范（SKILL.md 前置元数据 + 正文），存于 HERMES_HOME/skills/<name>/。

4.5 Gateway 多平台接入（s12）

Gateway 是 Entry Layer 的核心抽象，通过 BasePlatformAdapter 接口协议，Telegram、Discord、Slack、WeChat 等平台适配器实现统一的消息格式转换（MessageEvent），同一个 Agent 实例可同时服务多个平台。

4.6 MCP 集成（s16）

支持 Model Context Protocol：外部进程暴露的工具注册到同一 registry，Agent 感知不到内置工具与 MCP 工具的差异，实现外部能力无缝接入。

五、学习路径：五阶段渐进式

项目设计了清晰的五阶段学习路径，每阶段完成后停下来自己手写最小实现，再进入下一阶段：

阶段	目标	核心章节
阶段 1	做出能工作、能持久化的单 Agent	s01~s06
阶段 2	补智能层 — 记忆、技能、安全、委派、配置	s07~s11
阶段 3	跨平台 — Gateway、适配器、终端后端、定时任务	s12~s15
阶段 4	高级能力 — MCP、浏览器、语音、视觉、后台审视	s16~s20
阶段 5	自我进化 — 技能创作、Hook、轨迹/RL、插件自进化	s21~s27

六、上手门槛与部署

配置极简：只需要 .env 文件设置 OPENAI_API_KEY（走 OpenRouter）或直接配置其他 OpenAI 兼容端点。依赖仅 4 个包（openai、PyYAML、fastapi、uvicorn），pip install -r requirements.txt 即可运行。

部署难度：纯教学代码库，通过 Python 脚本直接运行，无需 Docker。不提供容器化文件，部署支持分 1/5。适合有 Python 基础的开发者本地学习研究。

硬件需求：CPU 友好，无需 GPU，512MB 内存 + 200MB 磁盘即可运行完整 Agent。

七、局限与争议

局限一：非生产就绪。作为教学项目，s01~s27 的脚本侧重展示原理，最小实现不等于生产最优实践。例如 s01 的命令黑名单仅检查字符串包含，生产环境需要正则+审批工作流（s09 才引入）。

局限二：API Key 管理。项目要求用户自行准备 LLM API Key，且 Key 明文写在 .env 中，本地安全性依赖文件系统权限管理。

争议点：部分开发者认为 27 章节过于细分，每个脚本都重新定义配置和 registry，可能造成初学者「只会运行示例脚本，不会独立写自己的工具」的困境。项目文档也承认了这一点，建议读者每阶段后自己手写最小版本。

八、行业意义

在 Agent 框架层出不穷的 2025-2026 年，这个项目的价值不在于又造了一个框架，而在于把黑盒变成白盒。大多数 Agent 框架（Hugging Face Agents、LangChain Agents 等）用户只知道「调用了工具」，不知道工具系统怎么设计、记忆怎么管理、上下文怎么压缩——该项目用 27 个可运行的最小版本，把这些隐藏决策全部显式化。

项目的中英双语教学设计（docs/en/ + docs/zh/ 各 27 篇文档）也降低了全球开发者的学习门槛，在开源 Agent 教学领域具有独特定位。

从零手写 AI Agent：Learn Hermes Agent 深度解析

一、痛点切入：当市面上的 Agent 教程都在「Hello World」

二、项目背景与作者

项目特点鲜明：27 个可独立运行的章节脚本（agents/s01_*.py ~ s27_*.py），每个章节配套中英双语文档（docs/en/ + docs/zh/），边读边跑，边跑边改。

三、技术架构：五层分层设计

层级	职责	代表组件
Entry Layer	统一消息入口	CLI / Telegram / Discord / Slack / WeChat 等 15+ 平台适配器
Core Loop Layer	核心对话循环	s01_agent_loop.py — 同步循环 + 事件桥接异步工具
Tool & Intelligence Layer	工具注册与智能	ToolRegistry / Memory / Skills / Permission
Execution Environment Layer	执行环境抽象	Local / Docker / SSH / Modal / Daytona
Persistence Layer	状态持久化	SQLite + FTS5 / MEMORY.md / Skills 文件

关键洞察：无论消息来自 Telegram 还是终端，核心循环完全一样。跨平台的秘密在于：只替换 Entry Layer 的适配器，Core Loop Layer 不变。

五层架构图 图1：Hermes Agent 五层架构（来源：项目文档）

消息流程图 图2：消息在系统中的完整流转路径（来源：项目文档）

四、核心机制详解

4.1 Agent Loop（s01）

最简单的 Agent 循环：调用模型 → 接收 tool_calls → 执行工具 → 回填结果 → 继续迭代。s01 用约 100 行代码实现了这个最小版本：

client = OpenAI(base_url=BASE_URL, api_key=API_KEY)
# 1. 发送消息给模型
response = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS)
# 2. 提取工具调用
if response.usage.tool_calls:
    for tool_call in response.usage.tool_calls:
        result = run_tool(tool_call.function.name, tool_call.function.arguments)
        messages.append({"role": "tool", "tool_call_id": tool_call.id, "content": result})
# 3. 循环直到模型停止请求工具

4.2 Tool System（s02）

工具系统采用自注册模式——每个工具文件在 import 时自动调用 registry.register()，新增工具不需要修改循环代码：

# 工具定义：OpenAI Function Calling 格式
TOOLS = [{"type": "function", "function": {
    "name": "terminal",
    "description": "Run a shell command",
    "parameters": {"type": "object", "properties": {"command": {"type": "string"}}}
}}]

# 注册表：name -> (schema, handler)
registry = ToolRegistry()
registry.register(name="terminal", toolset="system", schema=TOOLS[0], handler=run_terminal)

4.3 Session Store（s03）

对话历史存入 SQLite + FTS5 全文检索，支持 WAL 模式并发读写，重启不丢失。这解决了 Gateway 场景下多平台同时发消息的并发写入问题。

4.4 Skill System（s08）

4.5 Gateway 多平台接入（s12）

4.6 MCP 集成（s16）

支持 Model Context Protocol：外部进程暴露的工具注册到同一 registry，Agent 感知不到内置工具与 MCP 工具的差异，实现外部能力无缝接入。

五、学习路径：五阶段渐进式

项目设计了清晰的五阶段学习路径，每阶段完成后停下来自己手写最小实现，再进入下一阶段：

阶段	目标	核心章节
阶段 1	做出能工作、能持久化的单 Agent	s01~s06
阶段 2	补智能层 — 记忆、技能、安全、委派、配置	s07~s11
阶段 3	跨平台 — Gateway、适配器、终端后端、定时任务	s12~s15
阶段 4	高级能力 — MCP、浏览器、语音、视觉、后台审视	s16~s20
阶段 5	自我进化 — 技能创作、Hook、轨迹/RL、插件自进化	s21~s27

六、上手门槛与部署

部署难度：纯教学代码库，通过 Python 脚本直接运行，无需 Docker。不提供容器化文件，部署支持分 1/5。适合有 Python 基础的开发者本地学习研究。

硬件需求：CPU 友好，无需 GPU，512MB 内存 + 200MB 磁盘即可运行完整 Agent。

七、局限与争议

局限二：API Key 管理。项目要求用户自行准备 LLM API Key，且 Key 明文写在 .env 中，本地安全性依赖文件系统权限管理。

八、行业意义

项目的中英双语教学设计（docs/en/ + docs/zh/ 各 27 篇文档）也降低了全球开发者的学习门槛，在开源 Agent 教学领域具有独特定位。