1. 从“信使神”到智能代理：hermes-agent 项目全解析

最近在折腾一个很有意思的开源项目——hermes-agent。名字里有个 Hermes，就是希腊神话里那个脚底生风、专门给人传消息的信使之神。这个命名很贴切，因为你一旦把这个 agent 跑起来，就会发现它干的最核心的一件事也是“传消息”——在用户、模型和外部工具之间高效传递指令与数据。我用它在本地搭了一套个人助理系统，实测下来稳定性和扩展性都出乎意料，所以今天专门写一篇拆解文章，把自己从零到一踩坑、理解、实战的过程整理出来，给对 AI Agent 开发感兴趣的朋友一个可参考的路径。

先说清楚 hermes-agent 到底是什么。它本质上是一个轻量级的 AI Agent 编排框架，核心定位是“让非专业开发者也能用自然语言调度多种工具完成任务”。你可以把它理解为一个人形拼装玩具：主体是 LLM（大语言模型）的对话能力，四肢是外接的各种工具——比如查天气、算数字、读文件、调数据库——而 hermes-agent 就是那根把它们拼起来的线。它负责接收你的需求，拆解成若干步骤，自动选择调用哪些工具、按什么顺序调用，最终把结果组织成人类友好的回答。

这篇文章适合谁看？首先是对 AI 应用开发有兴趣，但不想从零手写 agent 逻辑的开发者；其次是已经接触过 LangChain、AutoGPT 这类框架，想找一个更轻、更透明、更易定制方案的玩家；最后还有一类人，就是纯粹对“自动化日常任务”有执念的效率党，想自己动手搭一套能联网、能读文件、能自己决策的小工具。无论你属于哪一类，这篇实战记录应该都能帮你省下不少摸索时间。

接下来我会从整体设计思路、核心机制、实操过程、踩坑实录四个层面展开，尽量把每个关键的“为什么”都讲透。文章里涉及的命令、配置和代码，都是我在自己的项目环境中实际跑过的，你可以放心参考。

2. hermes-agent 的底层设计思路，它和市面主流框架有什么不同

2.1 从“大而全”到“小而精”：为什么我最终选了她

说起 AI Agent 框架，很多人的第一反应是 LangChain 或 Semantic Kernel。这些工具功能确实很全，但也正因为“全”，带来了一个问题：概念太多、抽象层级太深。一个简单的“调用工具”的操作，会在里面被层层包裹，新手光是理解各种 Protocol 和抽象类就得耗掉一整天。

hermes-agent 走的是完全相反的路线。它的核心哲学是“你只需要一个循环和一张工具清单”。我理解下来，整个框架可以拆成三个核心概念：

• Agent ：负责推理的“大脑”，内部维护对话状态，接收任务后输出行动计划。
• Tool ：挂在 Agent 身上的“手脚”，一个 Agent 可以挂多个 Tool，每个 Tool 就是一行函数路由。
• Scheduler ：调度中枢，负责把 Agent 的决策转化为实际的 Tool 调用，并把结果重新喂回给 Agent。

这种设计的最大优势是 认知负担极低 。你不需要理解复杂的 Chain 或 Graph 抽象，只要记住“循环 + 工具”这两个词就能上手。我有个同事用半天时间读完了整个项目的核心源码，这在其他框架里是不可想象的。

2.2 插件即函数：工具注册机制是如何降低开发门槛的

hermes-agent 里注册一个新工具，本质上就是写一个普通的 Python 函数。你不需要继承什么基类，也不需要定义一堆 metadata。

# 一个标准的 hermes-agent 工具函数示例
def add_numbers(a: float, b: float) -> float:
    """Compute the sum of two numbers."""
    return a + b

看到没有？就是一个普通的不能再普通的函数。注册的时候，框架会自动解析函数的文档字符串和类型注解，把它们转换成模型能理解的工具描述。这意味着什么？意味着你想给 agent 加能力，只需要写 Python 函数，不需要额外学习任何特殊 API。

这一点对比其他框架有显著优势。在 LangChain 里如果你想做一个工具，你得理解 BaseTool 类的结构，重写 _run 方法，还要处理 name 、 description 这些字段。而在 hermes-agent 里，约定大于配置： 函数名 = 工具名，docstring = 工具描述，type hint = 参数 schema 。我实测下来，同样实现一个“获取系统时间”的工具，hermes-agent 的代码量大概是 LangChain 的三分之一。

