做AI Agent这一年多我踩过最大的坑就是“模型很聪明但Agent很蠢”。你可以让大模型流畅写出千字文案但让它按流程调三个工具、把结果拼成一份完整报告它经常中途掉链子。后来我把整套流程重构成一个叫hermes-agent的轻量级框架解决了工具调用不稳定、上下文失控、多轮任务断裂这些老大难问题。这个名字取自希腊神话里的信使神赫尔墨斯——它不做决策、不生产内容只负责准确传达意图、调度工具、带回结果这个定位恰好就是AI Agent应该干的活。这篇文章我会把这套框架的设计思路、核心模块实现、踩坑实录完整拆开讲。不吹架构多先进全部是能直接落地参考的代码和参数。适合正在做Agent应用、被工具调用搞到头秃的开发者也适合想从零搭一套可控Agent框架、不想被LangChain等重型框架绑架的朋友。1. 项目定位与设计拆解hermes-agent 到底在解决什么问题1.1 为什么叫“信使”而不是“大脑”先聊一个很关键的理念问题。很多人做Agent上来就想让大模型“思考”更多链式推理、树状搜索、自我反思全往上堆。我的体会是生产环境里真正缺的不是思考能力而是执行可靠性。大模型在单次对话里的推理能力已经够用了但一旦涉及多步骤任务比如“查一下上海明天天气如果下雨就提醒我带伞顺便把明天的会议改成线上”模型需要连续完成识别意图、分解子任务、调用天气工具、判断天气情况、根据判断触发提醒、修改会议日程。每一步都有概率出错五个步骤乘起来成功率可能只有60%。hermes-agent 的定位是“信使”用结构化协议约束模型的输出用强校验保证工具调用的准确用状态机管理多轮任务的流转。它不负责让模型变得更聪明而是保证模型“说出去的话”能被系统准确执行。这一点决定了后续所有的架构选型。另外一个现实原因Agent项目最大的成本其实不在模型推理而在排查问题。今天工具参数传错了明天上下文被撑爆了后天模型自己编了个不存在的工具名。如果框架本身不可观测、不可控制开发体验会非常痛苦。1.2 项目要解决的三类核心问题我把日常开发里遇到的高频问题收敛成三类hermes-agent 的所有功能都围绕这三类展开工具调用的确定性。模型返回的 tool_call 有时 JSON 格式不合法有时参数名对不上有时函数名是它自己编的。框架要做的是用 schema 校验、类型转换、重试兜底把“模型输出”和“系统执行”之间的裂缝填上。上下文的可管理性。Agent 跑几轮之后历史消息、工具返回结果、中间推理过程全部堆在上下文里token 消耗爆炸而且模型容易被超长内容带偏。框架需要一套消息压缩与摘要机制在保证任务连续性的前提下控制上下文长度。多轮任务的状态连续性。一次用户请求可能触发多个工具的串联调用比如先搜索再总结再发送。每一步的中间结果要能被后续步骤引用失败时要知道从哪里重试而不是傻乎乎从第一轮重来。1.3 为什么不用现成的重型框架你可能想问市面上有 LangChain、LlamaIndex 这些成熟框架为什么还要自己写我自己用过的感受是重型框架最大的问题不是功能不够而是“黑盒太多”。编排链里的每一步都有一层抽象出了问题要层层剥开才能定位。而且框架的升级频率非常高API 说变就变今天写的代码过了两周就要重构。更重要的是框架内置的 Agent 逻辑往往是“通用最优解”而真实业务里的 Agent 一定是强定制化的——你的工具列表、校验逻辑、人机确认流程每个业务都不一样。与其在框架的约束里各种 hack不如把核心骨架掌握在自己手里。hermes-agent 的代码量其实不大核心只有几千行但每一行都知道它在干什么。这也是这篇博文想传递的核心观点Agent 框架没有多神秘拆开看就是“循环 工具注册 消息管理 状态机”这几块积木。2. 核心架构与关键模块设计2.1 基础循环Agent 的主流程长什么样Agent 的主流程本质上是一个 while 循环把用户消息和系统提示组成 messages 发给大模型模型返回文本或者工具调用指令如果有工具调用就执行工具、把结果追加回消息列表再发给模型直到模型返回最终文本循环结束。这个循环听起来简单但有几个设计细节会直接影响稳定性。第一循环必须设置最大迭代次数。我见过模型陷入死循环连续调用同一个工具 20 次token 全烧光了还在转。设置一个max_iterations默认 10 次超出就强制终止并把已收集的结果返回给用户。第二异常处理不能放在循环外面统包而是每一轮都要捕获。工具执行超时、抛异常、返回非法结果这些都是高频事件。合理的做法是“把错误也当成一种工具返回结果”塞回给模型让模型自己修正。比如天气接口超时了就返回“查询超时请重试”给模型模型可能会换个关键词重新查询。这比直接崩溃强得多。下面是我项目里最初的 Agent 循环骨架去掉了具体业务逻辑保留核心结构def run_agent(user_message: str, max_iterations: int 10): messages build_initial_messages(user_message) for step in range(max_iterations): response llm.chat(messages, toolstool_schemas) assistant_msg response.message if response.tool_calls: messages.append(assistant_msg) for tool_call in response.tool_calls: result execute_tool(tool_call) # 这里的异常要捕获 messages.append({ role: tool, tool_call_id: tool_call.id, content: serialize_result(result) }) continue # 没有工具调用说明模型想要结束对话 return assistant_msg.content return 任务步骤过多已自动终止请精简需求后重试。2.2 工具注册机制把函数变成模型能看懂的协议要让大模型正确调用工具关键在于把 Python 函数转换成 JSON Schema 形式的工具描述。这里面有两个容易忽略的细节。第一参数描述要写清楚。模型不看你的函数实现它的全部判断依据就是工具描述。我见过很多人写工具描述时偷懒函数名叫send_message参数 description 只写“消息内容”结果模型经常传错。规范做法是描述里明确参数格式、取值范围、常见错误示例。比如一个日期参数要在描述里写清楚“格式为 YYYY-MM-DD例如 2025-03-14”模型出错率会下降一大截。第二类型校验不能只靠模型自觉。模型返回的参数虽然按 JSON 格式来但经常类型不对。OpenAI 系的模型容易把数字参数写成字符串把字符串数组写成逗号分隔的文本。框架里必须有一层强校验和类型转换把模型输出转成函数真正需要的类型。我当时写了一个基于 pydantic 的工具注册器用装饰器自动生成 schema并在调用前做类型校验from pydantic import create_model, ValidationError import inspect, json class ToolRegistry: def __init__(self): self._tools {} self._schemas [] def register(self, fn): 装饰器把一个函数注册为Agent可用工具 sig inspect.signature(fn) fields {} for name, param in sig.parameters.items(): annotation param.annotation if param.annotation is not inspect.Parameter.empty else str default param.default if param.default is not inspect.Parameter.empty else ... fields[name] (annotation, default) # 基于函数签名动态生成pydantic模型,用于参数校验 model create_model(f{fn.__name__}_model, **fields) schema model.model_json_schema() schema[name] fn.__name__ schema[description] fn.__doc__ or 暂无描述 self._tools[fn.__name__] {fn: fn, model: model} self._schemas.append(schema) return fn def execute(self, name: str, arguments: dict): tool self._tools.get(name) if not tool: raise ValueError(f工具 {name} 不存在) try: validated tool[model].model_validate(arguments) except ValidationError as e: # 校验失败时返回结构化错误给模型让它自行修正 return {success: False, error: str(e), hint: 请检查参数类型与必填项} result tool[fn](**validated.model_dump()) return {success: True, result: result}这一层注册器的价值在于新增工具只需要写一个普通函数加一行装饰器框架自动处理 schema 生成、类型校验、错误包装。团队里任何人都能往 Agent 里加能力不需要懂大模型调用细节。2.3 结构化输出解析解决模型返回的“烂摊子”调用工具之前模型会返回一个 tool_call 请求里面包含函数名和参数。听起来简单但实际生产中我遇到过的乱象包括函数名多加了空格或大小写不一致参数是纯 JSON 字符串但少了引号模型自作多情地加了 Markdown 代码块包裹。这些问题不处理工具调用就是薛定谔的可靠性。hermes-agent 的做法是分层解析第一层做宽松清洗去掉代码块标记、多余空白第二层做 JSON 容错解析引号不全的补引号、单引号换双引号第三层用 pydantic 做严格校验。三层都过不了才返回错误给模型重试而不是直接崩溃。清洗代码看起来很碎但真实场景特别管用import json, re def parse_tool_args(raw: str) - dict: # 第一层: 去掉可能包裹的代码块 text raw.strip() text re.sub(r^(?:json)?|$, , text, flagsre.MULTILINE).strip() # 第二层: 直接json.loads,失败就走容错 try: return json.loads(text) except json.JSONDecodeError: pass # 第三层: 单引号替换为双引号(只处理最简单的场景) fixed re.sub(r\, \, text) try: return json.loads(fixed) except json.JSONDecodeError: # 第四层: 尝试把裸数字/裸字符串包成合法JSON if text.isdigit(): return json.loads(f{{value: {text}}}) raise ValueError(f无法解析工具参数: {raw[:200]})这里要特别强调容错解析只作为兜底不能依赖它。真正的防线是提示词里给足示例同时每次模型返回 tool_call 之后先做 schema 校验校验不过就让模型重新生成。我统计过加了显式 tool_call 格式说明和示例之后解析失败率从 8% 降到了 1% 以下。3. 实操过程从第一行代码到跑通完整链路3.1 环境选型与依赖清单动手之前先说环境。语言我用 Python 3.11依赖保持最小化核心只需要openai或者任意 OpenAI 兼容接口的 SDK、pydantic、python-dotenv三个。模型方面我当时测试用的主力是 gpt-4o-mini 和国内的几个兼容模型凡是支持 function calling 的模型都可以平替接入。选型逻辑很简单pydantic 负责类型校验这是 Agent 最需要的刚性约束openai SDK 生态最成熟而且国内多家服务商提供 OpenAI 兼容接口换供应商只需要改 base_url 和 api_key。这套组合的好处是“哪都能跑”不会被任何一个云厂商锁死。我不建议一上来就引入向量数据库、消息队列这些重组件。Agent 的第一版核心目标只有一个让模型稳定地调用工具完成任务。存储是后话等数据量上来了再考虑也不迟。3.2 搭建系统提示词Agent 行为的“宪法”很多人忽略系统提示词的重要性上来就写一句“你是一个智能助手你可以使用工具”。这远远不够。Agent 的系统提示词本质上是一份行为契约要明确回答三个问题你是谁、你能干什么、遇到各种边界情况怎么处理。我项目里的系统提示词包含这么几块内容角色定义。明确 Agent 是任务执行者不是闲聊对象回答要简洁先动手再解释。可用工具清单。列出所有工具名称和一句话说明强调“只使用提供的工具不得编造工具”。调用规范。要求模型每次只做一件事复杂任务拆成多步执行调用工具前要确认参数完整缺参数就追问用户。错误处理约定。工具调用失败时先看错误原因能修就修不能修就如实告诉用户不要假装成功。安全边界。涉及删除、覆盖、发送等敏感操作必须先向用户确认再执行。这里放一份精简版模板供参考你是 hermes-agent,一位严谨的任务执行助手。你的工作方式是: 1. 拆解用户请求,决定是否需要调用工具。 2. 如果需要工具,严格按照提供的工具 schema 生成调用参数。 3. 工具返回结果后,基于结果继续推进任务或生成最终回复。 4. 绝不虚构工具或编造调用结果。工具报错时,根据错误信息调整参数重试,最多重试2次。 5. 涉及删除、发送、支付等敏感操作,先向用户确认。 6. 回复使用中文,简洁有条理,重要数据用列表呈现。这套提示词看着朴素但每一条都对应着真实踩过的坑。比如“最多重试2次”就是防止模型无限重试同一个失败工具。3.3 实现多工具并行调用我在开发过程中发现一个高频需求一次请求要同时查询多个独立数据。比如“查一下北京和上海明天的天气”如果一个个查要三轮对话才能完成体验很差。OpenAI 系的 function calling 支持一次返回多个 tool_call框架要做的就是允许多个工具并行执行。并行执行的实现比看起来复杂一点主要在于消息拼接的时序。模型返回多个 tool_call 时所有结果都要追加到 messages 里而且每个 tool 消息必须对应正确的tool_call_id。如果拼错模型会困惑“这个结果到底是哪个请求的”。我当时的实现是先把所有工具调用并发执行等全部返回后再统一追加到消息列表from concurrent.futures import ThreadPoolExecutor def handle_tool_calls(tool_calls, registry): with ThreadPoolExecutor(max_workersmin(len(tool_calls), 5)) as pool: futures { pool.submit(registry.execute, tc.function.name, tc.function.arguments): tc.id for tc in tool_calls } tool_messages [] for future in futures: tc_id futures[future] try: result future.result(timeout30) except Exception as e: result {success: False, error: str(e)} tool_messages.append({ role: tool, tool_call_id: tc_id, content: json.dumps(result, ensure_asciiFalse) }) return tool_messages这里有个细节并发数我限制在 5 以内。主要考虑到两个因素——大多数模型一次返回的 tool_call 数量很少超过 5 个另一方面并发太高会让下游接口承受压力尤其是内部系统接口普遍脆弱。3.4 引入“人机确认”机制让 Agent 学会停下来Agent 最让人不放心的一点是它做了破坏性操作怎么办。比如让 Agent 帮你删除一条数据库记录如果模型直接删了事后想恢复就麻烦了。我在 hermes-agent 里加了一个“敏感操作确认”机制把它做成一个特殊的工具ask_user_confirm。模型在系统提示词中被明确要求遇到删除、覆盖、发送、支付等操作先调用ask_user_confirm把操作描述和参数传给用户确认用户确认后才能真正执行目标工具。这个机制的好处是双重的既保护了业务安全又给模型创造了一个“停下来问人”的合法出口减少它擅自决策的概率。实现上就是注册两个工具一个是确认钩子一个是真实执行工具。确认工具返回“用户已确认”或“用户已取消”模型根据返回值决定下一步registry.register def ask_user_confirm(operation_desc: str, params: dict) - dict: 在执行敏感操作前向用户确认。operation_desc: 操作描述; params: 将要执行的参数 confirmed input(f是否确认执行以下操作? {operation_desc} {params} [y/n]: ) if confirmed.strip().lower() in (y, yes): return {confirmed: True} return {confirmed: False, message: 用户已取消操作}生产环境里把这个input换成推送确认卡片或者企业微信审批即可核心逻辑不变。4. 常见问题与排查实录4.1 模型幻觉工具名编造不存在的函数这是所有 Agent 开发者最先遇到的坑。模型在工具调用时偶尔会返回一个完全不在注册列表里的函数名比如工具叫search_news它返回news_search。原因多半是训练数据里见过类似的函数名被模型误当成了可用工具。排查方法很简单框架的错误回传信息里要包含“可用工具列表”让模型知道它用了不存在的函数。我在 execute 方法里当工具名找不到时会返回这么一条结构化错误给模型{ success: false, error: 工具 news_search 不存在, available_tools: [search_news, get_weather, send_email] }加上可用工具列表后模型基本能在下一轮修正回来。如果反复出现同一个幻觉说明工具名起得太模棱两可干脆换个更具体的名字比如把search_news改成search_news_by_keyword幻觉概率会明显下降。4.2 上下文膨胀token 越烧越多的真相Agent 长跑之后有个通病messages 列表越来越长每一轮的 tool 返回结果都原样塞进去。尤其工具返回的是大段文本或完整 JSON几轮下来上下文就爆了。我的处理策略是三管齐下第一工具返回结果要做裁剪。注册工具时给每个结果加一个max_result_length比如默认 2000 字符超过就截断并在末尾标注[已截断, 如需完整数据请指定查询字段]。模型做分析和决策其实不需要超长原始数据它需要的是关键信息摘要。第二历史消息启用滑动窗口。早于 N 轮的对话内容不再以原始消息形式发送而是压缩成一行摘要。这里可以用一个简单的做法把早于窗口的消息交给模型做一次压缩生成主题摘要后续轮次只带摘要和最近窗口的完整消息。第三设置单轮工具结果的 token 预算。我在消息组装层加了一个估算函数超过预算的轮次自动触发摘要流程。实测同样的任务上下文 token 消耗能降低 40% 以上而任务成功率基本持平。4.3 工具串行依赖第二步的结果依赖第一步怎么办有些任务必须严格串行比如“先查询订单状态再根据状态决定是否发送通知”。并行调度在这种情况下不适用因为第二步的参数学要第一步的结果。我的做法是在 Agent 循环里不做特殊处理靠模型自己调度。模型拿到第一步的工具返回值后自然会根据内容生成第二步的调用参数。真正需要关注的是第一步的结果要足够结构化方便模型提取关键字段。所以我在设计工具时尽量让返回值用 JSON 而不是自然语言描述。一个典型场景是查询订单后返回原始 JSON模型能够准确读到order_id和status然后决定下一步调什么工具。如果工具返回的是“订单已找到状态为已支付”这种自然语言模型虽然也能读懂但提取关键字段的准确率会下降。所以Agent 工具返回结构化数据是铁律。4.4 模型重复执行同一个工具另一种常见故障模型反复调用同一个工具比如连续查询五次天气。原因通常是模型觉得第一次的结果不够“准确”或者它在尝试不同的查询参数来自我验证。这个问题要分情况处理。如果重试是用来修正错误参数那是有益的如果是重复执行相同参数就是浪费。我在工具执行层加了一个简单的去重逻辑短时间窗口内比如 30 秒相同工具名加相同参数只允许执行一次后续相同请求直接返回缓存结果并附带提示“结果来自缓存”。这个逻辑在做 RAG 检索类工具时尤其有用因为检索本身耗时长、费用高。加上缓存后一次任务里多次相同检索直接命中缓存性能和成本都改善明显。5. 可观测性给 Agent 装上“行车记录仪”5.1 日志记录每一步都要能追溯Agent 调试最难的是“黑盒感”。模型中间想什么、工具返回了什么、为什么最终给出那个回答如果看不到过程出了问题只能盲猜。我在 hermes-agent 里内置了一套结构化日志把每一轮循环的关键信息记录下来。记录的信息包括step 编号、LLM 输入的 messages 摘要、模型返回的 content 和 tool_calls、每个工具的执行耗时和返回结果摘要、异常堆栈。日志格式我用 JSON Lines每一行是一条独立事件方便后续用 jq 或者日志平台检索。举个例子记录工具调用是这条命令搞定的logger.info(json.dumps({ event: tool_call, step: step, tool: tool_name, args: truncate(args, 500), latency_ms: latency_ms, success: is_success }, ensure_asciiFalse))生产环境里我还会把 trace_id 贯穿整个会话这样从用户发起请求到最终回复所有日志都能串成一条线。排查问题的时候按 trace_id 一搜问题链路一目了然。5.2 中途断点允许人为介入和修正Agent 跑偏的时候最理想的状态不是等它跑完再改而是在中途打断纠正。我在框架里实现了一个简单的“手工介入”接口每一轮循环结束后检查一个外部控制文件或数据库标记如果标记为“暂停”就停下来把当前进度暴露出来等人工修正后继续。这个功能在初期调试阶段极大提升了效率。模型连续两轮调用参数一致但结果不对我能及时打断修改提示词或工具描述后继续跑不用重新开整个任务。后续迭代里这个断点还能扩展成人工审批节点自动化团队里其他角色也能介入 Agent 的决策过程。5.3 成本追踪别让 token 悄悄烧光最后说成本。Agent 项目上线后最容易被忽视的就是 token 消耗尤其工具调用场景每多一轮循环就多一次完整请求成本随轮数线性增长。我在框架的日志系统里加了一个成本估算模块按模型单价实时统计每一步的输入输出 token 数和预估费用。每轮任务结束后输出一行汇总总轮数、总输入 token、总输出 token、预估费用。上线初期每天看一遍这个数字你会对“模型重复调用工具”的容忍度瞬间降低。我调优过一轮之后同样的任务成本降了一半靠的就是砍掉多余的循环和压缩过长的工具结果。写在最后hermes-agent 这个项目做到目前这个版本我的体会是Agent 的本质不是让模型“变聪明”而是给聪明的模型一套不犯错的工作流。工具注册、参数校验、结果裁剪、日志追踪这些看起来不性感的工作才是 Agent 能落地、能上生产、能被团队其他人放心使用的关键。最后分享一个我习惯的小技巧每次给 Agent 加一个新功能先别急着堆代码把“用户一句话 → Agent 操作工具 → 返回结果”的完整路径用文字写出来再对着路径检查哪一步可能出错、哪一步需要确认、哪一步需要回退。把这些问题想清楚代码只是顺手的翻译工作。这套“先想清楚边界再动手编码”的思路比任何框架都值钱。