00｜先别急着看代码：你到底在学什么是 Agent
先别急着钻进代码
很多人第一次接触 Agent，会有一个非常自然的误区：
把 Agent 理解成“会调用工具的大模型”。
这个说法不能算错，但它非常不够。
因为如果你只是把 Agent 理解成：
- 用户说一句话
- 模型想一想
- 模型决定要不要调工具
- 工具执行完再回给模型
那你其实只理解了 Agent 的一个横截面，还没有理解它为什么会在工程上变得越来越复杂。
真正值得你学的，不是“模型能不能调工具”这一个点，而是下面这件事：
怎么把一个本来只会生成文本的模型，改造成一个可以持续执行、可以被约束、可以跨会话延续、可以接入真实环境、还能在失败和风险里尽量稳定工作的系统。
这才是 Agent。
也是为什么我建议你在看 Hermes Agent 源码之前，先把概念站稳。
因为如果你没有先弄清楚“你到底在学什么”，后面你会非常容易陷入两种常见误区：
- 第一种，只盯 prompt，觉得 Agent 的本质就是提示词技巧
- 第二种，只盯 tool calling，觉得 Agent 的本质就是函数调用协议
这两种都只看到了局部。
而 Hermes Agent 这个项目最适合初学者的地方，恰恰在于它已经不只是一个 Demo，而是一个比较完整的 Agent Runtime。它会逼着你意识到：
真正的 Agent，不是一个 API 调用技巧，而是一套运行时工程。
1. 先把一个根误区拆掉：Agent 不等于“能调用工具的聊天机器人”
如果你看过不少 Agent 教程，会发现它们经常从一个非常小的例子开始：
- 给模型一组工具 schema
- 模型返回 tool_call
- 程序执行工具
- 再把结果发回模型
- 模型给出最后答案
这个例子当然有用，因为它让你第一次看见“模型不只是输出文本，还能驱动外部动作”。
但问题在于，很多人学到这里就停了。
于是脑子里形成的 Agent 图景会变成：
Agent = LLM + Tools
这句话的问题不在于错，而在于它太像“化学式”，不像“系统图”。
你用它无法解释很多现实问题：
- 为什么同样会调工具，有的 Agent 一到多轮任务就崩？
- 为什么有的 Agent 会话一长就开始前后矛盾？
- 为什么有的 Agent 在 CLI 里还行，搬到 Telegram / Discord 就一堆问题？
- 为什么有的 Agent 会因为一个危险命令、一个路径穿越、一个后台进程失控，直接从“聪明”变成“不可用”？
这些问题都说明，Agent 的关键不只是“会不会调工具”，而是：
它有没有一套围绕模型执行而设计出来的运行时约束。
从这个角度讲，Agent 更像什么？
我的建议是，你可以先把它理解成：
一个以大模型为核心决策器、以工具系统为外部行动面、以会话状态和上下文治理为持续性基础、以安全约束和执行编排为工程边界的运行系统。
这句话听起来很长，但你后面看 Hermes 源码时，会发现几乎每个目录都正好落在这几个词上。
2. Agent 真正比普通聊天更难的地方，在于它开始“碰真实世界”
普通聊天系统最主要处理的是文本。
你要关心的重点通常是：
- prompt 怎么写
- 历史消息怎么组织
- 输出怎么渲染
但一旦进入 Agent，系统的难度会突然上一个台阶。原因很简单：
它不再只是对话，而是开始碰真实世界。
所谓“真实世界”，在 Hermes 里其实很好理解，因为你能直接在仓库结构里看见这些边界：
tools/terminal_tool.py：开始执行命令tools/file_tools.py：开始读写文件tools/browser_tool.py：开始操作浏览器tools/send_message_tool.py：开始跨平台发消息cron/scheduler.py：开始按时间自动触发任务gateway/run.py：开始接入 Telegram、Discord、Slack、WhatsApp 等外部平台
一旦系统能做这些事，它就不是“回答问题”这么简单了。
它开始涉及：
- 状态一致性
- 权限边界
- 风险控制
- 长任务管理
- 多入口接入
- 历史恢复
- 失败重试
- 人机协作
换句话说，Agent 不是把 LLM 从“会说”变成“会做”这么简单。
它实际上是把软件系统从“生成结果”推进到“执行任务”。
只要跨过这一步，工程复杂度就会急剧上升。
这也是为什么学习 Agent，不能只学“提示词模板”，而要开始学“运行时设计”。
3. 对初学者来说，最重要的不是先学最炫的能力，而是先建立正确分层
很多人学 Agent，喜欢先看最炫的：
- 自动规划
- 多智能体协作
- 自主调用十几个工具
- 长链条自动化
但如果你是初学者，我反而建议你先把分层感建立起来。
为什么？
因为没有分层感，你看一个像 Hermes 这样的项目时，会把所有能力都糊成一团。
你会觉得：
- CLI、Gateway、Skills、Memory、Cron、Subagent、Session、Approval 都好像很重要
- 但又不知道它们各自属于哪一层
- 最后就只能机械地看文件，学不到结构
而一个比较稳的理解方式是，把 Agent 拆成下面几层：
3.1 决策循环层
这一层回答的是：
模型如何进入“模型输出 -> 执行动作 -> 再反馈给模型”的闭环。
在 Hermes 里，核心就是 run_agent.py。
3.2 能力暴露层
这一层回答的是：
系统有哪些工具、这些工具如何对模型可见、如何按平台和场景裁剪。
在 Hermes 里，核心是 model_tools.py、toolsets.py、tools/registry.py。
3.3 状态与连续性层
这一层回答的是：
会话怎么保存、历史怎么恢复、长期记忆和会话检索怎么区分。
在 Hermes 里，核心是 hermes_state.py、tools/memory_tool.py、tools/session_search_tool.py、gateway/session.py。
3.4 接入与交互层
这一层回答的是：
Agent 不只是活在终端里，还能通过哪些入口持续接入用户。
在 Hermes 里，核心是 cli.py 和 gateway/。
3.5 自动化与扩展层
这一层回答的是：
系统怎么学会长期工作、计划执行、技能复用、子代理拆任务、定时运行。
在 Hermes 里，对应 agent/skill_commands.py、tools/skills_tool.py、tools/delegate_tool.py、cron/。
3.6 安全与现实约束层
这一层回答的是：
真实可用的 Agent，如何避免自己把系统搞坏。
在 Hermes 里，对应 tools/approval.py、tools/path_security.py、tools/process_registry.py 等模块。
只要你先有这张分层地图，后面看源码就不会迷路。
4. 为什么我建议用 Hermes 学 Agent，而不是只看最小 Demo
最小 Demo 有一个很大的优点：容易懂。
但它也有一个致命缺点：它会让你误以为 Agent 的难点已经被你理解了。
事实上，最小 Demo 最容易忽略的，恰恰是 Agent 真正难的部分：
- 历史怎么保存
- 系统提示词怎么稳定装配
- 工具怎么筛选可见性
- 多平台接入怎么复用同一套运行时
- 定时任务怎么让 Agent“自己醒来”
- 子 Agent 怎么隔离上下文
- 后台进程怎么追踪
- 危险命令怎么拦截
- 路径和凭据怎么防泄露
这些问题如果没有遇到，你会觉得项目很简单； 如果真的遇到了，你会发现这才是决定系统能不能从 Demo 变成产品的地方。
Hermes Agent 的价值，就在于它已经把这些问题都摆到了台面上。
它不是一个“只展示模型很聪明”的项目，而是一个不断回答“聪明之后怎么管住、怎么接住、怎么持续运行”的项目。
这对初学者非常重要。
因为你真正要学的，不是一个酷炫功能，而是一种工程视角：
当模型被放进系统里以后，哪些东西会立刻变成一等问题？
Hermes 给出的答案是：
- 循环
- 工具
- 会话
- 记忆
- 接入
- 自动化
- 安全
这也是这本电子书后面 12 章的主线。
5. 学这本书时，建议你带着哪三个问题读
如果你只是把后面的章节当成“源码导读”，收获会有限。
我更建议你带着三个问题往下看。
5.1 一个能力到底属于“模型聪明”，还是“系统设计正确”？
很多看起来像模型能力的东西，其实本质上是运行时设计。
比如：
- 会不会恢复历史
- 会不会记住用户偏好
- 会不会在 Telegram 和 CLI 里都维持同一套行为
- 会不会拒绝危险命令
这些都不是模型“天生更强”，而是系统把正确的信息和边界组织给了模型。
5.2 哪些设计是在追求“更强”，哪些设计其实是在追求“更稳”？
初学 Agent 很容易只盯性能上限，老想让它更自主、更会规划、更会用工具。
但你看 Hermes 会发现，很多代码并不是为了“更强”，而是为了“别失控”：
- system prompt 缓存保持稳定
- memory 用 frozen snapshot
- delegate_task 默认限制深度
- terminal 命令先过 approval
- cron prompt 先过注入扫描
- 后台进程统一走 process registry
这说明一个成熟 Agent 项目的核心竞争力，很多时候不是更激进，而是更可控。
5.3 如果我要自己做一个 Agent，哪些层必须先做，哪些层可以后补？
这会是本书最后一章重点回答的问题。
但你从现在开始就可以带着这个问题读：
如果你不是要抄一整个 Hermes，而是要借鉴它的骨架，你到底应该优先学哪几层？
带着这个问题，后面的每一章都会更有抓手。
6. 本书接下来的阅读方式
接下来这本电子书不会按“功能炫不炫”排序，而会按“一个 Agent Runtime 是怎么逐层站起来的”来拆解。
大致顺序会是：
- 先看全局地图，知道 Hermes 是什么系统
- 再看
run_agent.py，理解核心循环 - 再看
model_tools.py和toolsets.py，理解工具系统 - 再看记忆与 SessionDB，理解连续性
- 再看 CLI 与 Gateway，理解接入层
- 再看 Skills、子 Agent、Cron，理解扩展和自动化
- 最后看安全约束与“怎么抄作业”，理解工程落地
你可以把这本书理解成：
不是教你“怎么做一个最小 Agent Demo”，而是教你“怎么开始像工程师一样理解 Agent”。
如果这个目标你认同，那么下一章我们就正式进入 Hermes Agent 的全局地图。