Hermes Agent架构总览：模块化设计与执行路径解析

1. 架构总览到底在解决什么问题

很多刚开始接触 Agent 开发的朋友，第一反应就是去翻框架源码，或者直接找几个 demo 跑起来。这本身没有错，但一旦项目从“跑通一个 demo”走向“接入真实业务”，你就会发现事情远没有那么简单。模型返回的结果不稳定、技能调用老是缺参数、记忆和上下文混在一起、并发一上来就开始互相抢资源……这些问题的根源往往不在某一个具体环节，而在你根本没看清整个系统是怎么串起来的。

所以我写这篇架构总览，核心就做一件事：把 Hermes Agent 当成一个可以拆解的工程系统，把它的子系统、模块边界、数据流向和执行路径全部摊开，给你一张能直接对着做设计、做排查、做二次开发的地图。

这里说的 Hermes Agent，简单概括就是一个基于大语言模型驱动、以工具调用为核心的 Agent 框架。它把“智能体”拆成了若干职责单一的子系统，每个子系统各管一段，再通过一条清晰的主执行路径串起来。你收到一条用户请求，经过意图解析、计划编排、技能匹配、工具调用、结果回流，最后输出收敛，完整走完一条链路。这条链路能不能走通、每段由谁负责、遇到问题从哪查起，就是架构总览要回答的。

适合看这篇内容的人，我觉得有三类。第一类是正准备基于 Agent 框架做业务集成的开发者，你需要先理解系统骨架再动手。第二类是自己想从零设计一套 Agent 架构的工程师，可以参考这里面的子系统划分和路径设计思路。第三类是已经在用但经常被各种诡异问题困扰的人，后面第 5 部分的问题排查实录会很有用。

这个系统设计上最重要的一点，是它没有把所有智能都塞进“模型调用”这一个环节，而是把智能拆散到各个子系统里。模型负责语言理解和决策，但真正的执行力来自技能库和编排器。这种设计的直接好处是：模型换了可以只动接入层，新增能力不用重写主流程，出了问题能快速定位到是哪一段链路故障。下面我先把整个系统的物理结构铺开。

1.1 一张架构图看懂全局

我们先从最宏观的层面看，整个 Hermes Agent 系统分四层。

表层是接入层，负责接收来自命令行、桌面端、聊天软件或者 API 网关的请求。它不关心进来的请求具体是什么，只做格式转换和协议适配，把各种来源的输入统一成系统内部的指令格式。

接入层往下是调度层，这是整个系统的中枢。它由会话管理、上下文记忆、意图引擎、执行编排器组成。调度层要做的事是：看明白用户要什么（意图识别），想清楚分几步做（计划生成），然后一步步把任务分发出去。

调度层下面是执行层，包括技能注册表、工具执行器、沙箱环境和结果解析器。这一层不负责“思考”，只负责“干活”。你注册了哪些技能、这些技能对应什么工具函数、参数怎么填、在什么环境里运行，都由这一层处理。

最底层是支撑层，包括模型接入网关、向量存储、日志监控和安全策略。它给上层提供基础设施能力，比如模型调用统一走网关、记忆写入向量库、每一步执行都有日志留痕。

这四个层次的划分，本质上是在复制一个成熟团队的协作方式：有人接需求、有人做方案、有人干活、有人管工具和保障。Agent 系统要稳定，就必须让这些职责在代码层面也清晰分开。

1.2 为什么选择模块化子系统并行协作

Hermes Agent 的架构没有采用“一个大的模型调用循环包打天下”的简单模式，这是经过权衡的。我见过不少原型项目，把所有逻辑塞进一个 while 循环：模型输出一段文本，正则匹配到工具名就调用，再传给模型继续。这种做法的确能让 demo 快速跑起来，但基本过了三轮以上就会出各种问题，上下文塞爆、错误累积、参数传递混乱、无法并发。

模块化的设计，相当于给这个“while 循环”拆出了清晰的职能部门。每个子系统只维护自己的状态，子系统之间通过定义好的接口通信。比如意图引擎不用管工具执行得怎么样，它只负责把“用户请求”翻译成“结构化任务”。技能注册表不需要了解模型怎么思考，它只维护“有哪些能力、参数长什么样”。

