市面上的Agent框架不少，但真正拿到生产环境里用的时候，问题一堆：要么工具调用不可控，要么会话状态乱七八糟，要么出了问题根本没法排查。我自己在做一个内部客服机器人项目的时候，被这些问题折磨得够呛，所以才动手写了hermes-agent这个项目。它不是一个“教你调大模型接口”的玩具框架，而是一个面向真实业务的Agent编排与执行基础设施，核心就干三件事：让Agent的行为可控、运行过程可观测、出问题之后可恢复。这篇文章我会从设计思路、核心架构、实操搭建、生产部署到问题排查，完整复现一遍我在这套框架上积累的经验，适合已经玩过LangChain或直接调过API、现在想把Agent真正落到业务里的开发者参考。
1. 项目定位与整体设计思路
1.1 为什么需要一个“Agent基础设施层”
很多团队做Agent应用，第一步就是用LangChain或直接写个循环调大模型。原型阶段确实很爽，代码量少，演示效果也好。但一旦进入生产，马上会遇到几个无法回避的问题。
最典型的是工具调用的不确定性。大模型返回的结果里说要调用某个工具，但参数经常是错的，甚至工具名字都能凭空捏造出来。我见过最离谱的一次，模型说要调用一个叫send_email的工具，我整个项目里压根没有这东西，它自己编了一个。另一个问题是状态管理混乱。用户多轮对话之间的上下文，Agent执行到一半的状态，这些如果都靠全局变量或者每次重新算，迟早出事。
第三个痛点是可观测性。大模型不是确定性程序，同样的输入每次输出可能都不一样。一旦线上出了问题，你连“Agent当时为什么做出这个决定”都说不清楚，排查一个故障可能要翻好几天的日志。
所以我才决定自己做一层“Agent基础设施”，而不是继续在应用层打补丁。hermes-agent的定位很明确：它是介于大模型和业务系统之间的执行框架，负责把模型输出转成可靠的工具调用、维护完整的会话状态、记录每一步执行的痕迹，并且提供一套恢复机制。业务开发只需要关注“注册什么工具给Agent用”和“拿到最终结果后干什么”，中间的编排逻辑、重试、日志，全部由框架接管。
1.2 hermes-agent的四个核心设计原则
我在设计这个框架的时候，给自己定了四条硬性原则，从第一版到现在都没变过。
第一，工具必须有Schema且严格校验。大模型可以自由发挥，但工具调用必须规范化。每个工具在注册时都要声明一个JSON Schema，框架会用强校验去拦截非法请求。模型说“我要调send_email”，但Schema里没这个名字，直接拒绝并把它记录成一次“幻觉调用”，而不是傻乎乎地报错崩溃。
第二，会话状态必须可持久化。Agent执行到一半，进程重启了，任务状态不能丢。我把状态全部序列化到存储层（默认是Redis），每一步执行完都会同步快照。这样即使服务挂掉，重新拉起之后可以从最近一个稳定状态继续跑，而不是从头再来。
第三，一切执行都要留痕。模型的输入输出、工具的参数和结果、每次重试的原因，全部写入审计日志。这不是为了做合规，而是为了出问题时能快速定位。我现在排查线上问题，第一件事就是打开审计日志看当时Agent执行到哪一步、模型返回了什么、工具报了哪个错，比大海捞针翻普通日志快得多。
第四，模型要可替换。我用了一个Adapter层把模型厂商的差异屏蔽掉。同一个Agent配置，你可以用OpenAI的、用开源的本地模型，或者用国内厂商的API，只需要改配置文件里的一个字段。这个设计在后来帮了大忙，某家API在高峰期疯狂超时，我直接把流量切到备用的本地模型，业务不停。
1.3 与直接调大模型API的差异对比
很多人会问一个问题：我什么时候应该引入这类框架，什么时候不该用？
我的建议很简单：如果只是做单轮的、单一工具的简单调用，比如“把这段文字翻译成英文”，直接调API完全够用，别引入额外复杂度。但如果是多步骤任务、多个工具协同、需要多轮对话记忆的场景，手写代码的代价会变得非常高。
用一个表格来对比会清晰很多：
| 维度 | 直接调大模型API | hermes-agent |
|---|---|---|
| 工具调用 | 模型输出JSON后自己解析、自己校验 | 内置Schema校验，非法调用自动拦截并重试 |
| 会话状态 | 自己管理，容易丢 | 自动持久化到Redis等存储，可恢复 |
| 可观测性 | 自己打日志，缺失关键信息 | 每一步执行都有审计追踪和耗时记录 |
| 重试与降级 | 自己写调用链 | 内置重试策略和模型降级机制 |
| 多Agent协同 | 自己编排 | 提供消息总线和任务分发机制 |
这个对比不是说要踩API直调，而是说在一个相对复杂的项目里，框架帮我们省掉了那些“基础设施”层面的重复工作，让我们能更专注在业务逻辑上。
2. 核心组件拆解：每一层在做什么
2.1 Model Adapter：让模型可替换是基础能力
Model Adapter是我最早写的一个组件，也是整个框架的地基。它的职责很纯粹：把不同厂商的模型接口封装成统一的调用方式，统一输入格式、统一输出格式、统一错误处理。
为什么要做这一层？因为模型厂商的API五花八门。有的是messages结构，有的是prompt字符串；有的返回choices[0].message.content，有的返回data.response。如果不做封装，每换一个模型就要改一遍业务代码，这谁也顶不住。
实现上，Adapter暴露一个统一的complete(session)方法，把本地格式的会话记录转成厂商API需要的格式，再把它返回的内容转成框架内部统一的ModelResponse结构。这个结构里有三个核心字段：content表示模型返回的正文字符串，tool_calls表示模型想要调用的工具列表（可能为空，也可能同时想调多个工具），finish_reason用来判断是正常结束还是达到最大长度被截断。
实际测试中，同一个业务配置，在GPT-4、Claude、还有几个开源模型上跑同一批测试用例，工具的调用成功率差距很大。所以Adapters层里我额外加了一个compatibility配置项，用来说明该模型在JSON输出和工具调用上的可靠程度，方便针对性地调整校验策略。比如有些模型输出JSON的时候喜欢加反引号包裹，框架会自动做清洗，而不是直接把这个任务判定失败。
2.2 工具注册中心与执行沙箱
工具注册中心是整个框架最核心的部分。在hermes-agent里，一个工具就是一个普通函数加一段声明。声明部分用JSON Schema描述这个函数的用途、参数类型、哪些参数必填、哪些是枚举值。注册的时候，框架会把这段Schema存起来，并在每次调用前用来校验模型生成的参数。
这样做的好处非常明显。有一次排查一个Agent老是调错“账户查询”接口，打开审计日志一看，模型生成的参数里余额方向搞反了，把“收入”当成了“支出”。因为Schema里定义了枚举值，框架在调用前拦截了这次错误请求，自动触发了模型重新生成参数，最终返回了正确结果。这个机制大大降低了模型幻觉对业务的影响。
执行沙箱则负责工具函数的安全运行。在Python环境里，我默认通过concurrent.futures把工具执行丢到单独的线程池，并设置超时时间。比如一个查询接口最多执行5秒，超过就杀掉线程并标记超时错误。同时沙箱还会捕获工具抛出的异常，转成框架统一的ToolError结构，里面带有错误码和信息，方便模型下一次生成时能够参考。
2.3 会话与记忆管理模块
Agent应用和普通API最大的区别在于它是有“记忆”的。多轮对话里，用户说“刚才那个需求再改一下”，Agent必须知道“刚才那个”指的是什么。这里我用了一个分层记忆的设计，分成短期记忆、长期记忆和任务记忆三层。
短期记忆就是当前会话窗口里的消息列表，它直接作为模型的上下文输入。长期记忆是用户与Agent交互过程中沉淀下来的持久化信息，比如用户偏好、常用参数等。任务记忆则是每一次任务执行的完整状态：当前执行到哪一步、哪些工具已经调用过、结果是什么、下一步待办是什么。
任务记忆需要重点说一下，因为这是生产环境里最容易出问题的地方。早期版本我就是把所有消息全塞到一个列表里，结果上下文越来越大，用户问到第五轮之后模型就开始“忘事”。后来改成按“任务会话”来组织，每个用户请求进来会创建一个TaskSession对象，内部保存状态机。任务执行完，短期记忆会被摘要压缩后转存到长期记忆，避免上下文无限膨胀。这个优化之后，长对话场景的任务完成率提升非常明显。
2.4 审计日志与行为追踪
很多人低估了审计日志的作用，直到线上出了事故才追悔莫及。hermes-agent的审计日志不是简单打印几行信息，而是把每次交互的关键节点都记录成结构化事件。
这里面有几个必记的事件类型：model_request记录发送给模型的完整请求和返回内容，tool_validation记录工具调用的Schema校验结果，tool_execution记录工具执行的入参、出参、耗时和错误信息，session_event记录会话的创建、恢复、归档等生命周期事件。每个事件都会附带一个request_id，从用户请求进入系统到最终响应返回，整条链路的日志可以通过这个ID串联起来。
这个设计在实际排查问题时帮了大忙。有一次线上一个Agent任务执行到一半卡死了，前端一直转圈。我拉出审计日志，发现卡在最开始的一次模型调用上，耗时已经超过60秒。再一看model_request的元数据，是上游API在高峰期返回变慢，而不是我们的代码死循环。定位问题花了不到两分钟，这在没有审计日志的时代是不可想象的。
3. 从零搭建一个可用的Agent实例
3.1 环境准备与安装
这一节是给第一次接触hermes-agent的读者准备的实操环节。我们一步步把一个能跑通“查询订单并退款”场景的Agent搭起来。示例用的Python版本是3.10+，跨平台通用，Windows和Linux都跑过。
安装很简单，直接用pip：
pip install hermes-agent这个包会把它依赖的核心库一起装上，比如pydantic用于Schema解析，redis用于状态存储（如果你不用Redis，本地会退回到SQLite或者内存模式，这点后面细说）。
安装完跑一下版本号确认安装成功：
hermes --version如果输出版本号，说明环境没问题。然后你需要准备一个模型服务的API Key。hermes-agent默认支持OpenAI格式的接口，所以理论上你只要有一个模型API的base_url和key就能配起来。
我建议第一次跑的时候不要在配置上花太多时间，先用一个最小配置把链路走通，再逐步增加配置项。
3.2 最小化配置说明
创建一个目录hermes-demo，然后在里面建一个config.yaml文件，内容是最小可用的配置：
hermes: default_model: gpt-4o-mini model_adapters: - name: openai_compatible env_key: OPENAI_API_KEY base_url: https://api.openai.com/v1 state_store: type: memory tool_packages: - demo_tools逐个解释一下这些配置项。default_model指定默认使用的模型名称，也就是你的模型服务商那边的真实模型ID。model_adapters配置有哪些模型可连接，这里用的是OpenAI兼容格式，如果你的服务商有自己的风格，需要换成对应的Adapter名称。state_store配置会话状态存在哪里，memory表示进程内存，适合本地测试，生产环境请换成Redis。tool_packages指定需要加载哪些工具包，这里我们指向待会儿要写的demo_tools模块。
配置文件的另外一个好处是可以放环境变量占位符，比如${OPENAI_API_KEY}，避免把密钥写死在仓库里。我第一次用的时候就是把Key写进了配置文件，结果忘了删就提交到了Git仓库，十分钟不到就收到了一封警告邮件，血泪教训。
3.3 注册第一个工具
接下来我们写第一个工具。在hermes-demo目录下创建demo_tools.py文件，内容大概是这样的：
from hermes_agent import tool @tool( name="query_order", description="根据订单号查询订单的基本信息，包括订单状态、金额、商品名称。", parameters={ "type": "object", "properties": { "order_id": { "type": "string", "description": "待查询的订单编号，格式通常为ORD开头后跟数字" } }, "required": ["order_id"] } ) def query_order(order_id: str) -> dict: # 这里模拟一个真实的订单系统查询 if order_id.startswith("ORD"): return { "order_id": order_id, "status": "paid", "amount": 99.99, "product": "会员年卡" } return { "order_id": order_id, "status": "not_found", "message": "订单不存在" }这里面最重要的地方是@tool装饰器里的parameters定义。这个JSON Schema就是前面说的“工具合同”，模型在生成调用参数时会参照这段定义，框架在执行前也会校验它。
关于字段description，我强烈建议写详细一点，不要只写“订单号”三个字。因为大模型是靠描述来理解参数的。写“订单号，格式通常为ORD开头后跟数字”和只写“订单号”，模型在生成参数时的准确率是完全不一样的。实测下来，描述越具体，工具调用的成功率越高。这算是Prompt工程在工具定义上的一个延伸。
demo_tools.py里还可以注册第二个工具“执行退款”，原理一样，这里就不重复贴代码了。
3.4 执行一个多步骤任务的完整流程
工具注册好之后，我们就可以用Agent来跑一个完整任务了。写一个run.py：
from hermes_agent import Agent def main(): agent = Agent.from_config("config.yaml") task = "帮我查一下订单ORD123456，如果订单状态是已支付，就执行退款操作；退款金额要等于订单金额。" result = agent.run(task) print("最终结果:", result.output) print("执行过程:") for step in result.trace: print(f" 步骤{step.index}: {step.description} -> {step.status}") if __name__ == "__main__": main()跑起来之后，框架内部会做这样几件事：
第一步，把用户的任务塞进一个TaskSession，调用模型。模型返回一个计划，里面包含“先调用query_order查询订单状态”这个意图。框架检查query_order工具的Schema，确认参数order_id合法，执行工具，拿到订单状态是“paid”。
第二步，模型发现订单是已支付状态，继续生成下一步计划“调用refund_order工具，退款金额99.99”。框架再次校验参数，确认金额和订单金额一致，执行退款工具。这里如果模型生成的金额和订单金额不一致，比如99.99写成了999.9，框架内置的校验逻辑会直接拦截，而不是傻乎乎地把钱退错。
第三步，模型拿到退款成功的返回，生成最终回复：“订单ORD123456已查询，状态为已支付，已执行退款99.99元。”然后finish_reason变为正常结束，整个TaskSession归档。
跑完上面这个示例，你就对hermes-agent的基本行为有了直观感觉。接下来可以试着改一下任务描述，让它处理一个查询不到的订单，看看框架会怎么处理“模型生成的参数合法但业务上不存在”的情况。这类分支逻辑在真实业务里非常常见。
3.5 关键配置参数速查
给新手整理一份常用配置参数对照表，方便调试时查阅：
| 配置项 | 默认值 | 作用 | 建议 |
|---|---|---|---|
hermes.max_retries | 3 | 模型调用失败时的重试次数 | 高峰期可调高到5 |
hermes.request_timeout | 30 | 每次模型请求的超时时间 | 流式模型可放宽到60 |
hermes.execution_timeout | 5 | 单个工具函数的最大执行时间 | 根据实际接口耗时调整 |
hermes.state_store.type | memory | 状态存储类型 | 生产环境必换redis |
hermes.audit_log.enabled | true | 是否记录审计日志 | 建议永远开启，日志可异步落盘 |
hermes.max_context_length | 8000 | 短期记忆的最大token估算值 | 超过后自动摘要压缩 |
新手最容易忽略的是max_context_length。早期我跑长对话任务经常莫名其妙报“token超出限制”，后来才发现是上下文积累得太长，模型的输入框直接塞爆了。配置好这个参数之后，框架会在接近上限时自动触发摘要逻辑，把早期的对话压缩成一段摘要，再和最近的对话拼在一起喂给模型。效果上，任务完成率没怎么下降，但token消耗降了将近一半。
3.6 三种典型运行模式
除了上面演示的“单次任务模式”，hermes-agent还内置了另外两种运行模式，分别是“流式对话模式”和“服务端守护模式”。
流式对话模式适合用在自己的产品里给用户交互。它维护一个常驻的对话循环，每一轮用户输入进来都会更新当前会话的上下文。这个模式在底层会自动管理短期记忆和长期记忆的转换，不需要应用层操心。我自己在接WebSocket的时候用的就是这种模式，用户发一句，Agent回一句，整个过程感觉就像和一个懂行的同事在聊天。
服务端守护模式则是为了应对高并发场景。框架内置了一个轻量的HTTP服务，你只需要把工具函数注册好，启动服务，就能通过HTTP接口调用Agent能力。每个请求会带上一个user_id，框架根据这个ID做好会话隔离。这种模式适合前后端分离的团队，后端只暴露工具接口，Agent服务由这个守护进程单独维护，互不干扰。
三种模式各有适用场景，单次任务模式适合批处理任务，流式对话模式适合聊天机器人，服务端守护模式适合当作微服务来用。选择的时候不用纠结，先按最贴近自己业务的模式开始，后续随时切换。
4. 生产环境部署与性能调优
4.1 服务化部署与并发控制
本地跑通之后，下一步就是把Agent发布到生产环境。我基于FastAPI封装了一套可选的HTTP服务，但推荐的做法是用容器化部署。这里给一份Dockerfile参考：
FROM python:3.10-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple COPY . . CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8080", "--workers", "4"]关于并发控制要专门提醒一下。大模型接口有频率限制，工具函数可能有数据库锁之类的并发隐患。所以我不建议直接横向扩容很多个Agent实例，而是建议用“分桶隔离”的策略。比如每个用户绑定到固定的Worker进程，或者用分布式锁控制每个用户同时最多执行一个任务。在我自己的部署里用的是Redis锁，先抢锁再执行，抢不到就直接返回“正在处理中”，避免同一个用户重复提交任务导致状态错乱。
--workers参数也要注意，不是越大越好。默认的Uvicorn单Worker就够了，因为同一个模型API的并发太高容易触发限流。如果必须多Worker，建议给每个Worker配独立的Redis库编号做状态隔离，否则多个Worker同时处理同一个任务，状态写来写去会把Session搞乱。
4.2 模型降级与重试策略
生产环境里最怕的不是Agent答错问题，而是模型接口突然不可用。一次大范围故障，所有业务全部停摆，这是我们做线上系统最不想遇到的场景。
hermes-agent内置了模型降级机制。配置中可以设置一个模型列表，按优先级排序：
hermes: model_chain: - name: gpt-4o-mini priority: 1 - name: local_llm priority: 2 - name: fallback_llm priority: 3当优先级最高的模型连续失败超过阈值后，框架会自动把请求切换到下一个优先级的模型，同时记录一条model_switch事件到审计日志。这个机制在实战中非常有用。有一次某家云端API服务故障了一个多小时，但我的业务没有中断，流量全部被框架自动切换到了本地部署的模型上，尽管响应质量略差，但至少服务是可用的。
重试策略也需要区分对待。模型接口报rate_limit错误时可以重试，但需要指数退避，避免雪上加霜；工具执行返回业务异常时不要盲目重试，因为同样的输入大概率还会得到同样的错误。我见过有人写循环重试，把一个查询余额的接口在余额不足时反复调用了好几次，最后被风控系统盯上了，这个场景有点啼笑皆非。
4.3 状态存储选型
状态存储是生产环境里非常基础的一个决策。它决定了Agent会话能否在多个进程、多台机器之间共享。
本地单机调试时，memory模式就够用，反正进程重启就一切归零。但生产环境中，尤其是用多个Worker部署时，我建议直接用Redis。
具体的配置是：
hermes: state_store: type: redis host: your-redis-host port: 6379 db: 0 prefix: agent_session ttl: 86400其中ttl是会话的过期时间，单位是秒。86400就是一天内没有活跃的会话会被自动清理，避免Redis内存无限增长。需要注意的是，Redis的maxmemory策略要设置成allkeys-lru或volatile-lru，防止遇到Redis内存满了之后写不进去数据的问题。
此外，我还遇到过Redis连接数被打满的情况。原因是每个Agent实例默认会创建自己的连接池，如果Worker数量较多，连接数就会涨得很快。建议把连接池的大小限制在10左右，并且开启连接复用，而不是每次请求都重新建连。
对于不想维护Redis的团队，也可以用PostgreSQL作为存储后端，框架会把Session状态序列化成JSONB字段存储。这种方案在高可用和备份上更简单，但读写性能会低于Redis。我个人的选择是：短会话用Redis，长会话或者包含敏感数据的用PostgreSQL，因为后者的审计和恢复能力更强。
4.4 监控与告警
最后一项是监控。我强烈建议给Agent相关的关键指标接上Prometheus，然后配上Grafana看板。
几个需要重点盯的指标：
agent_task_total：任务总数，按成功/失败/超时分开打标agent_step_duration_seconds：每一步执行时长的直方图，定位慢操作agent_tool_calls_total：工具调用总数，标注哪些工具被调用、成功率多少agent_model_requests_total：模型请求次数，标注哪个Adapter在被调用agent_session_active：当前活跃会话数，反映系统压力
如果团队规模不大，不想引入一整套路Prometheus+Grafana也没关系，写一个简单的指标上报到日志系统也可以。关键不是用什么工具，而是“有数可看”。我见过太多团队把Agent丢上线之后就不管了，直到用户投诉“Agent变笨了”才发现是上游模型接口悄悄改了输出格式，导致工具的Schema解析成功率骤降。
5. 常见问题与排查技巧实录
5.1 工具调用超时但任务还在继续
这个是我在生产上遇到的最多的问题。现象是：工具的耗时超过了execution_timeout设定的5秒，任务应该被判失败，但日志里显示Agent继续执行了下一步。
排查下来发现，问题出在早期的版本里，超时只是给模型返回了一个错误消息，并没有终止整体的Agent执行循环。模型看了错误消息之后，可能会根据自己的理解强行“继续”任务，编造一个看似合理的下一步。这个行为在逻辑上没错，但业务上可能产生不可控的后果。
现在的处理方式是：工具执行超时后，框架会标记当前工具为不可恢复状态，并且停止Agent的计划循环，直接返回失败结果给调用方。如果你需要在超时后让模型自主决策，可以在配置里设recover_on_timeout: true，但你要想清楚业务上是否真的能接受模型在超时后自行决定下一步。
5.2 上下文太长导致token爆炸
这个问题前面提过一次，但值得再展开。当max_context_length配置不当的时候，长对话会把模型输入窗口塞满，导致请求报错。
我们的示例配置里给的是8000，但不同模型的上下文窗口不一样。比如有的模型支持128K，有的是32K。建议设置成一个比你实际使用的模型上限低一些的值，比如200K窗口的模型可以设成150K，预留一部分给系统提示词和工具定义。
框架在处理超长上下文的时候，会先尝试把最老的消息做摘要，把摘要拼到前面，而不是简单地把旧消息丢弃。这样一个老对话可以拖很久，而不会因为早期信息丢失导致Agent“失忆”。
5.3 多轮对话状态串台
还有一个比较隐蔽的问题是状态串台。用户A和用户B同时在用系统，结果A的对话历史跑到了B的会话里。这个Bug非常致命，也很容易在开发阶段被忽略。
罪魁祸首通常是在手动维护Session的时候用了一个全局的current_session变量。当两个请求并发进来，这个变量就会被互相覆盖。如果用的是同步代码，还可能因为线程切换导致更诡异的现象。
hermes-agent从设计上就在规避这个问题：每个请求都会从请求头或者参数里取user_id和session_id，所有的上下文、状态全部基于这两个ID从存储中取出，不存在全局会话变量。如果你是自己手写Agent然后遇到了这个问题，建议从一开始就不要用全局变量来保存会话，养成从存储层取Session的习惯。
5.4 模型输出不是合法JSON
大模型输出非法JSON也是家常便饭，尤其是用一些开源小模型的时候。输出内容里会混入解释性文字、多余的逗号、反引号围栏。为解决这个问题，框架内部做了几层容错：先尝试直接json.loads，失败后清理Markdown围栏再解析，再不行就提取大括号最外层的内容尝试解析，最后实在不行才把结果返回给模型让它重新生成。
这里有一个经验是：与其在解析层面做各种容错，不如在给模型的System Prompt里把输出格式写得再死板一点。比如明确说“你是工具调用引擎，只输出JSON，不要输出任何解释。”再配合few-shot示例，非法JSON的出现概率会大大降低。解析容错是最后一层保险，不能本末倒置。
在过往的测试中，调节好System Prompt和Tool Schema的描述之后，工具调用的成功率从70%左右提升到95%以上。剩下5%的失败，框架会用重试逻辑来兜底。实测下来，这部分兜底逻辑占总任务的比例很小，但对体验的提升是肉眼可见的。
5.5 常见问题速查表
| 现象 | 可能原因 | 排查思路 | 解决办法 |
|---|---|---|---|
| 工具调用参数全是空 | 模型没有充分理解参数描述 | 查看审计日志里模型返回的原始tool_calls | 优化参数描述，增加示例值 |
| 任务执行到一半停止 | 上游模型请求超时 | 用model_request事件看耗时 | 调大request_timeout或切换模型 |
| Agent出现幻觉工具 | 模型凭空生成工具名 | 查看tool_validation事件的拒绝记录 | 检查工具Description的质量 |
| 长对话越聊越蠢 | 上下文窗口被占用 | 查看会话Token用量 | 配置max_context_length开启摘要压缩 |
| 并发请求状态错乱 | 全局Session变量污染 | 检查会话ID是否唯一 | 确保每个请求独立取Session |
| 模型输出被截断 | 输出Token上限不够 | 查看finish_reason是否length | 调大模型输出Token参数 |
6. 扩展思路：把hermes-agent接入现有系统
6.1 用插件机制新增领域工具
hermes-agent在设计上把工具做了插件化。上面提到了在配置文件的tool_packages加载工具包，每一个工具包就是一个Python模块，框架启动时会扫描并注册模块中所有被@tool装饰过的函数。这样既避免了把所有工具堆在一个庞大的文件里，也方便按业务线拆分配置。
比如你的系统有订单域、用户域、物流域，就可以建三个包：order_tools、user_tools、logistics_tools。然后给不同的Agent分配不同的工具包列表，比如客服Agent加载用户和订单工具，物流查询Agent只加载物流工具，隔离得干干净净。
这种做法很好地解决了工具数量膨胀后的管理难题。当工具数量超过20个之后，把它们全丢给一个Agent，模型反而会因为选择太多而出错，就像面前摆了50道菜反而不知道吃哪个。按领域拆分之后，每个Agent的工具数量控制在10个以内，效果会好很多。
6.2 对接企业内部API网关的经验
真实的企业系统很少会直接暴露Python函数给Agent调用，大部分业务是通过内部API网关暴露HTTP接口。所以在实际集成时，我写了一些“适配型工具”。这些工具本身不实现业务逻辑，只是把Agent的意图转成具体的HTTP请求，然后解析响应返回给模型。
这里面最容易踩的坑是“鉴权”。“Agent调用你的内部接口”和“人调用你的内部接口”是两回事。企业内部接口的鉴权通常绑定员工账号体系，而Agent没有员工账号。我们最后的方案是给Agent分配了一个专属服务账号，在网关侧做白名单：只有这个账号发起的请求才允许访问特定接口，并且所有请求都会带上一个x-agent-request-id头，方便追踪到具体是哪次Agent任务发起的调用。
这个方案落地之后，安全审计和问题排查都好做了很多。建议所有接入Agent的工具函数，都务必在日志里记录一次“工具调用”事件，即使这个工具内部只是分发HTTP请求。Agent链路的问题，越透明越好排查。
6.3 从单Agent到多Agent编排
最后一个扩展方向是多Agent协同。当业务复杂到一定程度，一个Agent什么都干反而干不好。我现在的做法是：拆成“主管Agent”和“专业Agent”。主管Agent负责理解用户意图，然后决定把任务分发给哪个专业Agent；专业Agent只处理自己领域的问题。
在hermes-agent的体系里，多Agent协同不需要额外搞一套复杂框架。每个Agent实例共享同一个工具注册中心，但每个Agent可以配置不同的工具集和系统提示词。主管Agent的工具列表里有一个dispatch_to_specialist工具，参数就是目标Agent的名称和任务描述。执行这个工具时，框架会在内部创建一个子任务，交给目标Agent执行，等结果返回后再由主管Agent汇总。
这种模式的好处是每个Agent都能保持聚焦，坏处是增加了任务链路长度和Token消耗。我一般只在业务确实需要多领域知识时才会拆，日常场景一个Agent加工具集就够用了。拆的时候也要注意别拆太细，理想的专业Agent数量是2到4个，再多的话，主管Agent光调度的精度就会下降，反而得不偿失。
写在最后
用hermes-agent这一年多，我最大的体会是：Agent能不能在业务里落地，很多时候不取决于模型本身的聪明程度，而取决于模型外面那层基础设施是否足够结实。工具调用可不可控、状态会不会丢、问题能不能排查、服务会不会挂，这些才是生产环境真正会用到的能力。框架能帮你把这些问题收敛到一个可控范围内，但最终每个团队的用法都不一样。我个人建议从最小闭环开始，先让一个Agent处理一个真实业务，把链路跑稳，再慢慢加工具、加场景。踩过几次坑之后，你对Agent在生产环境里的脾气会摸得越来越清楚，这时候再回头优化体验，就顺手多了。