它的函数注册器还会帮你做一层隐式的输入校验。当你给 add_numbers 传入一个字符串时，注册器会尝试把它强转为 float；转换失败才会报错。这种隐式容错在实际对话场景里非常有用，因为用户的自然语言输入往往是不规范的，你总不能让每个工具都自己写参数清洗逻辑吧。

2.3 透明可见的消息路由，以及它为什么对调试如此重要

这个特性是我个人最喜欢的部分。hermes-agent 的核心循环——我习惯叫它“ 决策-执行-观察 ”循环——是完全透明的。框架在运行时会通过标准输出实时打印每一步的中间状态：

• 模型收到了什么输入
• 模型决定调用哪个工具
• 工具返回了什么原始结果
• 模型基于该结果生成了什么话术

这种透明性对调试来说简直是救命稻草。我做过不少 AI 项目，大部分时间不是模型不聪明，而是你根本不知道它在哪一步跑偏了。显式地输出每个中间状态后，你可以像调试普通程序一样，逐行追踪 agent 的“思考”过程。

举个例子，有一次我搭多工具编排场景——用户输入“帮我统计昨天的营收，并对比前天的数据，生成一份摘要”。agent 的逻辑是需要按顺序调用三次数据库工具，第一次查昨天的总营业额，第二次查前天的，第三次把两者作为输入参数再调一次汇总工具。由于模型是个不靠谱的推理器，它可能在第一次拿到数据后就直接开始写总结，跳过了第二次查询。有了透明的消息路由，我一眼就能发现“哦，第二次调用没有被发起”，然后就能针对性地优化提示词，而不是对着最终的混乱结果瞎猜。

3. 核心机制与配置拆解：配置项少，不代表没有调优空间

3.1 模型提供商适配，以及如何选择底层大模型

hermes-agent 在设计上做了一个我很欣赏的决策——它不绑定任何特定厂商的模型接口，而是提供了一套统一的 Provider 抽象。你可以在配置里自由切换不同的底层模型，而对上层的 Agent 逻辑没有影响。

配置文件通常是一个 YAML 文件，核心内容大致是这样：

provider:
  type: openai
  api_key: ${OPENAI_API_KEY}
  base_url: https://api.example.com/v1
  model: hermes-pro-latest
  temperature: 0.2
  max_retries: 3

agent:
  name: hermes
  system_prompt: "You are a helpful assistant."

这里有一个关键设计值得注意： base_url 是特意被设计成开放的。这意味着你不仅能接官方的模型 API，也可以接任何 兼容 OpenAI 协议的自建服务 ——包括本地部署的开源模型、第三方推理服务等。我在测试中试过用本地跑的量化版本模型，通过这个字段接入，效果虽然不如旗舰模型，但当内网环境下的保密性需求优先时，这条路是能走通的。

关于底层模型的选择，我的实际使用经验是： 如果条件允许，优先选择支持“并行函数调用”的模型版本 。因为在多工具场景里，并行调用能极大缩短整体响应时间。比如用户问“帮我查一下北京和上海今天的天气”，支持并行的模型会同时发起两个工具请求，而旧模型只会串行地一次调一个，速度差了近一倍。这一点在你选型底层模型时要特别留意。

3.2 system prompt 的写法，如何让 agent 更听话

如果说配置里有什么最容易被低估，那一定就是 system_prompt 。很多人直接把 system prompt 写成一个简单句子——“You are a helpful assistant”——然后就抱怨模型不听话。实际上，在 hermes-agent 的架构下，system prompt 承担着两个重要职责：设定角色气质，以及明确工具调用的边界规则。

我在实践中摸索出一套比较有效的 prompt 结构，分享出来给大家参考：

你是 Hermes，一个能调用外部工具解决用户问题的智能代理。
你有以下能力：
1. 当遇到需要实时数据或精确计算的问题时，必须调用对应工具，禁止凭空捏造数据。
2. 工具返回的结果如果包含编号列表，你在展示给用户时必须保留原有编号，不得重排。
3. 当且仅当工具结果无法满足用户需求时，你才可以使用自身知识补全回答，并明确标注哪些是推断内容。
4. 如果用户使用了含糊表达（比如“那个文件”），在上下文不明确时，必须追问澄清，禁止擅自猜测。

