企业官网建设流程全解析

1. 客服 Agent 的 48 关到底在渡什么劫

做客服 Agent 这个方向快两年了，从最早拿 LangChain 拼一个"能查订单状态"的玩具，到后来带团队做日均百万级会话的生产系统，中间踩的坑如果写成文档，大概能装满一个 48 关的副本。这个标题里的"渡劫 48 关"不是夸张修辞，是我自己梳理下来，一个客服 Agent 从 Demo 走到生产可用，至少要跨过的 48 个关键决策点。这些决策点分布在 Tool、RAG、MCP、Eval 四个大方向上，每一个方向都有它自己的"天劫"。

先说清楚这个项目是什么。它是一个面向电商和 SaaS 场景的客服 Agent 系统，核心能力包括：多轮对话理解、订单与工单查询、知识库检索、工具调用、人工兜底转接。适合谁来参考？如果你正在做 Agent 开发，尤其是客服、售前、售后这类需要"查数据+答问题+执行动作"的场景，这篇内容基本可以当路线图用。如果你只是刚接触 Agent 概念，也没关系，我会把每个技术点用生活化的方式讲清楚，保证你能看懂"为什么要这么做"。

为什么是 48 关？因为客服 Agent 和通用聊天机器人的最大区别在于：它必须"说对话"且"做对事"。说对话靠 RAG 和 Prompt，做对事靠 Tool 和 MCP，而保证它一直说对做对，靠 Eval。这四个环节任何一个出问题，用户感受到的就是"这个客服是个智障"。我见过太多团队在 Demo 阶段效果惊艳，一上生产就崩，根本原因就是只渡了前 10 关，后面 38 关全跳过了。

这篇文章我会按四个大方向拆解：先讲整体设计思路和方案选型，再讲 Tool 和 RAG 的核心细节，然后是 MCP 的接入实操，最后是 Eval 体系怎么搭。每一部分都会给出我实际用过的参数、配置和避坑经验，不是纸上谈兵。

2. 整体架构设计与方案选型思路

2.1 为什么客服 Agent 不能只靠一个大模型

很多人第一反应是：客服嘛，把知识库塞进 Prompt，让大模型直接答不就行了？我早期也这么干过，结果就是三个字：贵、慢、不准。贵是因为每次请求都要带上几万 token 的知识库内容；慢是因为长上下文推理延迟高；不准是因为模型在长文本里找答案的能力远不如专门的检索系统。

所以客服 Agent 的架构必须是"分层"的。我的方案是四层：接入层负责多渠道消息归一化，编排层负责意图识别和路由，能力层负责 Tool 调用和 RAG 检索，评估层负责线上质量监控。这四层里，编排层和能力层是核心，也是 48 关里占坑最多的部分。

选型上，编排层我用的是状态机+LLM 混合模式，而不是纯 ReAct。原因很简单：客服场景有明确的业务流程，比如"查订单→确认问题→给出方案→执行退款"，这些步骤是确定的，用状态机保证流程不走偏，用 LLM 处理每一步的自然语言理解和生成。纯 ReAct 的自由度太高，在生产环境里容易"自由发挥"，比如用户问退款，它可能先去查了物流，浪费一轮交互。

2.2 Tool、RAG、MCP、Eval 四者的关系

这四个词经常被混在一起讲，但它们的职责边界其实很清楚。Tool 是 Agent 的"手"，负责执行具体动作，比如查订单、改地址、发工单。RAG 是 Agent 的"记忆"，负责从知识库里找到相关信息。MCP 是 Agent 的"神经接口"，负责标准化地连接外部工具和数据源。Eval 是 Agent 的"体检报告"，负责告诉你它哪里病了。

我见过最常见的错误是：把 RAG 当 Tool 用，或者把 Tool 当 RAG 用。比如用户问"我的订单到哪了"，这是 Tool 该干的事，因为需要实时查数据库；用户问"退货政策是什么"，这是 RAG 该干的事，因为答案是静态知识。如果搞混了，要么查不到实时数据，要么把静态知识硬编码成工具，维护成本爆炸。

MCP 的价值在于，它让 Tool 的接入标准化了。以前每接一个外部系统，就要写一套适配代码；有了 MCP，只要对方提供 MCP Server，我这边就能直接挂载。Eval 则是贯穿始终的，从 Tool 调用的准确率，到 RAG 的召回率，再到最终回答的满意度，都需要量化。

2.3 48 关的分布与优先级

我把 48 关按四个方向做了分布：Tool 相关 14 关，RAG 相关 16 关，MCP 相关 8 关，Eval 相关 10 关。优先级上，Tool 和 RAG 是必须最先渡的，因为它们是 Agent 的核心能力；MCP 可以后置，等 Tool 多了再上；Eval 要尽早搭，但可以先用简单指标，后面再完善。

