Hermes Agent 全栈入门

七天实战

边学边练请访问 7 天玩转 Hermes Agent 子站，涵盖课表、角色实验室、代码沙箱与社区资源。本文是理论底座；子站提供可交互的 Tool Call Inspector 与 Persona Lab，建议对照阅读。

本文要解决什么问题

很多初学者把 Agent 理解成「给 LLM 接几个 API」。这在 Demo 阶段能跑，一到生产就会遇到三类典型失败：

1. 选错工具：模型在十个工具里点了「搜索」而不是「计算器」，或参数 city 写成了 country。
2. 角色漂移：多轮对话后 Agent 忘记自己是「DevOps 助手」，开始闲聊或越权操作。
3. 链路不可观测：用户只看到最终一句「查询失败」，无法定位是 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」强调三点：

1. 节点 = 单个工具（含 Schema、描述、超时、权限）。
2. 边 = 允许的调用顺序或数据依赖（例如：必须先 read_pdf 再 summarize）。
3. 元数据 = 成功率、延迟 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 的检查清单

1. 每个工具是否有一句 WHEN 和一句 WHEN NOT？
2. 是否与 最常被混淆的邻居工具 做了对比？
3. 参数 description 是否含 合法/非法示例？
4. System Prompt Tools 层是否 重复关键策略（允许冗余，换准确率）？
5. 是否在 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 接入路径简述：

1. 部署 MCP Server（如 filesystem、github）。
2. Agent 侧 MCP Client 拉取 tool 列表，转成 OpenAI Schema 或 Hermes Prompt 附录。
3. 权限与审计在 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	引用格式约束

---

十、学习路径建议

1. 30 分钟：通读本文，画出你的业务在四件套中的位置。
2. 2 小时：完成 快速开始 天气 + 文件链。
3. 1 周：跟子站课表 + 从零到一。
4. 持续：用 benchmark 回归工具描述改动，而非凭感觉改 Prompt。

---

延伸阅读

• 快速开始：首个 Agent、Hermes 解析循环、Retry/Fallback
• 开发指南：工具链编排与自定义工具安全
• 最佳实践：生产检查清单
• 常见问题：格式混用、漂移、MCP 选型
• GitHub 项目与资源：上游 Hermes 模型与社区链接

当你能在 Inspector 里完整解释「模型为何在这一步选了 summarize 而不是 calculator」，你就已经越过 Agent 入门最大的门槛。下一步，打开子站写第一段可运行的工具循环。