第四点非常重要。我实际跑了几十轮对话之后发现，模型最常犯的一个错误就是 强行假设 。用户说“把昨天的数据发给我”，模型可能直接去文件系统里找昨天的报表，而没有意识到系统里有多个“昨天”的文件。一条“必须追问澄清”的规则能有效减少这类错误。你可以理解为这是在给模型做安全护栏，限定了它自由发挥的空间，这在实际使用中带来的效果往往比换更大的模型还明显。

3.3 工具调用的超时与重试策略，防止 agent 卡死在原地

hermes-agent 里有一个非常容易被忽略但极其有用的配置项： tool_timeout_seconds 。你可能会想，工具调用还会卡死吗？我的回答是，太会了。当你给 agent 挂上一个网络请求类的工具后，如果远端服务没有响应，默认配置下 agent 就会卡在那个工具调用里，既不返回结果，也不发起重试，体验非常糟糕。

这个参数可以直接在配置里指定：

execution:
  tool_timeout_seconds: 15
  tool_retry_times: 2
  observation_max_chars: 3000

前两个参数很好理解：超过 15 秒的工具调用直接判定超时，然后重试最多 2 次。第三个参数 observation_max_chars 则是一个细节控制：它限制工具返回结果的最大长度，防止某个工具返回了超长度的文本，直接把模型的上下文窗口塞满。

我一开始没设置第三个参数，结果遇到过一个“工具返回了 10 万字符的日志文件”的情况，然后模型直接告诉你“上下文太长了无法处理”。设成 3000 字符之后，框架会自动对工具结果做截断，并在前面加一个提示：“该结果已被截断，仅显示前 3000 字符”。模型会明白自己拿到的不是完整数据，这点在处理日志分析场景里很有用。

3.4 观察窗口与记忆机制，长对话不丢失关键上下文

另一个值得花心思理解的是 hermes-agent 的对话记忆机制。它和传统的“把全部历史都拼进 prompt”的方式不同，采用了 窗口滑动 的策略：配置里可以指定 max_history_messages ，超过数量的旧消息会被截断，只保留最近的 N 轮。

这个设计的初衷是保护上下文长度。但实际运行中你会发现一个问题：如果 agent 在很早的步骤里查到了某个关键数据，而后续又经过了很多轮工具调用，这个“关键数据”可能会被滑出窗口，导致 agent 最终回答问题时已经忘了那个数据。

解决办法是在 prompt 里做一次 关键信息锁定 ——你可以设计一个专门的“便签工具”，让 agent 在拿到关键数据时主动调用这个工具，把数据暂存到一个固定的地方（我就直接存在内存里），之后任何一轮对话都可以读取这个便签。

sticky_notes = {}

def save_note(key: str, value: str) -> str:
    """Save a key-value note for later reference."""
    sticky_notes[key] = value
    return f"Note saved under key '{key}'."

def read_note(key: str) -> str:
    """Read a note by key."""
    return sticky_notes.get(key, "Note not found.")

这个技巧是我在实战中开发出来的，虽然看着取巧，但解决了一大类问题——长对话中信息永久丢失的问题。你不妨在自己的项目里也试试。

4. 实战演练：5 分钟从零搭一个能查包裹、算账的个人助理 agent

4.1 环境准备：安装、初始化，以及第一个 hello world

说了这么多理论，现在进入实战环节。我用一台 Ubuntu 服务器做演示。首先把项目 clone 下来并安装依赖：

git clone https://github.com/your-fork/hermes-agent.git
cd hermes-agent
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

启动一个最基本的“无工具” agent 试试手：

hermes run --config configs/basic.yaml

如果配置正确，你会看到它输出一段提示，然后你就可以在终端里直接打字对话了。作为对照试验，我问它“今天北京天气怎么样”，它老老实实地用通用知识回答说无法访问实时数据。没有工具加持的 agent，就像一个只靠大脑记忆工作的人，很多实时性问题都搞不定。下面我们来给它接上工具。

4.2 三个实用工具的开发：包裹查询、简易计算器、文件检索

接下来我开发三个实用工具：一个包裹查询工具（模拟）、一个简易计算器、一个本地文件检索工具。这三个工具覆盖了“网络请求”、“数学计算”和“本地文件操作”三个典型场景。

包裹查询工具 ：实际项目中你会对接快递公司的 API，这里我写了一个模拟版本：

import requests

