我在本地跑了大半年的个人自动化任务最后沉淀成了一个叫 hermes-agent 的项目。起这个名字没有太多玄学Hermes 本来就是传信的神刚好这个 agent 干的最多的事也是“接需求、调工具、回结果”和信使的定位非常贴合。这半年里我用它处理过邮件摘要、定时抓取某几个网站的价格变动、把不同平台的通知统一收敛到单一入口甚至偶尔替我在几个系统里执行一些固定的表格整理动作。今天这篇不是炫耀架构而是把整个项目拆开从设计思路、技术选型、核心实现到踩坑记录完整复盘一遍。如果你也在折腾自己的 AI Agent或者想给手头重复性工作找一个自动化的出口这篇文章应该能帮你省掉不少弯路。1. 项目定位与设计思路拆解1.1 为什么需要一个专属 Agent很多人第一次听到“Agent”这个概念第一反应是“这不就是个聊天机器人吗”。这是最大的误解也是我一开始做 hermes-agent 时踩进过的坑。普通聊天机器人是“你说一句我回一句”本质上是一个无状态的对话引擎。而 Agent 的核心在“行动”它需要理解你的目标自己拆解成步骤调用外部工具完成动作最后把结果汇总给你。如果只是问答我根本不需要再造轮子直接用现成的对话产品就好。我真正想解决的是那些“每周固定要做、简单但繁琐”的事比如每天早上汇总各项目组的进展、定期检查某几个页面是否更新、根据关键词筛选信息并生成日报。这些事单独看都不难但累积起来非常消磨精力。hermes-agent 的出发点是把任务描述用自然语言写清楚它就能学会执行。从技术角度说现在的大模型已经具备很强的意图理解和工具调用能力但原生 API 只是给了开发者一个对话接口不会主动帮你管理任务状态、维护上下文、处理失败重试。hermes-agent 做的事情就是在模型之上加了一层“行动闭环”接收任务、规划步骤、调用工具、校验结果、反馈完成。这一步之差就是玩具和工具的分水岭。1.2 功能边界与核心使用场景做 Agent 项目最忌讳的是“什么都想管”。我见过很多项目死因都是盲目扩张功能今天加个画图明天加个订机票后天加个读数据库最后每个功能都没做好还拖垮了稳定性。hermes-agent 的核心原则是只做能用标准输入输出接口完成的事不做需要依赖不稳定第三方服务的深度集成。目前实际在用的场景大致分四类场景典型任务自动化价值信息聚合定时抓取指定页面、汇总 RSS、监控价格变化不需要每天手动刷网页文本处理文章摘要、周报生成、邮件草稿省去大量重复写作时间跨应用触发收到关键词邮件后创建待办、异常触发告警让系统主动发现并解决问题数据整理把非结构化文本转成表格、分类打标签减少人工复制粘贴的出错率每个场景接进来之前我都会先问三个问题输入是否能标准化输出是否有明确验收标准如果工具挂了影响范围可控吗这三点都通过的需求才会正式接入。这个边界意识帮我避开了很多后期维护的坑也给 hermes-agent 留下了清晰的迭代方向。2. 技术选型与整体架构解析2.1 模型选型为什么选择“同模型多配置”先声明一个观点Agent 项目的核心不是模型本身而是模型与外部工具之间的“契约”。模型负责把自然语言转换成结构化意图工具负责执行。所以选模型的标准不是“谁的榜单分数高”而是“谁的格式遵循能力稳定”。我在 hermes-agent 里实际跑过多个模型从开源到闭源都有。最终保留了两套配置日常任务用推理成本更低、响应更快的轻量型号复杂任务用推理能力更强、上下文更长的重量级模型。这里有一个重要技巧同一个 Agent 内核通过配置切换模型而不是为每个模型写不同的调用逻辑。OpenAI 兼容接口格式已经成了事实标准很多模型服务商都提供兼容层所以我在代码里只维护一套 client切换模型只需要改配置项里的 model 名称和 base_url。这给迭代省了很多事也避免了被单一模型厂商绑定的风险。配置名适用任务特征参考模型能力要求选择理由fast单步工具调用、简单摘要、关键词筛选指令遵循能力强快便宜适合高频低难度任务pro多步规划、长文本理解、复杂推理上下文长、规划能力强准确率优先可以容忍响应慢2.2 工具层设计函数声明做统一入口Agent 和普通聊天最本质的区别就是工具。hermes-agent 里我把每一个外部能力都封装成一个工具函数然后用一个 JSON Schema 描述这个函数的参数、返回类型和用途。大模型在需要时会从工具清单里选中一个并生成符合 Schema 的调用参数框架负责执行并把结果回传给模型。这个设计是受到 Function Calling 机制启发的。它的好处非常明显工具层不需要感知业务逻辑只需要暴露“输入输出契约”。新增一个能力就是写一个普通函数再注册一个 Schema。例如查询天气、搜索文档、执行定时任务对模型来说都是“某个可调用的函数”它可以自由组合这些函数完成复杂任务。这个抽象层次让 Agent 的可扩展性变得非常强目前项目里已经注册了 20 多个工具但核心引擎代码几乎没有改动。2.3 任务编排用“规划-执行-核对”循环代替状态机第一版我试过硬编码状态机每个业务流程画一条链路节点和节点之间用条件跳转连接。后来越改越痛苦新增一个分支就要动状态定义和流转逻辑代码很快变得没法维护。第二版我换成了“规划-执行-核对”循环思路非常朴素模型根据系统提示和用户目标判断下一步需要调用哪个工具。框架解析模型输出的工具调用请求执行对应函数拿到结构化结果。将结果返回给模型模型决定是继续调用下一个工具还是输出最终答案。循环直到模型主动结束或者超过最大步数限制。这个模式看起来简单但实际效果非常稳定。它不限制模型必须用哪条路径完成任务而是给了一个“观察-决策-行动”的通用框架。遇到新任务时模型可以动态规划步骤不需要人为预设所有分支。2.4 记忆与上下文管理不能什么都往会话里塞Agent 项目最常见的性能杀手就是上下文膨胀。每次工具执行结果都拼进对话历史几轮交互下来就可能上万 token。hermes-agent 目前的处理策略分三层短期记忆仅保留当前任务轮次内的模型对话记录用于维持即时推理。工作记忆保存本轮任务中产生的中间结果比如抓取到的文本、表格数据放进独立的 memory 存储不入对话上下文。长期记忆对重要事实用户偏好、历史结论、结构化档案单独建索引按需检索注入。我实际踩过一个大坑早期把所有工具结果都直接塞回 messages对话超过十轮之后模型开始“失忆”反复忘记前端几个步骤的要求。后来把大段文本结果放进工作记忆只在需要时用检索方式提取关键信息这个问题才真正解决。上下文管理的经验总结下来就一句话对话上下文只放“推理过程”不放“数据本体”。3. 核心实现与实操步骤3.1 项目结构一个不臃肿的 Python 项目hermes-agent 没有使用重量级框架核心依赖只有 FastAPI、openai SDK 和 pydantic。项目结构非常直白方便自己后续维护hermes-agent/ ├── agent/ # Agent 核心逻辑 │ ├── core.py # 规划-执行-核对主循环 │ ├── context.py # 上下文与记忆管理 │ └── schema.py # 统一的输入输出数据结构 ├── tools/ # 工具注册目录 │ ├── registry.py # 工具管理器 │ ├── web_fetch.py # 抓取网页内容 │ ├── timer.py # 定时任务注册 │ └── notify.py # 消息推送 ├── config/ │ ├── settings.yaml # 模型、接口、运行参数 │ └── tools.yaml # 工具开关和密钥配置 ├── server/ │ └── api.py # FastAPI 入口处理外部请求 └── main.py # 启动脚本这个结构是我重构过三次以后确定的。每次重构都在做减法把耦合的部分拆出来把重复的逻辑收拢进去。现在的状态是任何人拿到这个目录看两分钟就能知道某个功能对应的文件在哪这比任何架构图都重要。3.2 工具注册机制十几行代码接入一个新能力工具注册是 hermes-agent 的基石。我先定义一个 BaseTool 类所有工具都继承它并实现execute方法。接着用一个注册器维护“工具名 - 工具类”的映射# tools/registry.py from typing import Dict, Type from pydantic import BaseModel class BaseTool(BaseModel): name: str description: str parameters: dict # JSON Schema def execute(self, **kwargs) - dict: raise NotImplementedError class Registry: def __init__(self): self._tools: Dict[str, Type[BaseTool]] {} def register(self, tool_cls: Type[BaseTool]): self._tools[tool_cls.name] tool_cls return tool_cls def get_schemas(self) - list[dict]: schemas [] for tool in self._tools.values(): schemas.append({ type: function, function: { name: tool.name, description: tool.description, parameters: tool.parameters, }, }) return schemas def execute(self, name: str, arguments: dict): tool self._tools.get(name) if not tool: raise KeyError(ftool not found: {name}) return tool().execute(**arguments) registry Registry()实际接入一个网页抓取工具时只需要几行声明# tools/web_fetch.py from tools.registry import BaseTool, registry registry.register class WebFetchTool(BaseTool): name: str web_fetch description: str 抓取指定网页的正文内容返回纯文本 parameters: dict { type: object, properties: { url: {type: string, description: 需要抓取的完整网址} }, required: [url], } def execute(self, url: str) - dict: # 这里只做核心逻辑演示实际还会加超时、重试、反爬策略 text fetch_page_text(url) return {status: ok, content: text[:5000]}模型端看到的函数列表就是由registry.get_schemas()动态生成的。新增一个工具模型立刻就能感知并调用这是 Function Calling 机制最爽的地方也是 hermes-agent 能够快速扩展的关键。3.3 Agent 主循环最核心的“规划-执行-核对”主循环是 Agent 的大脑我的实现思路是不断拼接 messages让模型在“工具调用”和“最终回答”之间做选择。代码核心如下# agent/core.py import json from openai import OpenAI class Agent: def __init__(self, config, registry): self.client OpenAI( api_keyconfig[api_key], base_urlconfig[base_url], ) self.model config[model] self.registry registry self.max_steps config.get(max_steps, 10) self.system_prompt ( 你是 hermes-agent 的执行引擎。请严格根据工具返回结果分析。 如果需要调用工具只输出工具调用信息齐全后再输出最终答案。 ) def run(self, user_message: str, context: dict | None None): messages [] if context: messages.append({role: system, content: self.system_prompt}) messages.append({role: system, content: f已知工作记忆{json.dumps(context, ensure_asciiFalse)}}) else: messages.append({role: system, content: self.system_prompt}) messages.append({role: user, content: user_message}) for step in range(self.max_steps): response self.client.chat.completions.create( modelself.model, messagesmessages, toolsself.registry.get_schemas(), tool_choiceauto, ) message response.choices[0].message messages.append(message) if message.tool_calls: for tool_call in message.tool_calls: fn_name tool_call.function.name fn_args json.loads(tool_call.function.arguments or {}) print(f[step {step}] 调用工具: {fn_name} 参数: {fn_args}) # 实际操作中走日志 try: result self.registry.execute(fn_name, fn_args) tool_result { role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse), } print(f[step {step}] 工具返回: {json.dumps(result, ensure_asciiFalse)[:100]}...) except Exception as e: tool_result { role: tool, tool_call_id: tool_call.id, content: json.dumps({status: error, error: str(e)}, ensure_asciiFalse), } messages.append(tool_result) continue # 没有工具调用说明模型认为信息已足够返回最终答案 if message.content: return {answer: message.content, steps: step 1} return {answer: 达到最大步数限制未生成最终答案, steps: self.max_steps}这个循环最大的优点是简单直白。每一步都通过打印日志看到工具调用情况出问题时很容易定位是哪一步出了岔子。虽然看起来没有某些 Agent 框架的“任务规划”模块那么炫但实际运行中模型已经能在上下文里完成简单规划复杂的长期规划需求在“工作记忆”配合下也能应付。3.4 消息触达与定时触发从被动接到主动干活Agent 不能只是别人调 API 才动很多实用场景需要它在一个固定时间主动执行。hermes-agent 里我用的是 APScheduler 做定时调度。定时任务本身也被设计成一个工具让模型可以“注册一个每天上午十点执行的任务”这就形成了闭环。# tools/timer.py import datetime from apscheduler.schedulers.background import BackgroundScheduler from tools.registry import BaseTool, registry scheduler BackgroundScheduler(timezoneAsia/Shanghai) scheduler.start() registry.register class ScheduleTaskTool(BaseTool): name: str schedule_task description: str 注册一个定时任务。cron 表达式格式为分 时 日 月 周 parameters: dict { type: object, properties: { task_desc: {type: string, description: 任务描述}, cron: {type: string, description: cron 表达式如 0 10 * * *}, }, required: [task_desc, cron], } def execute(self, task_desc: str, cron: str) - dict: # 实际项目中这里会解析 cron 并注册一个新 job # job 执行时会把 task_desc 发回 Agent 主循环重新生成执行计划 scheduler.add_job( funcdispatch_task, triggerCronTrigger.from_crontab(cron), args[task_desc], idftask_{datetime.datetime.now().timestamp()}, ) return {status: ok, message: f已注册定时任务: {task_desc} {cron}}我把定时触发设计成一个“重新进入 Agent 入口”的动作而不是直接用旧上下文执行。因为定时任务执行时外部环境可能已经变了模型应该基于新的输入做全新推理这样更可靠。3.5 部署与运行本地跑起来只需要三步hermes-agent 的部署门槛很低不依赖 Kubernetes也不依赖专门的 Agent 运行时。一台普通 Linux 服务器或者 Mac 本机都能跑得很稳。部署步骤大致是准备 Python 3.11 环境安装依赖。在config/settings.yaml里填写模型 API 地址、密钥、默认模型。执行python main.py启动核心服务和调度器。# config/settings.yaml model: api_key: your-api-key base_url: https://your-llm-endpoint/v1 fast_model: fast-model-name pro_model: pro-model-name default_model: fast-model-name max_steps: 10 server: host: 0.0.0.0 port: 8765API 服务本身是 FastAPI 暴露出来的一个 POST 接口外部系统把任务描述用 JSON 发过来Agent 执行完把结果返回和调用普通 HTTP 服务体验完全一致。这也让 hermes-agent 很容易嵌入到其他业务系统里。4. 常见问题与排查技巧实录4.1 模型输出不稳定经常不按格式返回这个问题在刚接 Function Calling 时经常遇到尤其是模型在复杂指令下会“自作聪明”地输出一些非标准字段。我的经验是三个方向排查确认工具 Schema 的参数描述写清楚了尤其是每个参数的单位、边界值、可选必选。确认系统提示词里没有和工具调用冲突的约束比如同时要求“只回复 JSON”和“调用工具”模型会卡死。确认模型版本对 Function Calling 的支持程度某些开源模型需要特殊的提示词模板配合。后两者之间模型版本是最容易忽略的。同一个模型API 版本升级一次行为可能就变了。我现在的做法是在配置里记录每个任务对应的“最后经过验证的模型版本”升级模型时先在测试环境跑一遍回归用例。4.2 上下文膨胀导致“失忆”前文说过上下文管理这里再补充一个实际排查技巧。如果你发现 Agent 执行到第五六步时开始忽略前文的某个约束先不要直接加大模型的上下文窗口。更大的上下文窗口意味着更高的成本和更慢的响应但模型对“远端信息”的注意力依然会衰减。我建议的执行顺序是先压缩工作记忆只保留高价值信息再对历史消息做裁剪把已经完成的中介步骤合并成摘要实在不行再升级更大上下文的模型。4.3 工具调用偶发失败网络超时和参数异常工具执行不是永远成功的网络超时、对方站点反爬、参数类型错误都有可能让调用中断。hermes-agent 统一在registry.execute外层做异常捕获把错误信息原样返回给模型。这时候模型通常会自动修正参数重试或者换一个工具路径这是 Agent 相比传统脚本的优势。我还给每个工具加了一个“失败重试次数”约定超过三次就不再强制重试直接返回失败状态避免死循环烧 token。# tools/registry.py 补充重试逻辑 def execute_with_retry(self, name, arguments, retries3): last_error for attempt in range(retries): try: return self.execute(name, arguments) except Exception as e: last_error str(e) time.sleep(1 * (attempt 1)) return {status: error, error: f重试 {retries} 次仍失败: {last_error}}这里有个小技巧重试时间用退避策略避免在目标系统还没恢复时频繁请求反而把自己 IP 封了。4.4 并发任务乱序结果张冠李戴当多个任务同时进入 Agent 时如果使用的是同一个模型实例和同一个消息列表很容易串上下文。我最初为了省资源用了一个全局 Agent 实例结果两台业务同时请求时回复经常答非所问。后来把所有状态全部改为“每任务独立实例”每个任务拥有自己的 messages 和 memory。成本会高一些但换来的是隔离性和稳定性。生产环境如果本就打算高并发这一步绝对不能省。5. 一些体会与后续可以扩展的方向hermes-agent 做到现在我觉得最值钱的不是那几千行代码而是对“Agent 能做什么、不能做什么”的判断。它最适合的是那些边界清晰、流程固定但需要一点理解能力的任务。千万别指望它一次就能完美处理所有边缘情况但在 80% 的正常场景里它完全可以当一个不知疲倦的助手。最后分享一个小技巧给 Agent 写工具描述时不要只写“功能是什么”还要写“什么时候用、什么时候不用”。比如天气查询工具的描述可以写成“查询某城市的实时天气。当用户询问明日出行是否需要带伞时使用当用户询问穿衣建议而你没有历史偏好数据时也使用该工具获取温度”。这种带场景的提示词比干巴巴的“查询天气”四个字有效很多倍也能显著降低模型的误调用概率。下一步我打算给 hermes-agent 加一个基于规则的简易“自省模块”当一个任务执行失败超过两次自动生成一条失败摘要发送到消息入口让我能及时感知并介入。这样 Agent 就不只是一个被动执行者而是逐渐具备了一点主动发现问题、上报问题的能力。如果你也在做自己的 Agent 项目希望这篇复盘能帮你绕开一些已经存在的坑。