企业官网建设流程全解析

1. 项目概述：为什么我要重写 Hermes Agent？

如果你最近在折腾大语言模型（LLM）的应用开发，特别是想让模型能稳定、可靠地调用工具（Tools）或函数（Function Calling），那么你大概率听说过或者用过 Hermes Agent。它作为一个轻量级的代理框架，设计初衷是好的，旨在简化 Agent 的开发流程。然而，在实际的生产环境测试和几个中型项目的深度集成中，我发现了它存在的几个“硬伤”。这些硬伤不是小打小闹的 Bug，而是会直接影响系统稳定性、开发效率和最终用户体验的核心问题。比如，工具调用的结果解析时常“抽风”，上下文管理在长对话中容易“失忆”，错误处理机制简陋到几乎等于没有，以及配置的繁琐程度让人望而却步。

这些问题让我在 deadline 的压力下，不得不频繁地深入源码进行 Hack，写各种补丁。最终，我决定不再修修补补，而是基于 Hermes Agent 的核心思想，结合我在实际业务中积累的经验，从头重写一个更健壮、更易用的版本。这不是一个简单的 Fork 或升级，而是一次针对其架构和实现逻辑的深度重构。今天，我就来详细拆解我遇到的这四个硬伤，并分享在重写过程中，我是如何设计解决方案的。无论你是正在评估 Agent 框架，还是已经深受其扰，相信这些实战经验都能给你带来直接的帮助。

2. 硬伤一：脆弱的工具调用与结果解析

工具调用是 Agent 的灵魂，但原版 Hermes Agent 在这方面的表现却像是一个不稳定的“实习生”。

2.1 问题深挖：JSON 解析的“玄学”行为

最让人头疼的是工具调用结果的解析。框架期望 LLM 返回一个格式严格的 JSON 来指定调用的工具名和参数。理论上，现代 LLM（如 GPT-4, Claude-3）的 JSON 模式已经相当可靠。但原版实现中，对模型返回内容的处理过于简单粗暴。它通常只是做一个简单的json.loads()，一旦模型返回的文本在 JSON 之外包含了任何解释性文字（例如，“好的，我将调用天气查询工具，参数是：{“city”: “北京”}”），解析就会立即崩溃，整个 Agent 流程也就中断了。

更糟糕的是，其错误处理仅仅是抛出一个异常，没有任何 fallback 机制或重试逻辑。在实际场景中，LLM 的输出具有不可预测性，网络波动、提示词（Prompt）的微小变化都可能导致输出格式的轻微偏离。这种“非黑即白”的解析策略，使得系统在生产环境中极其脆弱。

我的解决方案：实现一个“宽容且智能”的解析层我重写的核心之一，就是构建了一个健壮的解析器。它的工作流程如下：

1. 正则提取优先：首先，使用精心设计的正则表达式，尝试从模型返回的整个文本块中，提取出类似 JSON 结构的字符串。正则表达式会匹配{...}模式，并具备一定的容错能力，允许参数值内存在未转义的双引号（这是一个常见问题）。
2. 安全解析与验证：提取到候选字符串后，使用json.loads()在try...except块中进行解析。如果失败，解析器会尝试一些自动修复策略，例如补全缺失的引号、处理常见的转义错误。
3. LLM 辅助修复（终极后备）：如果上述自动化方法都失败，解析器会启动一个轻量级的“修复流程”。它将有问题的文本和期望的 JSON Schema 再次发送给 LLM（可以是一个更小、更快的模型），专门请求其进行格式修正。这一步虽然增加了一点延迟，但相比整个 Agent 流程失败，代价小得多。
4. 结构化日志：无论成功与否，解析的每一步都会产生详细的、结构化的日志。这让我们能清晰地追踪是哪个工具的调用、因为什么原因出了问题，为后续的提示词优化提供了数据依据。