这种设计的一个直接收益是并发能力。当多个用户请求同时进来，会话管理可以做到每个会话独立调度、互不干扰。记忆子系统按会话维度隔离，技能执行器通过连接池共享但互不阻塞。你要是用过那种全局只有一个状态桶的 Agent，就会知道并发一上来场面有多混乱。

另外一个容易忽略的好处是可测试性。模块化之后，你可以单独构造一个意图引擎的单元测试，也可以单独测技能注册表的参数校验逻辑，不需要拉起整个模型。这对上生产环境之前的回归验证特别重要。

2. 核心子系统逐个拆解

架构总览的重点不只是画一张分层图，而是要把每个子系统内部到底在做什么讲清楚。只有理解了每个模块的职责边界，你在排查问题时才知道该往哪个方向找。

2.1 意图引擎：从自由文本到结构化指令

很多 Agent 系统把意图识别简单地理解为“让模型判断用户想干什么”，但 Hermes 的意图引擎做得更重一些。它除了识别意图，还要产出结构化指令。所谓结构化指令，就是一个包含动作类型、目标对象、必要参数、约束条件的数据结构。比如用户说“帮我查一下最近三天服务器 CPU 的平均负载”，意图引擎输出的不是一段自然语言，而是一份类似 JSON 的指令，包含了“query_metrics”这个动作、“cpu_avg”这个指标、“last_3_days”这个时间范围。

这一步非常关键，因为后续的编排流程只在结构化指令上操作，不再碰原始文本。这样做的意义在于缩小模型的出错范围。你可以针对结构化指令做参数校验，缺哪个参数就补哪个，而不是让整个流程都依赖模型自由发挥。

在实际实现上，意图引擎通常结合两种方式：一种是正则和槽位规则，处理格式固定的指令；另一种是模型分类加 JSON 模式输出，处理开放式的自然语言。Hermes 推荐的做法是规则优先、模型兜底。格式能确定的，绝不让模型去猜，这能大幅提高可靠性。

注意一个细节：意图引擎本身不做“用户意图以外的事情”。它不会自己决定去调用工具，也不会去查记忆，它就是一条流水线上的第一道工序。保持每个模块专注单一职责，是整个架构能维护下去的前提。

2.2 记忆子系统：短期上下文与长期记忆分层

记忆子系统负责管理 Agent 的“已知道的信息”，分短期上下文和长期记忆两层。

短期上下文对应的是当前会话内的对话历史、临时变量、最近几次工具调用的结果。这一层的管理核心是窗口控制。模型上下文窗口是有限的，你不能把三轮对话的所有原始信息都丢进去，要做摘要、裁剪和结构化缓存。Hermes 在这块的策略是：每轮工具调用的结果先存到一个结构化缓冲区，模型只读必要部分，而不是全量回灌。

长期记忆对应的是跨会话的信息，比如用户偏好、项目历史、事实类知识。这层通常落到向量数据库里，通过语义检索按需召回。例如用户之前说过“服务器部署用 8080 端口”，下次相关场景就能自动带出。这里要特别注意记忆的写入策略，不是所有对话内容都值得长期保存。Hermes 的做法是设置一个“记忆价值判断”阀值，只有与用户指令强相关的、明确的、可执行的信息才写入长期记忆，闲聊内容直接丢弃。

我在实际使用中发现，记忆子系统最容易踩的坑是“污染”。如果你不控制写入质量，长期记忆会越存越乱，检索出来的内容相关性越来越差。所以记忆写入前一定要做一次过滤，宁缺毋滥。

2.3 技能注册表：Agent 的“能力清单”与参数契约

技能注册表是 Agent 的能力清单，它决定了“Agent 会干什么”。每个技能本质上是一个带有元数据描述的工具函数条目，包括技能名称、功能描述、参数 Schema、运行环境要求、依赖关系和失败处理策略。

这个设计非常像 OpenAPI 规范之于微服务。技能注册表为每个工具定义了严格的参数契约。Agent 大模型在决策要调用哪个技能时，是依据技能描述和参数 Schema 来选择的。如果你的参数 Schema 写得不清晰，模型就很容易填错参数。所以编写技能注册表的时候，描述文字不能太随意。描述要讲清楚“这个技能什么时候用”“每个参数具体是什么意思”“有什么格式要求”。

