我去年年底决定认真做一个 AI Agent 项目，真正动手之后才发现，最难的不是“让大模型开口说话”，而是让它在没人盯着的时候，也能老老实实把活干完。我给自己写的这个工具起名叫hermes-agent，核心就一句话：给大模型配上可调用的工具、可追溯的任务队列、可控的记忆，以及一套足够轻量的多 Agent 调度机制，让它能在后台自动完成数据抓取、信息整理、定时汇报这类重复劳动。
如果你也在折腾 Agent，但对 LangGraph、AutoGen 这类重框架有点审美疲劳，或者你只是想快速把一个“能干活”的自动化脚本变成“会自我纠错”的智能体，那这篇笔记应该对你有用。下面全是我的真实设计取舍、踩坑记录和调参经验，不写废话。
1. hermes-agent 是什么：一个轻量 Agent 编排层的设计复盘
1.1 从“大模型对话”到“任务闭环”
大多数人对 Agent 的误解，是把 ChatGPT 套上一层 system prompt 就当成 Agent。其实真正常用的 Agent 长什么样？它更像一个“调度员 + 打工人”的组合体：大模型是脑子，负责理解和决策；工具是手，负责具体执行；记忆是笔记本，负责不重复犯错；任务循环是项目经理，负责盯着事情有没有做完。
hermes-agent 最开始只是我内部的一个 Python 脚本库，用来跑“抓取网页 → 提炼要点 → 生成日报”这条链路。后来我给它加上了任务队列、工具注册表和上下文管理器，才慢慢变成了一个可以扩展多 Agent 的编排层。它的核心循环并不复杂：拿到任务 → 拆解计划 → 调用工具 → 检查结果 → 决定继续还是结束。这个循环每个 Agent 框架都有，但 hermes-agent 把重心放在了“轻量、可控、可观测”这三件事上。
为什么强调这三件事？因为我见过太多 Agent 项目，demo 跑得很惊艳，上了生产就变成黑盒子：不知道它调了什么工具、不知道为什么卡住、不知道上下文已经被塞了多少垃圾。hermes-agent 的设计目标就是避免这些，让每一次决策、每一次工具调用、每一段记忆写入都有迹可循。
1.2 我为什么没用 LangGraph、AutoGen 或 Swarm
先说结论：不是这些框架不好，而是“杀鸡用了牛刀”。
LangGraph 表达能力最强，图结构可以精确控制状态流转，但代价是你要先理解 node、edge、state 那一整套概念，脚本稍微复杂一点，配置量就上来。AutoGen 的会话式多 Agent 设计很有意思，但它的消息流转是“几个人围在桌边开会”，自由度太大，调试的时候往往要翻大量对话日志才能定位一个问题。OpenAI Swarm 很轻，但它的记忆和任务持久化设计比较简单，适合教学和原型，不适合长期跑后台任务。
我做了一个很朴素的对比，贴在项目文档里，也放在这：
| 维度 | hermes-agent | LangGraph | AutoGen | Swarm |
|---|---|---|---|---|
| 上手成本 | 低，只要会写函数 | 高，要理解图模型 | 中，要理解对话模式 | 低 |
| 多 Agent 协作 | Pipeline + 任务队列 | 图结构，自由 | 群聊，自由 | 手写交接流程 |
| 可观测性 | 内建 Trace 日志 | 需自行搭建 | 需自行组装 | 较弱 |
| 生产适用性 | 面向定时任务和自动化 | 强，适合复杂状态机 | 偏研究原型 | 偏教学 |
| 依赖重量 | 轻，无强依赖 | 重 | 重 | 轻 |
所以如果你要做一个涉及复杂状态机、多轮人工介入的业务系统，LangGraph 是合理选择。但如果你像我一样，主要场景是“定时抓数据 → 清洗 → 生成报告 → 发通知”，那你需要的是一个能快速把大模型和几十个工具函数组装起来的薄层，hermes-agent 就是这个薄层。
1.3 这个项目到底适合谁
我自己的使用场景分三类：
- 个人自动化：比如每天定时拉取几个技术站点的更新，让 Agent 帮我挑出和我关注领域相关的文章，摘要后发到群里；
- 团队内部工具：在内部数据平台外面包一层自然语言接口，同事输入“查一下上周订单异常率”，Agent 自动拼接参数调用数据接口，再把结果解释成一句人话；
- 数据流水线里的“智能变体”：某些判断逻辑没法用固定规则写死，就交给 Agent 做轻量决策，例如对用户反馈先做情绪分类再转不同处理流程。
所以我建议的定位是：适合 Python 基础还可以、想快速搭一个生产可用 Agent、又不愿意被重型框架束缚的开发者。如果你完全刚入门，建议先把函数调用和大模型 API 的基本概念摸熟，再来玩这个编排层会顺很多。
2. 核心架构：消息总线、工具注册表和记忆分层
2.1 一切皆消息：任务队列与结构化消息协议
我在设计 hermes-agent 时最核心的一个决定，就是把 Agent 内部的一切交互都统一成“消息”。用户请求是一条消息，模型回复是一条消息，工具调用结果是一条消息，Agent 之间的交接也只是一条消息进入另一个队列。
每条消息长这样，简化后的结构是：
{ "message_id": "msg_8f1a...", "task_id": "task_03bc...", "trace_id": "trace_9a12...", "role": "assistant", "content": "我需要先调用 search_articles 工具获取最新文章", "tool_calls": [ { "id": "call_abc123", "name": "search_articles", "arguments": {"query": "AI Agent", "limit": 10} } ], "timestamp": 1735689600 }为什么统一成消息而不是“函数调用链”？因为消息天然适合做日志审计。出了问题，我可以把整个任务的所有消息按时间轴拉出来，像看聊天记录一样回放每个决策点。这条经验特别重要，尤其当你同时跑几十个任务时，没有 trace_id 根本没法排查问题。
任务队列放在内存里跑单机任务足够，但如果你要重启不丢任务，建议把任务状态丢到 Redis 或 SQLite。我在 hermes-agent 里做了个抽象层，默认用asyncio.Queue，生产环境可以换成 Redis Streams 的实现。
2.2 工具注册表：让模型知道“有什么牌可以打”
大模型本身不会调用工具，它只会根据函数描述生成一个“调用意图”。所以工具注册表的作用，就是把每个 Python 函数变成模型能理解的 JSON Schema，再把 Schema 拼到请求里。
我的做法是用 Pydantic 做参数校验，再自动生成 Schema。你只需要写一个普通函数，加上类型注解和描述，剩下的交给装饰器：
from pydantic import BaseModel, Field from hermes import tool class SearchArticlesInput(BaseModel): query: str = Field(description="搜索关键词，尽量具体，比如'大模型推理优化'") limit: int = Field(default=5, description="返回的文章数量，范围是1-20") @tool(name="search_articles", description="根据关键词搜索最新技术文章，返回标题、链接和摘要") def search_articles(input: SearchArticlesInput) -> dict: # 真实场景这里会调用搜索 API 或数据库 return { "articles": [ {"title": "示例文章", "url": "https://example.com", "summary": "这是一段摘要"} ] }这里有两个坑，我必须强调一下。
第一，字段描述一定要写清楚。模型不是人，它看到query: str只知道是个字符串，并不知道你要它把用户口语转化成关键词。我在所有工具描述里都写了“用户没说清楚时，请自行提取关键词”，工具命中率立刻提升了一截。
第二，不要相信模型第一次生成的参数。工具注册表会在调用前做 Pydantic 校验，参数不合法会返回一个“参数错误”消息，让 Agent 自己修正重试。这一步看着简单，实际帮我把非法调用从每天十几次降到了接近零。
2.3 上下文管理：让 Agent 学会“选择性遗忘”
上下文窗口是 Agent 项目最大的隐形敌人。一句话任务可能只有几十个 token，但循环十轮之后，历史消息轻轻松松超过几万 token，费用上去还是小事，关键是模型会开始“迷失重点”，回复越来越糊。
hermes-agent 的上下文管理分三层，我给它们取了朴素的名字：短期记忆、长期记忆、摘要记忆。
- 短期记忆：当前任务的最近 N 轮消息，直接放进模型上下文；
- 摘要记忆：超过 N 轮后，把更早的消息丢给一个轻量模型（或者用同一模型）压成 200 字摘要，替换掉原始消息；
- 长期记忆：任务结束后，把重点结论、常见偏好写入向量库，下次遇到类似任务可以检索出来当参考。
这套方案不复杂，但很管用。我最常用的配置是max_history_rounds=10，超过后只保留最近 10 轮完整消息，前面的全部转成摘要。摘要会包含“已经完成的工具调用”和“还没完成的目标”，这样模型不会因为摘要丢掉任务线索。
2.4 多 Agent 协作：不搞自由对话，改用 Pipeline 与 Subtask
很多 Agent 框架喜欢把多 Agent 做成“自由讨论”，几个角色互相发消息，聊着聊着出一个结果。这看起来高级，实际调试起来想死。因为自由对话不可预测，两个 Agent 可能开始互相客套，也可能陷入死循环。
hermes-agent 的多 Agent 协作方式更朴素：Pipeline。上游 Agent 的输出结构化成一条消息，进入下游 Agent 的输入队列，每个 Agent 只关心自己的任务边界。比如“日报生成”场景，我拆成三个 Agent：
collector：负责抓取文章列表，输出[{title, url, summary}]；analyzer：读取文章内容，提炼 3 条关键洞察，输出结构化文本；writer：把洞察改写成一份简洁日报，按固定模板输出。
三个 Agent 之间不直接对话，只通过消息队列传递结构化数据。这样做的好处是每个环节都能单独重跑，哪一步出了错就重放哪一步。我甚至会把中间结果落盘成 JSON 文件，方便人工检查。
3. 实操记录：让 hermes-agent 完成一次“数据收集 + 总结”任务
3.1 环境安装与目录结构
我建议你在虚拟环境里操作，避免污染系统 Python。我用的是 Python 3.11，依赖只装了pydantic、httpx、openai这几样。
git clone <repo-url> hermes-agent cd hermes-agent python -m venv .venv source .venv/bin/activate pip install -e .项目目录结构大概长这样：
hermes-agent/ ├── hermes/ │ ├── core/ │ │ ├── agent.py │ │ ├── bus.py │ │ ├── context.py │ │ └── trace.py │ ├── tools/ │ │ ├── registry.py │ │ └── builtin/ │ │ ├── web_fetch.py │ │ └── search.py │ └── memory/ │ ├── short_term.py │ └── vector_store.py ├── examples/ │ └── daily_report/ └── pyproject.toml这个结构是按“核心编排、工具、记忆”三层拆的，目的就是让你新加一个工具时只动tools/目录，不用碰核心逻辑。
3.2 定义一个网页抓取工具
我用的是httpx做异步抓取，避免阻塞事件循环。真实项目里一定要加超时和重试，不然一个跨掉的站点会让整个任务卡死。
import httpx from hermes import tool @tool(name="web_fetch", description="抓取指定 URL 的正文文本，返回 status_code、title、content") async def web_fetch(url: str, timeout: int = 10) -> dict: async with httpx.AsyncClient(timeout=timeout, follow_redirects=True) as client: resp = await client.get(url) if resp.status_code != 200: return {"error": f"HTTP {resp.status_code}"} # 真实场景这里会用 BeautifulSoup 或 trafilatura 提取正文 text = resp.text[:8000] return {"status_code": resp.status_code, "raw_text": text}注意我把raw_text截断到 8000 字符，而不是直接丢全文。因为大模型处理长文本很贵，而且网页里 90% 都是导航、广告和重复内容，截断反而能逼着 Agent 更聚焦。如果你需要全文分析，可以额外封装一个“分段读取”的工具，让 Agent 按需分段抓取。
3.3 创建 Agent 并运行任务
创建 Agent 的代码很直接：注册工具，设置模型和 system prompt，然后调用run。
import asyncio from hermes import Agent, ToolRegistry async def main(): registry = ToolRegistry() registry.register(web_fetch) agent = Agent( name="collector", model="qwen-plus", system_prompt=( "你是一个信息收集助手。用户会给你网址，" "你必须调用 web_fetch 工具抓取内容，" "然后提取标题和正文前 200 字作为摘要。" ), tools=registry, max_rounds=6, ) result = await agent.run( "抓取 https://example.com 的标题和正文第一段，输出为 JSON 格式" ) print(result) asyncio.run(main())我第一次跑这个例子就遇到了两个问题。
第一个问题是模型老想直接“编造”网页内容，而不去调用工具。原因很简单：system prompt 里没写死必须调用工具。后来我把提示词改成“不调用工具就无法完成任务”，并在工具调用失败时返回错误消息让 Agent 重试，行为立刻正常了。这个经验已经写进我所有的 Agent 项目里了。
第二个问题是模型调用完web_fetch之后，把raw_text原封不动塞进了上下文。虽然我截断了 8000 字符，但每轮 8k，三轮就把上下文撑爆了。解决办法是在返回结果里只放关键字段，或者让模型在调用工具后立即做一次信息提取，把提取结果作为后续上下文。
3.4 看执行轨迹和 Token 成本
hermes-agent 会把每一步写到日志里，格式大概是：
[trace_id: 9a12] user: 抓取 https://example.com 的标题和正文第一段 [trace_id: 9a12] agent: 我需要调用 web_fetch 工具 [trace_id: 9a12] tool call: web_fetch({"url": "https://example.com"}) [trace_id: 9a12] tool result: status_code=200, title="Example Domain" [trace_id: 9a12] agent: 已获取内容，正在生成摘要 [trace_id: 9a12] final: {"title": "Example Domain", "summary": ...}有了这种轨迹，我每次排查问题都是直接看日志里“tool call 和 tool result 是否匹配”，能省掉非常多的瞎猜时间。
Token 成本我建议也打点到日志里。我用的是 OpenAI 兼容接口返回的usage字段，在每次请求结束后累加到任务的 cost 记录中。别小看这一步，等你跑几天定时任务，回头一看成本爆炸，那时候再想追溯是哪个任务烧的钱，代价就没法补救了。
4. 常见问题与排查技巧实录
4.1 Agent 陷入工具调用循环
最常见的故障：Agent 反复调用同一个工具，每次拿到结果都像“失忆”一样，继续调用，直到把预算烧光。我遇到过一个案例，Agent 连续抓取了同一个 URL 六次，结果一模一样，它还在继续。
我的排查思路是先看 Trace 里每次调用的参数。如果参数完全没变，说明模型根本没有“消化”上一次结果；如果参数在变但结果不变，可能是工具本身有问题或者页面被反爬。解决方案有三个：
- 设置
max_rounds上限，比如 8 轮，超过后强制终止并返回目前收集到的信息； - 工具结果里加入“内容指纹”
hash，同一内容的重复结果直接提示 Agent “你已获取过此内容，请换一个角度”； - 在 system prompt 中显式写“如果工具结果没有提供新信息，请停止调用并输出结论”。
4.2 工具参数总是传错
有一天我的搜索工具频繁报错，日志显示 Agent 把limit传成了字符串"五"，而不是整数5。Pydantic 校验虽然拦住了，不会导致程序崩溃，但 Agent 会反复尝试修正参数，白白浪费两三轮调用。
后来我在每个字段里都加了更明确的描述和示例。以limit为例，描述从“返回数量”改成了“返回数量，必须是整数，范围 1-20，用户说‘几条’时自行转换为整数”。描述越具体，模型越少猜。这个改动看着很小，却让参数错误率明显下降。
另外，如果某个工具的参数是枚举值，比如状态pending / done / failed，一定要用Literal或Enum定义。否则模型很可能传"已完成"这种中文值进去。
4.3 上下文被多余内容塞满
我做日报抓取时，Agent 每轮调用都会把上一次的工具结果继续保留在上下文中，很快就把 GPT-4o-mini 的上下文塞满了。后来我在上下文管理器里加了“消息压缩”策略：当历史消息超过阈值时，用一次独立的摘要请求把老消息变成简短的进度说明。
有个小注意点：摘要请求会额外花钱，所以不要设太频繁。我的经验值是“历史超过 12 轮”再做摘要，低于这个阈值直接保留。摘要模型用便宜的小模型就行，不需要太聪明，因为只是提炼“已完成动作”和“当前目标”。
4.4 多 Agent 任务消息串线
当你同时跑多个任务，又用了同一个消息队列时，很容易出现 A 任务的工具结果跑到了 B 任务的上下文里。这属于数据串线，通常不会立刻报错，但会导致某个 Agent 突然引用不存在的数据。
我的解决方案是给每条消息强制带上task_id和trace_id，在消费者端做严格过滤。任何不匹配当前任务 ID 的消息，直接丢弃并告警。之前为了省事省略过这一步，结果排查起来非常痛苦，从那以后我再也不敢省了。
下面是我的问题排查速查表，直接抄走用：
| 现象 | 可能原因 | 排查路径 | 解决方案 |
|---|---|---|---|
| 反复调用同一工具 | 模型没消化结果，或结果无变化 | 对比多次 tool result 是否一致 | 加 hash 指纹，提示无新信息停止 |
| 工具参数错误 | 描述不清、缺示例 | 看调用参数与描述 | 补字段描述、加示例 |
| 上下文溢出 | 历史消息未压缩 | 统计每轮 token | 设置消息摘要策略 |
| 任务串线 | 缺少任务标识过滤 | 检查 trace_id | 订阅时过滤 task_id |
| 长时间无响应 | 外部 API 超时 | 看工具调用耗时 | 加超时、重试、熔断 |
| 结果不稳定 | 模型温度过高 | 对比多次输出 | 降 temperature 到 0 或 0.1 |
4.5 重试造成重复数据
还有一个隐蔽的坑：工具已经请求成功，但响应超时，Agent 重试后拿到新结果，任务继续推进。这时候如果工具本身是“写操作”，比如发通知、创建工单，就可能导致重复执行。解决办法是给写操作工具加“幂等键”：同一个task_id下，同一个幂等键只执行一次。这不算 hermes-agent 独有，任何自动化系统都要考虑。
5. 性能调优和工程化经验
5.1 用限流保护外部服务
Agent 跑起来之后，最容易被忽略的是它对下游服务的压力。工具函数看起来只是普通的请求，但模型的并发能力一开，几十个任务同时抓同一个网站，很容易把对方服务器打挂。我在httpx.AsyncClient外面加了一层asyncio.Semaphore，限制单个域名的并发数不超过 2，全局并发不超过 10。这样既保证效率，又不至于太粗暴。
5.2 把“计划”和“执行”拆开
最开始我把计划生成和执行放在同一个循环里，模型每轮都可能重新调整计划，导致任务路径不稳定。后来我改成“先出计划，再执行计划”的两段式：Agent 收到任务后，先调用一次plan，输出一个有序的步骤列表；然后执行器按照步骤逐条调用工具。每完成一步，把结果回填到计划里。
这样做有个明显好处：计划阶段可以用更聪明的模型，执行阶段可以用便宜模型；同时，如果某一步失败，我可以精确知道是哪个计划步骤出了问题，而不是在整个消息历史里大海捞针。
5.3 缓存优先级高的工具结果
有些工具是典型的“重计算、低变化”，比如查询数据库里的月度汇总，或者抓取同一个页面。我在工具注册表里加了一个可选参数cache_ttl，单位是秒。设置后，相同参数的调用在 TTL 内直接走缓存，不重复执行。实测下来，日报类任务大概能省 60% 的工具调用量，成本下降非常明显。但写操作工具绝对不能缓存，这个应该不用我多提醒。
6. 我总结出的几条设计原则
最后分享几个我现在做项目会反复强调的原则，都是被实际生产任务逼出来的。
第一条：让 Agent 的每一步都可回放。没有 trace 的 Agent 就是一个黑盒，只能靠“再跑一次”来猜问题。hermes-agent 里每轮消息都带唯一 ID 和时间戳，出了任何异常都可以按 trace_id 回放整个过程。
第二条：工具调用结果必须比模型生成内容更可信。模型在工具返回后仍然可能“幻觉”出工具里不存在的数据。所以我的 system prompt 里有一条硬性规则：“当工具返回结果与你的既有知识冲突时，以工具结果为准，并标注信息来源。”这能明显减少编造。
第三条：上下文不是越多越好。不要舍不得删历史，删掉旧消息不会让 Agent 变笨，反而会逼它更专注于当前目标。尤其是工具返回的长文本，一定要提取之后再用，别直接把原文全塞进去。
第四条：为每个 Agent 设置明确的“完工条件”。没有完工条件的 Agent 会一直迭代到预算耗尽。我给 Agent 增加了done_when配置，可以是一个函数，判断最终结果是否满足要求；也支持简单的规则，比如“已经输出结构化 JSON 并且包含所有必需字段”。
说实话，hermes-agent 不是一个功能特别完整的项目，它更像我把过去一年踩坑经验浓缩成的一层薄框架。如果你只需要一个能跑通演示的 Agent，那直接调大模型 API 就够了；但如果你想让它每天稳定地在后台干活，这套“任务队列 + 工具注册表 + 上下文压缩 + 可观测轨迹”的组合，我认为是比堆砌更复杂框架更值得优先投入的方向。