# 简化的容错解析函数示例 import json import re import logging def robust_json_parse(llm_output: str, tool_schema: dict) -> dict: """ 尝试从 LLM 输出中稳健地解析出工具调用 JSON。 """ # 步骤1：正则提取 json_pattern = r'\{[^{}]*\}' matches = re.finditer(json_pattern, llm_output, re.DOTALL) best_match = None for match in matches: candidate = match.group() # 步骤2：尝试直接解析 try: parsed = json.loads(candidate) # 简单验证结构 if “tool_name” in parsed and “parameters” in parsed: best_match = parsed break except json.JSONDecodeError: # 记录但不立即失败 logging.debug(f“初步解析失败，候选内容: {candidate}”) continue if best_match: return best_match # 步骤3：尝试自动修复（例如，处理单引号或缺失引号） # 这里省略具体的修复代码，可能涉及字符串替换和二次解析尝试 # 步骤4：如果自动修复失败，记录错误并准备进入LLM修复流程或抛出更友好的错误 logging.error(f“无法从输出中解析工具调用: {llm_output}”) # 可以在这里触发一个 fallback 或重试机制 raise RobustParseError(“工具调用解析失败，已记录详细日志。”)

注意：正则表达式不是万能的，复杂的嵌套 JSON 或格式极其混乱的文本可能无法处理。因此，清晰的工具调用提示词仍然是第一道防线。我的经验是，在系统提示词中明确要求“请只返回一个纯净的 JSON 对象，不要包含任何其他解释文本”，能预防 90% 的解析问题。

2.2 工具注册与发现的笨重之处

原版框架中，工具的注册和管理往往分散在代码各处，或者需要一个集中的大型配置文件。当工具数量增多时，维护和查找变得困难。此外，动态工具（根据运行时状态生成或失效的工具）支持很弱。

重写设计：基于装饰器的声明式工具注册我借鉴了现代 Web 框架（如 FastAPI）的思想，采用装饰器来声明工具。这使得工具的定义与其实现紧密相连，代码可读性极高，也便于利用 IDE 的跳转和查找功能。

from my_rewritten_agent import tool_registry @tool_registry.register( name=“get_weather”, description=“根据城市名称查询实时天气”, parameters_schema={ “type”: “object”, “properties”: { “city”: {“type”: “string”, “description”: “城市名称，如‘北京’、‘上海’”} }, “required”: [“city”] } ) async def get_weather(city: str) -> str: """实际的工具实现函数""" # 调用天气 API # ... return f“{city}的天气是晴，25摄氏度。”

工具注册中心 (tool_registry) 会自动收集所有被装饰的函数，并为其生成符合 OpenAI Function Calling 标准的 Schema。Agent 在初始化时，只需加载这个注册中心，就能获取所有可用工具的描述。这种方式天然支持模块化，你可以将不同领域的工具放在不同的 Python 模块中，通过导入来“注册”。

3. 硬伤二：上下文管理的混乱与“失忆”

Agent 经常需要处理多轮对话（Multi-turn Conversation）。原版 Hermes Agent 的上下文管理更像是一个“简易记事本”，存在两个主要问题：令牌（Token）计数不准确和关键信息丢失。

3.1 Token 计数不准与成本失控

LLM 的 API 调用成本与输入的 Token 数量直接相关。原版框架通常使用简单的字符串长度估算或简单的分词器，这在混合了中英文、代码和特殊符号的对话历史中，误差可能高达 20%-30%。这意味着你可能为实际 8000 Token 的内容支付 10000 Token 的费用，或者更糟，因为低估了 Token 数而导致请求被 API 拒绝（超过上下文长度限制）。

解决方案：集成精准的 Token 计数在重写版中，我强制集成了与目标 LLM 匹配的精准分词器。例如，如果主要对接 OpenAI GPT，就使用tiktoken；如果支持开源模型，就集成transformers库的相应分词器。上下文管理器在每次添加或删除消息时，都会实时、精确地计算 Token 消耗。