举个例子，你注册一个“发送邮件”技能，如果参数描述里只写“to、subject、content”，模型可能搞不清 to 是收件人地址还是收件人名称。你要写明：to 是标准 RFC 822 邮箱地址，必须包含 @ 符号；subject 长度限制在 100 字以内。模型看到这样的约束，错误率会明显下降。

技能注册表还有一个重要机制是技能分类和权限标记。不是所有技能都对所有用户开放。你可以标记哪些技能是管理员才能调用、哪些技能涉及敏感操作需要二次确认。这个权限管控移植到企业场景中特别有用。

2.4 执行编排器：每一步该由谁执行

执行编排器是执行层的指挥官，它把意图引擎产出的结构化指令，逐步展开为可执行的工具调用序列。很多人疑惑 Agent 和传统的任务流程引擎到底有什么不同，区别就在于编排器是动态决策的，而不是按照预先写死的流程图跑的。

编排器在工作时遵循一个循环：看当前任务状态，判断下一步是否还需要工具调用；如果需要，从技能注册表匹配可用技能；调用工具之后，把结果放回任务状态，继续循环；直到任务被判定为“完成”或“无法继续”。这个循环我用大白话说，就是“模型想一步，执行一步，看看结果，再想下一步”。

要注意的是，编排器的“动态决策”不等于“没有上限”。你必须给循环设置最大步数、超时时间、失败重试次数。否则一个任务进入死循环，整个 Agent 就会被卡死。我见过最典型的例子是：模型反复尝试调用同一个失败的工具，每次都报同样的错，但因为没有步数上限，就一直空转到超时。后来我们把最大工具调用轮次设成 10，并加上错误模式识别——同一工具连续失败 3 次就切换方案，这类问题就基本消失了。

编排器内部还要维护一个“执行上下文”，记录每一步执行后的中间结果。这个上下文很重要，它是模型继续决策的依据。执行上下文的结构决定了模型能不能高效地利用已有结果。Hermes 的做法是把执行上下文设计成一个有向的记录列表，每一条记录包括步骤序号、执行动作、输入摘要、输出摘要和状态标记，模型只读摘要而非完整数据。

2.5 安全边界层：Agent 不能触碰的红线

Agent 系统本质上是一个能自主调工具的 AI，安全边界层就是它的“护栏”。这一层负责三件事：权限校验、操作审计、危险操作拦截。

权限校验发生在执行编排器调用技能之前。每次工具调用都会检查当前会话的权限身份是否匹配该技能的权限要求。这个校验不能只做一次，因为 Agent 在执行过程中可能会动态产生新的子任务，每个子任务都要重新校验。

危险操作拦截则更细粒度。比如你的技能库里注册了一个“执行 Shell 命令”的工具，但你不能允许模型任性地执行 rm -rf 之类的高危命令。Hermes 的做法是为每个危险操作定义防护规则，Shell 工具默认运行在沙箱中，只允许访问白名单目录；删除操作必须走一个带回收站功能的专用接口。

操作审计则把所有的意图解析、计划生成、工具调用、参数信息、返回结果都记录到日志系统。这不仅是排查问题的依据，也是安全追溯的证据链。在企业环境里，这一步基本是必须的。

3. 执行路径地图：一次请求的完整旅程

架构图是静态的，真正的系统行为要看动态的执行路径。下面我把一次完整请求的流程拆开走一遍，你在排查问题的时候，基本就是沿着这条路径一段一段定位的。

3.1 入口与任务初始化：请求是怎么进的系统

一次请求从入口进入，比如从桌面端发来“帮我整理今天项目会议纪要并生成待办事项”。接入层先做协议转换，把这个消息包装成统一的任务对象。任务对象包含消息 ID、用户 ID、会话 ID、原始内容和到达时间戳。

接下来会话管理模块上场。它先查询这个会话 ID 是否已有历史上下文，如果有，就加载短期上下文摘要；如果是新会话，就初始化一个新的上下文空间。这一步的作用是给后续的意图解析和模型决策提供足够的背景信息。