def track_package(tracking_number: str) -> str:
    """
    Track a package by its tracking number and return logistics info.
    """
    # 真实场景替换为你的快递公司 API
    resp = requests.get(f"https://api.example-logistics.com/v1/track/{tracking_number}", timeout=10)
    data = resp.json()
    status = data.get("status", "UNKNOWN")
    location = data.get("location", "Unknown")
    return f"Package {tracking_number}: status={status}, last_location={location}"

简易计算器 ：这个非常基础，但却是测试 agent 是否会优先调用工具的经典例子。

def calculator(expression: str) -> str:
    """
    Evaluate a mathematical expression safely and return the result.
    """
    allowed = set("0123456789+-*/(). ")
    if not all(c in allowed for c in expression):
        return "Error: invalid characters"
    try:
        result = eval(expression)
        return f"{expression} = {result}"
    except Exception as e:
        return f"Error: {str(e)}"

注意这个函数里我做了一层字符白名单校验，这是为了防止用户在对话中输入一些奇怪的表达式导致 eval 出问题。实际开发中，所有涉及字符串拼接到代码执行的操作，都必须做严格的白名单校验，这是安全底线。

文件检索工具 ：用于搜索指定目录下的文件。

from pathlib import Path

def find_files(keyword: str, search_dir: str = ".") -> str:
    """
    Search for files whose name contains a keyword.
    """
    root = Path(search_dir)
    if not root.exists():
        return "Error: search directory does not exist."
    matches = []
    for p in root.rglob(f"*{keyword}*"):
        if p.is_file():
            matches.append(str(p))
        if len(matches) >= 20:
            break
    if not matches:
        return f"No files found containing '{keyword}'."
    return "\n".join(matches)

4.3 如何把工具挂载到 agent 上，以及注册时的几个隐藏规则

工具函数写好了，怎么挂到 agent 上？hermes-agent 支持两种注入方式：装饰器声明，或者配置清单。我倾向于在代码里用装饰器，可读性更好：

from hermes_agent import agent, register_tool

@register_tool
def track_package(tracking_number: str) -> str:
    """..."""
    return ...

@register_tool
def calculator(expression: str) -> str:
    """..."""
    return ...

@register_tool
def find_files(keyword: str, search_dir: str = ".") -> str:
    """..."""
    return ...

if __name__ == "__main__":
    agent.run()

这里有三个隐藏规则值得注意，都是我在实际使用中发现的：

规则一：工具描述里不要出现生僻缩写或术语 。你希望让模型知道何时该调用工具，但模型的知识来自预训练数据，它不一定知道你的业务术语。如果你写的是“调用该工具可获得 UPS ONDEMAND PRO 状态”，模型很可能困惑。更好的写法应该是“通过该工具查询包裹当前配送状态与最新位置”。

规则二：docstring 的第一行决定了工具的核心意图 。不要在这行写太多细节，写太多反而会稀释关键词。比如上面跟踪包裹的例子，第一行应该是“Track a package by tracking number and return logistics info”，非常直白。

规则三：参数名要尽量用全称，不要用缩写 。 tracking_number 就很好，不要写 tn 。理由和前面一样，模型是靠语义理解的，参数名越清晰，它填参的准确率越高。

4.4 验证测试：让 agent 完成一次完整的多步任务

工具挂载好后，重启服务，我开始测试。

用户输入：“帮我查一下包裹号 9400116901400000000 现在到哪了，另外算一下 25 乘以 4 加 10 等于多少。”

你看看这句话，包含两个任务。一个是查询包裹位置，一个是数学计算。我用眼睛盯住终端的输出，hermes-agent 的执行过程打印得很清楚：

• 步骤一：模型决定调用 track_package 工具，参数 tracking_number="9400116901400000000" 。
• 步骤二：包裹查询工具返回末尾地的物流更新信息。
• 步骤三：模型决定调用 calculator 工具，参数 expression="25*4+10" 。
• 步骤四：计算器返回 110 。
• 步骤五：模型组织最终回答：“包裹目前位于某某中转站，预计明天送达；25 乘以 4 加 10 的计算结果是 110。”

整个过程一气呵成，模型没有把两个任务搅在一起，也没有漏掉任何一个。这种多任务并行场景是最能检验 agent 框架好坏的试金石，hermes-agent 的表现让我比较满意。