import tiktoken class PreciseContextManager: def __init__(self, model: str = “gpt-4”): self.encoding = tiktoken.encoding_for_model(model) self.messages = [] self._token_count = 0 def add_message(self, role: str, content: str): message_token_count = len(self.encoding.encode(content)) if self._token_count + message_token_count > MAX_TOKENS[model]: # 触发智能裁剪策略，而非简单丢弃最旧消息 self._smart_trim(message_token_count) self.messages.append({“role”: role, “content”: content}) self._token_count += message_token_count def _smart_trim(self, incoming_tokens: int): """智能裁剪策略：优先压缩或删除非关键交互（如冗长的工具输出），保留最新的用户指令和系统提示。""" # 实现细节：可以给消息赋予权重，或识别工具输出进行摘要 # ...

此外，上下文管理器会提供一个实时的 Token 使用量仪表盘（通过日志或监控接口），让开发者对成本有清晰的感知，并能设置预警阈值。

3.2 长对话中的关键信息丢失

当对话历史超过模型上下文窗口时，需要裁剪（Trim）旧消息。原版通常采用简单的“先进先出”（FIFO）策略，即丢弃最老的几条消息。这极易导致灾难性遗忘：Agent 可能忘记了对话早期设定的关键目标或约束条件。

重写策略：基于重要性的智能裁剪我实现了一个优先级裁剪系统。系统提示词（System Prompt）和最近几轮的用户指令（User Message）具有最高优先级，永远不会被主动丢弃。对于较旧的消息，尤其是冗长的工具执行结果（Tool Call Result），系统会尝试进行“摘要”：

1. 自动摘要：对于文本类型的工具输出，使用一个轻量级的文本摘要模型（或再次调用 LLM 的摘要功能）将其压缩，用摘要替换原始长文本，节省大量 Token。
2. 重要性标记：允许开发者在定义工具时，标记其输出是否为“关键上下文”。例如，一个“查询数据库架构”的工具输出可能是关键的，而一个“计算器”工具的结果可能用完即弃。
3. 向量记忆库集成：对于超长对话或需要持久记忆的场景，我设计了插件式的记忆后端。可以将重要的对话片段或事实存储到向量数据库（如 Chroma, Weaviate）中。当后续对话需要相关背景时，Agent 可以先从向量库中检索（Recall）相关信息，再注入到当前上下文。这实现了“记忆的外挂”，突破了模型原生上下文长度的限制。

4. 硬伤三：简陋的错误处理与重试机制

在原版框架中，错误处理基本靠开发者自己用try...except包裹整个 Agent 运行流程。网络超时、API 限流、工具执行异常、模型返回格式错误……所有这些都混在一起，排查起来如同大海捞针。

4.1 构建分层的错误处理体系

我重写后的 Agent 将错误分为几个清晰的层级，并针对每一层提供处理策略：

1. 基础设施层错误：如网络连接失败、API 密钥无效。这类错误应立即失败，并给出明确的、可操作的建议（如“请检查网络”或“API 密钥已过期”）。
2. 模型层错误：如 API 返回速率限制（429错误）、服务器内部错误（5xx）。对于速率限制，框架应自动实现指数退避重试；对于服务器错误，可以进行有限次数的重试。
3. 工具执行层错误：这是重写的重点。工具执行失败（如调用的外部 API 无响应）不应导致整个 Agent 崩溃。框架应捕获异常，并将格式良好的错误信息（如“天气服务暂时不可用”）作为工具执行结果返回给 LLM。LLM 可以根据这个错误结果，决定下一步行动，例如尝试另一个工具，或向用户解释情况。这赋予了 Agent 从错误中恢复的能力。
4. 逻辑层错误：如解析失败、状态矛盾。这类错误需要记录最详细的上下文（包括当时的对话历史、工具调用记录）并触发告警，方便开发者进行深度调试。