任务对象随后被送入意图引擎。注意这个阶段用户 ID 也会被提取出来，用于后续的权限校验。会话管理还会判断当前会话是否需要用户身份确认。如果是匿名会话但任务涉及敏感操作，就在这一阶段提前拦截，而不是等到执行阶段才发现权限不足。

3.2 意图拆解与计划生成：大目标如何化成小步骤

意图引擎拿到任务对象，先做意图分类。针对“整理会议纪要并生成待办事项”，系统需要判断这是一个“多步骤复合任务”而非简单问题。复合任务的标志是：需要访问某个文件、需要理解会议内容结构、需要生成结构化待办列表，最后可能需要写入一个特定应用。

意图引擎把复合任务拆成多个子意图，并生成初步的步骤计划。这里模型的推理能力开始发挥关键作用。计划质量的好坏，直接决定了后续执行的效率。我见过的最常见问题是计划抽象层级不对，比如模型把“整理会议纪要”直接映射到“调用 text_summary 工具”，结果传进去的内容格式根本不符合工具要求，因为缺少了“先读取文件”和“提取关键议题”这两个前置步骤。

好的做法是让计划包含层级结构：先读取文件、再解析会议结构、接着提取待办事项、最后调用目标应用写入。每一层计划都要明确输入来源和输出去向。Hermes 里这一步输出的计划对象，是一份带优先级的步骤列表，后续执行编排器按优先级和依赖关系逐步推进。

3.3 技能匹配与参数填充：让工具读懂你的指令

计划生成之后，执行编排器开始按步骤驱动执行。每一步执行前，先要从技能注册表匹配技能。匹配过程基于语义相似度，但更重要的是参数结构是否匹配。技能注册表里每个技能都有输入参数 Schema，编排器会尝试把当前步骤的目标数据映射到 Schema 里的字段。

参数填充是整个链路里最容易出错的环节。我举个例子，计划要求“调用会议纪要解析工具”，工具需要输入 pdf_path、meeting_id、date_range 三个参数。但当前上下文里只有一份文件名“product_review_202506.pdf”，和目标日期 6 月 15 日。这里的映射需要把文件名转换成绝对路径，再把日期格式统一成 ISO 8601。这个过程通常有专门的参数填充模块来处理，它基于字段名相似度和格式转换规则，尽量把上下文中的数据映射到工具参数上。

填充完成后还要做一次本地参数校验，不依赖模型，直接用 Schema 规则检查。必填字段缺失的，要么从上游步骤补充，要么标记为参数不足并生成澄清性问题回问用户。这个机制极大避免了工具执行到一半发现参数是空的情况。

3.4 工具执行与结果回流：系统如何应对不稳定的返回

校验通过后，技能执行器开始真正调用工具。工具可能是内部函数、外部 HTTP API、命令行程序，甚至是另一个 Agent。执行器根据技能配置选择执行模式：本地函数直接进程内调用；外部 API 走网络请求；危险操作进沙箱。

工具调用完成后，结果要回流。回流不是简单地把原始返回文本扔给模型，而是要经过结果解析器结构化。比如你查询服务器监控 API 返回一段 JSON 数组，包含多个指标点，结果解析器会把这段数据整理成表格形式，提取关键摘要，同时保留原始数据供需要时回溯。这种“先结构化再喂给模型”的做法，显著减少了模型在阅读原始返回时的理解偏差和上下文浪费。

工具失败是常态而不是异常。Hermes 对失败的返回做了分级处理：可重试的错（比如网络超时）会自动重试，带退避策略；不可重试的错（比如参数格式非法）会直接返回给编排器，编排器决策是否换技能或修改参数方案。这里要特别提醒，不要在失败回流的文本里塞太多堆栈信息，模型看到一长串报错反而容易懵。

3.5 结果聚合与最终输出：如何优雅地结束一次任务

所有计划步骤执行完毕或者达到终止条件后，进入结果聚合阶段。聚合模块会收集各步骤的输出摘要，按照用户的原始请求组织最终答案。这个过程不是简单拼接，而是要生成一个连贯的、有上下文的、可读性强的输出。

