2026/9/8 12:16:58
FEATURED · 精选文章 
花了一段时间把 hermes-agent 这个项目跑通并接入到日常工具链之后我最大的体会是它不是一个聊天机器人框架而是一个把“想法变成动作”的任务代理。整条链路是用户输入指令agent 负责理解、拆解、调用工具、汇总结果最后把可执行的结果交回给人。这个过程把大模型和真实的业务系统连接起来。如果你也在做类似的事被各种重复性、跨系统又需要一点判断力的任务缠住或者正准备用 LLM 做自动化hermes-agent 的设计思路和踩坑经验都值得参考。这个项目不像常见的 ChatBot Demo它更接近一个自适应的自动化执行器。简单说你说“查一下最近一周每天的订单量并生成日报发到群里”它不只是给出建议而是会真的去数据库查询、算环比、格式化文本、调用消息接口发送。它不是无所不能的但只要你把边界划定清楚它能省下大量机械劳动。下面我直接从设计、理念、实操到排错完整拆一遍。1. hermes-agent是什么从名字到定位1.1 名字的由来和它真正解决的需求Hermes 是希腊神话里的信使神负责传递消息和执行指令。用在 agent 上非常贴切它不负责“生产”答案它负责把用户的意图准确传达到工具层再把工具的执行结果带回来。大模型像是一个很聪明的参谋但参谋自己不会动手只有配上信使和手脚才能真正办成事。hermes-agent 要解决的核心问题就是让大模型“懂事”之后还能“办事”。举一个我团队里的真实场景。之前每周要写一份渠道投放周报需要登录广告后台导出数据再和内部订单数做关联最后用 Excel 整理成表格发给运营负责人。这套流程每次要花 40 分钟而且操作全是重复的。后来我把这个流程做成了 agent 任务先说“跑本周投放周报”agent 会自动调用广告平台 API、查询内部订单库、计算 ROI、生成表格并发送到指定邮箱。中途如果某个数据源超时它还会回来问我如何处理。这个案例很能说明 agent 和普通脚本的差别脚本只能按写死的顺序执行agent 能在每一步根据返回结果动态调整下一步操作。这决定了 hermes-agent 适合谁被重复性任务困扰的分析师、运营、开发者以及对数据安全比较敏感、希望在自己可控环境里跑自动化代理的团队。它不适合完全没接触过 API 和命令行的小白但下文我会尽量把操作写得细普通技术背景的人照做也能跑通。1.2 设计思路把“对话”变成“任务编排”hermes-agent 的设计核心是“任务编排”而不是“多轮聊天”。聊天机器人关心的是回复是否自然、上下文是否连贯而 agent 关心的是任务是否完成。一次完整的 agent 执行大概会经历这几个阶段用户输入 - 意图识别 - 任务拆解 - 工具调用 - 结果反馈 - 继续规划 - 任务收敛 - 输出结果。这个过程并不是线性的因为工具返回的结果可能不符合预期agent 需要根据结果再规划下一步。比如用户让 agent“把下载失败的订单任务重新跑一遍”这个需求看起来简单实际处理时 agent 要先查询哪些任务失败再分析失败原因再决定是重试还是跳过还是报警。每一步都要结合工具反馈做判断。这就是 agent 和 RPA 最大的区别RPA 是录好固定流程后反复执行agent 是动态生成流程而不是提前录制。我当初选择这种设计还有一个原因是它保留了人的控制权。相比早年的 AutoGPT 那种“给个目标就开始无限循环”的风格hermes-agent 在关键节点可以停下来等人确认。这样既能享受自动化的效率又不会让系统失控。这个“自动 人工审批”的混合模式是我认为现阶段 agent 最能落地到实际业务里的原因。2. 核心功能拆解一个 agent 该有的能力2.1 意图理解与任务规划agent 的第一步是理解用户到底要干什么。现在主流做法不是让模型在自由文本里猜而是使用 function calling。你给 LLM 提供一组工具每个工具都有名字、参数、描述。模型会输出它想调用的工具和参数。比如用户说“查一下上海明天天气”模型可能输出调用get_weather参数是city上海和date明天。为了让这个步骤稳定我总结出几个关键点。第一工具描述写清楚模型选错的概率就低。不要说“查询数据”要说“根据时间范围查询销售订单表返回订单量、订单金额、订单状态等字段”。第二参数里尽量给出示例值比如period字段可以写“示例last_week、last_month”。第三对模糊请求要给规则不要放任模型自由发挥。比如用户没说时间范围我通常在系统提示词里要求“默认取最近 7 天并且在输出中注明使用的是默认值”。这样一来结果不会因为模型一时兴起而变化。任务规划发生在意图理解之后。复杂任务会被拆成多个子任务。比如“分析上周各渠道的转化率并输出图表”agent 需要拆成拉取渠道数据、计算转化率、绘制图表、输出图表链接。拆解一般也由 LLM 完成但我会在系统提示词里限制拆解粒度太粗则无法执行太细则 token 消耗高。经验是拆到“每个子任务可以通过一个工具完成”就好不要追求一步到位。2.2 工具调用与插件机制工具是 agent 的手脚。hermes-agent 把工具设计成插件每个插件就是一个函数加一段元数据。这样做的好处是新增能力时不需要改动调度器只写一个函数、注册一下就行。常见的工具类型有数据库只读查询、内部系统 API、文件读写、发送 HTTP 请求、执行命令行、发送消息到企微/钉钉/飞书、读写知识库等。下面是一个最简单的工具函数骨架def execute_sql(sql: str) - list[dict]: # 执行只读 SQL 并返回查询结果 ...注册时还需要给模型一段 schema 描述这部分非常重要。我在给工具写描述时会把参数的类型、默认值、示例、约束都写进去让模型不需要猜。举例说明如果是一个查询订单的工具sql参数描述不能只写“SQL语句”而要写成“只读 SELECT 查询语句例如 SELECT order_date, count(*) FROM orders WHERE order_date 2024-01-01 GROUP BY order_date”。模型看得越明白越不容易编造参数。在工具函数内部我一直强调要做输入校验。因为模型生成参数并不是百分之百可靠的你不校验它可能给你一个带拼接风险的字符串或者一个不存在的字段名。与其让异常击穿主流程不如在工具里直接返回一个友好错误把错误信息当成“工具结果”喂回给模型让模型自己调整参数重试。这种方式非常有效我后面会展开讲。2.3 记忆与上下文管理如果 agent 每次执行任务都像失忆一样那它就只能处理单轮指令无法完成复杂工作。记忆管理在 hermes-agent 里分成两层短期记忆和长期记忆。短期记忆是指当前任务上下文包括用户最初输入、中间的工具调用结果、模型每一步的判断。这些内容共同构成了一个问题解决链。但它的缺点是会越来越长因为每次工具返回都是一大段 JSON。我的做法是每完成一个子任务就把这部分原始内容压成摘要比如“已获得订单数据等待计算环比”然后把原始 JSON 从消息列表里删掉只保留摘要。这样既保住了任务路径又控制住了 token 消耗。长期记忆则用于跨会话。比如用户偏好用表格而不是文字回复或者对某些指标有特定口径要求这些信息可以存到长期记忆里下次任务再自动注入。实现上可以用向量数据库也可以用 SQLite 存关键词关键是“检索后按需注入”不要在每次请求里都把所有历史记忆堆进去。我早期犯过的错就是嫌麻烦把所有历史都塞进 prompt结果上下文爆炸费用直线上升模型回复质量反而下降。后来改成“分层记忆 按需检索”之后整体稳定了很多。3. 实操从零搭一个自己的 hermes-agent3.1 准备一个可运行的极简架构跑通一个 hermes-agent 不一定需要微服务和复杂框架。我自己做原型时用的是纯 Python 加 FastAPI核心就三样东西调度器、工具注册表、记忆存储。调度器负责和 LLM 交互、决定下一步工具注册表保存所有能调用的函数记忆存储负责记录上下文。目录结构参考hermes-agent/ ├── agent/ │ ├── dispatcher.py │ ├── tools.py │ └── memory.py ├── tools/ │ ├── sql_tool.py │ └── api_tool.py ├── config/ │ └── settings.yaml └── main.py依赖尽量少Python 3.11 以上安装openai、fastapi、uvicorn、pyyaml就够。如果你用的是支持 OpenAI 兼容接口的本地模型SDK 也不需要换只要把 base_url 指过去就行。pip install openai fastapi uvicorn pyyaml这里补充一下模型选型。如果只是实验gpt-4o-mini性价比很高如果对数据隐私敏感可以选择本地部署的 Qwen2.5 或 Llama 3.1 系列OpenAI SDK 可以设置base_url指向本地服务。我也测试过一些专用 function calling 模型确实在工具选择上更稳但响应速度会慢一些。3.2 调度器实现调度器是整个 agent 的核心本质上是一个循环。每一次循环都做同样的事把系统提示词、历史消息、工具定义发给 LLM然后看返回结果。如果 LLM 返回的是工具调用就执行工具把结果拼回消息队列然后继续循环。如果 LLM 返回的是最终答案就结束循环把答案返回给用户。下面是一个可以直接跑通核心逻辑的调度器import json from openai import OpenAI class HermesAgent: def __init__(self, api_key: str, base_url: str None, model: str gpt-4o-mini): self.client OpenAI(api_keyapi_key, base_urlbase_url) self.model model self.tools {} self.history [] def register_tool(self, schema: dict, fn: callable): self.tools[schema[function][name]] { schema: schema, fn: fn, } def run(self, user_input: str, max_iterations: int 10): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input}, ] for step in range(max_iterations): resp self.client.chat.completions.create( modelself.model, messagesmessages, tools[t[schema] for t in self.tools.values()], ) message resp.choices[0].message if not message.tool_calls: self.history.append((user_input, message.content)) return message.content messages.append({ role: assistant, content: message.content, tool_calls: message.tool_calls, }) for call in message.tool_calls: func_name call.function.name if func_name not in self.tools: continue fn self.tools[func_name][fn] args json.loads(call.function.arguments) try: result fn(**args) except Exception as exc: result {error: str(exc)} messages.append({ role: tool, tool_call_id: call.id, content: json.dumps(result, ensure_asciiFalse), }) return 达到最大迭代次数任务未能完成代码不复杂但有几个容易被忽略的细节。第一当模型返回多个tool_calls时要注意依次执行并把每个结果都用对应的tool_call_id回填这样模型才知道哪个结果对应哪个调用。第二工具执行可能抛异常要捕获并转成 JSON 字符串不要让异常打断主循环。第三max_iterations必须设置防止模型陷入循环。我一般设为 10复杂任务最多也就 15。系统提示词我单独写在常量里原则是强调“不确定就询问”、“禁止超出用户权限的操作”。3.3 接入一个实际工具查询数据并生成报表为了演示我注册一个查询数据库的工具。假设本机有一个 SQLite 文件里面有一张订单表import sqlite3 def query_database(sql: str, limit: int 100) - list[dict]: # 严格校验只允许 SELECT if not sql.lstrip().lower().startswith(select): raise ValueError(只允许SELECT查询) conn sqlite3.connect(orders.db) try: cursor conn.execute(f{sql} LIMIT ?, (limit,)) columns [d[0] for d in cursor.description] rows [dict(zip(columns, row)) for row in cursor.fetchall()] return rows finally: conn.close()这里我特意加了一个LIMIT ?的兜底避免模型真的执行一条返回百万行的查询。注册工具时要给模型提供清晰的 schemaagent HermesAgent(api_key你的KEY) agent.register_tool( { type: function, function: { name: query_database, description: 在订单数据库上执行只读SELECT查询返回查询结果列表, parameters: { type: object, properties: { sql: { type: string, description: SQL查询语句示例SELECT order_date, count(*) FROM orders GROUP BY order_date, }, limit: { type: integer, description: 最多返回行数默认100最大1000, }, }, required: [sql], }, }, }, query_database, )然后跑一句result agent.run(帮我查一下最近7天每天的订单量按日期倒序) print(result)模型会生成类似SELECT order_date, count(*) FROM orders WHERE order_date date(now, -7 day) GROUP BY order_date ORDER BY order_date DESC的 SQL调用query_database工具拿到结果后再组织自然语言回复。如果你再注册一个send_email工具agent 就能在查询完之后自动把结果发出去。这就是 agent 最吸引人的地方工具可以不断叠加能力也会随之扩展。接入外部 API 也很容易。比如加一个查询工单状态的工具本质上就是调用一个 HTTP 接口。工具数量变多后我建议在 register 里做一次命名规范校验名称统一用动词加名词比如get_order_amount、list_workflows避免模型混淆。4. 常见问题与排查技巧4.1 模型选错工具或编造参数这是 agent 开发初期最常遇到的问题。你明明给了它查询订单的工具它非要去调一个不存在的日程工具或者生成了一个完全不符合字段定义的时间格式。常见原因有三个工具描述写得含糊、参数定义没有示例、工具返回的错误没有正确反馈给模型。排查方法很简单打开日志把每次请求 LLM 的完整消息序列打出来一看便知模型是在哪个环节开始错的。大多数情况下优化工具 schema 的描述就能解决。尤其是参数描述里加上一个完整示例效果立竿见影。比如sql参数不要写“查询语句”要写“SQL查询语句示例SELECT * FROM orders WHERE order_date 2024-01-01。还有一个很管用的技巧是当工具返回错误时把错误信息包装成正常的 tool message 返回给模型并加上“请根据这个错误调整参数后重新调用”模型通常能自我修正。这个方法我救了很多次场。4.2 上下文越来越长成本越来越高agent 长时间运行后history 里会堆积大量原始工具输出。有时一个简单的查询工具丢回几十行 JSON再来几轮上下文就爆了。这个问题轻则费用飙升重则模型因为上下文过长而报错或能力下降。最直接的方案是“结果用完即丢”。我在调度器里加了一个逻辑每轮工具执行完之后如果这个工具结果已经参与了后续的模型判断就把它替换成一句话摘要比如“订单查询返回 30 行平台包括 iOS、Android、Web”。另外还可以在工具层面限制输出长度比如数据库查询默认最多返回 50 行如果结果超过限制就提示模型“结果过多请改写 SQL 聚合后重试”让模型自己收敛。4.3 权限和安全问题agent 能调用工具就相当于把一把刀递给了大模型。我遇到过最惊险的一次是在调试时模型生成了一条不带 WHERE 条件的 DELETE 语句幸好工具校验拦下来了。这件事给我提了一个醒凡是会修改数据的工具必须做严格校验。比如 SQL 工具只允许以SELECT开头命令行工具要放到沙箱或容器里执行外部 API 的 key 要用最小权限能只读就不要给写权限。对删除、发送、修改这类有副作用的操作我建议设计一个人工确认队列。agent 执行前先把意图和参数展示给用户用户点确认后才真正执行。这个设计会让 agent 少一点“全自动”的酷炫感但能避免绝大多数事故。4.4 超时和 API 限流大模型 API 偶尔会超时或返回 429如果不处理agent 会直接中断。我的做法是给每次 LLM 调用加上超时时间默认 30 秒超过后重试两次重试用指数退避。工具调用同样要有超时控制比如外部 HTTP 工具超过 10 秒就返回超时错误给模型模型可以选择换一个工具或者向用户说明。另外还要设置一个全局最大重试次数防止 agent 因为某个参数问题陷入无限重试导致浪费 token。5. 深入优化从能跑到好用5.1 高频流程固化为工作流虽然 agent 可以动态规划任务但对高频固定流程来说每次都让它现想一遍反而是浪费而且不稳定。我的做法是把这些流程固化为工作流配置用 YAML 或 JSON 定义步骤顺序、依赖关系和每个步骤调用的工具。举一个“每周订单周报”的例子name: weekly_order_report steps: - id: fetch_orders tool: query_database params: sql: SELECT order_date, count(*) FROM orders WHERE order_date date(now, -7 day) GROUP BY order_date - id: compute_growth tool: compute_growth_rate params: source: fetch_orders - id: send_report tool: send_message params: channel: report-group depends_on: compute_growth执行时agent 不再做意图理解直接按配置走。哪一步失败就定位到哪个节点重试也不影响其他步骤。这个模式让整体稳定性高了一大截。我甚至建议所有高频场景都慢慢沉淀成工作流库最终形成你自己的自动化资产。5.2 评估与反馈闭环要相信 agent 会改坏所以要有评估机制。每次任务执行完我会记录以下信息用户原始输入、agent 每一步的工具调用、最终输出、用户是否修改了结果、用户是否有负面反馈。这些数据攒下来就是一份真实评测集。以后你改了系统提示词或工具 schema可以先在这些历史 case 上跑一遍对比任务成功率有没有下降。不需要很复杂几个固定测试用例加一个脚本就够。我吃过亏有一段时间为了追求“更强的推理能力”换了更大的模型结果某些工具调用反而不稳定靠评估集才抓出来问题。5.3 多 agent 协作与人工审批节点当任务复杂到一定程度让一个 agent 包揽所有事会显得很笨重。可以考虑引入多 agent 协作一个主 agent 负责任务拆解然后把子任务分给不同的专门 agent比如一个负责数据查询一个负责文本生成一个负责发送通知。这里的关键是定义清楚子 agent 的输入输出协议否则调度会变成灾难。我更建议大家先保留一个“人工审批 agent”角色在所有有外部副作用的动作前插入确认节点。这个设计虽然多一次交互但在生产环境里非常值得。6. 哪些场景适合 hermes-agent哪些不适合6.1 值得投入的场景从我实际使用来看内部信息查询是回报最快的场景。团队里的数据指标、知识库内容、工单状态本来要打开多个系统才能查到现在用一句自然语言就能问出来。其次是重复的办公任务比如把多个表格合并、按模板生成周报、批量给候选人发面试通知。这类任务流程固定出错后果可控。再就是开发辅助agent 能自动跑测试、分析日志、生成代码改动但提交代码之前必须有人的 review。这些场景的共同点是规则相对明确工具接口稳定出错的成本可以接受。6.2 谨慎投入的场景需要毫秒级响应的高并发场景不适合因为大模型推理本身有延迟。强一致性的交易场景也不适合模型生成的 SQL 哪怕只读也可能产生不可预期的结果。还有一个常见误区是把极度模糊的需求交给 agent。比如“优化一下我们的运营”这个需求连人都需要大量业务上下文才能动手agent 更是无能为力。现阶段最合适的方式是把它定位成“高度可信的辅助工具”而不是无人值守系统。凡是可能出现人身安全、资金损失、法律责任的操作都不建议直接交给 agent 全权执行。6.3 我的总体体会做 hermes-agent 这类项目最大的收获不是代码量而是意识到自动化最难的环节不是写程序而是定义边界。明确它能做什么、不能做什么、什么情况下必须停下来问人比让它变得更聪明更重要。我建议每个准备入手的团队先用一个很小的场景跑通比如“查数据库并生成日报”把它做成稳定可用的工具再逐步加复杂能力。最后再分享一个小技巧从一开始就把每次请求的日志、token 消耗、工具调用结果都存下来。等你想优化 agent 的时候这些日志是最宝贵的资料评估和排查都需要它们支撑。
hermes-agent实践：用LLM打造可落地的任务代理与自动化工作流
花了一段时间把 hermes-agent 这个项目跑通并接入到日常工具链之后我最大的体会是它不是一个聊天机器人框架而是一个把“想法变成动作”的任务代理。整条链路是用户输入指令agent 负责理解、拆解、调用工具、汇总结果最后把可执行的结果交回给人。这个过程把大模型和真实的业务系统连接起来。如果你也在做类似的事被各种重复性、跨系统又需要一点判断力的任务缠住或者正准备用 LLM 做自动化hermes-agent 的设计思路和踩坑经验都值得参考。这个项目不像常见的 ChatBot Demo它更接近一个自适应的自动化执行器。简单说你说“查一下最近一周每天的订单量并生成日报发到群里”它不只是给出建议而是会真的去数据库查询、算环比、格式化文本、调用消息接口发送。它不是无所不能的但只要你把边界划定清楚它能省下大量机械劳动。下面我直接从设计、理念、实操到排错完整拆一遍。1. hermes-agent是什么从名字到定位1.1 名字的由来和它真正解决的需求Hermes 是希腊神话里的信使神负责传递消息和执行指令。用在 agent 上非常贴切它不负责“生产”答案它负责把用户的意图准确传达到工具层再把工具的执行结果带回来。大模型像是一个很聪明的参谋但参谋自己不会动手只有配上信使和手脚才能真正办成事。hermes-agent 要解决的核心问题就是让大模型“懂事”之后还能“办事”。举一个我团队里的真实场景。之前每周要写一份渠道投放周报需要登录广告后台导出数据再和内部订单数做关联最后用 Excel 整理成表格发给运营负责人。这套流程每次要花 40 分钟而且操作全是重复的。后来我把这个流程做成了 agent 任务先说“跑本周投放周报”agent 会自动调用广告平台 API、查询内部订单库、计算 ROI、生成表格并发送到指定邮箱。中途如果某个数据源超时它还会回来问我如何处理。这个案例很能说明 agent 和普通脚本的差别脚本只能按写死的顺序执行agent 能在每一步根据返回结果动态调整下一步操作。这决定了 hermes-agent 适合谁被重复性任务困扰的分析师、运营、开发者以及对数据安全比较敏感、希望在自己可控环境里跑自动化代理的团队。它不适合完全没接触过 API 和命令行的小白但下文我会尽量把操作写得细普通技术背景的人照做也能跑通。1.2 设计思路把“对话”变成“任务编排”hermes-agent 的设计核心是“任务编排”而不是“多轮聊天”。聊天机器人关心的是回复是否自然、上下文是否连贯而 agent 关心的是任务是否完成。一次完整的 agent 执行大概会经历这几个阶段用户输入 - 意图识别 - 任务拆解 - 工具调用 - 结果反馈 - 继续规划 - 任务收敛 - 输出结果。这个过程并不是线性的因为工具返回的结果可能不符合预期agent 需要根据结果再规划下一步。比如用户让 agent“把下载失败的订单任务重新跑一遍”这个需求看起来简单实际处理时 agent 要先查询哪些任务失败再分析失败原因再决定是重试还是跳过还是报警。每一步都要结合工具反馈做判断。这就是 agent 和 RPA 最大的区别RPA 是录好固定流程后反复执行agent 是动态生成流程而不是提前录制。我当初选择这种设计还有一个原因是它保留了人的控制权。相比早年的 AutoGPT 那种“给个目标就开始无限循环”的风格hermes-agent 在关键节点可以停下来等人确认。这样既能享受自动化的效率又不会让系统失控。这个“自动 人工审批”的混合模式是我认为现阶段 agent 最能落地到实际业务里的原因。2. 核心功能拆解一个 agent 该有的能力2.1 意图理解与任务规划agent 的第一步是理解用户到底要干什么。现在主流做法不是让模型在自由文本里猜而是使用 function calling。你给 LLM 提供一组工具每个工具都有名字、参数、描述。模型会输出它想调用的工具和参数。比如用户说“查一下上海明天天气”模型可能输出调用get_weather参数是city上海和date明天。为了让这个步骤稳定我总结出几个关键点。第一工具描述写清楚模型选错的概率就低。不要说“查询数据”要说“根据时间范围查询销售订单表返回订单量、订单金额、订单状态等字段”。第二参数里尽量给出示例值比如period字段可以写“示例last_week、last_month”。第三对模糊请求要给规则不要放任模型自由发挥。比如用户没说时间范围我通常在系统提示词里要求“默认取最近 7 天并且在输出中注明使用的是默认值”。这样一来结果不会因为模型一时兴起而变化。任务规划发生在意图理解之后。复杂任务会被拆成多个子任务。比如“分析上周各渠道的转化率并输出图表”agent 需要拆成拉取渠道数据、计算转化率、绘制图表、输出图表链接。拆解一般也由 LLM 完成但我会在系统提示词里限制拆解粒度太粗则无法执行太细则 token 消耗高。经验是拆到“每个子任务可以通过一个工具完成”就好不要追求一步到位。2.2 工具调用与插件机制工具是 agent 的手脚。hermes-agent 把工具设计成插件每个插件就是一个函数加一段元数据。这样做的好处是新增能力时不需要改动调度器只写一个函数、注册一下就行。常见的工具类型有数据库只读查询、内部系统 API、文件读写、发送 HTTP 请求、执行命令行、发送消息到企微/钉钉/飞书、读写知识库等。下面是一个最简单的工具函数骨架def execute_sql(sql: str) - list[dict]: # 执行只读 SQL 并返回查询结果 ...注册时还需要给模型一段 schema 描述这部分非常重要。我在给工具写描述时会把参数的类型、默认值、示例、约束都写进去让模型不需要猜。举例说明如果是一个查询订单的工具sql参数描述不能只写“SQL语句”而要写成“只读 SELECT 查询语句例如 SELECT order_date, count(*) FROM orders WHERE order_date 2024-01-01 GROUP BY order_date”。模型看得越明白越不容易编造参数。在工具函数内部我一直强调要做输入校验。因为模型生成参数并不是百分之百可靠的你不校验它可能给你一个带拼接风险的字符串或者一个不存在的字段名。与其让异常击穿主流程不如在工具里直接返回一个友好错误把错误信息当成“工具结果”喂回给模型让模型自己调整参数重试。这种方式非常有效我后面会展开讲。2.3 记忆与上下文管理如果 agent 每次执行任务都像失忆一样那它就只能处理单轮指令无法完成复杂工作。记忆管理在 hermes-agent 里分成两层短期记忆和长期记忆。短期记忆是指当前任务上下文包括用户最初输入、中间的工具调用结果、模型每一步的判断。这些内容共同构成了一个问题解决链。但它的缺点是会越来越长因为每次工具返回都是一大段 JSON。我的做法是每完成一个子任务就把这部分原始内容压成摘要比如“已获得订单数据等待计算环比”然后把原始 JSON 从消息列表里删掉只保留摘要。这样既保住了任务路径又控制住了 token 消耗。长期记忆则用于跨会话。比如用户偏好用表格而不是文字回复或者对某些指标有特定口径要求这些信息可以存到长期记忆里下次任务再自动注入。实现上可以用向量数据库也可以用 SQLite 存关键词关键是“检索后按需注入”不要在每次请求里都把所有历史记忆堆进去。我早期犯过的错就是嫌麻烦把所有历史都塞进 prompt结果上下文爆炸费用直线上升模型回复质量反而下降。后来改成“分层记忆 按需检索”之后整体稳定了很多。3. 实操从零搭一个自己的 hermes-agent3.1 准备一个可运行的极简架构跑通一个 hermes-agent 不一定需要微服务和复杂框架。我自己做原型时用的是纯 Python 加 FastAPI核心就三样东西调度器、工具注册表、记忆存储。调度器负责和 LLM 交互、决定下一步工具注册表保存所有能调用的函数记忆存储负责记录上下文。目录结构参考hermes-agent/ ├── agent/ │ ├── dispatcher.py │ ├── tools.py │ └── memory.py ├── tools/ │ ├── sql_tool.py │ └── api_tool.py ├── config/ │ └── settings.yaml └── main.py依赖尽量少Python 3.11 以上安装openai、fastapi、uvicorn、pyyaml就够。如果你用的是支持 OpenAI 兼容接口的本地模型SDK 也不需要换只要把 base_url 指过去就行。pip install openai fastapi uvicorn pyyaml这里补充一下模型选型。如果只是实验gpt-4o-mini性价比很高如果对数据隐私敏感可以选择本地部署的 Qwen2.5 或 Llama 3.1 系列OpenAI SDK 可以设置base_url指向本地服务。我也测试过一些专用 function calling 模型确实在工具选择上更稳但响应速度会慢一些。3.2 调度器实现调度器是整个 agent 的核心本质上是一个循环。每一次循环都做同样的事把系统提示词、历史消息、工具定义发给 LLM然后看返回结果。如果 LLM 返回的是工具调用就执行工具把结果拼回消息队列然后继续循环。如果 LLM 返回的是最终答案就结束循环把答案返回给用户。下面是一个可以直接跑通核心逻辑的调度器import json from openai import OpenAI class HermesAgent: def __init__(self, api_key: str, base_url: str None, model: str gpt-4o-mini): self.client OpenAI(api_keyapi_key, base_urlbase_url) self.model model self.tools {} self.history [] def register_tool(self, schema: dict, fn: callable): self.tools[schema[function][name]] { schema: schema, fn: fn, } def run(self, user_input: str, max_iterations: int 10): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input}, ] for step in range(max_iterations): resp self.client.chat.completions.create( modelself.model, messagesmessages, tools[t[schema] for t in self.tools.values()], ) message resp.choices[0].message if not message.tool_calls: self.history.append((user_input, message.content)) return message.content messages.append({ role: assistant, content: message.content, tool_calls: message.tool_calls, }) for call in message.tool_calls: func_name call.function.name if func_name not in self.tools: continue fn self.tools[func_name][fn] args json.loads(call.function.arguments) try: result fn(**args) except Exception as exc: result {error: str(exc)} messages.append({ role: tool, tool_call_id: call.id, content: json.dumps(result, ensure_asciiFalse), }) return 达到最大迭代次数任务未能完成代码不复杂但有几个容易被忽略的细节。第一当模型返回多个tool_calls时要注意依次执行并把每个结果都用对应的tool_call_id回填这样模型才知道哪个结果对应哪个调用。第二工具执行可能抛异常要捕获并转成 JSON 字符串不要让异常打断主循环。第三max_iterations必须设置防止模型陷入循环。我一般设为 10复杂任务最多也就 15。系统提示词我单独写在常量里原则是强调“不确定就询问”、“禁止超出用户权限的操作”。3.3 接入一个实际工具查询数据并生成报表为了演示我注册一个查询数据库的工具。假设本机有一个 SQLite 文件里面有一张订单表import sqlite3 def query_database(sql: str, limit: int 100) - list[dict]: # 严格校验只允许 SELECT if not sql.lstrip().lower().startswith(select): raise ValueError(只允许SELECT查询) conn sqlite3.connect(orders.db) try: cursor conn.execute(f{sql} LIMIT ?, (limit,)) columns [d[0] for d in cursor.description] rows [dict(zip(columns, row)) for row in cursor.fetchall()] return rows finally: conn.close()这里我特意加了一个LIMIT ?的兜底避免模型真的执行一条返回百万行的查询。注册工具时要给模型提供清晰的 schemaagent HermesAgent(api_key你的KEY) agent.register_tool( { type: function, function: { name: query_database, description: 在订单数据库上执行只读SELECT查询返回查询结果列表, parameters: { type: object, properties: { sql: { type: string, description: SQL查询语句示例SELECT order_date, count(*) FROM orders GROUP BY order_date, }, limit: { type: integer, description: 最多返回行数默认100最大1000, }, }, required: [sql], }, }, }, query_database, )然后跑一句result agent.run(帮我查一下最近7天每天的订单量按日期倒序) print(result)模型会生成类似SELECT order_date, count(*) FROM orders WHERE order_date date(now, -7 day) GROUP BY order_date ORDER BY order_date DESC的 SQL调用query_database工具拿到结果后再组织自然语言回复。如果你再注册一个send_email工具agent 就能在查询完之后自动把结果发出去。这就是 agent 最吸引人的地方工具可以不断叠加能力也会随之扩展。接入外部 API 也很容易。比如加一个查询工单状态的工具本质上就是调用一个 HTTP 接口。工具数量变多后我建议在 register 里做一次命名规范校验名称统一用动词加名词比如get_order_amount、list_workflows避免模型混淆。4. 常见问题与排查技巧4.1 模型选错工具或编造参数这是 agent 开发初期最常遇到的问题。你明明给了它查询订单的工具它非要去调一个不存在的日程工具或者生成了一个完全不符合字段定义的时间格式。常见原因有三个工具描述写得含糊、参数定义没有示例、工具返回的错误没有正确反馈给模型。排查方法很简单打开日志把每次请求 LLM 的完整消息序列打出来一看便知模型是在哪个环节开始错的。大多数情况下优化工具 schema 的描述就能解决。尤其是参数描述里加上一个完整示例效果立竿见影。比如sql参数不要写“查询语句”要写“SQL查询语句示例SELECT * FROM orders WHERE order_date 2024-01-01。还有一个很管用的技巧是当工具返回错误时把错误信息包装成正常的 tool message 返回给模型并加上“请根据这个错误调整参数后重新调用”模型通常能自我修正。这个方法我救了很多次场。4.2 上下文越来越长成本越来越高agent 长时间运行后history 里会堆积大量原始工具输出。有时一个简单的查询工具丢回几十行 JSON再来几轮上下文就爆了。这个问题轻则费用飙升重则模型因为上下文过长而报错或能力下降。最直接的方案是“结果用完即丢”。我在调度器里加了一个逻辑每轮工具执行完之后如果这个工具结果已经参与了后续的模型判断就把它替换成一句话摘要比如“订单查询返回 30 行平台包括 iOS、Android、Web”。另外还可以在工具层面限制输出长度比如数据库查询默认最多返回 50 行如果结果超过限制就提示模型“结果过多请改写 SQL 聚合后重试”让模型自己收敛。4.3 权限和安全问题agent 能调用工具就相当于把一把刀递给了大模型。我遇到过最惊险的一次是在调试时模型生成了一条不带 WHERE 条件的 DELETE 语句幸好工具校验拦下来了。这件事给我提了一个醒凡是会修改数据的工具必须做严格校验。比如 SQL 工具只允许以SELECT开头命令行工具要放到沙箱或容器里执行外部 API 的 key 要用最小权限能只读就不要给写权限。对删除、发送、修改这类有副作用的操作我建议设计一个人工确认队列。agent 执行前先把意图和参数展示给用户用户点确认后才真正执行。这个设计会让 agent 少一点“全自动”的酷炫感但能避免绝大多数事故。4.4 超时和 API 限流大模型 API 偶尔会超时或返回 429如果不处理agent 会直接中断。我的做法是给每次 LLM 调用加上超时时间默认 30 秒超过后重试两次重试用指数退避。工具调用同样要有超时控制比如外部 HTTP 工具超过 10 秒就返回超时错误给模型模型可以选择换一个工具或者向用户说明。另外还要设置一个全局最大重试次数防止 agent 因为某个参数问题陷入无限重试导致浪费 token。5. 深入优化从能跑到好用5.1 高频流程固化为工作流虽然 agent 可以动态规划任务但对高频固定流程来说每次都让它现想一遍反而是浪费而且不稳定。我的做法是把这些流程固化为工作流配置用 YAML 或 JSON 定义步骤顺序、依赖关系和每个步骤调用的工具。举一个“每周订单周报”的例子name: weekly_order_report steps: - id: fetch_orders tool: query_database params: sql: SELECT order_date, count(*) FROM orders WHERE order_date date(now, -7 day) GROUP BY order_date - id: compute_growth tool: compute_growth_rate params: source: fetch_orders - id: send_report tool: send_message params: channel: report-group depends_on: compute_growth执行时agent 不再做意图理解直接按配置走。哪一步失败就定位到哪个节点重试也不影响其他步骤。这个模式让整体稳定性高了一大截。我甚至建议所有高频场景都慢慢沉淀成工作流库最终形成你自己的自动化资产。5.2 评估与反馈闭环要相信 agent 会改坏所以要有评估机制。每次任务执行完我会记录以下信息用户原始输入、agent 每一步的工具调用、最终输出、用户是否修改了结果、用户是否有负面反馈。这些数据攒下来就是一份真实评测集。以后你改了系统提示词或工具 schema可以先在这些历史 case 上跑一遍对比任务成功率有没有下降。不需要很复杂几个固定测试用例加一个脚本就够。我吃过亏有一段时间为了追求“更强的推理能力”换了更大的模型结果某些工具调用反而不稳定靠评估集才抓出来问题。5.3 多 agent 协作与人工审批节点当任务复杂到一定程度让一个 agent 包揽所有事会显得很笨重。可以考虑引入多 agent 协作一个主 agent 负责任务拆解然后把子任务分给不同的专门 agent比如一个负责数据查询一个负责文本生成一个负责发送通知。这里的关键是定义清楚子 agent 的输入输出协议否则调度会变成灾难。我更建议大家先保留一个“人工审批 agent”角色在所有有外部副作用的动作前插入确认节点。这个设计虽然多一次交互但在生产环境里非常值得。6. 哪些场景适合 hermes-agent哪些不适合6.1 值得投入的场景从我实际使用来看内部信息查询是回报最快的场景。团队里的数据指标、知识库内容、工单状态本来要打开多个系统才能查到现在用一句自然语言就能问出来。其次是重复的办公任务比如把多个表格合并、按模板生成周报、批量给候选人发面试通知。这类任务流程固定出错后果可控。再就是开发辅助agent 能自动跑测试、分析日志、生成代码改动但提交代码之前必须有人的 review。这些场景的共同点是规则相对明确工具接口稳定出错的成本可以接受。6.2 谨慎投入的场景需要毫秒级响应的高并发场景不适合因为大模型推理本身有延迟。强一致性的交易场景也不适合模型生成的 SQL 哪怕只读也可能产生不可预期的结果。还有一个常见误区是把极度模糊的需求交给 agent。比如“优化一下我们的运营”这个需求连人都需要大量业务上下文才能动手agent 更是无能为力。现阶段最合适的方式是把它定位成“高度可信的辅助工具”而不是无人值守系统。凡是可能出现人身安全、资金损失、法律责任的操作都不建议直接交给 agent 全权执行。6.3 我的总体体会做 hermes-agent 这类项目最大的收获不是代码量而是意识到自动化最难的环节不是写程序而是定义边界。明确它能做什么、不能做什么、什么情况下必须停下来问人比让它变得更聪明更重要。我建议每个准备入手的团队先用一个很小的场景跑通比如“查数据库并生成日报”把它做成稳定可用的工具再逐步加复杂能力。最后再分享一个小技巧从一开始就把每次请求的日志、token 消耗、工具调用结果都存下来。等你想优化 agent 的时候这些日志是最宝贵的资料评估和排查都需要它们支撑。 
