企业官网建设流程全解析

最近我把手头几个零散的AI脚本收拢成一个可以统一调度的agent服务，取名hermes-agent。整个过程踩了不少坑，也把一些很隐蔽的坑给填平了。如果你也在纠结怎么把多个AI能力、多个工具调用组合成一个稳定可维护的智能体服务，这篇东西值得你花几分钟看完。我不打算讲那种PPT架构，就把实际跑通的方案、参数、还有翻车记录都摊开来说。

这个项目本质上解决的是“AI能力怎么编排”的问题。单个大模型接口只能做对话，但真实业务需要的是“听懂需求、拆解任务、调用工具、返回结果”一整条链路。hermes-agent就是把这套链路变成可配置、可扩展的服务。适合谁看？正在用LangChain但觉得太重、被AutoGPT那种野路子坑过、或者想自己搭一套轻量agent框架的开发者，这里面很多细节对你们都有参考价值。

1. 项目定位与核心设计思路

1.1 为什么叫Hermes，以及它的核心定位

Hermes在希腊神话里是信使神，负责传递消息、连接诸神与凡人。我给这个项目取名hermes-agent，就是希望它在系统里的角色类似“信使”——把用户的话翻译成机器能理解的指令，把各种内部工具的能力汇聚到一个入口，再把结果翻译回人能看懂的语言。

这个定位决定了它的核心架构不能太复杂。市面上很多agent框架动辄引入一堆概念，什么Plan-and-Execute、ReAct、多智能体协商，听着很高级，但到了生产环境你会发现，80%的场景根本不需要那么重的抽象。hermes-agent只做了四件事：

• 接收用户请求，解析意图；
• 根据意图选择合适的工具链；
• 执行工具调用，并把结果反馈给模型；
• 组织最终回复，完成一轮完整交互。

听起来很简单，但就是这四件事，在实际落地时牵扯出大量细节：怎么设计意图解析规则？工具调用失败后要不要重试？上下文多长时需要截断？多个工具结果怎么合并？这些问题在第2、3章会详细展开。

1.2 它和LangChain、AutoGPT这类框架的差异

我用过LangChain跑过几个 demo，也看过不少AutoGPT的案例，最后选择自己写一个轻量框架，不是因为它们不好，而是因为它们解决的问题域和我不一样。

LangChain的核心优势是“集成多”，但这也带来了学习成本高、抽象层级多、排查问题要翻好几层源码的问题。AutoGPT的自治度太高，容易跑偏，实际业务里谁也不敢让模型完全没有约束地执行任务。hermes-agent走的是中间路线：保留一块核心的调度引擎，但所有行为都由显式配置控制，不追求全自动，而是“人在回路中”的半自动模式。

打个比方，LangChain像一辆配置齐全的房车，什么都有但想改装很费劲；AutoGPT像一辆无人驾驶出租车，能不能安全到达全看命；hermes-agent更像一辆手动挡越野车，功能不算花哨，但每个操作都在掌控之中，出了问题知道去哪儿修。我的核心设计原则就是：模型负责聪明的部分，代码负责确定的部分，两者通过清晰的接口配合，谁也不越界。

2. 系统整体架构与关键模块拆解

2.1 从单体Agent到Agent编排的转变

一开始我犯过一个典型错误：把所有逻辑写在一个大函数里，让模型“自由发挥”地调用函数。代码大概是下面这样的：

def run_agent(user_input): prompt = build_prompt(user_input, all_tools) result = llm.chat(prompt) return parse_and_execute(result)

这个写法跑demo没问题，最多三五轮也看不出毛病。但一旦工具数量超过五个，模型就开始犯迷糊：该调A工具的时候调了B工具，该传字符串参数的时候传了JSON，甚至会把不存在的函数名一本正经地编出来。更头疼的是，每次新增工具都要改提示词，改了之后可能影响已有工具的调用准确性。

后来我把架构改成了“路由层 + 执行层 + 记忆层 + 编排层”四层结构。路由层负责理解用户意图，输出结构化的任务描述；执行层根据任务描述去调用具体工具；记忆层保存会话状态和上下文摘要；编排层负责整体的任务流转和异常处理。

这个转变的本质是：把“让模型决定一切”改成“让模型做有限选择”。模型不再面对全部工具列表，而是先由路由层做一次粗过滤，再在候选工具集里做精确选择。实践下来，工具调用的准确率从70%左右提升到了90%以上。

2.2 核心模块一：意图识别与任务路由

路由层的设计是整个项目最关键的部分，我前后重构了三版才稳定下来。