比如“整理会议纪要并生成待办事项”这个任务，最终输出应该包含：会议的关键议题摘要、每项待办事项的描述、负责人、截止时间和来源段落引用。结果聚合模块会把这些信息按模板组织成结构化文本，再交由桌面端渲染。

终止条件的设计也很重要。除了“所有步骤执行完成”外，还包括“达到最大重试次数”“用户主动中断”“安全策略触发拦截”等异常终止。异常终止时输出的消息应该明确告知用户当前进度和未完成部分，并给出下一步建议。这个设计能让系统在失败时依然保持可用性，而不是抛出一句“我无法完成”。

4. 从零搭建一个 Agent 实例：核心配置与实现细节

讲完架构和执行路径，我们用 Hermes Agent 从一个空目录开始，把系统跑起来。这一节我给的是可以直接抄作业的流程，同时会解释每一步配置背后的设计考量。

4.1 环境准备与基础依赖

先交代环境：Ubuntu 22.04 LTS，Python 3.11，Node.js 20 用于技能侧的工具运行时。Hermes Agent 本身基于 Rust 开发，安装时会提供预编译的二进制包，所以我们不需要本地编译整个项目。

依赖方面，需要 Docker 作为沙箱运行环境，需要 Redis 做会话缓存和分布式锁，需要 PostgreSQL 或者 SQLite 做任务元数据持久化。向量数据库这块，本地开发用 SQLite 加向量扩展即可，量大了再迁移到独立的向量库。

安装过程我走的是预编译发布包的方式，直接把 Hermes Agent 的可执行文件放到 /usr/local/bin，然后建一个单独的运行目录，用来放配置文件和技能目录。建目录这一步很多人会忽略，但把运行目录和应用目录分开，后面做版本升级和数据备份都会方便很多。我把运行目录规划成这样子：

/opt/hermes/ ├── bin/ # 可执行文件和启动脚本 ├── config/ # 配置文件 ├── data/ # 数据存储，包括 SQLite 数据库和向量索引 ├── skills/ # 技能注册目录，每个技能一个子目录 ├── logs/ # 日志输出目录 └── tmp/ # 临时文件沙箱工作区

4.2 模型接入与系统提示词设计

Hermes Agent 支持接入多种模型服务，统一走模型接入网关。配置文件里需要指定模型提供方、模型名称、API 密钥和基础 URL。本地开发时我习惯用兼容 OpenAI 接口的本地模型服务，这样调试方便、成本低，还能离线工作。

模型接入后，最关键的一步是设计系统提示词。提示词不是简单的几句“你是一个助手”，而是要把 Agent 的工作准则、工具使用规范和输出格式要求都写清楚。我用的提示词结构包含四个部分：角色定义、工作流程、工具使用规范、输出约束。

角色定义写清楚“你是 Hermes Agent，基于工具调用完成用户的复杂任务”。工作流程告诉模型“先理解意图，再制定计划，逐步调用工具，每次调用后观察结果再决策下一步”。工具使用规范是重点，明确要求“只有工具返回成功才能宣称任务完成，工具失败要尝试替代方案或明确告知用户”。输出约束规定“最终输出必须是结构化中文文本，重要事实附来源引用”。

这段提示词是整个系统里性价比最高的调优点。我实测过，同样的模型同样的技能库，提示词结构优化后，工具调用成功率可以从不到百分之七十提升到百分之九十以上。值得花时间反复打磨。

4.3 配置文件逐项解读

Hermes Agent 的主配置文件是 config.yaml，下面我把我实际使用的一段配置展开讲。为了演示，我把敏感信息替换成占位符。

server: host: "127.0.0.1" port: 8324 timeout_seconds: 30 agent: name: "hermes-worker" max_steps: 10 max_retries: 3 default_timeout_ms: 15000 model: provider: "openai-compatible" base_url: "http://127.0.0.1:8000/v1" model_name: "local-qwen-32b" api_key_env: "HERMES_MODEL_API_KEY" temperature: 0.2 max_tokens: 4096 memory: session_ttl_seconds: 7200 long_term_store: "sqlite+vector" retriever_top_k: 5 retriever_threshold: 0.65 skills: root_dir: "/opt/hermes/skills" default_runner: "docker" allowed_commands: - "python3" - "node" sandbox: true security: admin_users: - "uid-user-001" sensitive_skills: - "file_write" - "shell_exec" audit_log_path: "/opt/hermes/logs/audit.log" logging: level: "info" path: "/opt/hermes/logs/agent.log" rotation: "50MB"

