上个月我们团队在给 Hermes Agent 做内部演示时现场翻车了。场景很简单让它在文档站上查一个接口的变更说明然后基于查到的内容改写一段调用代码。它第一步就卡住了——既没有接搜索引擎也没有读网页的能力连上一轮我明确告诉过它的输出格式要求都忘得干干净净。坐在旁边的同事说了一句这不就是个套壳聊天框吗后来我把这四样东西——会话、工具、MCP、记忆——一件件补齐演示才从看起来聪明变成真的能干活。这篇文章想把这些设计思路和踩坑记录完整拆开。如果你正在做 AI Agent、机器人对话系统、自动化工作流中间件或者只是好奇一个 Agent 内部到底怎么组织这篇应该对你有用。我会从能力边界讲起再逐个看会话、工具、MCP、记忆的实现细节最后用一次真实的跨天任务把这些能力串起来并盘点落地阶段最常见的五个坑。1. 为什么我把这四件事叫能力而不是功能和团队争论过很多次会话、工具、MCP、记忆到底算功能还是能力功能思维是用户点一下系统做一件事所以自然会把工具拆成一个一个菜单、把记忆做成一个查询按钮。能力思维则是先把对话状态怎么维护外部能力怎么接入信息怎么长期保留这些问题在底座层面解决再让上层的具体业务各自复用。Hermes Agent 选择了后者这个选择直接影响了后续所有代码结构。1.1 功能思维 vs 能力思维功能思维下的典型实现是这样的遇到查天气就写一个 getWeather 接口遇到发邮件就写一个 sendEmail 接口用户在对话框里说发邮件给某客户前端做关键词匹配命中邮件就把参数抽出来调用接口。这套逻辑对固定话术好用但一旦用户的表达方式变一点、任务组合起来代码就变成一坨 if-else 叠加正则维护成本指数级上升。能力思维的核心是把模型的意图理解和外部系统的执行解耦。模型负责把用户一句口语转换成结构化的调用意图比如帮我把昨天的销售数据整理成表格发给财务模型先判断需要调用读取销售数据工具再判断需要调用发送邮件工具然后按顺序执行。这里的关键是工具注册表、调用协议、结果回传机制是一等公民而不是为某个业务临时写的分支。1.2 四个能力的分工边界如果用一句话概括这四者的关系会话是 Agent 的工作台工具是 Agent 的手MCP 是让手能插进各种标准插座的那套协议记忆是 Agent 的硬盘加检索系统。能力解决什么问题核心组件不做什么会话让多轮对话上下文连续、状态可恢复上下文窗口、系统提示词、会话快照不负责跨会话长期知识保留工具让模型能操作真实系统、获取实时数据函数注册表、参数校验、调用调度不负责协议标准化MCP统一外部工具和数据源的接入方式MCP Server/Client、资源、工具协议不负责业务逻辑实现记忆让 Agent 跨会话记住用户偏好和事实向量库、记忆摘要、冲突管理不替代会话上下文的工作台角色边界清晰之后开发速度反而更快。业务团队不需要关心模型怎么调用工具只需要按规范暴露一个 MCP Server不需要关心上下文怎么压缩只需要在会话开启时声明这次任务需要保留哪些关键事实。后面我会逐个说明每个能力是怎么落地的。2. 会话能力除了问一句答一句还需要什么对话接口谁都会调但会话和聊天是两码事。聊天是把当前这句话发给模型拿到回复就结束。会话则需要维护一个持续存在的状态容器让模型能意识到我们已经聊到第几步刚才你让我记住的约束条件还没落实这几个工具调用返回的结果还在栈里。2.1 会话上下文里到底装着什么Hermes Agent 的会话对象并不只是消息列表它包含四部分内容。第一部分是系统提示词固定声明 Agent 的角色、行为边界、输出规范这部分几乎不回被裁剪。第二部分是工具清单告诉模型当前会话可以调用哪些函数、每个函数的入参结构是什么。第三部分是消息历史按 user、assistant、tool 三种角色排列。第四部分是会话摘要和中间态比如某轮工具调用生成了临时文件路径、某个子任务处于运行中状态。把工具清单和消息历史分开存放是我踩过的一个小坑。早期我把工具描述直接拼进系统提示词里结果每次新增工具都要重建整个提示词而且容易超 token 上限。后来改成动态注入会话开启时根据配置把工具 Schema 渲染成文本再拼到消息队列最前面这样工具列表的增删不会污染历史消息。2.2 上下文窗口是稀缺资源总得有个预算现在的主流模型上下文窗口从几万到几十万 token 都有看起来很大但真用到 Agent 场景就会发现根本不够。一次工具调用返回一个大文件内容或者一轮长文档分析几千 token 就没了。所以上下文预算必须像家庭开支一样提前分配。我习惯用一套比例总上下文中系统提示词占固定开销工具清单控制在总预算的 15% 左右以满足复杂多工具场景最近 N 轮完整对话保留约 40%历史更早的内容压成摘要约 20%剩余的留给模型输出和波动空间。具体数字不是死的但有一点很关键一旦超出预算必须主动升级为摘要化而不是简单丢弃早期消息。因为早期消息里常常埋着用户的真实目标比如用户第一句说我要对比三种方案最终给我推荐一个如果直接丢掉后面所有判断都会失去锚点。2.3 会话怎么活过重启预览序列化与恢复本地一个 Agent 进程挂掉、用户隔天继续追问这种情况太常见了。会话能力要保证跨进程甚至跨设备恢复因此核心是两件事会话快照和恢复策略。Hermes 会为每个会话生成一个 session_id每当进入稳定状态比如一轮工具调用完成、一次回复输出完毕就把当前的系统提示词、配置版本、消息序列、摘要、中间产物指针整体序列化写入本地存储。恢复时有个细节不要无脑全量重放历史消息。如果昨天聊了四十轮今天恢复会话直接把四十轮全部塞进上下文除了浪费 token 外还会让模型把早期无关信息当成当前重点。正确做法是恢复时先注入压缩摘要再追加最近几轮原始消息最后给模型一句以下是该任务此前完成的进度作为衔接。2.4 多轮工具调用时的会话一致性工具调用不是一步到位的。真实的 Agent 任务里模型通常先调用工具 A 拿数据再根据结果决定调用工具 B中间模型还会穿插自己的推理。如果工具结果没有正确回注到会话流里模型后续推理就会基于错误前提这是会话一致性最大的风险点。我的实现是给每条工具调用分配一个 call_id工具执行结果以 tool 角色的消息回传并且携带状态码和错误信息。模型看到工具返回后必须等本轮 tool 消息结束、assistant 再输出下一轮推理整个顺序才被标记为一致。如果工具返回的是异常比如超时或权限不足会话对象会把异常信息也塞回去让模型感知这个失败然后调整策略而不是假装无事发生继续硬猜。3. 工具能力模型负责想工具负责做语言模型天生有两个短板训练数据截止时间之前的知识它不知道现实世界的操作它无法执行。工具能力就是补齐这两个短板的关键。但能力和调用函数之间隔着一段不小的工程距离这段距离才是真正值得玩味的地方。3.1 工具调用的本质是模型输出结构化指令很多人第一次接触 function calling 时会误以为模型自己在跑函数其实不是。模型只做一件事根据系统提示词里的函数 Schema在回复里输出一段符合格式的 JSON声明它想调用哪个函数、传什么参数。真正执行函数的是运行时也就是 Hermes 的调度层。模型生成的是意图运行时负责执行。所以工具能力的第一个设计核心是函数描述质量。描述越清晰模型选对函数的概率越高。我见过团队写函数描述时很随意比如搜索函数只写search(query, limit)模型面对帮我查一下上周的项目进度根本不知道 translate 该不该用。后来我们统一采用带详细介绍的 JSON Schema不仅写参数类型还写这个函数适合什么场景、不适合什么场景。3.2 工具中枢函数注册表与动态注入Hermes Agent 里有一个独立的 function registry 模块。它维护一张注册表函数名、函数对象、JSON Schema、执行权限、超时配置、是否可以并行执行。开发新工具时只需要用装饰器标注比如 register_tool(search_web, 搜索公开网页内容适合查询实时信息与新闻), 然后实现普通函数即可。注册表会在每次会话建立时动态渲染一份精简的 Schema 清单注入到系统提示词的工具列表中。代码大体长这样register_tool( namesearch_web, description搜索公开网页内容适合查询实时信息、新闻、文档资料。不适合查数据库内部表。, schema{ type: object, properties: { query: {type: string, description: 搜索关键词建议简洁}, max_results: {type: integer, description: 返回结果数量默认5, default: 5} }, required: [query] } ) def search_web(query: str, max_results: int 5) - list: # 实际的搜索逻辑 return results注册表还要承担参数校验、权限校验和超时控制。模型生成参数时偶尔会漏填 required 字段或者填错类型这些都在调度层拦截拦截后把错误信息回传模型让它纠正而不是直接崩溃。3.3 工具选择策略全交给模型还是加规则干预一个实际争论点是当工具数量变多、场景变复杂时完全让模型自由选择工具还是不放心地加规则。我的结论是二者结合但规则要少而准。工具少的时候自由选择没毛病工具多了比如超过三十个模型在没有先验信息的情况下容易选错或者反复犹豫。Hermes 采用的方法是白名单提示 自由选择根据用户当前消息的关键词匹配为候选工具打一个分数把得分最高的三到五个工具优先放到提示词更靠前的位置。模型仍然有权调用列表外工具但默认会优先考虑靠前的选项。这相当于给模型一个粗略的方向感又不剥夺它的决策力。这样既避免了硬性路由规则的僵硬又提升了工具选择准确率。3.4 工具结果标准化与错误兜底工具执行返回的数据不能直接塞回对话就完事。比如搜索接口返回 200 条结果模型上下文可能根本装不下或者数据库查询返回了一个 Python 字典模型可能看不懂。所以 Hermes 增加了一个结果规范化层对工具返回内容做裁剪、格式转换、必要的摘要最后统一成简洁的文本送进上下文。错误兜底是另一个容易被忽略的环节。无兜底时工具调用失败模型通常会假装成功或者直接报错。更稳妥的做法是在调度层捕获异常生成一段标准的错误说明函数 search_web 执行失败原因请求超时。你可以尝试缩小关键词或稍后重试。然后继续让模型决策下一步。这避免了 Agent 因为一个工具挂掉而整体崩溃。4. MCP把接 N 个 API变成插一个插座如果只有两三个工具自己写注册表完全够了。但真实场景是一会儿接数据库、一会儿接文件系统、一会儿接企业内部系统每家的接口风格都不同A 系统用 RESTB 系统用 WebSocketC 系统还要自己拼签名。如果每接入一个系统就写一套定制对接逻辑Agent 就废了。MCPModel Context Protocol解决的正是这个问题。4.1 MCP 到底解决什么问题MCP 是 2024 年底开源的一套开放协议核心目标是给 AI 应用与外部系统之间建立一个统一接口标准。打个比方如果没有 USB 标准每家厂商都做自己的充电口你得带一堆线MCP 就是充电协议上的统一标准让各种外部工具和数据源能以统一的插座形式被 Agent 识别和调用。协议里分三个角色Host 是 Agent 本体Client 是 Host 内部的连接器Server 是外部工具或数据源的包装进程。Server 通过描述自己的能力和资源让 Client 像发现新设备一样动态发现工具而不是在 Agent 里硬编码。这意味着你的 Agent 可以在运行时加载一个新 MCP Server立刻获得它暴露的所有工具。4.2 MCP 里最有用的三类能力MCP 不仅约定了工具调用还定义了资源Resource和提示词模板Prompt。三者侧重点不同类型作用典型场景Tools可执行的函数Agent 自主决定调用搜索网页、发送邮件、数据库查询Resources可读取的数据和文件上下文加载到对话读取项目文档、API 文档、业务数据文件Prompts预设的任务模板引导模型按固定流程执行编写周报模板、代码审查模板、翻译风格模板实际使用时Tools 用得最多Resources 适合做按需拉取文档的场景Prompts 则用来封装那些经常重复的标准操作流程。4.3 在 Hermes 里接入一个 MCP Server接入过程非常直接。Hermes 的配置文件里声明 mcpServers本地工具用 stdio 传输方式远程服务用流式 HTTP。下面是一个本地时间服务的实例{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /tmp] }, remote-notes: { url: http://127.0.0.1:8931/mcp } } }连接流程是固定的先 initialize 握手客户端和服务端交换协议版本和能力声明然后 tools/list 拉取服务器上可用的工具列表之后所有需要的时候发 tools/call。整个过程对上层业务是透明的。协议层的存在让工具发现变成了动态过程系统重启后即使有新工具上线Agent 也不需要改代码。4.4 十分钟写一个自己的 MCP Server如果官方生态里没有合适的 Server自己写也很快。以 Python 为例用官方 SDK 或社区封装库都可以下面是一段极简示例from mcp.server.fastmcp import FastMCP mcp FastMCP(hermes-weather) mcp.tool() def get_weather(city: str) - dict: 获取指定城市当前天气入参为城市中文名。 # 这里替换为真实天气 API return {city: city, weather: 晴, temperature: 24} mcp.resource(doc://weather_api) def weather_doc() - str: 返回天气 API 使用说明文档。 return 本服务提供天气查询能力。调用 get_weather 并传城市名。 if __name__ __main__: mcp.run()启动这个 Python 文件后它就在本地监听。再把配置里的 command 指向对应的启动命令Hermes 立刻就能调用 get_weather。我可以负责任地说从零到接入完成在有现成 SDK 的情况下不会超过半小时真正耗时的地方反而是你想清楚这个服务到底对外暴露哪些工具。4.5 MCP 和内置工具怎么选不是说有了 MCP就不需要内置工具注册表。我的判断标准是看复用边界和隔离需求。如果某个能力只服务于当前一个 Agent 项目而且调用逻辑极其简单直接用内置注册表更省事如果这个能力未来会被多个 Agent、多个应用共享或者涉及数据权限隔离、需要独立升级就做成 MCP Server。另外安全隔离也是一个重要理由核心业务系统不希望把接口细节直接暴露给模型通过 MCP Server 做一层代理可以在服务端做更严格的鉴权和审计。5. 记忆能力让 Agent 从每轮失忆变成长期学徒会话能力解决的是当前任务内连续记忆能力解决的则是跨任务跨时间的持续。没有记忆的 Agent每次对话都像一个刚入职的实习生昨天教过的偏好今天全忘了。记忆能力是用户粘性的核心也是最容易做得华而不实的部分。5.1 记忆不是数据库是分层缓存一上来就建 MySQL 表存记忆是最大的误区。记忆和普通业务数据至少有两点不同一是记忆有置信度用户随口说的一句话和反复强调的事实可信度完全不同二是记忆会过期三个月前的喜好放到现在可能已经失效。所以 Hermes 把记忆分成三层工作记忆当前会话窗口内、短期记忆同一次任务会话内的进展状态、长期记忆跨会话的事实、偏好、技能经验。工作记忆就是上下文里的消息和工具结果短期记忆对应前面说的会话摘要长期记忆才落到持久化存储。这三层之间的流动方向是对话中产生的关键事实先进入短期记忆当任务结束时经过抽提和置信度过滤才沉淀为长期记忆。5.2 长期记忆的存取流程写入、检索、应用写入阶段最关键不是所有对话内容都值得记。Hermes 采用一个记忆抽提器模型在每轮重要交互后判断当前有没有值得长期保留的信息这里有三个判据是否为用户的显式偏好我喜欢简洁的回答、是否为明确的事实我在北京工作、是否对后续任务有用客户方最看重交付时间)。每一条候选记忆都会附带置信度分数低于阈值的直接丢弃高于阈值才写入记忆存储。检索阶段用的是向量库加关键词兜底。用户开启新会话时Hermes 先做一次记忆检索把用户当前输入向量化与历史记忆做相似度匹配召回 top_k 条再与最近活跃记忆做融合。检索结果不是全部塞进上下文而是只在系统提示词里加一段已知关于用户的信息限制在两三条摘要级别。5.3 记忆管理冲突、遗忘与隐私边界记忆管理里最容易出问题的就是冲突。真实的用户会变上周说我在上海这周说我已经搬到北京了。如果不处理冲突模型会同时看到两条矛盾记忆回答时逻辑混乱。Hermes 的做法是给每条记忆打上主题键和写入时间戳新写入的同主题记忆如果置信度更高或时间更新就覆盖旧记忆同时把旧记忆降级为候选记录保留一段时间以防用户反悔。遗忘机制同样需要主动设计。记忆会按活跃度和时间衰减长期没有被检索到的记忆慢慢降级容量接近上限时最久远且低置信度的记忆先被归档。隐私边界则直接做硬规则身份证号、银行卡号、家庭住址这类信息默认不写入长期记忆涉及敏感信息的对话用户可以选择本会话不记录。5.4 记忆能力怎么量化评估很多团队做完记忆系统后说不清楚到底有没有变聪明。我的土办法是搭一个跨会话测试集模拟真实用户行为创建十组任务每组包含第一次会话里埋下的偏好信息然后隔两小时或隔一天开启第二次会话要求 Agent 正确使用之前的偏好完成任务。统计成功率、是否需要用户重复信息、答案是否符合偏好。在这套评估下Hermes 从最初的成功率不到四成经过优化抽提器和检索策略稳定到八成以上。没有评测记忆系统就是自我感觉良好。6. 四个能力串起来一次跨天任务的真实运行链路讲了半天单个能力总要合起来看才能感受到价值。我用一个真实模拟场景来还原整体协作链路。6.1 任务背景与前置条件某用户周一上午给 Hermes 布置了一个任务帮我调研三款自动化测试工具的对比整理出一份选型建议。我偏好表格、重点标注开源协议的差异。另外我周三上午要用不需要太长控制在两页以内。这句话里藏着很多信息值得记住任务目标调研三款测试工具对比、输出偏好表格、标注开源协议差异、节奏偏好周三上午前交付、篇幅约束两页以内。这些不是所有都会进入长期记忆但偏好表格篇幅短这类是典型长期记忆候选。6.2 第一次会话的完整时序会话开始时Hermes 先加载该用户的长期记忆发现此前用户曾表达过喜欢对比表格技术方案希望给出明确推荐等偏好于是系统提示词里注入已知该用户偏好表格和明确结论。随后进入工具调用阶段Hermes 通过内置工具注册表调用搜索工具同时对三款工具官网与开源仓库分别发起抓取。抓取时某个官网访问超时工具返回错误信息Hermes 调整策略改用另一个文档镜像站成功拿到了许可证字段。这一系列工具调用被记录到会话日志每步结果都规范化为文本回注上下文。第一轮会话结束后任务未完成会话摘要里记录了已完成两家工具调研第三家待确认输出模板已选定。6.3 隔天恢复会话的衔接过程周三用户只发了一句那个测试工具的对比弄好了吗Hermes 通过 session_id 恢复快照先注入摘要让模型知道上次进展再把用户偏好记忆调入上下文。模板中先输出已完成的初稿模型判断还缺第三家工具的许可证对比于是再次发起搜索和抓取调用补充内容后按表格格式完成输出。整个过程中用户没有重复任何偏好也没有再解释自己到底想要什么格式。如果把这个过程拍成一眼能看懂的清单大概是会话恢复 → 记忆注入 → 工具调用 → 结果回注 → 摘要更新 → 最终输出。四个能力各有分工缺一个都会让体验断链没有会话恢复就断片没有记忆就忘偏好没有工具就查不到数据没有 MCP 就要为每个新系统写死一套对接代码。7. 落地阶段躲不开的五个坑实现和演示之间隔着一个真实环境。接下来这几个坑基本是每个做 Agent 的团队都会轮到的这里整理成完整链路供你排查。7.1 上下文塞太满模型反而变笨症状任务简单但模型回答开始答非所问中文夹英文甚至重复内容。根因往往不是模型退化而是上下文窗口里塞了太多无关历史模型的注意力被稀释。排查思路看当前上下文 token 分布确认摘要策略是否正常工作看每次用户消息之后系统有没有主动裁剪过期内容。修复方法把摘要粒度从每 5 轮压缩一次调高到每 3 轮压缩一次宁可多花一点摘要 token也要保证最近内容有足够空间。曾经有一个会话我在上下文里留下了大量工具返回的原始日志模型开始照着日志猜答案后来我把工具返回统一改成摘要问题立刻缓解。7.2 工具调用死循环症状日志里反复出现同一个工具调用模型似乎着了魔一样不断用同样的参数重试甚至一条错误路径走到黑。根因是模型被工具结果中的错误信息误导或者调度层缺少重试次数限制。排查思路先看工具返回是不是包含大量与当前目标无关的噪声再看调度层有没有每次调用次数累计。修复方法设计一个循环检测器统计同一个 call_id 连续调用同一工具的次数超过三次就强制触发模型重新规划并把整个失败链路摘要注入上下文明确告诉模型该路径已失败请换一种方案。同时给每个工具设置默认超时避免单次调用卡死整个队列。7.3 MCP 连接超时与重复握手症状MCP Server 明明启动了但 Agent 经常报工具不可用而且每次报错后会自动重连反而造成资源占用。根因是 MCP 连接生命周期管理不完善每次调用都重新握手。排查思路看 MCP 的连接池配置检查是否有连接复用再看服务端日志确认超时是因为服务端处理慢还是网络不稳定。修复方法为 MCP Client 建立连接池用 keep-alive 机制复用已建立的会话对每个 Server 单独设置超时阈值不能让一个慢服务拖垮整个 Agent。另外本地 stdio 模式下的 Server 要留意启动耗时如果启动需要十几秒第一次调用大概率超时就得在配置里预启动。7.4 记忆覆盖太激进把用户的纠偏搞丢了症状用户第一次说我喜欢表格第二次又说这次不要表格用段落吧Agent 后来还是默认表格用户很崩溃。根因是记忆写入逻辑把临时偏好当成了长期偏好或者冲突覆盖策略过于简单直接覆盖了用户的临时纠偏。修复方法区分任务级偏好和用户级长期偏好。任务级偏好只存进会话摘要不进入长期记忆真实进入长期记忆的只有那些在多个场景中反复出现的信息。冲突处理策略也要细化新信息来了不直接覆盖旧信息而是先降级旧信息并标记可能已被用户纠正只有新信息再次出现时才真正替代它。7.5 幻觉记忆——模型把推断当事实写进了记忆症状Agent 突然在对话中说出用户从来没提供过的细节比如您之前提到喜欢蓝色系的设计但用户从没说过。根因是记忆抽提器把模型的推断用户可能喜欢蓝色直接当成事实写入了长期记忆。排查思路看记忆写入日志确认每一条记忆的来源是用户原始表达还是模型的推理产物。修复方法抽提器中增加一道事实性校验提示要求模型区分用户明确说出的内容和模型根据上下文推测的内容推测内容一律标记为低置信度不进入长期记忆。如果抽提结果里出现推断猜测等词直接拒绝写入。这条规则看似简单但对长期记忆可信度的保护作用非常明显。最后再分享一点个人体会把 Agent 当成一个刚入职的实习生来管效率会高很多。实习生有聪明的脑子但不知道公司系统怎么用、不知道同事的偏好、也不知道之前项目做过什么——你给他配工作台、给他接好系统接口、让他记笔记他才能稳定产出。Hermes Agent 的会话、工具、MCP、记忆四件套本质上就是在给这个实习生配齐办公环境。如果只让我提一个建议那就是别一次性把四个能力全做完。最快的路径是先把会话和工具两个底座打通让 Agent 能连续对话、能调工具做真实任务接着引入 MCP 解决外部接入的标准化把工具多起来之后的维护成本降下来最后再做记忆因为记忆是在有真实用户反馈之后才能调出好效果的。顺序反了很可能前期就在记忆上过度设计到头来用户根本不关心。