第一版是纯提示词工程，把所有工具描述塞进System Prompt里让模型选。优点是实现最快，缺点是上下文越长选择越不准，基本到十个工具以上就瘫痪了。第二版是把工具按功能分组，路由层先选组再选工具，稍微好一点，但组和组之间容易混淆。第三版也就是现在的方案，采用了“意图槽位”的设计：

intents: - name: data_query description: 查询数据库、统计数据、生成报表 required_fields: [table, condition] optional_fields: [time_range, group_by] tools: [query_mysql, query_clickhouse] fallback_tool: query_mysql

每个意图定义了自己的工具集、必填字段和可选字段。路由层的工作是判断“用户想做什么”，而不是“用户想调用哪个工具”。这个微妙的差别很重要：用户的表达是写在字面上的，意图是藏在话后面的。比如“帮我看看上个月销量怎么样”，意图是data_query，工具是query_mysql，字段是table=sales, time_range=last_month。如果直接让模型从工具名列表里选，它可能会困惑“销量”对应哪个表，但有了意图槽位，模型的脑筋急转弯就少了。

2.3 核心模块二：工具注册与调用链

工具的接入方式我设计成了装饰器注册制，新工具只需要写一个函数，加几行注解就能挂到agent上：

@agent.register_tool( name="query_mysql", description="查询MySQL数据库，支持标准SQL", parameters={ "sql": {"type": "string", "required": True, "description": "要执行的SQL语句"}, "limit": {"type": "integer", "required": False, "description": "返回行数上限"} } ) def query_mysql(sql: str, limit: int = 100) -> dict: # 实际的查询逻辑 return result

参数schema直接沿用JSON Schema规范，这样大模型在生成调用参数时，可以用结构化输出（比如OpenAI的function calling格式或者通用的JSON模式）来约束格式，避免模型乱传参。

执行链上我加了两层保护。第一层是参数校验，凡是必填字段缺失或类型不对，直接返回校验错误，不让模型“硬试”。第二层是超时保护和重试机制。默认超时时间是10秒，工具执行超过10秒返回超时错误，如果错误信息里包含“timeout”或“connection refused”，会自动重试一次。重试是为了对抗网络类工具的偶发故障，但必须限次，防止调用链因为重试陷入死循环。

所有工具执行都会记录日志，包括入参、出参、耗时、成功还是失败。这一步在开发期好像无所谓，但到了生产环境，没有完整日志你根本无法定位“模型为什么调错了工具”或者“哪个工具拖慢了整个请求”。

3. 关键机制详解与实际调优经验

3.1 上下文管理：不失控的记忆

做agent绕不开上下文管理。LLM的上下文窗口再大也是有限的，而且窗口塞得越满，响应越慢、越贵、越容易在指令遵循上“精神涣散”。hermes-agent把记忆分成了三层：

• 短期记忆：最近的几轮对话原文，默认保留10轮，超出后压缩；
• 工作记忆：当前任务的相关信息，比如查询结果、工具返回的数据；
• 长期记忆：跨会话的摘要信息，存储在向量数据库里，按需检索。

压缩策略用的是“摘要+淘汰”的组合。每满5轮对话，就对最早的两轮生成一条摘要存进工作记忆，然后把这5轮原文里最早的3轮丢弃。摘要要模型生成，每次会话可能要做几次摘要调用，成本不高，但换来的是长对话不跑偏，这是很划算的买卖。

关于上下文截断，有一条我踩过好几次的线：不要轻易截断System Prompt里的工具描述和指令部分，要截就截对话历史。工具描述是模型正确调用工具的“说明书”，截了它相当于让新人不看说明书直接上岗，出错率直接飙升。我最终把System Prompt的固定部分控制在1200字以内，对话历史用摘要替代原文，整体上下文一般稳定在6000字以内，模型表现最稳定。

3.2 工具调用的错误处理与降级策略

工具调用失败太常见了，网络抖动、数据库锁表、第三方API限流，每一种都有不同表现。我根据错误类型做了一版分级降级策略，跑了两个月效果很不错。

• 第一级：校验错误。参数不合法、必填字段缺失，直接反馈给模型让它改参数，不重试；
• 第二级：可重试错误。网络超时、HTTP 5xx、限流，重试一次，间隔1秒和3秒；
• 第三级：业务错误。比如SQL执行后查询不到数据，这种重试也没用，直接返回空结果给模型，让模型基于“查不到”这个事实组织回复。