逐个说下关键配置的思路。max_steps和max_retries是执行编排器的安全阀值，分别控制任务总步数和单步失败重试次数。我给的是 10 和 3，这个组合在大多数任务里够用，既不会过早终止，也不会空转。

temperature设成 0.2，是因为我们做的是工具调用类任务，需要偏确定性的输出。如果你做的是创意写作类的 Agent，可以调到 0.7 以上，但涉及执行类任务，低温更稳。

retriever_threshold是长期记忆召回的阈值，取值范围在 0 到 1 之间，决定什么相关度的记忆会被召回。0.65 是我反复试下来比较合适的值。阈值太高，很多有用的历史信息召不回；阈值太低，召回了一堆垃圾，反而干扰模型决策。

allowed_commands限定了技能执行器可以启动的进程类型。它的作用是缩小攻击面，即使沙箱被攻破，模型能触达的命令也极其有限。注意我不建议把curl放进来，因为大部分 API 调用已经有专属工具，不需要 Agent 自己发网络请求。

4.4 注册第一个技能并验证执行路径

配置完成，模型也接好了，下面注册第一个技能。Hermes 的技能目录里每个技能对应一个目录，包含一个技能描述文件和若干执行脚本。这里我注册一个“获取当前时间”技能，功能虽然简单，但能把路径完整走通。

技能描述文件 content 部分写清楚技能用途，参数 Schema 定义好参数类型。这是模型能否正确调用技能的关键。时间技能的描述我这样写的：用于获取当前日期时间，参数 timezone 为可选参数，接受 IANA 时区名称，如 Asia/Shanghai，默认 UTC。

技能脚本内部用 Python 获取本地时间，做完时区转换输出标准格式。启动服务之后，向接入层发送一条测试请求“现在几点了，请使用工具获取”。如果一切正常，你会看到日志里依次出现意图分类、技能匹配、参数填充、执行调用、结果回流这几条记录。这就说明整条执行路径已经打通。

5. 常见问题与排查技巧实录

架构总览的价值最终要体现在排查问题上。这一节我整理几个高频问题，每一个都是我或者社区的同行在实际使用中真实踩过的坑。

5.1 模型一直在循环调用同一个工具

表现：任务开始后，编排器反复调用同一个工具，每次都得到相同或类似的失败结果，直到触发 max_steps 才终止。

原因主要有两个：一是系统没有在失败时为模型提供足够的差异化信息。每次工具返回的错误都被原样塞回上下文，模型看到的都是同一个报错，自然无法做不同的决策。二是计划阶段没有为“失败后怎么走”设计分支。当主路径失败时，模型不知道应该换一个策略，于是只会重试同一条路。

解决方法：第一，在错误回流时增加错误类别分析，告诉模型“这次失败是参数问题还是环境问题”。第二，在编排器层面增加一种模式识别：如果同一个技能连续失败 N 次，自动切换为“询问用户”模式，而不是继续尝试。我这边的参数是连续失败 3 次就触发切换，效果很明显。

5.2 技能参数总是填充不全

表现：配置好的技能描述和参数 Schema 都没问题，但模型填充的参数总缺东少西，经常出现必填项为空的情况。

原因很多时候不在模型配置，而在上游的数据流转。参数填充模块拿到的上下文数据，本身就可能不足，比如前一步产出结果里没有模型发起任务时承诺的字段。另外参数 Schema 描述行本身容易被忽略，很多字段名称太短或歧义太多。

解决方法：第一，在计划阶段就让模型显式列出每个步骤的“输出字段清单”，后续步骤的参数映射都从这些输出字段里取。第二，在技能描述里给参数加示例值，模型对“有示例的参数”理解会好很多。第三，实在填不齐的参数，不要硬填，走追问流程，明确告诉用户缺什么，让用户补。

5.3 长期记忆检索出来全是无关内容

