Hermes Agent 全栈入门
边学边练请访问 7 天玩转 Hermes Agent 子站，涵盖课表、角色实验室、代码沙箱与社区资源。本文是理论底座；子站提供可交互的 Tool Call Inspector 与 Persona Lab，建议对照阅读。
本文要解决什么问题
很多初学者把 Agent 理解成「给 LLM 接几个 API」。这在 Demo 阶段能跑，一到生产就会遇到三类典型失败：
- 选错工具：模型在十个工具里点了「搜索」而不是「计算器」，或 参数 city 写成了 country。
- 角色漂移：多轮对话后 Agent 忘记自己是「DevOps 助手」，开始闲聊或越权操作。
- 链路不可观测：用户只看到最终一句「查询失败」，无法定位是 Schema 问题、超时还是 Fallback 未配置。
Hermes Agent 在本站语境下，是一套围绕 工具调用（Tool Calling）与自主推理（Autonomous Reasoning） 的工程方法论，名称来自 Nous Research 的 Hermes 系列模型——它们在函数调用、结构化输出与多轮工具链上经过专门对齐训练。你不必绑定 Hermes 模型才能学这套方法；核心是 协议、图谱、角色与可观测性 四件事做对了，换 GPT-4o、Qwen2.5 或本地 Ollama 同样适用。
读完本文，你应能回答：
- Agent 的「四件套」各自负责什么，边界在哪里？
- OpenAI Functions、Hermes
<tool_call>、Claude XML 三种格式如何选型与解析？ - Active / Passive 工具描述如何影响注意力与调用准确率？
- 五层 System Prompt 与 ReAct+、Plan-and-Execute 如何组合？
- MCP、LangChain、AutoGen 在架构里分别占哪一层？
一、Agent 四件套：LLM + Tool Graph + Memory + Persona
Hermes 课程 （hermes_frontend 子站）用一张「四件套」心智图贯穿 7 天学习：内核、工具图谱、记忆宫殿、角色面具。它们不是四个独立微服务，而是同一条推理环路上的四个职责分区。
1.1 LLM 内核：不是「更聪明的聊天框」
在 Agent 架构里，LLM 承担三项 不可外包 的认知工作：
| 职责 | 说明 | 常见误区 |
|---|---|---|
| 意图路由 | 判断用户是要查天气、改代码还是闲聊 | 用关键词 if-else 替代，导致同义句失败 |
| 工具选择 | 在 Tool Graph 中选中一个或多个工具及参数 | 工具过多且不分类，注意力稀释 |
| 结果综合 | 将 tool_response 转为人话，并决定是否继续调用 | 把原始 JSON 直接返回给用户 |
Hermes 模型族的优势在于：预训练与 SFT 阶段大量见过 结构化工具回合，对 <tool_call> 块的出现位置、JSON 合法性更稳定。但 工具描述工程 仍决定上限——同一模型，Passive 描述与 Active 描述的工具选择准确率可差 20% 以上（业界 benchmark 常见区间，具体因任务而异）。
注意力机制与工具选择（直觉模型）
可以把一次推理想象成：System Prompt + 工具描述 + 历史消息共同构成「候选动作空间」。模型不是执行 if user.contains("天气") 这样的代码，而是在高维 表示里比较「继续生成文本」与「闭合 tool_call 块」两类轨迹的似然。描述里出现 WHEN / WHEN NOT 相当于在特征空间里拉开类间距离；Passive 描述里只有「参数 query: 字符串」，类间边界模糊，模型更容易选错邻居工具。
1.2 Tool Graph：工具不是列表，是图谱
「Tool Graph」强调三点：
- 节点 = 单个工具（含 Schema、描述、超时、权限）。
- 边 = 允许的调用顺序或数据依赖（例如：必须先
read_pdf再summarize）。 - 元数据 = 成功率、延迟 P99、Fallback 指向哪条边。
与「扁平 tools 数组」相比，图谱思维迫使你回答：
- 哪些工具 互斥（查天气 vs 查股价，不应同时误触）？
- 哪些工具 必须串行（PDF 未读不能摘要）？
- 失败时走 哪条备用边？
LangChain 的 @tool + bind_tools 是图谱的一种轻量实现；MCP 则是把图谱节点托管到独立 Server 上。详见本文第六节。
工具分类（Hermes 课程 Day 3）
| 类别 | 代表工具 | 风险等级 | 描述要点 |
|---|---|---|---|
| 信息类 | search、read_file、wiki | 低 | 强调 freshness 与来源 |
| 计算类 | calculator、python_repl | 中 | 强调精确，禁止心算 |
| 行动 类 | send_email、git_push | 高 | 必须写审批与幂等 |
| 感知类 | vision、speech_to_text | 中 | 写清输入格式与大小限制 |
1.3 Memory：三层记忆，避免「什么都塞进 Context」
| 层级 | 典型实现 | 写入时机 | 读取时机 |
|---|---|---|---|
| 工作记忆 | 当前 messages 列表 | 每轮 user/assistant/tool | 每轮推理 |
| 情节记忆 | 会话摘要、Handoff 包 | 每 N 轮或角色切换 | 新 Agent 接手时 |
| 语义记忆 | 向量库、用户偏好表 | 显式工具或离线 job | RAG 检索后注入 Prompt |
Hermes 路径 Day 4 专讲记忆；入门阶段只需遵守一条纪律：工具返回的大块文本不要永久进 System Prompt，应摘要后写入 episodic 或向量库，否则成本与漂移双杀。
会话压缩示例策略
当 messages 超过 8k tokens 时：保留 System + 最近 6 轮 + 一条「Earlier summary: …」情节记忆。压缩本身可以是一次 无工具的 LLM 调用，输出结构化 {facts, open_tasks, user_prefs}，再写回 Memory。这与 Tool Graph 正交，但决定了长任务是否可完成。
1.4 Persona：角色面具不是「语气词」
Persona 同时控制 说什么、不做什么、优先用哪些工具。多 Agent 场景（心理咨询工作室、专家委员会）里，每个 Persona 应有：
- 独立的 System Prompt 五层（见第三节）
- 隔离的角色记忆（督导不应看到初评的 raw notes，除非 Handoff 协议允许）
- 防漂移锚点（每 5 轮注入一句角色提醒）
Persona 与 Tool Graph 的交叉点在于 Tool Policy 层：例如 DevOps Agent 的 Prompt 明确「禁止调用 send_email，除非用户确认」，这比事后 ACL 更贴近模型行为。
二、三种工具调用协议：OpenAI Functions、Hermes 标签、Claude XML
模型厂商训练数据不同，线上协议必须与模型对齐。混用解析器是最常见的 Day 1 踩坑之一。
2.1 OpenAI Functions / JSON Schema + tool_calls
OpenAI 兼容 API（含多数国产兼容层）返回结 构化字段，而非纯文本标签：
{
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_abc123",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"city\": \"北京\"}"
}
}
]
}
特点：
- 工具定义在请求体的
tools数组，JSON Schema 描述参数。 - 客户端用 SDK 解析
tool_calls，执行后把role: tool消息塞回。 - 适合 GPT-4o、Qwen2.5-Instruct（function calling 模式）等。
Schema 设计要点：
# 枚举约束减少幻觉参数
{
"name": "get_weather",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "中国城市名，如北京、上海"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"}
},
"required": ["city"]
}
}
客户端回合（OpenAI 路径）
2.2 Hermes <tool_call> / <tool_response> 标签格式
Hermes 系列（及不少开源微调模型）在文本里直接生成：
<tool_call>
{"name": "get_weather", "arguments": {"city": "北京"}}
</tool_call>
工具执行后，开发者拼回：
<tool_response>
{"name": "get_weather", "result": "北京：晴，25°C，湿度 40%"}
</tool_response>
解析循环心智模型：
与 OpenAI 路径的差异：你要自己写解析器，并处理「模型一次输出多个 tool_call」「JSON 尾逗号」「arguments 是字符串还是对象」等边界。快速开始文档给出可运行 Python 循环；子站 Tool Call Inspector 用于逐步对照模型 raw 输出。
Hermes 解析器必须覆盖的边界
| 边界情况 | 处理策略 |
|---|---|
| JSON 外包在 markdown 代码块 | 先 strip ``` 再 parse |
| arguments 是字符串化 JSON | 二次 json.loads |
| 多个 tool_call 连续出现 | 循环执行或队列 |
| 未知工具名 | 返回 tool_response error，让模型自我修正 |
| 模型未闭合标签 | 超时截断 + Retry 同一 user 消息 |
2.3 Claude XML 工具格式
Anthropic Messages API 使用 XML 块，例如：
<function_calls>
<invoke name="get_weather">
<parameter name="city">北京</parameter>
</invoke>
</function_calls>
Claude 对 长工具描述、嵌套说明 的遵循度较好，适合复杂 Schema；与 Hermes JSON-in-tag 不同，解析器需按 XML 路径提取。
2.4 三协议对照表
| 维度 | OpenAI Functions | Hermes 标签 | Claude XML |
|---|---|---|---|
| 工具定义位置 | API tools 参数 | Prompt + Schema 附录 | API tools |
| 模型输出形态 | tool_calls 字段 | <tool_call> 文本 | <invoke> XML |
| 典型模型 | GPT-4o, Qwen2.5 FC | Hermes-2-Pro, 部分 Llama FT | Claude 3.5+ |
| 解析难度 | 低（SDK） | 中（自写 parser） | 中（XML parser） |
| 多工具并行 | 原生支持 | 需约定分隔规则 | 原生多 invoke |
| 与本站子站 | LangChain 默认 | Inspector 重点展示 | 需单独适配 |
选型建议： 选模型 → 读官方工具文档 → 锁定一种协议 → 全链路单元测试（含错误 JSON、空参数、未知工具名）。不要在同一 Agent 里混跑 Hermes 标签解析与 OpenAI tool_calls 而不做分支。
三、工具描述工程：Active vs Passive
工具描述是 隐式的 few-shot。模型通过注意力阅读 name + description + parameters.description，决定调用谁。
3.1 Passive 描述（被动，列表式）
@tool
def search_web(query: str) -> str:
"""搜索网络。参数 query: 查询字符串。"""
...
问题：模型不知道 何时 该搜索、何时该用内部知识；与 read_file、wiki_lookup 边界模糊。
3.2 Active 描述（主动，决策式）
@tool
def search_web(query: str) -> str:
"""当用户询问实时新闻、股价、天气或你训练数据之外的事实时调用。
不要用此工具回答数学纯计算或已提供的文档内容。
参数 query: 精简关键词，不含礼貌用语。"""
...
Active 描述包含 触发条件、反例、参数格式，等效于把分类边界写进 Prompt。实践建议：
| 技巧 | 示例 |
|---|---|
| WHEN / WHEN NOT | 「当…时调用；不要用于…」 |
| 工具互斥声明 | calculator 描述里写「不要用于需要联网的汇率」 |
| 参数示例 | city: 北京 而非 city: 用户提到的城市 |
| 错误成本 | 「 误调用会泄露 PII」提高模型谨慎度 |
在 Persona 五层 的 Tools 层再次强调策略，形成 描述 + 策略双保险。
3.3 从 Passive 迁移到 Active 的检查清单
- 每个工具是否有一句 WHEN 和一句 WHEN NOT？
- 是否与 最常被混淆的邻居工具 做了对比？
- 参数 description 是否含 合法/非法示例？
- System Prompt Tools 层是否 重复关键策略（允许冗余，换准确率）？
- 是否在 Inspector 里看过 误调用样本 并反向改描述？
四、System Prompt 五层架构
Hermes 课程推荐的五层结构，把「角色工程」从散文变成可评审的清单：
4.1 各层示例片段（天气 Agent）
## 1. Identity
你是 HermesWeather，chenxiaoshivivid 文档站演示用的天气助手。
## 2. Expertise
你熟悉中国城市名、常见单位换算；你不提供医疗或投资建议。
## 3. Tone
简洁、中文优先；温度默认摄氏度。
## 4. Constraints
禁止编造天气数据；查不到时必须说明并建议用户确认城市名。
禁止调用未注册的工具。
## 5. Tools
优先 get_weather；若城市模糊，先 ask_clarification 再调用。
若 get_weather 超时，使用 get_weather_backup。
4.2 防漂移与多 Agent
| 机制 | 做法 |
|---|---|
| 周期提醒 | 每 5 轮 user 消息注入：「Remember: 你是 HermesWeather…」 |
| Handoff 摘要 | Agent A 退出前输出结构化 {role, task_done, open_questions} |
| 记忆隔离 | 督导 Agent 的 thread 不包含初评 raw 日志，仅摘要 |
| 意图路由 | 接待员 Persona 只做 triage，禁止直接给治疗建议 |
Day 2 心理咨询工作室实战是这套理论的完整沙盘；本文只建立框架。
多 Agent 协作模式（Day 2 预览）
- 专家委员会： 并行咨询，主席综合——适合研究型任务。
- Handoff 流水线：上文所示——适合流程合规场景。
- 两种模式可混用：委员会产出候选方案，Handoff 负责执行单一方案。
五、自主推理：ReAct+ 与 Plan-and-Execute
工具调用解决「一步动作」；复杂任务需要 推理模式 选型。
5.1 ReAct（Reason + Act）与 ReAct+
经典 ReAct 循环：Thought → Action → Observation 交替，直到模型输出 Final Answer。
ReAct+ 在本站语境指增强版：
- Thought 结构化（可选 JSON：
{"plan_step": 2, "hypothesis": "..."}） - 强制 Observation 进 Memory，避免重复调用同一工具
- 工具失败时 Thought 必须解释 Retry 或 Fallback 理由
适用： 步骤数 ≤ 5、分支少、需可解释 trace 的任务（文件摘要、单域 QA）。
ReAct+ 伪代码结构
while not done and steps < MAX_STEPS:
reply = llm(messages)
if contains_tool_call(reply):
obs = execute_tool(parse(reply))
messages.append(tool_response(obs))
elif is_final_answer(reply):
done = True
else:
messages.append(assistant(reply)) # 纯 Thought 续写
5.2 Plan-and-Execute
先 规划 再 执行，适合研究型、DevOps 流水线、Day 5 毕业方向：
| 对比项 | ReAct+ | Plan-and-Execute |
|---|---|---|
| 规划可见性 | 逐步显露 | upfront 计划可展示给用户 |
| 失败恢复 | 单步 Retry | Replanner 改计划 |
| 成本 | 较低 | 较高（多轮 LLM） |
| 典型场景 | 天气、PDF 摘要 | 多源调研、发布清单 |
纪律： 简单任务勿过度 Plan；Planner 步骤需 可映射到具体工具，否则执行层幻觉「假完成」。
5.3 与 Tool Graph 的关系
- ReAct+ 的 Action = 图谱上的 单步遍历。
- Plan-and-Execute 的 Plan = 图谱上的 路径模板；Executor 负责走边并写 Memory。
决策树：选哪种推理模式
六、与 MCP、LangChain、AutoGen 的关系
| 技术 | 层级 | 与 Hermes 路径的关系 |
|---|---|---|
| LangChain | 框架 | @tool、bind_tools、消息循环；快速开始默认栈 |
| AutoGen | 多 Agent 框架 | 专家委员会、Handoff 对话模式；Day 2–3 可选 |
| MCP | 工具服务器协议 | 把 Git、Slack、DB 封成标准 Server；与手写 @tool 并存 |
| OpenClaw / DSH | 网关/运行时 | 偏部署与路由；Hermes 偏工具选择与角色 |
集成原则： 方法论（四件套、五层 Prompt、Active 描述）高于框架选型；换 LangChain 到 LlamaIndex 不应推翻 Tool Graph 设计。
MCP 接入路径简述：
- 部署 MCP Server（如 filesystem、github）。
- Agent 侧 MCP Client 拉取 tool 列表，转成 OpenAI Schema 或 Hermes Prompt 附录。
- 权限与审计在 Server 侧配置；Agent 只看见允许的工具子集。
LangChain vs AutoGen 选型（FAQ 浓缩）
| 维度 | LangChain | AutoGen |
|---|---|---|
| 上手曲线 | 低，文档多 | 中，对话抽象 |
| 单 Agent 工具链 | 强 | 够用 |
| 多 Agent | 需自拼 | 原生 ConversableAgent |
| 可视化编排 | LangGraph 另学 | 社区示例多 |
| 与本站 Day 1 | 默认 | Day 2+ 可选 |
七、七天场景地图（与子站课表对齐）
与 Hermes 七天子站课表 及 从零到一 文档对齐的 场景—能力—产出 地图：
| 天数 | 主题 | 核心能力 | 实战产出 | 本文对应章节 |
|---|---|---|---|---|
| Day 1 | 架构与工具调用 | 三协议、Inspector、@tool | 天气 Agent + 文件处理链 | 二、三、快速开始 |
| Day 2 | 角色工程 | 五层 Prompt、Handoff | 心理咨询工作室 | 四 |
| Day 3 | 工具生态 | 工具分类、线性/条件/并行链 | DevOps Agent | 1.2 Tool Graph |
| Day 4 | 记忆与上下文 | RAG、会话压缩、画像 | 长期记忆 Agent | 1.3 Memory |
| Day 5 | 自主推理 | ReAct+、Plan-and-Execute | 研究 Agent | 五 |
| Day 6 | 评估与安全 | Benchmark、Prompt 注入 | 红蓝对抗 | 八（生产） |
| Day 7 | 生产部署 | 监控、成本、容器化 | 毕业项目 | 八 |
每日节奏（Morning 概念 / Afternoon 编码 / Evening 社区）见子站 Curriculum 区块；文档站提供文字深度，子站提供 Persona Lab、Code Sandbox 交互。
Day 1 与 Day 5 的能力跳跃
Day 1 只要求你能 稳定完成单链工具调用；Day 5 才要求 Planner 把研究问题拆成可验证子 问题。中间 Day 2–4 分别在 Persona、Tool Graph 广度、Memory 深度上垫步，避免直接上 Plan-and-Execute 导致「计划很漂亮、工具全错」。
八、生产模式：从 Demo 到可运维
入门后必须提前建立四项生产意识（Day 6–7 展开）：
8.1 可观测性
- 记录每步：
model_raw→parsed_tool_call→tool_latency→final_reply。 - 对齐子站 Tool Call Inspector 字段，便于教学与线上 trace 同构。
8.2 失败策略
| 策略 | 配置要点 |
|---|---|
| Retry | 同工具最多 2–3 次，指数退避 |
| Fallback Tool | 主 API 失败切备用数据源 |
| 自我修正 | 把 error message 作为 Observation 喂回模型 |
8.3 安全与成本
- 敏感工具（邮件、Git push、支付）→ 人工审批 gate。
- 每 session token 预算；大 PDF 先摘要再进上下文。
- 定期用固定 benchmark 测 工具选择准确率，而非只看最终 BLEU。
8.4 评估维度
九、典型场景速览
| 场景 | Tool Graph 特征 | 推理模式 | Persona 要点 |
|---|---|---|---|
| 天气查询 | 单工具 + Fallback | ReAct+ | 禁止编造；单位默认 |
| 文件 PDF→摘要→计算 | 线性链 C→D→E | ReAct+ | 大文件分块策略 |
| 心理咨询工作室 | 多 Agent Handoff | 对话 + 少量工具 | 强 Constraints |
| DevOps 自动化 | 并行 Fan-out 日志/指标 | Plan-and-Execute | 行动工具需审批 |
| 研究 Agent | 搜索 + 阅读 + 引用 | Plan-and-Execute | 引用格式约束 |
十、学习路径建议
- 30 分钟：通读本文，画出你的业务在四件套中的位置。
- 2 小时：完成 快速开始 天气 + 文件 链。
- 1 周：跟子站课表 + 从零到一。
- 持续：用 benchmark 回归工具描述改动，而非凭感觉改 Prompt。
延伸阅读
- 快速开始：首个 Agent、Hermes 解析循环、Retry/Fallback
- 开发指南：工具链编排与自定义工具安全
- 最佳实践：生产检查清单
- 常见问题：格式混用、漂移、MCP 选型
- GitHub 项目与资源：上游 Hermes 模型与社区链接
当你能在 Inspector 里完整解释「模型为何在这一步选了 summarize 而不是 calculator」，你就已经越过 Agent 入门最大的门槛。下一步，打开子站写第一段可运行的工具循环。