这里给一个我实际用的优先级表，供你参考：

这个表不是死的，但大方向是这样。我见过有团队第一阶段就花两个月，结果 Tool 还没定义清楚，这就是没抓住重点。

3. Tool 层：从定义到错误处理的 14 关

3.1 Tool 定义的三要素与常见坑

定义一个 Tool，看起来简单，其实有三个要素必须想清楚：名称、描述、参数 schema。名称要语义明确，比如query_order_status就比get_info好得多，因为 LLM 是靠名称和描述来判断该不该调用的。描述要写清楚"什么时候用"和"什么时候不用"，比如"当用户询问订单物流状态时使用，不要用于查询历史订单列表"。

参数 schema 是最容易出坑的地方。我踩过的坑包括：参数类型不明确导致 LLM 传字符串给数字字段；参数没有枚举约束导致 LLM 传了不存在的状态值；参数没有必填标记导致调用时缺参。后来我定了一个规矩：所有参数必须有类型、有描述、有示例，枚举字段必须列出所有合法值。

# 一个规范的 Tool 定义示例 { "name": "query_order_status", "description": "查询指定订单的当前物流状态。当用户询问某个订单的配送进度时使用。不要用于查询订单列表或历史订单。", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单编号，通常是 16 位数字字符串", "example": "2024051712345678" }, "query_type": { "type": "string", "enum": ["status", "detail", "estimate"], "description": "查询类型：status 查状态，detail 查详情，estimate 查预计送达" } }, "required": ["order_id"] } }

这个定义看起来啰嗦，但实测下来，LLM 的调用准确率能提升 30% 以上。原因很简单：LLM 不是人，它没有常识，你写得越明确，它越不容易猜错。

3.2 Tool 调用的错误处理与重试策略

Tool 调用失败是常态，不是异常。网络超时、参数错误、权限不足、下游系统故障，这些都会发生。我的处理策略是分三级：可重试错误、可降级错误、不可恢复错误。

可重试错误包括超时、限流、临时故障，这类错误我会重试 2 次，间隔 500ms 和 1500ms，指数退避。可降级错误包括下游系统返回空数据、部分字段缺失，这类错误我会让 Agent 用兜底话术回复，比如"暂时查不到物流信息，我帮您转人工确认"。不可恢复错误包括参数格式错误、订单不存在，这类错误直接返回明确提示，不重试。

这里有个坑：重试不能无脑重试。我见过有团队对所有错误都重试 3 次，结果下游系统已经挂了，重试只是雪上加霜。我的经验是，只有明确是"临时性"的错误才重试，而且重试次数不要超过 2 次，否则用户等待时间太长。

提示：Tool 调用的超时时间建议设置在 3-5 秒。太短容易误判超时，太长用户等不及。如果是查询类 Tool，可以放宽到 8 秒；如果是写操作类 Tool，建议 3 秒内必须返回，否则走异步。

3.3 Tool 编排与并行调用

客服场景里，很多问题需要多个 Tool 配合。比如用户说"我上周买的鞋还没到，帮我看看"，这需要先查订单列表，再查具体订单的物流。如果串行调用，延迟就是两次调用之和；如果并行调用，延迟就是最慢的那次。

我的做法是：能并行的必须并行。比如查订单状态和查用户等级，这两个没有依赖关系，可以同时调。但查订单详情和查物流，这两个有依赖关系，必须先拿到订单号才能查物流，只能串行。

并行调用的实现上，我用的是 asyncio.gather，但要注意异常处理。如果并行调用中有一个失败，不能让整个流程崩掉，而是要让成功的部分继续，失败的部分走降级。这个细节很多教程不讲，但生产环境里非常重要。

3.4 Tool 权限与安全边界

Tool 是 Agent 的手，但这只手不能乱伸。我定了几条硬规矩：写操作类 Tool 必须二次确认，比如退款、改地址，Agent 必须先问用户"确认要退款吗"，用户确认后才能调用；敏感数据类 Tool 必须脱敏，比如查手机号，返回时只显示后四位；高频操作类 Tool 必须限流，比如查订单，单个用户每分钟最多查 5 次。

这些规矩不是技术问题，是产品问题，但必须在 Tool 层实现。我见过有 Agent 被用户诱导，直接把别人的订单信息返回了，这就是权限没做好。安全边界这件事，宁可严一点，不能松。

4. RAG 层：从检索到重排的 16 关

4.1 RAG 的核心瓶颈到底在哪