class ResilientAgent: async def run_tool(self, tool_name: str, params: dict): try: result = await self._execute_tool(tool_name, params) return {“status”: “success”, “data”: result} except ExternalServiceError as e: # 外部服务错误，返回友好信息供LLM决策 logging.warning(f“工具{tool_name}调用外部服务失败: {e}”) return {“status”: “error”, “message”: f“{tool_name}服务暂时不可用，原因: {str(e)}”} except Exception as e: # 未预期的内部错误，记录并返回通用错误 logging.error(f“工具{tool_name}执行内部错误: {e}”, exc_info=True) return {“status”: “error”, “message”: “工具执行过程中发生意外错误”} async def _execute_tool(self, tool_name: str, params: dict): # 实际的工具分发和执行逻辑 tool_func = self.tool_registry.get(tool_name) if not tool_func: raise ToolNotFoundError(f“工具 {tool_name} 未注册”) # 这里可能涉及异步调用、超时控制等 return await tool_func(**params)

4.2 可配置的重试与熔断机制

对于模型调用和外部工具调用，我引入了可配置的重试策略。开发者可以针对不同的错误类型设置不同的重试次数、重试间隔（如指数退避）。同时，借鉴微服务中的熔断器（Circuit Breaker）模式，如果一个外部工具连续失败多次，可以暂时将其“熔断”，在一段时间内不再尝试调用，直接返回降级结果，避免雪崩效应。

5. 硬伤四：不友好的配置与集成体验

原版框架的配置往往散落在环境变量、代码常量和配置文件里，缺乏统一管理。想要切换 LLM 提供商（比如从 OpenAI 切换到 Anthropic），或者调整底层通信协议（比如使用不同的 HTTP 客户端），可能需要修改多处代码。

5.1 基于 Pydantic 的集中化配置管理

我使用 Pydantic 的BaseSettings来管理所有配置。这带来了类型安全、环境变量自动加载、配置验证等好处。所有 Agent 运行所需的参数——LLM 的 API 密钥、基础 URL、模型名称、超时设置、重试策略——都集中在一个配置对象中。

from pydantic import BaseSettings, Field class AgentSettings(BaseSettings): llm_provider: str = Field(“openai”, description=“LLM 提供商: openai, anthropic, azure 等”) openai_api_key: str | None = None anthropic_api_key: str | None = None model_name: str = Field(“gpt-4-turbo-preview”, description=“使用的模型名称”) request_timeout: int = Field(30, description=“API请求超时时间（秒）”) max_retries: int = Field(3, description=“失败重试次数”) class Config: env_file = “.env” env_prefix = “AGENT_” # 环境变量如 AGENT_LLM_PROVIDER # 使用配置 settings = AgentSettings() agent = MyRewrittenAgent(config=settings)

通过环境变量AGENT_LLM_PROVIDER=anthropic，就可以无缝切换底层 LLM，而无需改动业务逻辑代码。

5.2 模块化与清晰的扩展点

重写版框架被明确划分为几个松耦合的模块：

• LLM 客户端模块：负责与不同的大模型 API 通信。定义统一的接口，方便接入新的提供商。
• 工具管理模块：负责工具的注册、发现和调用。
• 上下文管理模块：负责对话历史的存储、Token 计数和智能裁剪。
• 执行引擎模块：负责驱动“思考-行动-观察”的循环逻辑。

每个模块都通过清晰的抽象类或协议定义接口。如果你想替换默认的 HTTP 客户端（比如使用httpx替代aiohttp），或者想增加一个自定义的记忆存储，只需要实现对应的接口并在配置中指定即可。这种设计让框架的定制和扩展变得非常直观。

6. 重写后的核心架构与工作流

经过上述改造，新的 Agent 框架内部工作流变得更加清晰和健壮。一个典型的执行循环如下：