关键是降级逻辑要和模型协同，而不是把错误堆给用户看。比如数据库查询超时，agent重试后还是失败，就会生成“系统暂时无法获取数据，请稍后再试”这样的回复，同时把具体错误原因写入日志。用户看到的是可理解的提示，开发看到的是可排查的错误，两边都照顾到了。

3.3 可观测性：让Agent的行为“可回放”

AI应用调试的难点在于，同样的输入，模型这次和下次可能给出不一样的行为。为了应对这个问题，我给hermes-agent加了一个“请求追踪”功能，每次完整交互都会生成一个trace，里面包含：

• 路由结果：模型把用户请求归类到哪个意图、置信度多少；
• 工具选择：选了哪个工具，为什么选（模型输出的reasoning字段）；
• 参数生成：工具调用的完整参数JSON；
• 执行结果：工具返回的数据、耗时、状态码；
• 最终回复：模型组织回复时使用了哪些上下文片段。

一开始我觉得这个功能“有了就行”，实际用起来才知道，它对调优的决策帮助有多大。有一次用户反馈“某些问题agent答非所问”，我翻trace发现路由层把问题归错了意图，模型老老实实按错误意图去调用工具，自然答不对。没有trace，这种问题你要靠猜，可能纠结好几天。

4. 实操过程与核心环节实现

4.1 快速启动：从配置到跑通一次对话

我做了个极简的启动流程，核心是让新环境五分钟内能跑起来。第一步是准备配置文件和启动脚本：

git clone https://github.com/yourname/hermes-agent cd hermes-agent pip install -r requirements.txt cp config.example.yaml config.yaml python main.py

config.yaml 是核心配置文件，下面是精简版的结构：

server: host: 0.0.0.0 port: 8600 llm: provider: openai_compatible base_url: http://localhost:11434/v1 model: qwen2.5:14b temperature: 0.2 max_tokens: 1024 memory: max_short_term_rounds: 10 compress_every: 5 vector_store_path: ./data/embeddings tools: enabled_tools: [query_mysql, http_request, time_tool] default_timeout: 10 max_retries: 1 routing: confidence_threshold: 0.6 fallback_strategy: ask_clarification

里面有两个值得注意的参数。一个是temperature，我调到了0.2。agent不是聊天机器人，不需要太高的创造力，低了反而稳定，工具调用的格式错误会明显减少。另一个是confidence_threshold，用户消息被路由时的置信度阈值。低于0.6时agent不会硬猜，而是反问用户澄清需求，这个机制比硬着头皮执行要好得多，能避开大量无意义的工具调用。

启动后，可以调用一个简单的REST接口验证：

curl -X POST http://localhost:8600/chat \ -H "Content-Type: application/json" \ -d '{"message": "现在几点了？", "session_id": "test-001"}'

如果配置正确，很快会返回agent调用time_tool并生成的自然语言回复。这一步跑通了，基础链路就没问题了。

4.2 跑一个自定义工具：从写函数到接入路由

用一个实际例子演示工具接入。假设我现在想让agent能查本地库存，我先写一个函数：

@agent.register_tool( name="query_inventory", description="查询当前仓库的库存情况", parameters={ "sku": {"type": "string", "required": True, "description": "商品SKU编号"}, "warehouse": {"type": "string", "required": False, "description": "仓库编号，默认所有仓库"} } ) def query_inventory(sku: str, warehouse: str = "ALL"): sql = "SELECT warehouse_id, stock FROM inventory WHERE sku = %s" params = [sku] if warehouse != "ALL": sql += " AND warehouse_id = %s" params.append(warehouse) rows = db_query(sql, params) return {"sku": sku, "warehouse": warehouse, "items": rows}

然后还要在配置文件的available_tools里加上query_inventory，否则注册了也不生效。这个双重开关是故意的，防止代码里注册了一堆工具，某个环境里又不需要暴露。

接入路由层时，只需要在意图配置文件里把query_inventory挂到库存查询这个意图下，模型就能在你问“还剩多少货”的时候自动调用它。整个过程不需要改一行框架代码，新工具接入的成本就是写一个函数和加两行配置。

还有一点建议：工具描述写得越具体越准确，模型调用就越准。试过很抽象的写法，比如“查询库存”——结果模型经常在用户问“什么时候补货”的时候也去调它；改成“查询当前仓库的实时库存数量，常用于回答现货、缺货、剩余量相关问题时”，调用准确性大幅提升。工具的description是给模型看的，不是在写文档，要用模型容易理解的“触发条件+用途”句式。

4.3 并发和性能的参数选择