RAG 的瓶颈从来不是"能不能检索到"，而是"检索到的是不是对的"。我做过统计，在客服场景里，RAG 出问题的情况中，70% 是召回阶段就没找到正确文档，20% 是找到了但排序不对，只有 10% 是生成阶段的问题。所以优化 RAG，重点要放在召回和重排上，而不是天天调 Prompt。

召回阶段的核心是切分和向量化。切分粒度太粗，一个 chunk 里混了多个主题，检索时容易召回不相关的；切分粒度太细，一个完整答案被拆成好几段，检索时可能只召回一半。我的经验是，客服知识库的 chunk 大小控制在 300-500 字，并且要按语义切分，不能按固定字数硬切。

向量化模型的选择上，我试过 OpenAI 的 embedding、BGE、M3E，最后在中文客服场景里用的是 BGE-large-zh。原因是对中文语义的捕捉更准，尤其是"退货"和"退款"这种近义词，BGE 的区分度更好。当然，如果你的知识库以英文为主，OpenAI 的 embedding 也是好选择。

4.2 混合检索：向量+关键词的必要性

纯向量检索有个致命问题：对专有名词和数字不敏感。比如用户问"订单 2024051712345678 的物流"，向量检索可能召回一堆"订单物流"相关的文档，但就是找不到这个具体订单。这时候就需要关键词检索来兜底。

我的方案是混合检索：向量检索召回 Top 20，关键词检索召回 Top 20，然后用 RRF 算法融合，取 Top 10 进入重排。RRF 的公式很简单：score = sum(1 / (k + rank))，k 通常取 60。这个方案实测下来，召回率比纯向量提升了 25% 左右。

# RRF 融合的简化实现 def rrf_fusion(vector_results, keyword_results, k=60): scores = {} for rank, doc in enumerate(vector_results): scores[doc.id] = scores.get(doc.id, 0) + 1 / (k + rank + 1) for rank, doc in enumerate(keyword_results): scores[doc.id] = scores.get(doc.id, 0) + 1 / (k + rank + 1) return sorted(scores.items(), key=lambda x: x[1], reverse=True)

这个实现很简单，但效果很稳。我试过用加权求和代替 RRF，结果发现权重很难调，RRF 的好处是不需要调权重，对异常值也更鲁棒。

4.3 重排模型的选择与部署

重排是 RAG 的第二道关。召回阶段追求的是"不漏"，重排阶段追求的是"精准"。我用的重排模型是 BGE-reranker-large，部署在本地，延迟大概 50ms 左右，可以接受。

重排的输入是 query 和候选文档，输出是相关性分数。我的做法是取 Top 10 候选，重排后取 Top 3 进入生成。为什么是 Top 3？因为客服场景的答案通常很聚焦，Top 3 足够覆盖，再多反而会引入噪声。

这里有个坑：重排模型和向量模型最好用同一个系列的，比如都用 BGE，因为它们的语义空间更一致。我试过向量用 OpenAI、重排用 BGE，效果明显不如都用 BGE。

4.4 RAG 的评估与迭代

RAG 不做评估，就是盲人摸象。我用的评估指标有三个：召回率、准确率、MRR。召回率看的是正确文档有没有被召回，准确率看的是召回的文档里有多少是相关的，MRR 看的是正确文档的排名。

评估数据的构建上，我建议从线上真实问题里采样，人工标注正确答案，然后定期跑评估。我一般每周跑一次，每次 200 条左右，能覆盖主要场景。如果召回率低于 80%，就要检查切分和向量模型；如果准确率低于 70%，就要检查重排和阈值。

注意：RAG 的评估不能只看整体指标，要分场景看。比如"退货政策"类问题的召回率可能是 95%，但"订单物流"类可能只有 60%，因为后者需要实时数据，RAG 本身就不擅长。分场景看指标，才能找到真正的瓶颈。

5. MCP 层：标准化接入的 8 关

5.1 MCP 到底解决了什么问题

MCP 刚出来的时候，我以为它就是个"工具协议"，后来用下来发现，它解决的是"工具接入的标准化"问题。以前每接一个外部系统，就要写一套适配代码，A 系统的订单查询和 B 系统的订单查询，接口格式完全不一样。有了 MCP，只要对方提供 MCP Server，我这边就能用统一的方式挂载。

MCP 的核心概念是 Server 和 Client。Server 提供工具和资源，Client 负责调用。在客服 Agent 里，Agent 就是 Client，各个业务系统就是 Server。这个架构的好处是解耦：业务系统只需要实现 MCP Server，不需要关心 Agent 怎么用；Agent 只需要知道 MCP 协议，不需要关心业务系统的具体实现。