值得留意的是，当我故意把问题改成：“帮我查一下包裹号 9400116901400000000 现在到哪了，算一下 25 乘以 4 加 10 等于多少，然后告诉我包裹和计算结果哪个数值更大？”——这是一个坏问题，因为物流中转站地址跟 110 根本没法比较。但模型在调用完两个工具后，自己判断出无法进行比较，并直接向用户澄清：“包裹位置信息无法与数值 110 直接比较，请确认您想要的比较方式。”这个处理展现了 agent 的判断力而非机械执行，背后的基础仍然是模型本身的能力。

5. 常见问题与排查技巧：运行 hermes-agent 最容易踩的 7 个坑

5.1 工具“失联”问题：为什么你注册了工具，模型却视而不见

我遇到最多的一个问题：明明工具已经注册成功了，但模型就是不调用它，好像完全没有感知。查了源码之后终于搞明白了，hermes-agent 在启动时会做一次 工具清单构建 ，如果你的工具函数没有成功导入到运行时的命名空间里，注册器不会报错，它只是在构建清单时静默忽略了。

这个坑尤其容易在“自动扫描工具文件”模式下触发的。比如你把 register_tool 装饰器写在一个模块里，但模块没有被 import，装饰器执行不到，就出现了“文件存在但工具不生效”的假象。自查方法非常简单：启动时加 --list-tools 参数，框架会打印当前已经识别的所有工具清单。如果清单里没有你的工具，那基本就是导入链路的问题。

5.2 参数校验过严导致的“近乎正确但拒绝执行”

第二个常见问题出在参数类型上。hermes-agent 的隐式类型转换有时候也会聪明过头，有时候又会死板得要命。比如模型给 calculator 传参时，把 expression 字符串传成了 ["25*4+10"] 这种列表结构。按照常规强类型校验，这直接就报错了；但 hermes-agent 的转换器会尝试提取列表里的第一个元素作为字符串继续转换，所以有时候它能救回来，有时候又完全卡住。

我后来排查发现，真正的问题不是转换器不够好，而是模型给的参数本来就带了些多余的格式。要解决这个问题，最有效的手段是在 prompt 里明确强调“调用工具时，请将全部参数压缩为纯 JSON 对象，不要包含多余的前缀说明”。加了这条规则之后，类似问题发生率降低了很多。

5.3 上下文被工具结果撑爆：如何控制观察值的体积

第三个高频问题是用长文本工具时，上下文体积一下子飙升。我在前面提到过 observation_max_chars 配置，这里再强调一次：务必把这个参数设好。我之前遇到过一个情况，在测试一个日志分析工具时，工具返回了一段 5 万字的运行日志，然后模型直接罢工，因为 token 超了。设置截断后，整个流程就稳定了。

一个小细节：当你设置了 observation_max_chars 后，建议同时给截断标记加一个显式前缀，比如 [TRUNCATED] ,这样模型在看到后续内容时会自动意识到这是不完整的，它在做总结时就会加上“数据可能存在截断”这类自我提示，不会把截断后的内容当成全部真相。

5.4 模型乱用工具：禁止某类场景调用的处理策略

用户有时会问一些超出预期的问题，比如当 agent 挂了文件检索工具后，用户直接问“帮我列出整个服务器上所有包含密码的文件”。如果你的系统设计是“查文件”就随便查，那会直接释放一个巨大的权限问题。不要指望模型自己有足够的安全判断力，你的安全体系必须建立在上层的工具权限控制上。

我自己是这样处理的：写的 find_files 工具里加了一层过滤规则，自动排除文件名中包含 password 、 secret 、 id_rsa 等敏感关键字的文件。这是工具层面的控制，不管模型怎么诱导，它都无法通过这个工具读取到敏感文件。这个思路可以参考—— 工具权限的控制权应该牢牢掌握在开发者手里，而不该寄托于模型自我约束 。

5.5 一个容易被忽视的问题：同义工具名导致的调用混乱

还有一次我遇到一个特别无语的问题：我注册了两个工具，一个叫 get_stock_price ，一个叫 get_stock_price_history 。结果模型面对“查询股票价格”的需求时，居然同时调用了这两个工具，返回了一堆冗余数据。这实际上不是 bug，而是模型对工具名的语义边界理解不够。

解决办法是在描述里把工具的适用场景限定得更严格，比如第一个写成“用于获取股票当前实时价格，只含当前行情”，第二个写成“用于获取股票历史价格序列，需要传入起止日期”。这相当于给每个工具画了精准的“势力范围”。