1. 接收用户输入：将用户问题放入上下文管理器。
2. 准备系统提示与上下文：结合系统指令、裁剪后的历史对话，并可能从向量记忆库中检索相关记忆，组装成最终的 Prompt。
3. 调用 LLM：通过可配置、带重试和熔断的客户端调用 LLM，请求下一步动作（可能是直接回答，也可能是工具调用）。
4. 容错解析：使用“宽容且智能”的解析器处理 LLM 返回内容，提取工具调用指令或最终回答。
5. 执行工具：如果解析出工具调用，则通过工具管理模块分发给对应的函数执行。执行过程被完整的错误处理包裹，任何异常都会被转化为结构化的错误结果。
6. 处理工具结果：将工具执行的成功结果或错误信息，格式化为一条新的“工具返回”消息，添加到上下文中。
7. 循环或返回：如果上一步添加了工具返回，则回到步骤 3，让 LLM 根据工具结果进行下一步思考（这就是 ReAct 模式中的“观察”）。如果 LLM 返回的是最终答案，则将其返回给用户，并选择性地将本轮关键信息存入长期记忆。

这个流程的每一个环节都包含了之前提到的改进：精准的 Token 管理、智能的上下文裁剪、分层的错误处理和可替换的模块。

7. 实战对比：新旧版本处理复杂任务的差异

让我们通过一个具体场景来感受差异：“帮我分析过去三个月公司官网的访问数据，总结趋势，并写一份简短的报告。”

这个任务可能涉及多个工具调用：查询数据库获取原始数据、调用数据分析库生成图表、最后调用 LLM 撰写报告。

• 原版 Hermes Agent 可能的表现：

  • 在第一步查询数据库时，如果 SQL 查询因网络波动超时，工具调用抛出未捕获的异常，Agent 直接崩溃，用户收到一个 Python 栈追踪错误。
  • 或者，LLM 在返回调用“生成图表”工具的指令时，多了一句“我觉得用折线图比较好”，导致 JSON 解析失败，流程中断。
  • 即使前几步成功，在生成报告时，因为长达数十轮的对话历史超过了上下文限制，且被简单裁剪，Agent 可能已经忘记了“三个月”和“官网”这两个关键约束，生成的报告文不对题。

• 重写版 Agent 的表现：

  • 数据库查询超时，错误被捕获，LLM 收到的结果是：“数据库查询服务超时，请稍后重试或检查网络。” LLM 可以理解这个错误，并回复用户：“数据服务暂时不可用，请您稍等片刻再试，或者我先为您撰写报告的大纲？”
  • LLM 返回内容附带了额外文本，智能解析器成功提取出了正确的 JSON，流程继续。
  • 长对话中，系统提示词（“你是数据分析助手…”）和用户最初的问题（“分析过去三个月官网数据…”）被标记为高优先级始终保留。中间庞大的数据结果被自动摘要为：“过去三个月访问量分别为 10万、12万、15万，呈上升趋势。” 从而节省了大量 Token，确保了最终报告不偏离核心目标。

8. 迁移与适配建议

如果你正在使用原版 Hermes Agent，并考虑迁移或借鉴思路，以下是我的建议：

1. 评估痛点：首先确认你遇到的是否是上述四个硬伤。如果只是简单使用且运行良好，未必需要立即重写。
2. 渐进式重构：不要试图一次性替换整个系统。可以从最痛的点开始，例如先实现一个独立的、健壮的工具调用解析器，替换掉原来的脆弱解析逻辑。然后再逐步重构上下文管理、错误处理等模块。
3. 关注接口兼容性：如果你希望平滑迁移，在设计新框架时，可以暂时保留原版的主要对外接口（如agent.run(query)），内部实现则用新的健壮模块。这样业务代码改动最小。
4. 强化测试：新的 Agent 框架必须配备完善的测试套件，包括单元测试（测试工具解析、上下文裁剪逻辑）、集成测试（模拟完整的多轮对话）和混沌测试（模拟网络延迟、API 失败等异常情况）。这是保证其稳定性的基石。

重写 Hermes Agent 的过程，本质上是对生产级 AI 应用稳定性和可维护性的一次深度思考。它不再是一个简单的“模型调用包装器”，而是一个具备韧性（Resilience）、可观测性（Observability）和可扩展性（Extensibility）的智能体运行时环境。这次经历让我深刻体会到，在 AI 应用工程化的道路上，对细节的打磨和对故障的预设，与算法模型的选择同样重要。