5.2 MCP Server 的接入实操

接入一个 MCP Server，步骤其实不复杂，但有几个细节容易出问题。第一步是确认 Server 的传输方式，MCP 支持 stdio 和 SSE 两种，本地工具用 stdio，远程服务用 SSE。第二步是配置连接参数，比如命令、参数、环境变量。第三步是测试连接，确认工具列表能正常拉取。

// MCP Server 配置示例 { "mcpServers": { "order-service": { "command": "node", "args": ["/path/to/order-mcp-server.js"], "env": { "API_KEY": "your-api-key" } }, "knowledge-base": { "url": "https://internal.example.com/mcp", "transport": "sse" } } }

这个配置看起来简单，但坑不少。比如 stdio 模式下，Server 的日志不能输出到 stdout，否则会干扰协议通信，必须输出到 stderr。这个细节很多文档不写，但实际接入时一定会遇到。

5.3 MCP 工具的动态发现与缓存

MCP 的一个好处是工具可以动态发现。Agent 启动时，会向每个 Server 请求工具列表，然后把这些工具注册到自己的工具池里。但这里有个性能问题：如果每次请求都去拉工具列表，延迟会很高。我的做法是启动时拉一次，缓存起来，定期刷新（比如每 5 分钟）。

缓存带来的问题是：如果 Server 更新了工具，Agent 可能不知道。我的解决方案是加一个版本号机制，Server 的工具列表带版本号，Agent 定期检查版本号，变了就刷新。这个机制不复杂，但能避免很多"工具明明更新了但 Agent 还在用旧版"的问题。

5.4 MCP 的安全与权限控制

MCP 让工具接入变简单了，但也带来了安全风险。如果任意 Server 都能注册工具，那恶意 Server 可能注册一个"删除订单"的工具，Agent 一旦调用就出大事。所以我的做法是：MCP Server 必须白名单，只有经过审核的 Server 才能接入；工具注册时必须声明权限等级，写操作类工具需要额外审批。

权限控制上，我用的是"最小权限原则"：Agent 只挂载当前场景需要的工具，不需要的不挂。比如售前场景只挂"查商品"和"查库存"，不挂"退款"和"改地址"。这样即使 Agent 被诱导，也做不了危险操作。

6. Eval 层：从指标到闭环的 10 关

6.1 Eval 的三个层次

Eval 不是单一指标，而是三个层次：组件级、链路级、业务级。组件级评估的是单个 Tool 或 RAG 的准确率；链路级评估的是整个对话流程的完成率；业务级评估的是用户满意度和问题解决率。

组件级评估最容易做，也最应该先做。比如 Tool 调用的准确率，我可以构造 100 个测试用例，看 Agent 有没有调对工具、传对参数。RAG 的召回率，我可以标注 200 个问答对，看正确文档有没有被召回。这些指标能快速定位问题。

链路级评估需要模拟完整对话。我用的方法是"脚本回放"：把线上真实对话录下来，去掉 Agent 的回复，让新版本 Agent 重新跑一遍，对比结果。这个方法能发现很多组件级评估发现不了的问题，比如多轮对话中的上下文丢失。

业务级评估最直接，就是看用户满意度。我用的指标是"一次解决率"和"转人工率"。一次解决率越高，说明 Agent 越能干；转人工率越高，说明 Agent 越无能。这两个指标是最终检验标准。

6.2 自动化评估流水线的搭建

Eval 不能靠人工跑，必须自动化。我的流水线是这样的：代码提交后，自动触发评估任务；评估任务从测试集里采样，跑一遍 Agent；跑完后生成报告，对比基线；如果指标下降超过阈值，就阻断发布。

这个流水线听起来复杂，其实用 GitHub Actions 就能搭。核心是测试集的管理和指标的计算。测试集我放在版本控制里，每次更新都记录变更；指标计算用 Python 脚本，输出 JSON 格式的报告。

# 评估指标计算的简化示例 def evaluate_agent(test_cases, agent): results = { "tool_accuracy": 0, "rag_recall": 0, "task_completion": 0 } for case in test_cases: response = agent.run(case.input) if case.expected_tool: results["tool_accuracy"] += int(response.tool == case.expected_tool) if case.expected_doc: results["rag_recall"] += int(case.expected_doc in response.docs) results["task_completion"] += int(response.completed) n = len(test_cases) return {k: v / n for k, v in results.items()}

这个脚本很简单，但能跑起来就是胜利。我见过有团队评估全靠人工，结果一周只能跑一次，迭代速度极慢。

6.3 线上监控与告警