表现：Agent 在对话中会引用一些和当前任务毫不相关的历史信息，导致回答显得十分混乱。

原因大概率是记忆写入时没有做好质量过滤，聊天中的杂谈、情绪化表达、无效问题都被写进了长期记忆。召回时阈值又偏低，结果一堆低质量内容被拉出来干扰决策。

解决方法：第一，长期记忆写入增加一个门槛：只有与任务强相关且明确的事实性信息才落库。第二，给记忆条目增加“新鲜度”评分，最近用过的记忆权重更高。第三，把召回阈值调高，以 0.7 为基准重新测试。

5.4 并发请求下崩溃

表现：单机部署的 Hermes Agent，平时单会话运行正常，一旦同时进来 5 个以上请求，系统就开始超时甚至崩溃。

原因通常是两个：一是模型网关成了瓶颈，同一个模型端点被高频调用，响应时间成倍上升。二是会话上下文存储在本地内存数组，多会话并发时互相抢占没有加锁。

解决方法：第一，在模型网关和 Agent 之间加一层请求合并和限流，同一个模型端点的并发查询数设置一个上限。第二，将短期上下文从本地内存迁到 Redis，利用 Redis 的事务特性保证读写一致。第三，给每个会话在编排器里分配独立的上下文状态槽，进程内数据共享全部通过状态槽互相隔离。

5.5 日志排查路径速查表

实际操作中，日志是最重要的排查线索。我把关键日志出现的位置和执行路径对应起来，做成一张速查表给各位，排查问题时可以直接对表索引：

6. 架构设计的演进方向与我的实践建议

架构总览写到这个程度，主体内容已经完整了。我再从架构演进的角度，聊聊这套系统未来往哪里走，以及我自己实践下来的一些心得。

第一点，工具调用质量是 Agent 体验的分水岭。以我接触过的项目来看，用户对一个 Agent 是“好用”还是“玩具”的评价，往往取决于工具调用能不能稳定地成功，而不是模型本身是否聪明。因此架构设计里，技能注册表、参数填充器、错误回流这三位一体的部分，应该拿最高优先级去打磨。80% 的精力投在代码层面的确定性上，才不会让自己淹没在模型的不确定性里。

第二点，记忆系统是 Agent 个性化的支柱。一套好的记忆子系统，能让 Agent 在与同一用户第二次对话时，明显表现出对上下文的承接。这种体验感知，在架构层面不需要复杂的强化学习，扎实的写入过滤和召回策略就足够。某同事在社区分享的一个经验是：先做长期记忆的“记录侧”优化，再做“读取侧”优化，顺序不能反。因为读取到的内容质量，上限不会超过写入端存储的内容质量。

第三点，安全边界不要留到上线前才补。很多 Agent 项目在原型阶段完全不做权限和审计，等到要部署到企业内网才想起这块缺失，然后导致项目被迫返工。安全问题一定要从第一个技能提交就开始建立，记录日志、控制技能权限、标记敏感操作，这些应该在开发阶段就成为框架内建功能的一部分。

第四点，执行的确定性优先于交互的灵活性。Agent 最终要落在业务场景里，用户希望 Agent 能在多次操作中保持一致的行为。因此我在设计执行路径时，会把“规则优先、模型兜底”作为原则渗透到各个子系统中。能用代码和 Schema 约束的，就不让模型自由发挥。这样系统更可控，排查问题的难度也更低。

最后分享一个小技巧：每次改动架构后，我会用一个固定的基准任务集回归测试整个执行路径。任务集里包含 10 个典型场景，覆盖简单查询、多步骤操作、工具失败恢复、并发请求这几类情况。任何一次改动导致某个场景挂掉，都能在测试阶段发现而不是线上暴露。这个习惯，帮我避免了很多次线上事故。

架构总览的意义在于，它让你从“调用代码”的视角上升到“看清系统”的视角。当系统出问题时，你能快速判断这是意图识别环节的偏差、参数填充环节的疏漏、还是工具执行环节的故障，而不是在一大坨混乱的逻辑里盲目调试。按照上面的思路把子系统边界划清，把执行路径理顺，再配上规范的日志追踪，一个 Agent 系统就真正具备了工程化落地的基础。