最近在折腾 AI Agent 项目时发现越来越多人在讨论 Hermes AI Agent Bot 的几种运行模式。相比传统一问一答的聊天机器人这类 Agent Bot 会自己判断什么时候该调工具、什么时候该查资料、什么时候该把任务拆给另一个子 Agent整个交互过程完全不一样。这篇文章不打算堆砌概念而是围绕 Hermes AI Agent Bot 的几种核心运行模式展开从背景概念、环境准备到最小实战项目一步步拆解最后给出高频问题排查和工程落地建议。无论你是刚接触 AI Agent 的新手还是已经写过几个 Bot、想深入了解 Agent 模式的开发者都能在这篇文章里找到可以直接上手的内容。1. 背景为什么 AI Agent Bot 模式值得关注1.1 从“问答机器人”到“Agent”过去我们大多数开发的 Bot 属于“问答机器人”用户发一句话程序把这句话拼进 Prompt调用大模型拿到回复再原样返回。这种模式实现简单但问题很明显——模型不知道实时天气、库存、订单状态模型不能执行“查询数据库”“创建工单”“发送邮件”这类操作多轮对话稍微复杂一点上下文就乱掉遇到需要拆解的任务模型只能给建议不能真正执行。AI Agent 的出现就是为了解决这些问题。Agent 在“生成文本”之外增加了一个很重要的能力工具调用Tool Calling / Function Calling。大模型不再只负责“说话”而是负责“思考下一步做什么”然后由程序执行具体的工具再把工具的返回结果交还给模型继续推理。于是 Bot 从一个“话痨”变成了一个“会干活的小助手”这就是 Hermes AI Agent Bot 这类方案的核心价值。1.2 Agent Bot 的核心能力图谱一个完整的 AI Agent Bot通常由下面几层组成层级作用典型实现交互层接收用户消息返回最终回复终端、Web 页面、IM 机器人、WebhookAgent 引擎负责决策循环理解任务、选择工具、判断完成Agent 主循环、ReAct 模式、Plan-and-Execute工具层提供模型可调用的外部能力天气查询、数据库操作、HTTP API、计算器记忆层保存多轮对话与长期信息上下文窗口、向量数据库、Redis 缓存模型层提供推理与生成能力通过 API 接入各类大模型在 Hermes AI Agent Bot 的架构里这几层职责划分得很清楚模型层只负责“思考”工具层由开发者自己控制Agent 引擎把两者串起来。这也意味着模型能力决定了 Agent 的上限工具设计决定了 Agent 的下限。1.3 Hermes AI Agent Bot 是什么从社区资料来看Hermes 不是单指某一个模型而是指一类“模型 Agent 引擎 消息接入”组合起来的智能体方案。它支持以 Bot 的形式部署常见用途包括在 IM 群里充当运维助手查询日志、发布状态在业务系统里充当客服查订单、退换货流程在个人电脑上充当效率工具处理文档、整理信息通过 WebUI 提供可视化的对话与调试界面。需要注意的是不同渠道来源的“Hermes”版本差异较大有的侧重模型推理有的侧重 Bot 框架有的附带可视化界面。本文不绑定任何具体闭源平台而是以“Agent Bot 模式”为主线讲清楚一套通用的搭建思路。按这套思路你可以迁移到任意支持工具调用的大模型服务和任意消息平台上。2. 环境准备与版本说明2.1 开发环境本文实战示例使用 Python版本建议 3.9 及以上。用到的核心依赖如下openai1.30.0 python-dotenv1.0.0 requests2.31.0需要说明的是版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。如果你使用的模型服务兼容 OpenAI 的接口格式那么下面的代码可以直接复用如果不兼容只需要替换客户端封装部分。其他环境要求一台能访问模型服务的开发机一个可用的模型 API Key如果需要接入消息平台准备对应的 Bot Token 或 Webhook 地址。2.2 模型服务与接口本文示例采用“OpenAI 兼容接口”的调用方式。这样做的原因在于目前主流大模型服务大多提供了兼容接口你在代码里只需要修改base_url和model两个参数就能切换到不同的后端模型。from openai import OpenAI client OpenAI( api_keyyour-api-key, base_urlhttps://your-model-endpoint/v1 )这里要注意工具调用能力是 Agent 模式的基础选择模型时优先确认它是否支持 Function Calling。如果不支持后面我们讲的“工具调用模式”就跑不起来。2.3 消息平台接入思路Agent Bot 最终要跟用户交互。常见接入方式有三种接入方式适用场景实现要点命令行 / 控制台本地调试、开发测试最简单适合验证 Agent 主循环Webhook 回调服务端部署、IM 机器人暴露 HTTP 接口接收消息并异步回复长轮询个人项目、小规模使用定时拉取消息适合免公网部署本文实战先用“控制台”跑通 Agent再给出一个 Webhook 适配的思路。这样分两步走能避免一上来被消息平台的鉴权和回调逻辑干扰先聚焦 Agent 本身。3. Hermes AI Agent Bot 的几种核心模式“模式”这个词在不同 Agent 框架里有不同含义。这里我把它拆成四类对话模式、工具调用模式、多 Agent 协同模式、技能文件模式。理解这四类模式基本就理解了 Agent Bot 的骨架。3.1 对话模式Chat Mode这是最基础的模式。用户发消息Agent 直接返回文本。在这个模式下Agent 引擎只做一件事把用户的输入和系统提示词一起发给模型然后把模型的输出返回给用户。response client.chat.completions.create( modelmodel, messages[ {role: system, content: 你是一个乐于助人的助手。}, {role: user, content: 今天天气怎么样} ] ) print(response.choices[0].message.content)对话模式的问题在于模型对“今天天气”没有感知能力。所以真实项目的 Agent Bot 不会停留在这种模式而是需要工具。3.2 工具调用模式Tool Call Mode工具调用模式是 Agent Bot 的核心。它的大致流程如下开发者预先定义一组工具每个工具包含“名称、描述、参数结构”模型收到用户请求后判断是否需要调用工具如果需要模型返回一个结构化调用指令包含工具名和参数程序执行对应函数把结果作为一条tool消息返回给模型模型根据工具结果生成最终回复。如果结果不满足要求模型可以继续调用其他工具直到拿到足够信息。这个“思考 → 调用 → 观察 → 再思考”的循环是实现 Agent 的关键。后面第 4 节会给出完整的工具调用实现代码。3.3 多 Agent 协同模式Multi-Agent Mode单个 Agent 做不了太复杂的任务时可以拆成多个角色 Agent一个“主管 Agent”负责理解用户意图、拆分任务多个“专家 Agent”分别负责查数据、算结果、写文档主管 Agent 汇总各专家的结果生成最终回复。多 Agent 协同的优势是职责清晰每个 Agent 的系统提示词可以设计得更专注。代价是调用次数变多、Token 消耗变大、调试难度上升。对于个人项目或中小型业务我建议先从“单 Agent 多个工具”开始等单一 Agent 确实处理不过来再考虑引入多 Agent 协同。不要为了“架构好看”而提前复杂化。3.4 技能文件模式Skill Mode当 Agent 需要按照固定的步骤处理一类任务时可以把流程写进一个 Markdown 技能文件让模型在特定场景下加载它。技能文件通常包含技能名称与触发条件执行步骤需要的工具列表示例与注意事项。下面是一个技能文件的最小示例# 技能查天气并生成出行建议 触发条件用户提到天气、出行、带伞等关键词。 执行步骤 1. 调用 get_weather 工具获取用户指定城市的天气。 2. 如果天气为雨推荐携带雨具。 3. 输出包含城市、温度、天气状况和建议的完整回复。 注意事项 - 城市参数必须由用户提供不要臆测。 - 工具返回异常时回复用户“暂时无法获取天气信息”。技能文件模式的核心思想是**“把经验固化到提示词里”**。相比每次手写长提示词技能文件更易维护、可版本化也能显著节省 Token——因为只有触发特定任务时才加载对应文件。4. 完整实战搭建一个最小可运行的 Agent Bot下面我们动手实现一个带工具调用能力的 Agent Bot。它的功能是支持查询天气模拟数据支持执行简单的数学计算支持多轮对话跑通“模型 → 工具 → 模型”的完整循环。4.1 创建项目结构先创建项目目录和文件hermes-agent-demo/ ├── agent.py # Agent 主循环 ├── tools.py # 工具定义与实现 ├── config.py # 配置读取 ├── bot.py # 消息平台适配Webhook 示例 ├── skills.md # 技能文件示例 ├── requirements.txt # 依赖清单 └── .env # 存放 API Key不提交到仓库4.2 封装模型客户端config.py负责读取环境变量# 文件路径hermes-agent-demo/config.py import os from dotenv import load_dotenv load_dotenv() API_KEY os.getenv(HERMES_API_KEY, ) BASE_URL os.getenv(HERMES_BASE_URL, https://api.example.com/v1) MODEL os.getenv(HERMES_MODEL, hermes-chat).env文件内容如下请替换成你自己的配置HERMES_API_KEYyour-api-key HERMES_BASE_URLhttps://api.example.com/v1 HERMES_MODELhermes-chat如果你的模型服务不支持工具调用可以把MODEL换成支持 Function Calling 的模型名称。4.3 实现工具层tools.py中实现两个简单的工具函数并提供工具定义列表。# 文件路径hermes-agent-demo/tools.py import json import math TOOL_DEFINITIONS [ { type: function, function: { name: get_weather, description: 查询指定城市的天气情况返回温度和天气状况。, parameters: { type: object, properties: { city: { type: string, description: 城市名称例如北京、上海、广州 } }, required: [city] } } }, { type: function, function: { name: calculate, description: 计算数学表达式的值例如1 2 * 3。, parameters: { type: object, properties: { expression: { type: string, description: 数学表达式只支持数字和四则运算 } }, required: [expression] } } } ] def get_weather(city: str): # 实际项目中这里应调用真实天气 API本文返回模拟数据演示流程 mock_data { 北京: {temperature: 26, condition: 晴}, 上海: {temperature: 29, condition: 多云}, 广州: {temperature: 33, condition: 小雨}, } data mock_data.get(city, {temperature: 25, condition: 未知}) return {city: city, **data} def calculate(expression: str): # 仅允许数字和四则运算避免任意代码执行 allowed_chars set(0123456789-*/(). ) if not set(expression).issubset(allowed_chars): return {error: 表达式包含非法字符} try: # 这里使用 eval 仅用于教学演示生产环境请使用专业表达式解析库 result eval(expression, {__builtins__: {}}, {math: math}) return {expression: expression, result: result} except Exception as exc: return {error: f计算失败{str(exc)}} TOOL_HANDLERS { get_weather: get_weather, calculate: calculate, }这里有两个点需要强调工具函数的入参由模型生成不能信任模型生成的参数一定合法函数内部必须做参数校验。计算器示例使用了eval这是为了简化演示。真实生产环境请使用asteval、py-expression-eval等安全解析库避免任意代码执行风险。4.4 实现 Agent 主循环agent.py是整个项目的核心。它的职责是维护消息历史调用模型处理工具调用返回直到模型给出最终文本回复。# 文件路径hermes-agent-demo/agent.py import json from openai import OpenAI import config import tools class HermesAgent: def __init__(self): self.client OpenAI( api_keyconfig.API_KEY, base_urlconfig.BASE_URL, ) self.model config.MODEL self.messages [ {role: system, content: 你是一个能调用工具的 AI 助手。 当用户需要查询天气或计算表达式时请调用对应工具。} ] self.max_iterations 5 def _execute_tool(self, name: str, arguments: str): handler tools.TOOL_HANDLERS.get(name) if handler is None: return {error: f未找到工具{name}} try: args json.loads(arguments) if arguments else {} return handler(**args) except TypeError as exc: return {error: f工具参数错误{str(exc)}} except json.JSONDecodeError: return {error: 工具参数不是合法 JSON} def run(self, user_input: str): self.messages.append({role: user, content: user_input}) for _ in range(self.max_iterations): response self.client.chat.completions.create( modelself.model, messagesself.messages, toolstools.TOOL_DEFINITIONS, ) message response.choices[0].message if message.tool_calls: self.messages.append(message) for tool_call in message.tool_calls: result self._execute_tool( tool_call.function.name, tool_call.function.arguments, ) self.messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse), }) else: self.messages.append(message) return message.content return 处理超时请简化问题后重试。 if __name__ __main__: agent HermesAgent() print(Agent 已启动输入 exit 退出。) while True: user_input input( ).strip() if user_input.lower() in (exit, quit): break reply agent.run(user_input) print(Agent:, reply)这段代码的关键逻辑在run方法里把用户输入追加到消息列表调用模型并传入工具定义如果模型返回了tool_calls就依次执行工具把工具结果追加到消息列表然后继续下一次循环如果没有工具调用说明模型已经生成最终回复返回内容。max_iterations是一个安全闸门防止 Agent 陷入“反复调用工具”的死循环。4.5 接入消息平台Webhook 适配控制台调试通过后可以把 Agent 暴露成 HTTP 服务。bot.py使用 Python 标准库实现一个简单的 Webhook 服务方便你接入 IM 机器人或自建前端。# 文件路径hermes-agent-demo/bot.py import json from http.server import BaseHTTPRequestHandler, HTTPServer from agent import HermesAgent agent HermesAgent() class BotHandler(BaseHTTPRequestHandler): def do_POST(self): content_length int(self.headers.get(Content-Length, 0)) body json.loads(self.rfile.read(content_length)) user_input body.get(message, ) reply agent.run(user_input) response json.dumps({reply: reply}, ensure_asciiFalse).encode(utf-8) self.send_response(200) self.send_header(Content-Type, application/json; charsetutf-8) self.send_header(Content-Length, str(len(response))) self.end_headers() self.wfile.write(response) def log_message(self, format, *args): # 简化日志输出 print(f[Bot] {self.address_string()} - {format % args}) if __name__ __main__: server HTTPServer((0.0.0.0, 8000), BotHandler) print(Bot Webhook 已启动监听端口 8000) server.serve_forever()启动后可以用下面的命令模拟消息推送curl -X POST http://127.0.0.1:8000 \ -H Content-Type: application/json \ -d {message: 北京天气怎么样}预期会得到类似输出{reply: 北京今天的天气是晴天气温 26 摄氏度适合出行。}4.6 运行与验证按以下顺序执行cd hermes-agent-demo pip install -r requirements.txt python agent.py然后在控制台输入 北京天气怎么样 Agent: 北京今天的天气是晴天气温 26 摄氏度。 计算 (12 34) * 2 Agent: 计算结果是 92。 exit如果模型服务不支持工具调用你会看到模型直接返回文本而不是执行工具这时需要检查模型是否开启了 Function Calling 能力或者更换支持该能力的模型。5. 常见问题与排查思路实战中遇到最多的几个问题我整理成了一张表问题现象常见原因解决思路模型不调用工具直接给文本回复模型不支持 Function Calling或工具描述不够清晰确认模型能力优化工具 description明确触发条件工具返回后Agent 不再继续推理消息顺序错误tool消息没有跟对应的tool_call_id对应检查role: tool消息中的tool_call_id是否匹配提示“工具参数错误”模型生成的参数与工具定义不一致工具函数增加默认值和容错在向模型描述参数时写清楚类型上下文越来越长Token 消耗快消息历史无限累积设置历史窗口超出后做截断或摘要压缩Agent 陷入工具调用死循环缺少最大迭代次数限制设置max_iterations到达上限后强制返回输入中文乱码编码未指定 UTF-8HTTP 响应头显式声明charsetutf-8除了表格里的方案还有两个值得关注的排查技巧打开模型的原始响应日志。很多 SDK 支持打印response.model_dump()可以直接看到模型到底返回了什么是工具调用参数错了还是模型压根没打算调工具。先用固定参数测试工具函数。不经过模型直接在 Python 里调用tools.get_weather(北京)确认工具本身没问题再排查 Agent 循环。6. 最佳实践与工程建议6.1 安全边界Agent Bot 拥有了“调用工具”的能力也就意味着模型生成的参数可能被你的程序执行。这引入了新的安全风险建议至少做到四点参数校验前置。工具函数入口处必须校验参数类型和取值范围绝不直接信任模型输出。不执行不可信代码。上面示例为了演示用了eval生产环境应替换为安全表达式解析库。权限最小化。Agent 使用的数据库账号、API Token 只授予它完成任务所需的最小权限。涉及删除、修改数据的操作必须二次确认。敏感信息隔离。不要在系统 Prompt 中暴露数据库密码、内部地址等敏感信息模型输出可能被用户诱导泄露。6.2 成本与性能Agent 模式的 Token 消耗远高于普通问答。一次任务可能涉及多次模型调用每次调用都带着累计的历史消息。控制成本的方法设置上下文窗口超过 N 轮就丢弃早期消息或做摘要工具返回结果尽量精简避免把大段 JSON 塞进上下文对重复性任务优先使用固定模板减少自由推理在非高峰时段使用更经济的模型处理简单问题。6.3 可观测性Agent Bot 的调试比普通 Bot 难得多因为中间过程是不可见的。工程化部署时建议增加[Agent] 用户输入北京天气怎么样 [Agent] 模型选择工具get_weather参数{city: 北京} [Agent] 工具返回{city: 北京, temperature: 26, condition: 晴} [Agent] 模型最终回复北京今天晴天26 摄氏度。把这四行日志打印出来你就能完整还原一次 Agent 的决策链路定位问题会快很多。有条件的话可以把这些日志汇入 ELK 或 Loki 做集中检索。6.4 技能文件与配置管理技能文件、系统提示词、工具定义这些内容建议纳入 Git 管理并区分环境config/ ├── dev/ │ └── skills.md ├── staging/ │ └── skills.md └── prod/ └── skills.md每次修改技能文件都要走评审流程因为技能内容直接影响模型行为改一句提示词可能导致线上表现大幅波动。发布前先在 staging 环境跑一遍回归用例再同步到生产。7. 总结与下一步学习路线这篇文章从 AI Agent 的基本概念出发拆解了 Hermes AI Agent Bot 常见的几种运行模式重点讲了工具调用模式和多 Agent 协同模式的区别并给出了一套最小可运行的 Agent Bot 示例代码。你可以直接把它跑起来也可以在此基础上替换成自己的工具和提示词。掌握了这套基础之后下一步建议按这个顺序深入学习读懂 Function Calling 协议。不同模型服务对工具调用的报文格式略有差异深入研究官方文档理解tool_call_id和消息顺序的作用。加入记忆能力。把多轮对话历史存入 Redis 或向量数据库让 Agent 支持跨会话的“记忆”。实践多 Agent 协同。先设计两个子 Agent 的分工比如“检索 Agent”和“写作 Agent”再让主管 Agent 调度它们。关注可观测性方案。使用 LangSmith、Langfuse 或自建日志系统完整追踪每次 Agent 调用的细节。探索技能文件工程化。研究如何把技能文件拆分成可复用、可测试的模块减少提示词维护成本。AI Agent 方向目前发展非常快网上的资料也很杂但核心的“模型思考 工具执行 结果反馈”这个循环是相对稳定的。把今天这套最小实现理解透后续不管是换模型、换消息平台还是接更复杂的工具都会轻松很多。如果这篇文章对你有帮助可以收藏备用如果你在搭建过程中遇到其他问题欢迎在评论区留言交流。