项目上线后最容易被问到的就是“并发能撑多少”。这取决于你的LLM服务和内部工具的能力，框架本身能做的是控制并发上限和排队策略。

我在hermes-agent里做了一个简单的信号量控制：

from asyncio import Semaphore class AgentSession: def __init__(self, max_concurrent=16): self.semaphore = Semaphore(max_concurrent) async def process(self, user_input): async with self.semaphore: return await self._process_internal(user_input)

max_concurrent默认16，如果LLM服务比较弱，建议调到4到8，否则大量请求会堆积在模型接口上，整体延迟反而更高。工具调用的内部并发也要设限，尤其是数据库连接池，我在query_mysql里用的是每进程最大5个连接，超过了就排队等待。这个数字看起来保守，但对绝大多数内部系统绰绰有余。

4.4 知识检索和私有数据接入

如果你的agent需要回答和私有知识相关的问题，比如内部规章制度、产品文档，那就得加一个检索增强生成（RAG）模块。hermes-agent把检索做成了两阶段：

• 第一阶段是召回，关键是将文档切片并向量化，用语义检索找到最相关的段落；
• 第二阶段是重排，粗排后的文档再算一次更精细的相关度评分，把干扰项过滤掉。

切片策略非常影响效果。我之前用512个字固定切，发现很多知识点被拦腰截断，检索出来的段落“上气不接下气”。后来改成按标题层级和段落边界切，最大长度控制在700字。文档的内容要尽量是陈述性文本，不要带表格或图片，否则向量化效果很差。

接入之后，用户在问“设备报修流程是什么样”的时候，agent先从知识库里召回相关文档段落，再把段落拼进上下文，最后组织成回答。整个流程对用户是透明的，体验上就像agent“本来就知道”这些规则一样。

5. 踩坑实录与排查技巧

5.1 高频问题速查表

我把两个月里遇到的典型问题整理成了一张表，希望对你有参考价值：

5.2 几个容易忽略但很关键的细节

实际排障中我发现，很多问题的根因不在模型本身，而在周围工程细节上，举三个典型例子。

第一个是时间处理。模型生成的时间参数经常是“今天”“下周一”这种相对表达，直接拿去查数据库根本没法执行。我的解法是加一个“时间标准化”工具，让模型先把相对时间用系统当前时间换算成绝对时间，再交给查询工具。这个工具本身很简单，但能把一大类日期解析问题挡在门外。

第二个是敏感信息过滤。工具返回的数据里经常混着手机号、身份证号等敏感信息，如果直接全部塞给模型再生成回答，等于变相把这些信息打印到日志里。我在工具链出口加了一个脱敏层，匹配到敏感字段就替换成“***”，需要原值时走单独的授权接口。这不仅是合规要求，也是实际部署中经常被审计的点。

第三个是“空结果不等于出错”。很多agent在工具返回“没有数据”的时候会自作聪明地编一个假数据出来。我专门在System Prompt里加了一条硬性指令：如果工具返回结果为空，必须明确告知用户未找到数据，不能推测或编造。同时工具结果里也要标注“is_empty”字段，模型看到这个标记后会走“如实告知”分支。这个问题只靠提示词约束不够，必须在数据层面给模型一个明确的信号。

5.3 后续可以扩展的方向

hermes-agent现在的版本做的是单agent的任务编排，也就是一个问题由一条链路解决。我已经在规划下个迭代，让它支持更复杂的任务，思路是拆成分层结构：顶层是一个编排agent，负责拆解任务、分配子任务；底层是一组执行agent，各自负责一个领域的工具集合。这样当一个需求跨越多个领域时，编排agent先把任务拆成几步，再分配给不同的执行agent，最后汇总结果。

另一个正在测试的方向是嵌入更细粒度的反馈学习。现在模型选了错误的工具，我只能通过日志事后分析；后面打算加一个显式反馈接口，让用户在回复下方点“正确/错误”，错误样本会自动进入评估集，定期跑回归测试，帮助定位到底是路由问题、工具描述问题还是模型能力问题。有了这条闭环，agent的优化就不靠感觉，而是靠数据了。

最后再分享一个实用的小技巧。如果你也打算在本地调试agent，建议给每个会话配置一个独立的上下文存储目录，这样模型在出错时你可以直接翻出该会话的完整上下文，看清楚它到底基于哪些信息做出了错误判断。很多时候你以为“模型抽风了”，看完上下文才发现是某一步工具返回了错误数据，模型只是忠实地用了错误输入。这个排查习惯，能帮你少走很多弯路。