5.6 问题修复后的回归测试，以及一套简单的自查清单

每次改完配置和代码之后，我建议强制跑一遍回归测试。我在项目目录下放了一组测试用例，包括：

• 单工具查询（查天气、查物流）
• 双工具并行（查询加计算）
• 长对话保持（连续对话 20 轮后，确认还能正确引用早期信息）
• 错误输入容错（给工具传无效参数，确认 agent 能礼貌地识别错误）

这组回归测试花不了多少时间，但能帮助你在改动框架版本后快速发现行为偏差。

5.7 社区经验：遇到问题去哪找答案，以及如何正确地提问

开源项目如果遇到问题，优先看两处：项目的 examples 目录和 issues 区。hermes-agent 的 examples 目录里有很多可以直接拿来跑的示例，配置、工具、多轮对话一应俱全。提问或者讨论问题时，尽量带着以下信息：你的配置文件、工具注册代码、完整输出日志。有了这些，社区其他人能很快定位问题，而不是反复询问“你的配置呢”“什么报错”。

6. 把 hermes-agent 扩展到实际业务场景的几条经验

6.1 用作自动化测试助理：让它帮你检查接口状态

我现在把 hermes-agent 的一个实例跑在测试环境，接上了一个端口扫描工具和接口连通性检查脚本。每天早上它会自动巡检一遍核心服务列表，把异常结果汇总成一份自然语言报告发到团队群里。这听着其实很普通，但实际效果是帮团队节省了不少手工巡检时间。

6.2 个人知识库问答：对接本地文档，减少幻觉

另一个我正在尝试的方向是本地知识库问答。思路是给 agent 挂一个 “文档检索工具”，它负责把用户的自然语言问题转换为关键词，去本地 PDF/Word 文件列表里匹配文件名，然后返回相关文档列表，再结合模型自己的总结能力给出带出处的答案。这条路走得通的关键在于——agent 比纯 RAG 流程更多了一层“主动检索”的决策能力，它会判断问题是否需要检索、检索词怎么组合更好，这明显比固定流程的 embedding 检索要灵活。

6.3 权限与安全边界的思考

最后分享一点关于安全底线的思考。Agent 越强大，它的工具权限就越需要收敛。我的原则是“最小权限”：不在一个实例上挂载不可能同时用到的工具，比如个人助理场景就不放“删库”类工具。同时，所有工具都必须自带参数校验，尤其是网络请求类工具，必须限定访问的域名范围。这个原则帮助我在各种试验里避免了至少三次可能的生产事故。

7. 我实测下来的几点体会

前面讲了这么多配置、机制和技巧，最后说点我自己这些天折腾下来最真实的感悟。

第一，hermes-agent 这个框架最打动我的不是某个炫酷的特性，而是它的“不折腾”。大部分 AI 领域的新框架都喜欢创造一套复杂的抽象概念，让你的学习曲线变得很陡峭，而 hermes-agent 的设计者显然在选择反方向——以函数为锚点，所有的工具注册、调用、结果回传，都围绕最朴素的 Python 函数展开。这种极简主义对中小型项目和个人开发者来说，太友好了。

第二，框架的选择固然重要，但决定 agent 上限的永远是两件事：底层的模型能力，以及你的系统提示词和工具设计能力。我做过一个很直观的对比，同一个 agent 配置，不同的 system prompt 写法和不同的工具描述方案，最终产出质量可能相差 60%。所以在模仿先锋探索的同时，一定要花时间打磨自己的“语言——工具映射”能力，这才是 Agent 项目里最值钱的部分。

第三，不要忽视透明日志的力量。每个 AI 项目在调试阶段都像个黑箱，而 hermes-agent 的实时日志就是我撬开这个黑箱的一根撬棍。做 AI 应用开发最怕的就是“看不到中间状态”，一旦你能精确看到模型每一步做了什么，所有问题就都变成了“可见的 bug”，用传统软件工程的排查手段就能逐一解决。

最后再分享一个小技巧：在跑任何新项目之前，先花半小时把它自带的示例配置完整跑一遍。很多时候你觉得一个框架这不合理那不好用，实际是自己没有把底仓走扎实。hermes-agent 的样例配置覆盖了从单工具到多工具、从串行到并行的全部典型场景，把这些样例吃透，再开始改自己的业务逻辑，你已经赢在起跑线上了。