Eval 不只是离线评估，线上监控同样重要。我监控的指标包括：Tool 调用失败率、RAG 空召回率、对话轮次异常率、用户负面反馈率。这些指标一旦超过阈值，就触发告警。

告警的阈值设置上，我的经验是：Tool 失败率超过 5% 告警，RAG 空召回率超过 10% 告警，对话轮次超过 10 轮告警，负面反馈率超过 3% 告警。这些阈值不是绝对的，要根据业务调整，但大方向是这样。

线上监控的另一个价值是发现"未知问题"。离线评估只能发现已知问题，线上监控能发现未知问题。比如某天突然 Tool 失败率飙升，查下来发现是下游系统改了接口，这种问题离线评估永远发现不了。

6.4 评估驱动的迭代闭环

Eval 的最终目的是驱动迭代。我的做法是：每周跑一次全量评估，生成报告；报告里列出 Top 5 问题；每个问题指派负责人；下周评估时看问题有没有解决。这个闭环看起来简单，但坚持下来效果很好。

迭代的优先级上，我一般按"影响面×严重度"排序。影响面大且严重度高的问题先修，比如 Tool 调用错误导致用户被误导；影响面小但严重度高的问题也要修，比如 RAG 召回错误导致答案完全不对；影响面大但严重度低的问题可以缓，比如回复语气不够友好。

7. 实操中的常见问题与排查技巧

7.1 Tool 调用失败的排查路径

Tool 调用失败是最常见的问题，排查路径我总结成三步：先看参数，再看网络，最后看下游。参数问题占 50%，通常是 LLM 传错了类型或漏了必填字段；网络问题占 30%，通常是超时或限流；下游问题占 20%，通常是下游系统故障或返回格式变了。

排查参数问题时，我会把 LLM 的原始输出和 Tool 的 schema 对比，看哪里不匹配。排查网络问题时，我会看超时日志和限流日志。排查下游问题时，我会直接调下游接口，看返回什么。

7.2 RAG 召回不准的优化手段

RAG 召回不准，优化手段有四个：调切分、换模型、加关键词、加重排。调切分是最容易的，把 chunk 大小从 500 调到 300，或者按标题切分；换模型成本高，但效果可能明显；加关键词能解决专有名词问题；加重排能解决排序问题。

我的经验是，先调切分和加关键词，这两个成本低见效快；如果还不行，再考虑换模型和加重排。换模型不是万能的，我试过换了好几个模型，效果提升有限，最后还是靠混合检索和重排解决的。

7.3 MCP 连接不上的排查

MCP 连接不上，常见原因有三个：配置错误、网络不通、Server 没启动。配置错误包括命令写错、参数写错、环境变量没设；网络不通包括防火墙拦截、端口不对；Server 没启动就是字面意思。

排查时，我会先用命令行手动启动 Server，看能不能跑起来；然后用 MCP Client 测试连接，看能不能拉取工具列表；最后看日志，找具体报错。这个流程能解决 90% 的连接问题。

7.4 Eval 指标波动的归因

Eval 指标波动，归因要看是"真波动"还是"假波动"。真波动是 Agent 真的变差了，假波动是测试集或评估方法变了。我一般先看测试集有没有变，再看评估代码有没有变，最后才看 Agent 代码。

如果确认是 Agent 变差了，我会用二分法定位：把最近的代码变更列出来，逐个回滚测试，找到导致变差的那个变更。这个方法笨但有效，我靠它定位过好几次"看起来无关但实际有关"的变更。

8. 一些踩坑之后的个人体会

做客服 Agent 这两年，最大的体会是：技术不是最难的，难的是"定义清楚问题"。Tool 该定义成什么样，RAG 该召回什么，Eval 该评估什么，这些问题想清楚了，技术实现反而简单。我见过太多团队技术很强，但问题没定义清楚，做出来的东西没人用。

第二个体会是：不要追求一步到位。48 关不是一天渡完的，我自己的系统也是迭代了十几版才稳定。先渡最关键的几关，让系统能跑起来，然后再逐步优化。完美主义在 Agent 开发里是毒药，因为 Agent 本身就有不确定性，你永远等不到"完美"的那天。

第三个体会是：Eval 要尽早做。我早期不做 Eval，全靠人工看，结果就是"感觉还行"但实际一堆问题。后来搭了 Eval 流水线，才发现问题比想象的多。Eval 不是负担，是眼睛，没有眼睛就是盲人摸象。

最后分享一个小技巧：客服 Agent 的 Prompt 里，一定要加一句"如果不确定，就说不知道，并转人工"。这句话能避免 80% 的胡编乱造。Agent 最大的风险不是答不上来，而是答错了还理直气壮。宁可转人工，不可瞎回答。